musa-dsl 0.30.2 → 0.40.0

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

@@ -1,5 +1,26 @@
 module Musa::Sequencer
   class BaseSequencer
+    # Implements recurring event execution at regular intervals.
+    #
+    # Recursively schedules block execution at interval-based positions.
+    # Handles stopping conditions, callbacks, and precise timing without drift.
+    #
+    # ## Timing Precision
+    #
+    # Next iteration is always scheduled at:
+    #   start_position + execution_counter * interval
+    #
+    # This ensures iterations align to exact positions regardless of execution
+    # time or accumulated delays.
+    #
+    # @param interval [Rational, nil] bars between iterations (nil = one-shot)
+    # @param control [EveryControl] control object managing lifecycle
+    # @param block_procedure_binder [SmartProcBinder, nil] cached binder (for recursion)
+    # @yield block to execute each iteration (receives control:)
+    #
+    # @return [nil]
+    #
+    # @api private
     private def _every(interval, control, block_procedure_binder: nil, &block)
       block ||= proc {}
 
@@ -41,12 +62,65 @@ module Musa::Sequencer
       nil
     end
 
+    # Control object for every loops.
+    #
+    # Manages lifecycle of every loop including stopping conditions, callbacks,
+    # and execution tracking. Extends EventHandler to support event-based
+    # control (e.g., launching custom events).
+    #
+    # ## Stopping Conditions
+    #
+    # - **duration**: Maximum loop duration in bars
+    # - **till**: Absolute position to stop at
+    # - **condition**: Proc returning true to continue, false to stop
+    # - **manual stop**: Call `control.stop` to halt loop
+    #
+    # ## Callbacks
+    #
+    # - **on_stop**: Called when loop stops (any reason)
+    # - **after**: Called after loop stops, with optional delay in bars
+    #
+    # ## Execution Tracking
+    #
+    # - **_start_position**: Position when loop started
+    # - **_execution_counter**: Number of iterations executed
+    #
+    # @example Dynamic control
+    #   control = sequencer.every(1r) { |control| puts control._execution_counter }
+    #   control.duration(4r)  # Stop after 4 bars
+    #   control.on_stop { puts "Finished!" }
+    #   control.after(2r) { puts "2 bars after finish" }
+    #
     class EveryControl < EventHandler
-      attr_reader :duration_value, :till_value, :condition_block, :do_on_stop, :do_after
-
+      # @return [Rational, nil] maximum duration in bars
+      attr_reader :duration_value
+      # @return [Rational, nil] absolute position to stop at
+      attr_reader :till_value
+      # @return [Proc, nil] condition block (returns true to continue)
+      attr_reader :condition_block
+      # @return [Array<Proc>] callbacks when loop stops
+      attr_reader :do_on_stop
+      # @return [Array<Hash>] after callbacks with delays
+      attr_reader :do_after
+
+      # @return [Rational] position when loop started
+      # @api private
       attr_accessor :_start_position
+      # @return [Integer] number of iterations executed
+      # @api private
       attr_accessor :_execution_counter
 
+      # Creates every loop control.
+      #
+      # @param parent [EventHandler] parent event handler
+      # @param duration [Rational, nil] maximum duration in bars
+      # @param till [Rational, nil] absolute stop position
+      # @param condition [Proc, nil] continuation condition
+      # @param on_stop [Proc, nil] stop callback
+      # @param after_bars [Rational, nil] delay for after callback
+      # @param after [Proc, nil] after callback block
+      #
+      # @api private
       def initialize(parent, duration: nil, till: nil, condition: nil, on_stop: nil, after_bars: nil, after: nil)
         super parent
 
@@ -62,22 +136,64 @@ module Musa::Sequencer
         self.after after_bars, &after if after
       end
 
+      # Sets maximum loop duration.
+      #
+      # @param value [Numeric] duration in bars
+      #
+      # @return [void]
+      #
+      # @api private
       def duration(value)
         @duration_value = value.rationalize
       end
 
+      # Sets absolute stop position.
+      #
+      # @param value [Numeric] position to stop at
+      #
+      # @return [void]
+      #
+      # @api private
       def till(value)
         @till_value = value.rationalize
       end
 
