Class: Musa::Sequencer::BaseSequencer::EventHandler Private

Inherits:
Object
  • Object
show all
Defined in:
lib/musa-dsl/sequencer/base-sequencer-implementation.rb

Overview

This class is part of a private API. You should avoid using this class if possible, as it may be removed or be changed in the future.

Hierarchical event handler with parent delegation.

EventHandler implements a pub/sub event system with hierarchical event propagation. Handlers can be registered for named events, and events bubble up to parent handlers if not handled locally. Used as control objects for play, every, and move operations.

Event Hierarchy

Events are first checked locally. If no handler is registered, the event propagates to the parent handler. This enables:

  • Control-specific event handling (e.g., :stop for this play)
  • Global event handling (e.g., :stop for entire sequencer)
  • Override parent behavior by registering local handler

Lifecycle

  • stop: Marks handler as stopped (events no longer execute)
  • stopped?: Checks if stopped
  • pause/continue: Not fully implemented

Event Registration

Use on(event, &block) to register handlers. Handlers receive parameters via SmartProcBinder, enabling flexible parameter signatures.

Examples:

Basic event handling

control = EventHandler.new
control.on(:finished) { puts "Done!" }
control.launch(:finished)  # Prints "Done!"

Parent delegation

parent = EventHandler.new
parent.on(:stop) { puts "Parent stops" }

child = EventHandler.new(parent)
child.launch(:stop)  # Prints "Parent stops" (delegates to parent)

child.on(:stop) { puts "Child stops" }
child.launch(:stop)  # Prints "Child stops" (local handler, no delegation)

One-time handler

control.on(:init, only_once: true) { puts "Initialize" }
control.launch(:init)  # Prints "Initialize"
control.launch(:init)  # Does nothing (handler removed)

Constant Summary collapse

@@counter =

This classvariable is part of a private API. You should avoid using this classvariable if possible, as it may be removed or be changed in the future. 

0

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(parent = nil) ⇒ EventHandler

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Creates event handler with optional parent.

Parameters:

  • parent (EventHandler, nil) (defaults to: nil) —

    parent for event delegation



356
357
358
359
360
361
362
363
 
# File 'lib/musa-dsl/sequencer/base-sequencer-implementation.rb', line 356

def initialize(parent = nil)
  @id = (@@counter += 1)

  @parent = parent
  @handlers = {}

  @stop = false
end

Instance Attribute Details

#continue_parameters ⇒ Hash?

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Parameters for continue operation (not fully implemented).

Returns:

  • (Hash, nil) —

    continue parameters



347
348
349
 
# File 'lib/musa-dsl/sequencer/base-sequencer-implementation.rb', line 347

def continue_parameters
  @continue_parameters
end

Instance Method Details

#_launch(event, value_parameters = nil, key_parameters = nil, proc_parameter = nil) ⇒ void

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

This method returns an undefined value.

Internal launch implementation with delegation.

Processes handlers locally, then delegates to parent if no local handlers processed the event. Removes only_once handlers after first invocation.

Parameters:

  • event (Symbol) —

    event name

  • value_parameters (Array) (defaults to: nil) —

    positional args

  • key_parameters (Hash) (defaults to: nil) —

    keyword args

  • proc_parameter (Proc, nil) (defaults to: nil) —

    block arg



483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
 
# File 'lib/musa-dsl/sequencer/base-sequencer-implementation.rb', line 483

def _launch(event, value_parameters = nil, key_parameters = nil, proc_parameter = nil)
  value_parameters ||= []
  key_parameters ||= {}
  processed = false

  if @handlers.key? event
    @handlers[event].each do |name, handler|
      handler[:block].call *value_parameters, **key_parameters, &proc_parameter
      @handlers[event].delete name if handler[:only_once]
      processed = true
    end
  end

  @parent._launch event, value_parameters, key_parameters, proc_parameter if @parent && !processed
end

#continue ⇒ void

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

This method returns an undefined value.

Continues from pause (not fully implemented).



400
401
402
 
# File 'lib/musa-dsl/sequencer/base-sequencer-implementation.rb', line 400

def continue
  @paused = false
end

#id ⇒ String

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns hierarchical identifier.

Builds identifier showing parent chain and instance ID.

