musa-dsl 0.30.2 → 0.40.0

data/lib/musa-dsl/sequencer/base-sequencer-implementation-play.rb

@@ -5,6 +5,79 @@ using Musa::Extension::InspectNice
 
 module Musa::Sequencer
   class BaseSequencer
+    # Play implementation for series-based event scheduling.
+    #
+    # Implements the `play` method that consumes a Musa::Series and schedules
+    # events based on series elements. Supports multiple evaluation modes for
+    # interpreting series elements (e.g., as timing deltas, absolute positions,
+    # or complex data structures).
+    #
+    # ## Execution Model
+    #
+    # Play iterates through series elements:
+    # 1. Gets next element from series
+    # 2. PlayEval evaluates element to determine operations
+    # 3. Executes current operation (call block, launch event, nested play, etc.)
+    # 4. Schedules continuation based on continue operation
+    # 5. Recursively processes next element
+    #
+    # ## PlayEval System
+    #
+    # PlayEval.create builds appropriate evaluator based on mode parameter.
+    # Evaluator's run_operation method returns hash with:
+    #
+    # - current_operation: what to do now (:block, :event, :play, etc.)
+    # - current_parameter: data for current operation
+    # - continue_operation: when to continue (:now, :at, :wait, :on)
+    # - continue_parameter: data for continue operation
+    #
+    # ## Operations
+    #
+    # Current operations (what to do now):
+    #
+    # - **:none**: Skip element
+    # - **:block**: Call user block with element
+    # - **:event**: Launch named event
+    # - **:play**: Nested sequential play
+    # - **:no_eval_play**: Nested play without evaluation
+    # - **:parallel_play**: Multiple parallel plays
+    #
+    # Continue operations (when to continue):
+    #
+    # - **:now**: Immediately
+    # - **:at**: At absolute position
+    # - **:wait**: After time delta
+    # - **:on**: When event fires
+    #
+    # ## Running Modes
+    #
+    # Different modes interpret series elements differently:
+    #
+    # - **:at**: Elements specify absolute positions via :at key
+    # - **:wait**: Elements with duration specify wait time
+    # - **:neumalang**: Full Neumalang DSL with variables, commands, series, etc.
+    #
+    # @param serie [Series] series to play
+    # @param control [PlayControl] control object for lifecycle
+    # @param neumalang_context [Object, nil] context for neumalang evaluation
+    # @param mode [Symbol, nil] running mode
+    # @param decoder [Object, nil] custom decoder
+    # @param __play_eval [PlayEval, nil] evaluator (internal, created if nil)
+    # @param mode_args [Hash] additional mode-specific arguments
+    # @yield block to call for each element (mode-dependent)
+    #
+    # @return [nil]
+    #
+    #
+    # @api private
+
+    # Plays series by iterating elements and scheduling events.
+    #
+    # Recursively consumes series, 
+    #
+    #
+    #
+    # @api private
     private def _play(serie,
                       control,
                       neumalang_context = nil,
@@ -140,9 +213,55 @@ module Musa::Sequencer
       nil
     end
 
+    # Control object for play operations.
+    #
+    # Manages play lifecycle including pause/continue and after callbacks.
+    # Extends EventHandler to support custom events and hierarchical control.
+    #
+    # ## Pause/Continue
+    #
+    # When paused:
+    # 1. Stores continuation parameters (series state, evaluator, etc.)
+    # 2. Stops processing series
+    # 3. Awaits continue call
+    #
+    # When continued:
+    # 1. Restores continuation parameters
+    # 2. Resumes play from stored position
+    #
+    # ## After Callbacks
+    #
+    # Executed after play completes, with optional delay in bars.
+    #
+    # @example Basic play control
+    #   seq = Musa::Sequencer::BaseSequencer.new(4, 24)
+    #
+    #   series = Musa::Series::S(60, 62, 64, 65, 67)
+    #   played_notes = []
+    #   after_executed = []
+    #
+    #   control = seq.play(series) do |note|
+    #     played_notes << { pitch: note, position: seq.position }
+    #   end
+    #
+    #   control.after(2r) { after_executed << seq.position }
+    #
+    #   seq.run
+    #   # Result: played_notes contains all 5 notes
+    #   # Result: after_executed contains position 2 bars after play completes
+    #
+    # @api private
     class PlayControl < EventHandler
+      # @return [Array<Hash>] after callbacks with delays
       attr_reader :do_after
 
+      # Creates play control with optional after callback.
+      #
+      # @param parent [EventHandler] parent event handler
+      # @param after_bars [Rational, nil] delay for after callback
+      # @param after [Proc, nil] after callback block
+      #
+      # @api private
       def initialize(parent, after_bars: nil, after: nil)
         super parent
 
@@ -151,10 +270,34 @@ module Musa::Sequencer
         after(after_bars, &after) if after
       end
 
+      # Pauses play and stores continuation state.
+      #
+      # Sets paused flag. Continuation must be stored separately via
+      # store_continuation.
+      #
+      # @return [void]
+      #
+      # @api private
       def pause
         @paused = true
       end
 
+      # Stores state for continue operation.
+      #
+      # Saves all parameters needed to resume play from current position.
+      # Called automatically by _play when paused.
+      #
+      # @param sequencer [BaseSequencer] sequencer instance
+      # @param serie [Series] series being played
+      # @param neumalang_context [Object, nil] neumalang context
+      # @param mode [Symbol, nil] evaluation mode
+      # @param decoder [Object, nil] decoder
+      # @param play_eval [PlayEval] evaluator
+      # @param mode_args [Hash] mode arguments
+      #
+      # @return [void]
+      #
+      # @api private
       def store_continuation(sequencer:, serie:, neumalang_context:, mode:, decoder:, play_eval:, mode_args:)
         @continuation_sequencer = sequencer
         @continuation_parameters = {
@@ -167,11 +310,29 @@ module Musa::Sequencer
           mode_args: mode_args }
       end
 
+      # Continues from pause.
+      #
+      # Restores paused state and resumes play using stored continuation.
+      #
+      # @return [void]
+      #
+      # @api private
       def continue
         super
         @continuation_sequencer&.continuation_play(@continuation_parameters)
       end
 
+      # Registers callback to execute after play completes.
+      #
+      # @param bars [Numeric, nil] delay in bars after completion (default: 0)
+      # @yield after callback block
+      #
+      # @return [void]
+      #
+      # @example Delayed callback
+      #   control.after(4r) { puts "4 bars after play ends" }
+      #
+      # @api private
       def after(bars = nil, &block)
         bars ||= 0
         @do_after << { bars: bars.rationalize, block: block }

data/lib/musa-dsl/sequencer/base-sequencer-implementation.rb

@@ -5,6 +5,31 @@ module Musa::Sequencer
   using Musa::Extension::InspectNice
 
   class BaseSequencer
+    # Executes all events scheduled at position.
+    #
+    # Processes the event queue at the given position, executing each command's
+    # block in sequence. Handles parent control hierarchy for event handlers,
+    # thread safety with mutexes, and cleanup of empty timeslots.
+    #
+    # ## Execution Flow
+    #
+    # 1. Calls all before_tick callbacks with position
+    # 2. Gets event queue at position from timeslots
+    # 3. For each command in queue:
+    #
+    #    - Shifts command from queue
+    #    - Deletes timeslot if queue becomes empty
+    #    - Pushes parent_control to event handler stack if present
+    #    - Executes command block with parameters (mutex-protected)
+    #    - Pops parent_control from stack
+    #
+    # 4. Yields to other threads
+    #
+    # @param position_to_run [Rational] position to execute events at
+    #
+    # @return [void]
+    #
+    # @api private
     private def _tick(position_to_run)
       @before_tick.each { |block| block.call position_to_run }
       queue = @timeslots[position_to_run]
@@ -33,6 +58,24 @@ module Musa::Sequencer
       Thread.pass
     end
 
+    # Low-level event scheduling without control or quantization.
+    #
+    # Schedules a block at a position with minimal overhead. Used internally
+    # for basic scheduling where control hierarchy and quantization are not
+    # needed. Executes immediately if at current position, schedules for future
+    # if ahead, warns if attempting to schedule in past.
+    #
+    # @param at_position [Rational] position to schedule at
+    # @param force_first [Boolean] if true, insert at front of queue
+    # @yield block to execute at position
+    #
+    # @return [nil]
+    #
+    # @example Force execution order
+    #   _raw_numeric_at(1r) { puts "second" }
+    #   _raw_numeric_at(1r, force_first: true) { puts "first" }
+    #
+    # @api private
     private def _raw_numeric_at(at_position, force_first: nil, &block)
       force_first ||= false
 
@@ -59,6 +102,33 @@ module Musa::Sequencer
       nil
     end
 
+    # Schedules event with control hierarchy and quantization.
+    #
+    # Full-featured event scheduling that:
+    # - Quantizes position to timing grid (tick-based) or passes through (tickless)
+    # - Wraps block in SmartProcBinder for parameter binding and error handling
+    # - Passes control parameter to block if it accepts it
+    # - Adds debug callbacks if logging enabled
+    # - Handles parent_control hierarchy for event handlers
+    # - Thread-safe execution
+    #
+    # ## Position Handling
+    #
+    # - **Current position**: Executes immediately with try_lock
+    # - **Future position**: Adds to timeslots queue
+    # - **Past position**: Warns and ignores
+    # - **nil position** (tickless before first event): Allows scheduling
+    #
+    # @param at_position [Rational] position to schedule at
+    # @param control [EventHandler] parent control for hierarchy
+    # @param debug [Boolean, nil] enable debug callbacks
+    # @yield block to execute at position (may accept control:)
+    #
+    # @return [nil]
+    #
+    # @raise [ArgumentError] if at_position is nil or block not given
+    #
+    # @api private
     private def _numeric_at(at_position, control, debug: nil, &block)
       raise ArgumentError, "'at_position' parameter cannot be nil" if at_position.nil?
       raise ArgumentError, 'Yield block is mandatory' unless block
@@ -101,6 +171,36 @@ module Musa::Sequencer
       nil
     end
 
+    # Recursively schedules events from a series of positions.
+    #
+    # Implements series-based scheduling by:
+    # 1. Getting next position from series
+    # 2. Scheduling user block at that position
+    # 3. Scheduling recursive call to continue series
+    #
+    # This enables scheduling blocks at positions generated by a Musa::Series,
+    # creating patterns like "every 4 beats" or "at positions from fibonacci
+    # sequence". Recursion continues until series is exhausted.
+    #
+    # ## Recursive Structure
+    #
+    # Each iteration schedules two events at the same position:
+    # - User's block (with debug enabled)
+    # - Recursive call to _serie_at (debug disabled to avoid duplication)
+    #
+    # @param position_or_serie [Series] series yielding positions
+    # @param control [EventHandler] parent control for hierarchy
+    # @param debug [Boolean, nil] enable debug callbacks
+    # @yield block to execute at each position from series
+    #
+    # @return [nil]
+    #
+    # @example Series scheduling
+    #   positions = Musa::Series.from_array([1r, 1.5r, 2r, 3r])
+    #   _serie_at(positions, control) { puts "event" }
+    #   # Schedules events at 1r, 1.5r, 2r, 3r
+    #
+    # @api private
     private def _serie_at(position_or_serie, control, debug: nil, &block)
       bar_position = position_or_serie.next_value
 
@@ -117,6 +217,17 @@ module Musa::Sequencer
       nil
     end
 
+    # Handles errors during event execution.
+    #
+    # Logs error message and full backtrace, then calls all registered
+    # on_error callbacks with the exception. Used by SmartProcBinder and
+    # direct rescue blocks to centralize error handling.
+    #
+    # @param e [Exception] exception that occurred
+    #
+    # @return [void]
+    #
+    # @api private
     def _rescue_error(e)
       @logger.error('BaseSequencer') { e.to_s }
       @logger.error('BaseSequencer') { e.full_message(highlight: true, order: :top) }
@@ -126,11 +237,66 @@ module Musa::Sequencer
       end
     end
 
+    # 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.
+    #
+    # @example Basic event handling
+    #   control = EventHandler.new
+    #   control.on(:finished) { puts "Done!" }
+    #   control.launch(:finished)  # Prints "Done!"
+    #
+    # @example 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)
+    #
+    # @example One-time handler
+    #   control.on(:init, only_once: true) { puts "Initialize" }
+    #   control.launch(:init)  # Prints "Initialize"
+    #   control.launch(:init)  # Does nothing (handler removed)
+    #
+    # @api private
     class EventHandler
+      # Parameters for continue operation (not fully implemented).
+      #
+      # @return [Hash, nil] continue parameters
       attr_accessor :continue_parameters
 
       @@counter = 0
 
+      # Creates event handler with optional parent.
+      #
+      # @param parent [EventHandler, nil] parent for event delegation
+      #
+      # @api private
       def initialize(parent = nil)
         @id = (@@counter += 1)
 
@@ -140,26 +306,74 @@ module Musa::Sequencer
         @stop = false
       end
 
+      # Stops this event handler.
+      #
+      # Marks handler as stopped, preventing future event execution. Used by
+      # control objects to halt play/every/move operations.
+      #
+      # @return [void]
+      #
+      # @api private
       def stop
         @stop = true
       end
 
+      # Checks if handler is stopped.
+      #
+      # @return [Boolean] true if stopped
+      #
+      # @api private
       def stopped?
         @stop
       end
 
+      # Pauses handler (not implemented).
+      #
+      # @raise [NotImplementedError] pause not yet implemented
+      #
+      # @api private
       def pause
         raise NotImplementedError
       end
 
+      # Continues from pause (not fully implemented).
+      #
+      # @return [void]
+      #
+      # @api private
       def continue
         @paused = false
       end
 
+      # Checks if handler is paused.
+      #
+      # @return [Boolean] true if paused
+      #
+      # @api private
       def paused?
         @paused
       end
 
+      # 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.
+      #
+      # @param event [Symbol] event name to handle
+      # @param name [Symbol, nil] optional handler name (for removal)
+      # @param only_once [Boolean] remove after first call (default: false)
+      # @yield handler block with flexible parameters
+      #
+      # @return [void]
+      #
+      # @example Register handler
+      #   control.on(:finished) { puts "Done" }
+      #   control.on(:progress, name: :logger) { |pct| puts "#{pct}%" }
+      #
+      # @api private
       def on(event, name: nil, only_once: nil, &block)
         only_once ||= false
 
@@ -169,10 +383,47 @@ module Musa::Sequencer
         @handlers[event][name] = { block: Musa::Extension::SmartProcBinder::SmartProcBinder.new(block), only_once: only_once }
       end
 
+      # 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).
+      #
+      # @param event [Symbol] event name to launch
+      # @param value_parameters [Array] positional arguments for handlers
+      # @param key_parameters [Hash] keyword arguments for handlers
+      # @param proc_parameter [Proc, nil] block parameter for handlers
+      #
+      # @return [void]
+      #
+      # @example Launch with parameters
+      #   control.on(:progress) { |percent| puts "#{percent}%" }
+      #   control.launch(:progress, 50)  # Prints "50%"
+      #
+      # @example Launch with keyword parameters
+      #   control.on(:update) { |position:, value:| puts "#{position}: #{value}" }
+      #   control.launch(:update, position: 1r, value: 60)
+      #
+      # @api private
       def launch(event, *value_parameters, **key_parameters, &proc_parameter)
         _launch event, value_parameters, key_parameters, proc_parameter
       end
 
+      # 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.
+      #
+      # @param event [Symbol] event name
+      # @param value_parameters [Array] positional args
+      # @param key_parameters [Hash] keyword args
+      # @param proc_parameter [Proc, nil] block arg
+      #
+      # @return [void]
+      #
+      # @api private
       def _launch(event, value_parameters = nil, key_parameters = nil, proc_parameter = nil)
         value_parameters ||= []
         key_parameters ||= {}
@@ -189,10 +440,22 @@ module Musa::Sequencer
         @parent._launch event, value_parameters, key_parameters, proc_parameter if @parent && !processed
       end
 
+      # Returns string representation.
+      #
+      # @return [String] "EventHandler <id>"
+      #
+      # @api private
       def inspect
         "EventHandler #{id}"
       end
 
+      # Returns hierarchical identifier.
+      #
+      # Builds identifier showing parent chain and instance ID.
+      #
+      # @return [String] hierarchical ID like "EventHandler-1.PlayControl-5"
+      #
+      # @api private
       def id
         if @parent
           "#{@parent.id}.#{self.class.name.split('::').last}-#{@id}"