+      # Sets continuation condition.
+      #
+      # @yield condition block (returns true to continue, false to stop)
+      #
+      # @return [void]
+      #
+      # @api private
       def condition(&block)
         @condition_block = block
       end
 
+      # Registers callback for when loop stops.
+      #
+      # @yield stop callback block
+      #
+      # @return [void]
+      #
+      # @api private
       def on_stop(&block)
         @do_on_stop << block
       end
 
+      # Registers callback to execute after loop stops.
+      #
+      # @param bars [Numeric, nil] delay in bars after stop (default: 0)
+      # @yield after callback block
+      #
+      # @return [void]
+      #
+      # @example Immediate after callback
+      #   control.after { puts "Done" }
+      #
+      # @example Delayed after callback
+      #   control.after(2r) { puts "2 bars after stop" }
+      #
+      # @api private
       def after(bars = nil, &block)
         bars ||= 0
         @do_after << { bars: bars.rationalize, block: block }

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

@@ -6,6 +6,50 @@ module Musa::Sequencer
     using Musa::Extension::Arrayfy
     using Musa::Extension::InspectNice
 
+    # Animates value(s) over time with flexible parameter control.
+    #
+    # Implements smooth value transitions supporting single values, arrays,
+    # and hashes. Handles complex parameter calculation to derive missing
+    # timing or step information. Uses _every for iteration scheduling.
+    #
+    # ## Yield Block Parameters
+    #
+    # Block receives current value(s), next value(s), and metadata:
+    # - In single mode: `|value, next_value, control:, duration:, ...|`
+    # - In array mode: `|values, next_values, control:, duration:, ...|`
+    # - In hash mode: `|values_hash, next_values_hash, control:, ...|`
+    #
+    # Optional parameters: control, duration, quantized_duration,
+    # position_jitter, duration_jitter, started_ago, right_open
+    #
+    # ## Implementation Details
+    #
+    # 1. Validates and normalizes parameters
+    # 2. Calculates missing parameters (step or every) from others
+    # 3. Creates MoveControl wrapping EveryControl
+    # 4. Uses _every with common interval (GCD of all intervals)
+    # 5. Calculates values, applies function, checks stop conditions
+    # 6. Yields to user block with values and metadata
+    #
+    # @param every [Rational, Array, Hash, nil] interval(s) between iterations
+    # @param from [Numeric, Array, Hash] starting value(s)
+    # @param to [Numeric, Array, Hash, nil] target value(s)
+    # @param step [Numeric, Array, Hash, nil] increment(s) per iteration
+    # @param duration [Rational, nil] total duration in bars
+    # @param till [Rational, nil] absolute end position
+    # @param function [Proc, Array<Proc>, nil] interpolation function(s)
+    # @param right_open [Boolean, Array, Hash, nil] exclude final value
+    # @param on_stop [Proc, nil] callback when movement stops
+    # @param after_bars [Rational, nil] delay for after callback
+    # @param after [Proc, nil] callback after movement completes
+    # @yield block to execute at each iteration with current/next values
+    #
+    # @return [MoveControl] control object for managing movement
+    #
+    # @raise [ArgumentError] if incompatible parameters used together
+    # @raise [ArgumentError] if insufficient parameters to calculate movement
+    #
+    # @api private
     private def _move(every: nil,
                       from:, to: nil,
                       step: nil,
@@ -356,6 +400,18 @@ module Musa::Sequencer
       control
     end
 
+    # Calculates time elapsed since each value last changed.
+    #
+    # Returns array where each element is position delta since that value
+    # was last updated, or nil if value is being updated this iteration.
+    #
+    # @param last_positions [Array<Rational, nil>] positions of last updates
+    # @param position [Rational] current position
+    # @param affected_indexes [Array<Integer>] indexes being updated now
+    #
+    # @return [Array<Rational, nil>] deltas or nils
+    #
+    # @api private
     private def _started_ago(last_positions, position, affected_indexes)
       Array.new(last_positions.size).tap do |a|
         last_positions.each_index do |i|
@@ -366,6 +422,16 @@ module Musa::Sequencer
       end
     end
 
+    # Calculates duration for each value based on interval grouping.
+    #
+    # Returns array of durations, one per value, based on its interval group.
+    #
+    # @param every_groups [Hash{Rational => Array<Integer>}] interval groups
+    # @param largest_duration [Rational] fallback duration
+    #
+    # @return [Array<Rational>] durations per value
+    #
+    # @api private
     private def _durations(every_groups, largest_duration)
       [].tap do |a|
         if every_groups.any?
@@ -380,10 +446,28 @@ module Musa::Sequencer
       end
     end
 
+    # Reconstructs hash from separate key and value arrays.
+    #
+    # @param keys [Array<Symbol>] hash keys
+    # @param values [Array] hash values
+    #
+    # @return [Hash] reconstructed hash
+    #
+    # @api private
     private def _hash_from_keys_and_values(keys, values)
       {}.tap { |h| keys.each_index { |i| h[keys[i]] = values[i] } }
     end
 
+    # Calculates greatest common divisor of intervals for scheduling.
+    #
+    # Computes GCD of all intervals to find common iteration frequency
+    # that hits all interval positions. Uses rational arithmetic.
+    #
+    # @param intervals [Array<Rational>] intervals to find GCD of
+    #
+    # @return [Rational, nil] common interval or nil if empty
+    #
+    # @api private
     private def _common_interval(intervals)
       intervals = intervals.compact
       return nil if intervals.empty?
@@ -397,9 +481,48 @@ module Musa::Sequencer
       Rational(gcd_numerators, lcm_denominators)
     end
 
+    # Control object for move operations.
+    #
+    # Wraps EveryControl to provide move-specific lifecycle management.
+    # Delegates timing control to EveryControl while adding move-specific
+    # callbacks and state.
+    #
+    # ## Delegation Pattern
+    #
+    # MoveControl delegates to EveryControl for:
+    # - Duration and till timing control
+    # - Iteration scheduling
+    # - Stop conditions
+    #
+    # Adds move-specific features:
+    # - on_stop callbacks when movement completes
+    # - after callbacks with delays
+    # - Stopped state synchronization
+    #
+    # @example Basic move control
+    #   control = sequencer.move(from: 0, to: 100, duration: 4r, every: 1/4r) { |v| }
+    #   control.on_stop { puts "Movement finished!" }
+    #   control.after(2r) { puts "2 bars after finish" }
+    #   control.stop  # Manually halt movement
+    #
     class MoveControl < EventHandler
-      attr_reader :every_control, :do_on_stop, :do_after
-
+      # @return [EveryControl] underlying every control for timing
+      attr_reader :every_control
+      # @return [Array<Proc>] stop callbacks
+      attr_reader :do_on_stop
+      # @return [Array<Hash>] after callbacks with delays
+      attr_reader :do_after
+
+      # Creates move control with timing parameters.
+      #
+      # @param parent [EventHandler] parent event handler
+      # @param duration [Rational, nil] maximum duration in bars
+      # @param till [Rational, nil] absolute stop position
+      # @param on_stop [Proc, nil] stop callback
+      # @param after_bars [Rational, nil] delay for after callback
+      # @param after [Proc, nil] after callback block
+      #
+      # @api private
       def initialize(parent, duration: nil, till: nil, on_stop: nil, after_bars: nil, after: nil)
         super parent
 
@@ -417,19 +540,43 @@ module Musa::Sequencer
         end
       end
 
+      # Registers callback for when movement stops.
+      #
+      # @yield stop callback block
+      #
+      # @return [void]
+      #
       def on_stop(&block)
         @do_on_stop << block
       end
 
+      # Registers callback to execute after movement stops.
+      #
+      # @param bars [Numeric, nil] delay in bars after stop (default: 0)
+      # @yield after callback block
+      #
+      # @return [void]
+      #
+      # @example Delayed callback
+      #   control.after(2r) { puts "2 bars after movement ends" }
+      #
       def after(bars = nil, &block)
         bars ||= 0
         @do_after << { bars: bars.rationalize, block: block }
       end
 
+      # Stops movement.
+      #
+      # @return [void]
+      #
       def stop
         @every_control.stop
       end
 
+      # Checks if movement is stopped.
+      #
+      # @return [Boolean] true if stopped
+      #
       def stopped?
         @stop
       end