musa-dsl 0.30.2 → 0.41.0

data/lib/musa-dsl/series/proxy-serie.rb

@@ -1,11 +1,78 @@
+#
+# @api public
 require_relative 'base-series'
 
 module Musa
   module Series::Constructors
+    # Creates a proxy serie with optional initial source.
+    #
+    # Proxy series enable late binding - creating a serie placeholder that will
+    # be resolved later. Useful for:
+    #
+    # ## Use Cases
+    #
+    # - **Forward references**: Reference series before definition
+    # - **Circular structures**: Self-referential or mutually referential series
+    # - **Dependency injection**: Define structure, inject source later
+    # - **Dynamic routing**: Change source serie at runtime
+    #
+    # ## Method Delegation
+    #
+    # Proxy delegates all methods to underlying source via method_missing,
+    # making it transparent proxy for most operations.
+    #
+    # ## State Resolution
+    #
+    # Proxy starts in :undefined state, becomes :prototype/:instance when
+    # source is set and resolved.
+    #
+    # @param serie [Serie, nil] initial source serie (default: nil)
+    #
+    # @return [ProxySerie] proxy serie
+    #
+    # @example Forward reference
+    #   proxy = PROXY()
+    #   proxy.undefined?  # => true
+    #
+    #   # Define later
+    #   proxy.proxy_source = S(1, 2, 3)
+    #   proxy.prototype?  # => true
+    #
+    # @example Circular structure
+    #   loop_serie = PROXY()
+    #   sequence = S(1, 2, 3).after(loop_serie)
+    #   loop_serie.proxy_source = sequence
+    #   # Creates infinite loop: 1, 2, 3, 1, 2, 3, ...
+    #
+    # @example With initial source
+    #   proxy = PROXY(S(1, 2, 3))
+    #
+    # @api public
     def PROXY(serie = nil)
       ProxySerie.new(serie)
     end
 
+    # Proxy/wrapper serie that delegates to another serie.
+    #
+    # Acts as transparent proxy forwarding all method calls to the wrapped
+    # serie. Useful for lazy evaluation, conditional serie switching, or
+    # adding indirection layer.
+    #
+    # The proxy can be reassigned to a different serie dynamically by
+    # changing the `proxy_source` attribute.
+    #
+    # @example Basic proxy
+    #   original = FromArray.new([1, 2, 3])
+    #   proxy = ProxySerie.new(original)
+    #   proxy.next_value  # => 1 (delegates to original)
+    #
+    # @example Dynamic serie switching
+    #   proxy = ProxySerie.new(serie_a)
+    #   proxy.next_value  # Uses serie_a
+    #   proxy.proxy_source = serie_b
+    #   proxy.next_value  # Now uses serie_b
+    #
+    # @api private
     class ProxySerie
       include Series::Serie.with(source: true, source_as: :proxy_source)
 

data/lib/musa-dsl/series/quantizer-serie.rb

@@ -3,16 +3,54 @@ require_relative '../core-ext/inspect-nice'
 
 require_relative 'base-series'
 
-# TODO remove debugging puts, intermediate hash comments on :info and InspectNice
 module Musa
   module Series::Operations
