musa-dsl 0.30.2 → 0.40.0

data/docs/subsystems/transport.md

@@ -0,0 +1,177 @@
+# Transport - Timing & Clocks
+
+Comprehensive timing infrastructure connecting clock sources to the sequencer. The transport system manages musical playback lifecycle, timing synchronization, and position control.
+
+**Architecture:**
+```
+Clock --ticks--> Transport --tick()--> Sequencer --events--> Music
+```
+
+The system provides precise timing control with support for internal timers, MIDI clock synchronization, and manual control for testing and integration.
+
+## Clock - Timing Sources
+
+**Clock** is the abstract base class for timing sources. All clocks generate regular ticks that drive the sequencer forward. Multiple clock implementations are available for different use cases.
+
+### Clock Activation Models
+
+Clocks use two different activation models:
+
+**Automatic Activation** (DummyClock):
+- Begins generating ticks immediately when `transport.start` is called
+- No external activation required
+- Appropriate for testing, batch processing, simulations
+
+**External Activation** (TimerClock, InputMidiClock, ExternalTickClock):
+- Requires external signal/control to begin generating ticks
+- `transport.start` blocks waiting for activation
+- Appropriate for live coding, DAW sync, external control
+
+### Available Clock Types
+
+**DummyClock** - Simplified clock for testing (automatic activation):
+- Fast playback without real-time constraints
+- Immediately begins generating ticks
+- Useful for test suites or batch generation
+- No external dependencies
+
+**TimerClock** - Internal high-precision timer-based clock (external activation):
+- Standalone compositions with internal timing
+- Requires calling `clock.start()` from another thread
+- Configurable BPM (tempo) and ticks per beat
+- Can dynamically change tempo during playback
+- Appropriate for live coding clients
+
+**InputMidiClock** - Synchronized to external MIDI Clock messages (external activation):
+- DAW-synchronized playback
+- Waits for MIDI "Start" (0xFA) message to begin ticks
+- Automatically follows external MIDI Clock Start/Stop/Continue
+- Locked to external timing source
+
+**ExternalTickClock** - Manually triggered ticks (external activation):
+- Testing and debugging with precise control
+- Integration with external systems (game engines, etc.)
+- Call `clock.tick()` manually to generate each tick
+- Frame-by-frame control
+
+```ruby
+require 'musa-dsl'
+
+# TimerClock - Internal timer-based timing
+timer_clock = Musa::Clock::TimerClock.new(
+  bpm: 120,              # Beats per minute
+  ticks_per_beat: 24     # Resolution
+)
+
+# InputMidiClock - Synchronized to external MIDI Clock
+require 'midi-communications'
+midi_input = MIDICommunications::Input.gets  # Select MIDI input
+
+midi_clock = Musa::Clock::InputMidiClock.new(midi_input)
+
+# ExternalTickClock - Manual tick control
+external_clock = Musa::Clock::ExternalTickClock.new
+
+# DummyClock - For testing (100 ticks)
+dummy_clock = Musa::Clock::DummyClock.new(100)
+```
+
+## Transport - Playback Lifecycle Manager
+
+**Transport** connects a clock to a sequencer and manages the playback lifecycle. It provides methods for starting/stopping playback, seeking to different positions, and registering callbacks for lifecycle events.
+
+**Lifecycle phases:**
+1. **before_begin** - Run once before first start (initialization)
+2. **on_start** - Run each time transport starts
+3. **Running** - Clock generates ticks → sequencer processes events
+4. **on_change_position** - Run when position jumps/seeks
+5. **after_stop** - Run when transport stops
+
+**Key methods:**
+- `start` - Start playback (blocks while running)
+- `stop` - Stop playback
+- `change_position_to(bars: n)` - Seek to position (in bars)
+
+```ruby
+require 'musa-dsl'
+
+# Create clock
+clock = Musa::Clock::TimerClock.new(bpm: 120, ticks_per_beat: 24)
+
+# Create transport
+transport = Musa::Transport::Transport.new(
+  clock,
+  4,   # beats_per_bar (time signature numerator)
+  24   # ticks_per_beat (resolution)
+)
+
+# Access sequencer through transport
+sequencer = transport.sequencer
+
+# Schedule events
+sequencer.at 1 do
+  puts "Starting at bar 1!"
+end
+
+sequencer.at 4 do
+  puts "Reached bar 4"
+  transport.stop
+end
+
+# Register lifecycle callbacks
+transport.before_begin do
+  puts "Initializing (runs once)..."
+end
+
+transport.on_start do
+  puts "Transport started!"
+end
+
+transport.after_stop do
+  puts "Transport stopped, cleaning up..."
+end
+
+# IMPORTANT: TimerClock requires external activation
+# Start transport in background thread (it will block waiting)
+thread = Thread.new { transport.start }
+sleep 0.1  # Let transport initialize
+
+# Activate clock from external control (e.g., live coding client)
+clock.start  # NOW ticks begin generating
+
+# Wait for completion
+thread.join
+
+# Seeking example (in separate context)
+# transport.change_position_to(bars: 2)  # Jump to bar 2
+```
+
+**Complete example with MIDI Clock synchronization:**
+
+```ruby
+require 'musa-dsl'
+require 'midi-communications'
+
+# Setup MIDI-synchronized clock
+midi_input = MIDICommunications::Input.gets
+clock = Musa::Clock::InputMidiClock.new(midi_input)
+
+# Create transport
+transport = Musa::Transport::Transport.new(clock, 4, 24)
+
+# Schedule events
+transport.sequencer.at 1 do
+  puts "Synchronized start at bar 1!"
+end
+
+# Start and wait for MIDI Clock Start message
+transport.start
+```
+
+## API Reference
+
+**Complete API documentation:**
+- [Musa::Transport](https://rubydoc.info/gems/musa-dsl/Musa/Transport) - Playback lifecycle management
+- [Musa::Clock](https://rubydoc.info/gems/musa-dsl/Musa/Clock) - Timing sources and clock implementations
+
+**Source code:** `lib/transport/`

data/lib/musa-dsl/core-ext/array-explode-ranges.rb

@@ -1,6 +1,74 @@
+require_relative 'extension'
+
 module Musa
   module Extension
+    # Refinement that expands Range objects within arrays into their constituent elements.
+    #
+    # This is particularly useful in musical contexts where arrays may contain both
+    # individual values and ranges (like MIDI note ranges or channel ranges), and you
+    # need to work with the fully expanded list.
+    #
+    # ## Use Cases
+    #
+    # - Expanding MIDI channel specifications: [0, 2..4, 7] → [0, 2, 3, 4, 7]
+    # - Expanding note ranges in chord definitions
+    # - Processing mixed literal and range values in musical parameters
+    # - Any scenario where ranges need to be flattened for iteration
+    #
+    # @example Basic usage
+    #   using Musa::Extension::ExplodeRanges
+    #
+    #   [1, 3..5, 8].explode_ranges
+    #   # => [1, 3, 4, 5, 8]
+    #
+    # @example MIDI channels
+    #   using Musa::Extension::ExplodeRanges
+    #
+    #   channels = [0, 2..4, 7, 9..10]
+    #   channels.explode_ranges
+    #   # => [0, 2, 3, 4, 7, 9, 10]
+    #
+    # @example Mixed with other array methods
+    #   using Musa::Extension::ExplodeRanges
+    #
+    #   [1..3, 5, 7..9].explode_ranges.map { |n| n * 2 }
+    #   # => [2, 4, 6, 10, 14, 16, 18]
+    #
+    # @see Musa::MIDIVoices::MIDIVoices#initialize Uses this for channel expansion
+    # @note This refinement must be activated with `using Musa::Extension::ExplodeRanges`
+    #
+    # ## Methods Added
+    #
+    # ### Array
+    # - {Array#explode_ranges} - Expands all Range objects in the array into their individual elements
     module ExplodeRanges
+      # @!method explode_ranges
+      #   Expands all Range objects in the array into their individual elements.
+      #
+      #   Iterates through the array and converts any Range objects to their
+      #   constituent elements via `to_a`, leaving non-Range elements unchanged.
+      #   The result is a new flat array.
+      #
+      #   @note This method is added to Array via refinement. Requires `using Musa::Extension::ExplodeRanges`.
+      #
+      #   @return [Array] new array with all ranges expanded.
+      #
+      #   @example Empty ranges
+      #     using Musa::Extension::ExplodeRanges
+      #     [1, (5..4), 8].explode_ranges  # (5..4) is empty
+      #     # => [1, 8]
+      #
+      #   @example Exclusive ranges
+      #     using Musa::Extension::ExplodeRanges
+      #     [1, (3...6), 9].explode_ranges
+      #     # => [1, 3, 4, 5, 9]
+      #
+      #   @example Nested arrays are NOT expanded recursively
+      #     using Musa::Extension::ExplodeRanges
+      #     [1, [2..4], 5].explode_ranges
+      #     # => [1, [2..4], 5]  # Inner range NOT expanded
+      class ::Array; end
+
       refine Array do
         def explode_ranges
           array = []

data/lib/musa-dsl/core-ext/arrayfy.rb

@@ -1,8 +1,87 @@
+require_relative 'extension'
 require_relative 'deep-copy'
 
 module Musa
   module Extension
+    # Refinement that converts any object to an array, with optional repetition and defaults.
+    #
+    # This refinement is essential for normalizing parameters in the DSL, allowing users
+    # to provide either single values or arrays and have them processed uniformly.
+    #
+    # ## Core Behavior
+    #
+    # - **Object**: Wraps in array; nil becomes []
+    # - **Array**: Returns clone or cycles to requested size
+    # - **size parameter**: Repeats/cycles to achieve target length
+    # - **default parameter**: Replaces nil values
+    #
+    # ## Use Cases
+    #
+    # - Normalizing velocity parameters (single value or per-note array)
+    # - Ensuring consistent array handling in DSL methods
+    # - Cycling patterns to fill required lengths
+    # - Providing default values for missing data
+    #
+    # @example Basic object wrapping
+    #   using Musa::Extension::Arrayfy
+    #
+    #   5.arrayfy           # => [5]
+    #   nil.arrayfy         # => []
+    #   [1, 2, 3].arrayfy   # => [1, 2, 3]
+    #
+    # @example Repetition with size
+    #   using Musa::Extension::Arrayfy
+    #
+    #   5.arrayfy(size: 3)        # => [5, 5, 5]
+    #   [1, 2].arrayfy(size: 5)   # => [1, 2, 1, 2, 1]
+    #   [1, 2, 3].arrayfy(size: 2) # => [1, 2]
+    #
+    # @example Default values for nil
+    #   using Musa::Extension::Arrayfy
+    #
+    #   nil.arrayfy(size: 3, default: 0)           # => [0, 0, 0]
+    #   [1, nil, 3].arrayfy(size: 5, default: -1)  # => [1, -1, 3, 1, -1]
+    #
+    # @example Musical application - velocity normalization
+    #   using Musa::Extension::Arrayfy
+    #
+    #   # User provides single velocity for chord
+    #   velocities = 90.arrayfy(size: 3)  # => [90, 90, 90]
+    #
+    #   # User provides array of velocities that cycles
+    #   velocities = [80, 100].arrayfy(size: 5)  # => [80, 100, 80, 100, 80]
+    #
+    # @see Musa::MIDIVoices::MIDIVoice#note Uses arrayfy for velocity normalization
+    # @note This refinement must be activated with `using Musa::Extension::Arrayfy`
+    # @note Arrays are cloned and singleton class modules are preserved
+    #
+    # ## Methods Added
+    #
+    # ### Object
+    # - {Object#arrayfy} - Converts any object into an array, optionally repeated to a target size
+    #
+    # ### Array
+    # - {Array#arrayfy} - Clones or cycles the array to achieve the target size, with nil replacement
     module Arrayfy
+      # @!method arrayfy(size: nil, default: nil)
+      #   Converts any object into an array, optionally repeated to a target size.
+      #
+      #   @note This method is added to Object via refinement. Requires `using Musa::Extension::Arrayfy`.
+      #
+      #   @param size [Integer, nil] target array length. If nil, returns single-element array.
+      #   @param default [Object, nil] value to use instead of nil.
+      #
+      #   @return [Array] single element repeated size times, or wrapped in array if size is nil.
+      #
+      #   @example With size
+      #     using Musa::Extension::Arrayfy
+      #     "hello".arrayfy(size: 3)  # => ["hello", "hello", "hello"]
+      #
+      #   @example Nil handling
+      #     using Musa::Extension::Arrayfy
+      #     nil.arrayfy(size: 2, default: :empty)  # => [:empty, :empty]
+      class ::Object; end
+
       refine Object do
         def arrayfy(size: nil, default: nil)
           if size
@@ -17,6 +96,37 @@ module Musa
 
       # TODO add a refinement for Hash? Should receive a list parameter with the ordered keys
 
+      # @!method arrayfy(size: nil, default: nil)
+      #   Clones or cycles the array to achieve the target size, with nil replacement.
+      #
+      #   The cycling behavior multiplies the array enough times to reach or exceed
+      #   the target size, then takes exactly the requested number of elements.
+      #   Singleton class modules (like P, V dataset extensions) are preserved.
+      #
+      #   @note This method is added to Array via refinement. Requires `using Musa::Extension::Arrayfy`.
+      #
+      #   @param size [Integer, nil] target length. If nil, returns clone of array.
+      #   @param default [Object, nil] value to replace nil elements with.
+      #
+      #   @return [Array] processed array of exactly the requested size.
+      #
+      #   @example Cycling shorter array
+      #     using Musa::Extension::Arrayfy
+      #     [1, 2].arrayfy(size: 5)  # => [1, 2, 1, 2, 1]
+      #
+      #   @example Truncating longer array
+      #     using Musa::Extension::Arrayfy
+      #     [1, 2, 3, 4, 5].arrayfy(size: 3)  # => [1, 2, 3]
+      #
+      #   @example Preserving dataset modules
+      #     using Musa::Extension::Arrayfy
+      #     p_sequence = [60, 1, 62].extend(Musa::Datasets::P)
+      #     p_sequence.arrayfy(size: 6)  # Result also extended with P
+      #
+      #   @note The cycling formula: array * (size / array.size + (size % array.size).zero? ? 0 : 1)
+      #     ensures enough repetitions to reach target size.
+      class ::Array; end
+
       refine Array do
         def arrayfy(size: nil, default: nil)
           if size

data/lib/musa-dsl/core-ext/attribute-builder.rb

@@ -1,10 +1,52 @@
+require_relative 'extension'
+
 module Musa
   module Extension
+    # Module providing metaprogramming methods for creating DSL builder patterns.
+    #
+    # AttributeBuilder defines class methods that generate instance methods for
+    # creating and managing collections of objects in a DSL-friendly way. It's
+    # heavily used throughout Musa DSL to create fluent, expressive APIs.
+    #
+    # ## Method Categories
+    #
+    # - **Adders to Hash**: Create methods that build hash-based collections
+    # - **Adders to Array**: Create methods that build array-based collections
+    # - **Builders**: Create single-object getter/setter DSL methods
+    #
+    # ## Naming Conventions
+    #
+    # - `add_item` / `item`: singular form adds one object
+    # - `items`: plural form adds multiple or retrieves collection
+    # - Automatic pluralization (item → items) unless specified
+    #
+    # @example Using in a class
+    #   class Score
+    #     extend Musa::Extension::AttributeBuilder
+    #
+    #     def initialize
+    #       @tracks = {}
+    #     end
+    #
+    #     attr_tuple_adder_to_hash :track, Track
+    #   end
+    #
+    #   score = Score.new
+    #   score.add_track :piano, params
+    #   score.tracks  # => { piano: Track(...) }
+    #
+    # @see Musa::Datasets Score classes use these extensively
     module AttributeBuilder
-      # add_thing id, parameter
-      # things id1: parameter1, id2: parameter2 -> { id1: Thing(id1, parameter1), id2: Thing(id2, parameter2) }
-      # things -> { id1: Thing(id1, parameter1), id2: Thing(id2, parameter2) }
+      # Creates methods for adding id/value tuples to a hash collection.
+      #
+      # Generates:
+      # - `add_#{name}(id, parameter)` → creates instance and adds to hash
+      # - `#{plural}(**parameters)` → batch add or retrieve hash
       #
+      # @param name [Symbol] singular name for the item.
+      # @param klass [Class] class to instantiate (receives id, parameter).
+      # @param plural [Symbol, nil] plural name (defaults to name + 's').
+      # @param variable [Symbol, nil] instance variable name (defaults to '@' + plural).
       def attr_tuple_adder_to_hash(name, klass, plural: nil, variable: nil)
 
         plural ||= name.to_s + 's'
@@ -26,10 +68,15 @@ module Musa
         end
       end
 
-      # add_thing id, parameter
-      # things id1: parameter1, id2: parameter2 -> [ Thing(id1, parameter1), Thing(id2, parameter2) ]
-      # things -> [ Thing(id1, parameter1), Thing(id2, parameter2) ]
-
+      # Creates methods for adding id/value tuples to an array collection.
+      #
+      # Similar to attr_tuple_adder_to_hash but stores items in an array instead of hash.
+      # Useful when order matters or duplicates are allowed.
+      #
+      # @param name [Symbol] singular name for the item.
+      # @param klass [Class] class to instantiate.
+      # @param plural [Symbol, nil] plural name.
+      # @param variable [Symbol, nil] instance variable name.
       def attr_tuple_adder_to_array(name, klass, plural: nil, variable: nil)
 
         plural ||= name.to_s + 's'
@@ -51,10 +98,14 @@ module Musa
         end
       end
 
-      # add_thing param1, param2, key1: parameter1, key2: parameter2 -> Thing(...)
-      # thing param1, param2, key1: parameter1, key2: parameter2 -> Thing(...)
-      # things -> (collection)
-
+      # Creates methods for adding complex objects (with multiple parameters) to an array.
+      #
+      # Supports both positional and keyword arguments when creating instances.
+      #
+      # @param name [Symbol] singular name.
+      # @param klass [Class] class to instantiate.
+      # @param plural [Symbol, nil] plural name.
+      # @param variable [Symbol, nil] instance variable name.
       def attr_complex_adder_to_array(name, klass, plural: nil, variable: nil)
 
         plural ||= name.to_s + 's'
@@ -86,10 +137,14 @@ module Musa
       end
 
 
-      # add_thing param1, param2, key1: parameter1, key2: parameter2 -> Thing(...)
-      # thing param1, param2, key1: parameter1, key2: parameter2 -> Thing(...)
-      # things -> (collection)
-
+      # Creates methods for adding complex objects with custom construction logic.
+      #
+      # The block receives parameters and should construct and add the object.
+      #
+      # @param name [Symbol] singular name.
+      # @param plural [Symbol, nil] plural name.
+      # @param variable [Symbol, nil] instance variable name.
+      # @yield Constructor block executed in instance context.
       def attr_complex_adder_to_custom(name, plural: nil, variable: nil, &constructor_and_adder)
 
         plural ||= name.to_s + 's'
@@ -121,9 +176,11 @@ module Musa
         end
       end
 
-      # thing value -> crea Thing(value)
-      # thing -> Thing(value)
-
+      # Creates a simple getter/setter DSL method for a single value.
+      #
+      # @param name [Symbol] attribute name.
+      # @param klass [Class, nil] class to instantiate (nil = use value as-is).
+      # @param variable [Symbol, nil] instance variable name.
       def attr_simple_builder(name, klass = nil, variable: nil)
         variable ||= ('@' + name.to_s).to_sym
 
@@ -140,34 +197,38 @@ module Musa
         attr_writer name
       end
 
-      # thing id: value -> crea Thing(id, value)
-      # thing -> Thing(id, value)
-
+      # Creates a getter/setter DSL method for a single id/value tuple.
+      #
+      # @param name [Symbol] attribute name.
+      # @param klass [Class] class to instantiate.
+      # @param variable [Symbol, nil] instance variable name.
       def attr_tuple_builder(name, klass, variable: nil)
         variable ||= ('@' + name.to_s).to_sym
 
         define_method name do |**parameters, &block|
-          raise ArgumentError, "Method #{name} can only create instances with one id: value arguments pattern" unless parameters.size == 1
-
           if parameters.empty?
             instance_variable_get variable
-          else
+          elsif parameters.size == 1
             parameter = parameters.first
             klass.new(*parameter, &block).tap do |object|
               instance_variable_set variable, object
             end
+          else
+            raise ArgumentError, "Method #{name} can only create instances with one id: value arguments pattern"
           end
         end
 
         attr_writer name
       end
 
-      # thing value1, value2, key1: value3, key2: value4 -> crea Thing(value1, value2, key1: value3, key2: value3)
-      # thing -> Thing(value1, value2, key1: value3, key2: value4)
-      # y también...
-      # thing value1, value2, key1: value3, key2: value4 -> crea Thing(first_parameter, value1, value2, key1: value3, key2: value3)
-      # thing -> Thing(first_parameter, value1, value2, key1: value3, key2: value4)
-
+      # Creates a getter/setter DSL method for complex objects with multiple parameters.
+      #
+      # Supports optional first_parameter that's automatically prepended when constructing.
+      #
+      # @param name [Symbol] attribute name.
+      # @param klass [Class] class to instantiate.
+      # @param variable [Symbol, nil] instance variable name.
+      # @param first_parameter [Object, nil] parameter automatically prepended to constructor.
       def attr_complex_builder(name, klass, variable: nil, first_parameter: nil)
         variable ||= ('@' + name.to_s).to_sym