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



324
325
326
327
328
329
330
331
 
# File 'lib/musa-dsl/sequencer/base-sequencer-implementation.rb', line 324

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



315
316
317
 
# File 'lib/musa-dsl/sequencer/base-sequencer-implementation.rb', line 315

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



451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
 
# File 'lib/musa-dsl/sequencer/base-sequencer-implementation.rb', line 451

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).



368
369
370
 
# File 'lib/musa-dsl/sequencer/base-sequencer-implementation.rb', line 368

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"



483
484
485
486
487
488
489
 
# File 'lib/musa-dsl/sequencer/base-sequencer-implementation.rb', line 483

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 "



472
473
474
 
# File 'lib/musa-dsl/sequencer/base-sequencer-implementation.rb', line 472

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



433
434
435
 
# File 'lib/musa-dsl/sequencer/base-sequencer-implementation.rb', line 433

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



401
402
403
404
405
406
407
408
 
# File 'lib/musa-dsl/sequencer/base-sequencer-implementation.rb', line 401

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



359
360
361
 
# File 'lib/musa-dsl/sequencer/base-sequencer-implementation.rb', line 359

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



377
378
379
 
# File 'lib/musa-dsl/sequencer/base-sequencer-implementation.rb', line 377

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.



341
342
343
 
# File 'lib/musa-dsl/sequencer/base-sequencer-implementation.rb', line 341

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



350
351
352
 
# File 'lib/musa-dsl/sequencer/base-sequencer-implementation.rb', line 350

def stopped?
  @stop
end