musa-dsl 0.30.2 → 0.40.0

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

@@ -4,9 +4,62 @@ require_relative '../core-ext/with'
 
 module Musa
   module Sequencer
+    # High-level DSL wrapper for BaseSequencer.
+    #
+    # Provides user-friendly interface with block context management via
+    # `with` method. Wraps BaseSequencer methods to automatically evaluate
+    # blocks in DSL context, enabling clean musical composition code.
+    #
+    # ## DSL Context
+    #
+    # Blocks passed to scheduling methods (now, at, wait, play, every, move)
+    # are evaluated in DSL context via `with`, providing access to sequencer
+    # methods and allowing for cleaner composition syntax.
+    #
+    # ## Delegation
+    #
+    # Delegates most methods to either BaseSequencer or DSLContext:
+    #
+    # - Timing: beats_per_bar, ticks_per_beat, position, tick, reset
+    # - Scheduling: now, at, wait, play, play_timed, every, move
+    # - Events: launch, on
+    # - Inspection: size, empty?, everying, playing, moving
+    #
+    # ## Musical Applications
+    #
+    # Provides composer-friendly API for:
+    #
+    # - Musical composition scripts
+    # - Interactive sequencing
+    # - Live coding
+    # - Algorithmic composition
+    #
+    # @example Basic DSL usage
+    #   sequencer = Musa::Sequencer::Sequencer.new(4, 96) do
+    #     at(1r) { puts "Bar 1" }
+    #     at(2r) { puts "Bar 2" }
+    #
+    #     every(1r, duration: 4r) do
+    #       puts "Every beat"
+    #     end
+    #   end
+    #
+    #   sequencer.run
+    #
+    # @example DSL context access
+    #   sequencer = Musa::Sequencer::Sequencer.new(4, 96) do
+    #     at(1r) do
+    #       puts "Position: #{position}"  # DSL context method
+    #
+    #       wait(1r) { puts "One bar later" }  # Nested scheduling
+    #     end
+    #   end
+    #
+    # @api public
     class Sequencer
       extend Forwardable
 
+      # Delegates to BaseSequencer
       def_delegators :@sequencer,
                      :beats_per_bar, :ticks_per_beat, :ticks_per_bar, :tick_duration,
                      :offset,
@@ -18,12 +71,38 @@ module Musa
                      :position=,
                      :event_handler
 
+      # Delegates to DSLContext
       def_delegators :@dsl, :position, :quantize_position, :logger, :debug
       def_delegators :@dsl, :now, :at, :wait, :play, :play_timed, :every, :move
       def_delegators :@dsl, :everying, :playing, :moving
       def_delegators :@dsl, :launch, :on
       def_delegators :@dsl, :run
 