+    # Quantizes time-value serie to discrete steps.
+    #
+    # ## Quantization Modes
+    #
+    # - **Raw**: Rounds values to nearest step, interpolates between points
+    # - **Predictive**: Predicts crossings of quantization boundaries
+    #
+    # ## Applications
+    #
+    # - Quantize MIDI controller data to discrete values
+    # - Convert continuous pitch bends to semitones
+    # - Snap timing to grid
+    # - Generate stepped automation curves
+    # - Convert analog input to digital steps
+    #
+    # @param reference [Numeric, nil] quantization reference (default: 0)
+    # @param step [Numeric, nil] step size (default: 1)
+    # @param value_attribute [Symbol, nil] attribute to quantize (default: :value)
+    # @param stops [Boolean, nil] include stop points (default: false)
+    # @param predictive [Boolean, nil] use predictive mode (default: false)
+    # @param left_open [Boolean, nil] left boundary open (raw mode)
+    # @param right_open [Boolean, nil] right boundary open (raw mode)
+    #
+    # @return [RawQuantizer, PredictiveQuantizer] quantized serie
+    #
+    # @example Basic quantization
+    #   # Quantize to semitones (12 steps per octave)
+    #   pitch_bend = S({time: 0r, value: 60.3}, {time: 1r, value: 61.8})
+    #   quantized = pitch_bend.quantize(step: 1)
+    #   quantized.i.to_a  # => [{time: 0, value: 60, duration: 1}, ...]
+    #
+    # @example Predictive quantization
+    #   continuous = S({time: 0r, value: 0}, {time: 4r, value: 10})
+    #   pred = continuous.quantize(step: 2, predictive: true)
+    #   # Generates crossing points at values 0, 2, 4, 6, 8, 10
+    #
+    # @api public
     def quantize(reference: nil, step: nil,
-                 value_attribute: nil,
-                 stops: nil,
-                 predictive: nil,
-                 left_open: nil,
-                 right_open: nil)
-
+      value_attribute: nil,
+      stops: nil,
+      predictive: nil,
+      left_open: nil,
+      right_open: nil)
+      
+      # TODO remove debugging puts, intermediate hash comments on :info and InspectNice
+      
       Series::Constructors.QUANTIZE(self,
                       reference: reference,
                       step: step,
@@ -25,6 +63,18 @@ module Musa
   end
 
   module Series::Constructors
+    # Quantizes time-value serie to discrete steps.
+    #
+    # @param time_value_serie [Serie] source timed serie
+    # @param reference [Numeric, nil] quantization reference
+    # @param step [Numeric, nil] step size
+    # @param value_attribute [Symbol, nil] attribute to quantize
+    # @param stops [Boolean, nil] include stop points
+    # @param predictive [Boolean, nil] use predictive mode
+    # @param left_open [Boolean, nil] left boundary open
+    # @param right_open [Boolean, nil] right boundary open
+    #
+    # @return [RawQuantizer, PredictiveQuantizer] quantized serie
     def QUANTIZE(time_value_serie,
                  reference: nil, step: nil,
                  value_attribute: nil,

data/lib/musa-dsl/series/queue-serie.rb

@@ -1,11 +1,76 @@
+# Queue serie for dynamic series concatenation.
+#
+#
+# @api public
 require_relative 'base-series'
 
 module Musa
   module Series::Constructors
+    # Creates queue serie from initial series.
+    #
+    # Queue allows adding series dynamically during playback, creating flexible
+    # sequential playback with runtime modification.
+    #
+    # ## Features
+    #
+    # - **Dynamic addition**: Add series with `<<` during playback
+    # - **Sequential playback**: Plays series in queue order
+    # - **Method delegation**: Delegates methods to current serie
+    # - **Clear**: Can clear queue and reset
+    #
+    # ## Use Cases
+    #
+    # - Interactive sequencing with user input
+    # - Dynamic phrase assembly
+    # - Playlist-style serie management
+    # - Reactive composition systems
+    # - Live coding pattern queuing
+    #
+    # @param series [Array<Serie>] initial series in queue
+    #
+    # @return [QueueSerie] queue serie
+    #
+    # @example Basic queue
+    #   queue = QUEUE(S(1, 2, 3)).i
+    #   queue.next_value  # => 1
+    #   queue << S(4, 5, 6).i  # Add dynamically
+    #   queue.to_a  # => [2, 3, 4, 5, 6]
+    #
+    # @example Dynamic playlist
+    #   queue = QUEUE().i
+    #   queue << melody1.i
+    #   queue << melody2.i
+    #   # Plays melody1 then melody2
+    #
+    # @api public
     def QUEUE(*series)
       QueueSerie.new(series)
     end
 
+    # Serie that processes multiple source series in queue/sequence fashion.
+    #
+    # Combines multiple series by playing them sequentially - when one
+    # series exhausts, moves to the next. New series can be added dynamically
+    # with `<<` operator.
+    #
+    # All queued series must be instances (not prototypes). The queue can
+    # be cleared with `clear` method.
+    #
+    # @example Sequential series playback
+    #   serie_a = FromArray.new([1, 2, 3]).instance
+    #   serie_b = FromArray.new([4, 5, 6]).instance
+    #   queue = QueueSerie.new([serie_a, serie_b])
+    #   queue.next_value  # => 1
+    #   queue.next_value  # => 2
+    #   queue.next_value  # => 3
+    #   queue.next_value  # => 4 (switches to serie_b)
+    #
+    # @example Dynamic queueing
+    #   queue = QueueSerie.new([serie_a]).instance
+    #   queue << serie_b  # Add series on the fly
+    #   queue.clear       # Empty the queue
+    #
+    # @api private
     class QueueSerie
       include Series::Serie.with(sources: true)
 
@@ -14,6 +79,13 @@ module Musa
         init
       end
 
+      # Adds serie to queue.
+      #
+      # @param serie [Serie] instance serie to add
+      #
+      # @return [self] for chaining
+      #
+      # @raise [ArgumentError] if serie is not an instance
       def <<(serie)
         # when queue is a prototype it is also frozen so no serie can be added (it would raise an Exception if tried).
         # when queue is an instance the added serie should also be an instance (raise an Exception otherwise)
@@ -26,6 +98,9 @@ module Musa
         self
       end
 
+      # Clears all series from queue.
+      #
+      # @return [self] for chaining
       def clear
         @sources.clear
         init
@@ -83,6 +158,9 @@ module Musa
   end
 
   module Series::Operations
+    # Wraps this serie in a queue.
+    #
+    # @return [QueueSerie] queue containing this serie
     def queued
       Series::Constructors.QUEUE(self)
     end