Returns:

  • (String) —

    hierarchical ID like "EventHandler-1.PlayControl-5"



515
516
517
518
519
520
521
 
# File 'lib/musa-dsl/sequencer/base-sequencer-implementation.rb', line 515

def id
  if @parent
    "#{@parent.id}.#{self.class.name.split('::').last}-#{@id}"
  else
    "#{self.class.name.split('::').last}-#{@id.to_s}"
  end
end

#inspect ⇒ String Also known as: to_s

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns string representation.

Returns:

  • (String) —

    "EventHandler "



504
505
506
 
# File 'lib/musa-dsl/sequencer/base-sequencer-implementation.rb', line 504

def inspect
  "EventHandler #{id}"
end

#launch(event, *value_parameters, **key_parameters, &proc_parameter) ⇒ void

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

This method returns an undefined value.

Launches event with parameters.

Triggers all registered handlers for the event, passing parameters. If no local handlers exist, delegates to parent handler (bubbling). Supports value parameters (*args), keyword parameters (**kwargs), and block parameter (&block).

Examples:

Launch with parameters

control.on(:progress) { |percent| puts "#{percent}%" }
control.launch(:progress, 50)  # Prints "50%"

Launch with keyword parameters

control.on(:update) { |position:, value:| puts "#{position}: #{value}" }
control.launch(:update, position: 1r, value: 60)

Parameters:

  • event (Symbol) —

    event name to launch

  • value_parameters (Array) —

    positional arguments for handlers

  • key_parameters (Hash) —

    keyword arguments for handlers

  • proc_parameter (Proc, nil) —

    block parameter for handlers



465
466
467
 
# File 'lib/musa-dsl/sequencer/base-sequencer-implementation.rb', line 465

def launch(event, *value_parameters, **key_parameters, &proc_parameter)
  _launch event, value_parameters, key_parameters, proc_parameter
end

#on(event, name: nil, only_once: nil) { ... } ⇒ void

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

This method returns an undefined value.

Registers event handler.

Registers a block to be called when event is launched. Handlers are identified by event name and optional handler name. If only_once is true, handler is removed after first invocation.

Block is wrapped in SmartProcBinder for flexible parameter binding.

Examples:

Register handler

control.on(:finished) { puts "Done" }
control.on(:progress, name: :logger) { |pct| puts "#{pct}%" }

Parameters:

  • event (Symbol) —

    event name to handle

  • name (Symbol, nil) (defaults to: nil) —

    optional handler name (for removal)

  • only_once (Boolean) (defaults to: nil) —

    remove after first call (default: false)

Yields:

  • handler block with flexible parameters



433
434
435
436
437
438
439
440
 
# File 'lib/musa-dsl/sequencer/base-sequencer-implementation.rb', line 433

def on(event, name: nil, only_once: nil, &block)
  only_once ||= false

  @handlers[event] ||= {}

  # TODO: add on_rescue: proc { |e| _rescue_block_error(e) } [this method is on Sequencer, not in EventHandler]
  @handlers[event][name] = { block: Musa::Extension::SmartProcBinder::SmartProcBinder.new(block), only_once: only_once }
end

#pause ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Pauses handler (not implemented).

Raises:

  • (NotImplementedError) —

    pause not yet implemented



391
392
393
 
# File 'lib/musa-dsl/sequencer/base-sequencer-implementation.rb', line 391

def pause
  raise NotImplementedError
end

#paused? ⇒ Boolean

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Checks if handler is paused.

Returns:

  • (Boolean) —

    true if paused



409
410
411
 
# File 'lib/musa-dsl/sequencer/base-sequencer-implementation.rb', line 409

def paused?
  @paused
end

#stop ⇒ void

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

This method returns an undefined value.

Stops this event handler.

Marks handler as stopped, preventing future event execution. Used by control objects to halt play/every/move operations.



373
374
375
 
# File 'lib/musa-dsl/sequencer/base-sequencer-implementation.rb', line 373

def stop
  @stop = true
end

#stopped? ⇒ Boolean

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Checks if handler is stopped.

Returns:

  • (Boolean) —

    true if stopped



382
383
384
 
# File 'lib/musa-dsl/sequencer/base-sequencer-implementation.rb', line 382

def stopped?
  @stop
end