+      # Creates sequencer with optional initialization block.
+      #
+      # @param beats_per_bar [Integer, nil] beats per bar (tick-based mode)
+      # @param ticks_per_beat [Integer, nil] ticks per beat (tick-based mode)
+      # @param offset [Rational, nil] starting position offset
+      # @param sequencer [BaseSequencer, nil] use existing sequencer
+      # @param logger [Logger, nil] logger instance
+      # @param do_log [Boolean, nil] enable logging
+      # @param do_error_log [Boolean, nil] enable error logging
+      # @param log_position_format [Symbol, nil] position format for logs
+      # @param dsl_context_class [Class, nil] custom DSL context class
+      # @param keep_block_context [Boolean, nil] preserve block's original binding
+      # @yield initialization block evaluated in DSL context
+      #
+      # @example Tick-based sequencer
+      #   seq = Sequencer.new(4, 96) do
+      #     at(1r) { puts "Start" }
+      #   end
+      #
+      # @example Tickless sequencer
+      #   seq = Sequencer.new do
+      #     at(1r) { puts "Start" }
+      #   end
+      #
+      # @api public
       def initialize(beats_per_bar = nil,
                      ticks_per_beat = nil,
                      offset: nil,
@@ -49,16 +128,89 @@ module Musa
         @dsl.with &block if block_given?
       end
 
+      # Evaluates block in DSL context.
+      #
+      # Provides `with` method for evaluating blocks with DSL context access.
+      # The block is executed in the DSL context, giving it direct access to
+      # sequencer methods like at, wait, play, every, move without needing to
+      # reference the sequencer object.
+      #
+      # @param value_parameters [Array] positional parameters
+      # @param key_parameters [Hash] keyword parameters
+      # @yield block to evaluate in DSL context
+      #
+      # @return [Object] block return value
+      #
+      # @example Evaluating blocks in DSL context
+      #   seq = Musa::Sequencer::Sequencer.new(4, 96)
+      #
+      #   executed = []
+      #
+      #   # Use 'with' to evaluate block in DSL context
+      #   seq.with do
+      #     # Inside this block, we have direct access to DSL methods
+      #     at(1) { executed << "bar 1" }
+      #     at(2) { executed << "bar 2" }
+      #
+      #     every(1, duration: 4) do
+      #       executed << "beat at #{position}"
+      #     end
+      #   end
+      #
+      #   seq.run
+      #
+      #   # executed contains ["bar 1", "beat at 1", "bar 2", "beat at 2", ...]
+      #
+      # @example Passing parameters to with block
+      #   seq = Musa::Sequencer::Sequencer.new(4, 96)
+      #
+      #   notes = []
+      #
+      #   seq.with(60, 64, 67) do |c, e, g|
+      #     at(1) { notes << c }  # Uses parameter c = 60
+      #     at(2) { notes << e }  # Uses parameter e = 64
+      #     at(3) { notes << g }  # Uses parameter g = 67
+      #   end
+      #
+      #   seq.run
+      #
+      #   # notes contains [60, 64, 67]
+      #
+      # @example Comparison: with DSL context vs external context
+      #   seq = Musa::Sequencer::Sequencer.new(4, 96)
+      #
+      #   # Without 'with': need to reference seq explicitly
+      #   seq.at(1) { seq.at(2) { puts "nested" } }
+      #
+      #   # With 'with': DSL methods available directly
+      #   seq.with do
+      #     at(1) { at(2) { puts "nested" } }  # Cleaner syntax
+      #   end
+      #
+      # @api public
       def with(*value_parameters, **key_parameters, &block)
         @dsl.with(*value_parameters, **key_parameters, &block)
       end
 
+      # DSL context providing block evaluation with sequencer method access.
+      #
+      # Wraps BaseSequencer methods to evaluate user blocks in controlled
+      # context via `with`. Enables clean DSL syntax by providing direct
+      # access to sequencer methods within block scopes.
+      #
+      # ## Block Context Modes
+      #
+      # - **keep_block_context: false** (default): Evaluate blocks in DSL context
+      # - **keep_block_context: true**: Preserve block's original binding
+      #
       class DSLContext
         extend Forwardable
         include Musa::Extension::With
 
+        # @return [BaseSequencer] underlying sequencer
         attr_reader :sequencer
 
+        # Delegates to BaseSequencer
         def_delegators :@sequencer,
                        :launch, :on,
                        :position, :quantize_position,
@@ -67,11 +219,20 @@ module Musa
                        :ticks_per_bar, :logger, :debug, :inspect,
                        :run
 
+        # @api private
         def initialize(sequencer, keep_block_context:)
           @sequencer = sequencer
           @keep_block_context_on_with = keep_block_context
         end
 
+        # Schedules block at current position via DSL context.
+        #
+        # Wraps BaseSequencer#now, evaluating block in DSL context.
+        #
+        # @param value_parameters [Array] parameters to pass to block
+        # @param key_parameters [Hash] keyword parameters
+        # @yield block to execute at current position
+        # @return [void]
         def now(*value_parameters, **key_parameters, &block)
           block ||= proc {}
 
@@ -80,6 +241,14 @@ module Musa
           end
         end
 
+        # Schedules block at absolute position via DSL context.
+        #
+        # Wraps BaseSequencer#at, evaluating block in DSL context.
+        #
+        # @param value_parameters [Array] parameters (first is position)
+        # @param key_parameters [Hash] keyword parameters
+        # @yield block to execute at position
+        # @return [void]
         def at(*value_parameters, **key_parameters, &block)
           block ||= proc {}
 
@@ -88,6 +257,14 @@ module Musa
           end
         end
 
+        # Schedules block after wait duration via DSL context.
+        #
+        # Wraps BaseSequencer#wait, evaluating block in DSL context.
+        #
+        # @param value_parameters [Array] parameters (first is duration)
+        # @param key_parameters [Hash] keyword parameters
+        # @yield block to execute after wait
+        # @return [void]
         def wait(*value_parameters, **key_parameters, &block)
           block ||= proc {}
           @sequencer.wait *value_parameters, **key_parameters do |*values, **key_values|
@@ -95,6 +272,14 @@ module Musa
           end
         end
 
+        # Plays series via DSL context.
+        #
+        # Wraps BaseSequencer#play, evaluating block in DSL context.
+        #
+        # @param value_parameters [Array] parameters (series, etc.)
+        # @param key_parameters [Hash] keyword parameters
+        # @yield block to execute for each element
+        # @return [PlayControl] control object
         def play(*value_parameters, **key_parameters, &block)
           block ||= proc {}
 
@@ -103,6 +288,14 @@ module Musa
           end
         end
 
+        # Plays timed series via DSL context.
+        #
+        # Wraps BaseSequencer#play_timed, evaluating block in DSL context.
+        #
+        # @param value_parameters [Array] parameters (timed series, etc.)
+        # @param key_parameters [Hash] keyword parameters
+        # @yield block to execute for each element
+        # @return [PlayTimedControl] control object
         def play_timed(*value_parameters, **key_parameters, &block)
           block ||= proc {}
 
@@ -111,6 +304,15 @@ module Musa
           end
         end
 
+        # Repeats block at intervals via DSL context.
+        #
+        # Wraps BaseSequencer#every, evaluating block in DSL context.
+        # Uses SmartProcBinder to apply parameters before with.
+        #
+        # @param value_parameters [Array] parameters (interval, etc.)
+        # @param key_parameters [Hash] keyword parameters
+        # @yield block to execute each iteration
+        # @return [EveryControl] control object
         def every(*value_parameters, **key_parameters, &block)
           block ||= proc {}
 
@@ -120,6 +322,14 @@ module Musa
           end
         end
 
+        # Animates values over time via DSL context.
+        #
+        # Wraps BaseSequencer#move, evaluating block in DSL context.
+        #
+        # @param value_parameters [Array] parameters (from, to, etc.)
+        # @param key_parameters [Hash] keyword parameters
+        # @yield block to execute each iteration with current value
+        # @return [MoveControl] control object
         def move(*value_parameters, **key_parameters, &block)
           block ||= proc {}
 

data/lib/musa-dsl/sequencer/timeslots.rb

@@ -3,24 +3,101 @@ require 'set'
 module Musa
   module Sequencer
     class BaseSequencer
+      # Sorted time-indexed event storage for sequencer.
+      #
+      # Timeslots extends Hash to maintain scheduled events indexed by time,
+      # with efficient sorted access for sequential playback. Each timeslot
+      # (key) maps to an array of events scheduled at that time.
+      #
+      # ## Implementation
+      #
+      # Uses a SortedSet to track keys in temporal order, enabling fast
+      # lookup of next scheduled event without full hash traversal.
+      #
+      # ## Usage
+      #
+      # - **Store**: `timeslots[time] = events` schedules events at time
+      # - **Retrieve**: `timeslots[time]` gets events at specific time
+      # - **Next**: `first_after(pos)` finds next scheduled time >= position
+      # - **Delete**: `delete(time)` removes timeslot and updates sort index
+      #
+      # ## Time Representation
+      #
+      # Times are Rational numbers representing musical beats/ticks.
+      # Granularity depends on sequencer configuration (tick-based or tickless).
+      #
+      # ## Internal Usage Examples
+      #
+      # Note: These are illustrative examples for internal implementation.
+      # Timeslots is private and cannot be instantiated from public API.
+      #
+      #   # Within BaseSequencer context:
+      #   timeslots = Timeslots.new
+      #   timeslots[0r] = [event1, event2]    # Events at time 0
+      #   timeslots[1/2r] = [event3]          # Event at beat 0.5
+      #   timeslots[1r] = [event4, event5]    # Events at beat 1
+      #
+      #   next_time = timeslots.first_after(0.5)  # => 1r
+      #   events = timeslots[next_time]           # => [event4, event5]
+      #
+      # @api private
       class Timeslots < Hash
 
+        # Creates empty timeslots storage.
+        #
+        # @param several_variants [Array] optional Hash initialization parameters
+        # @api private
         def initialize(*several_variants)
           super
           @sorted_keys = SortedSet.new
         end
 
+        # Stores events at time, maintaining sort index.
+        #
+        # @param key [Rational] time position
+        # @param value [Array, Object] events at this time
+        #
+        # @return [Array, Object] stored value
+        # @api private
         def []=(key, value)
           super
           @sorted_keys << key
         end
 
+        # Removes timeslot, updating sort index.
+        #
+        # @param key [Rational] time position to remove
+        #
+        # @return [Array, Object, nil] removed value
+        # @api private
         def delete(key)
           super
           @sorted_keys.delete key
 
         end
 
+        # Finds first scheduled time at or after position.
+        #
+        # Used by sequencer to find next event to execute during playback.
+        #
+        # Internal behavior (illustrative, not executable from public API):
+        #
+        #   timeslots[1r] = [:event_a]
+        #   timeslots[2r] = [:event_b]
+        #   timeslots[3r] = [:event_c]
+        #
+        #   timeslots.first_after(nil)   # => 1r
+        #   timeslots.first_after(0r)    # => 1r
+        #   timeslots.first_after(1r)    # => 1r
+        #   timeslots.first_after(1.5r)  # => 2r
+        #   timeslots.first_after(3r)    # => 3r
+        #   timeslots.first_after(4r)    # => nil
+        #
+        # @param position [Rational, nil] search position (nil for first overall)
+        #
+        # @return [Rational, nil] next scheduled time, or nil if none
+        #
+        # @api private
         def first_after(position)
           if position.nil?
             @sorted_keys.first
@@ -29,6 +106,8 @@ module Musa
           end
         end
       end
+
+      private_constant :Timeslots
     end
   end
 end

data/lib/musa-dsl/series/array-to-serie.rb

@@ -1,8 +1,36 @@
 require_relative '../series'
 
-# TODO: esto sería un refinement, no?
 
 class Array
+  # TODO: esto sería un refinement, no?
+  
+  # Converts array to Serie.
+  #
+  # Three conversion modes:
+  #
+  # - **Basic**: Direct conversion to serie
+  # - **of_series**: Each element of the array becomes a new serie (for array of arrays)
+  # - **recursive**: Recursive conversion of nested arrays
+  #
+  # @param of_series [Boolean, nil] convert each element to a serie (default: false)
+  # @param recursive [Boolean, nil] recursively convert nested arrays (default: false)
+  #
+  # @return [Serie] converted serie
+  #
+  # @raise [ArgumentError] if both of_series and recursive are true
+  #
+  # @example Basic conversion
+  #   [60, 64, 67].to_serie.i.to_a  # => [60, 64, 67]
+  #
+  # @example Serie of series
+  #   [[1, 2], [3, 4]].to_serie(of_series: true)
+  #   # Each [1,2], [3,4] becomes S(1,2), S(3,4)
+  #
+  # @example Recursive conversion
+  #   [[1, [2, 3]], [4, 5]].to_serie(recursive: true)
+  #   # Nested arrays become nested series
+  #
+  # @api public
   def to_serie(of_series: nil, recursive: nil)
     of_series ||= false
     recursive ||= false
@@ -18,5 +46,13 @@ class Array
     end
   end
 
+  # Short alias for {#to_serie}.
+  #
+  # @return [Serie] converted serie
+  #
+  # @example Short form
+  #   [1, 2, 3].s  # => S(1, 2, 3)
+  #
+  # @api public
   alias_method :s, :to_serie
 end