musa-dsl 0.30.2 → 0.40.0

data/lib/musa-dsl/neumas/array-to-neumas.rb

@@ -3,7 +3,146 @@ require_relative '../neumalang'
 
 module Musa
   module Extension
+    # Array refinement for converting to neuma series.
+    #
+    # Adds methods to Array class for converting arrays of neuma elements (strings,
+    # neuma objects) into merged series. Enables convenient composition of multiple
+    # neuma sequences.
+    #
+    # ## Array to Neumas Conversion
+    #
+    # Arrays are converted using `MERGE` to create sequential series:
+    # ```ruby
+    # ["0 +2 +4", "+5 +7"].to_neumas
+    # # Equivalent to:
+    # MERGE("0 +2 +4".to_neumas, "+5 +7".to_neumas)
+    # ```
+    #
+    # ## Element Types
+    #
+    # Array elements can be:
+    # - **Strings**: Parsed as neuma notation
+    # - **Neuma::Serie**: Used directly
+    # - **Neuma::Parallel**: Wrapped in series
+    #
+    # ## Usage with Refinement
+    #
+    # This is a refinement - must be activated with `using`:
+    # ```ruby
+    # using Musa::Extension::Neumas
+    #
+    # phrases = [
+    #   "0 +2 +4 +5",    # First phrase
+    #   "+7 +5 +4 +2",   # Second phrase
+    #   "0 -2 -4 -5"     # Third phrase
+    # ].to_neumas
+    # ```
+    #
+    # ## Musical Applications
+    #
+    # - **Phrase composition**: Combine multiple musical phrases
+    # - **Section building**: Assemble larger structures from fragments
+    # - **Pattern sequencing**: Chain melodic/rhythmic patterns
+    # - **Mixed sources**: Combine string notation with existing neuma objects
+    #
+    # @example Sequential phrases
+    #   using Musa::Extension::Neumas
+    #
+    #   melody = [
+    #     "0 +2 +4 +5",    # Phrase A
+    #     "+7 +5 +4 +2",   # Phrase B
+    #     "0 -2 -4 -5"     # Phrase C
+    #   ].to_neumas
+    #
+    # @example Mixed element types
+    #   using Musa::Extension::Neumas
+    #
+    #   intro = "0 +2 +4".to_neumas
+    #   verse = "0 +2 +2 -1 0"
+    #   chorus = "+7 +5 +7"
+    #
+    #   song = [intro, verse, chorus].to_neumas
+    #
+    # @example Single element
+    #   using Musa::Extension::Neumas
+    #
+    #   # Single element returns converted element directly (not merged)
+    #   single = ["0 +2 +4"].to_neumas
+    #
+    # Must be activated with `using Musa::Extension::Neumas`.
+    #
+    # ## Methods Added
+    #
+    # ### Array
+    # - {Array#to_neumas} - Converts array elements to merged neuma series
+    # - {Array#neumas} - Alias for to_neumas
+    # - {Array#n} - Short alias for to_neumas
+    #
+    # @see Musa::Extension::Neumas String refinement
+    #
+    # @api public
     module Neumas
+      # @!method to_neumas
+      #   Converts array elements to merged neuma series.
+      #
+      #   - Single element: Returns converted element directly
+      #   - Multiple elements: Returns MERGE of all converted elements
+      #
+      #   Each element is converted based on its type:
+      #   - String → parsed as neuma notation
+      #   - Neuma::Serie → used directly
+      #   - Neuma::Parallel → wrapped in series
+      #
+      #   @note This method is added to Array via refinement. Requires `using Musa::Extension::Neumas`.
+      #
+      #   @return [Serie, Neuma] merged series or single neuma
+      #
+      #   @raise [ArgumentError] if element type cannot be converted
+      #
+      #   @example Convert string array
+      #     using Musa::Extension::Neumas
+      #
+      #     phrases = [
+      #       "0 +2 +4",
+      #       "+5 +7"
+      #     ].to_neumas
+      #     # Returns MERGE of two parsed series
+      #
+      #   @example Mixed types
+      #     using Musa::Extension::Neumas
+      #
+      #     existing = "0 +2".to_neumas
+      #     combined = [existing, "+4 +5"].to_neumas
+      #
+      #   @example Single element
+      #     using Musa::Extension::Neumas
+      #
+      #     single = ["0 +2 +4"].to_neumas
+      #     # Returns parsed series directly (not merged)
+      #
+      #   @api public
+      class ::Array; end
+
+      # @!method neumas
+      #   Alias for `to_neumas`.
+      #
+      #   @note This method is added to Array via refinement. Requires `using Musa::Extension::Neumas`.
+      #
+      #   @see Array#to_neumas
+      #
+      #   @api public
+      class ::Array; end
+
+      # @!method n
+      #   Short alias for `to_neumas`.
+      #
+      #   @note This method is added to Array via refinement. Requires `using Musa::Extension::Neumas`.
+      #
+      #   @see Array#to_neumas
+      #
+      #   @api public
+      class ::Array; end
+
       refine Array do
         def to_neumas
           if length > 1
@@ -14,10 +153,20 @@ module Musa
         end
 
         alias_method :neumas, :to_neumas
+
         alias_method :n, :to_neumas
 
         private
 
+        # Converts element to neuma based on type.
+        #
+        # @param e [Object] element to convert
+        #
+        # @return [Serie] converted neuma serie
+        #
+        # @raise [ArgumentError] if type cannot be converted
+        #
+        # @api private
         def convert_to_neumas(e)
           case e
           when Musa::Neumas::Neuma::Serie then e

data/lib/musa-dsl/neumas/neuma-decoder.rb

@@ -1,28 +1,216 @@
 require_relative 'neumas'
 
 module Musa::Neumas
+  # Neuma decoder infrastructure for converting neuma notation to musical events.
+  #
+  # Provides base classes for decoding neuma notation (a musical representation format)
+  # into GDV (Grade-Duration-Velocity) events. The decoder system supports differential
+  # decoding where each event is interpreted relative to the previous event.
+  #
+  # ## Architecture Overview
+  #
+  # ### Decoder Hierarchy
+  #
+  # ```
+  # ProtoDecoder (abstract)
+  #   └── DifferentialDecoder (abstract)
+  #         └── Decoder (stateful base)
+  #               ├── NeumaDecoder (GDV output)
+  #               └── NeumaDifferentialDecoder (GDVD output)
+  # ```
+  #
+  # ### Key Concepts
+  #
+  # 1. **Differential Decoding**: Each neuma is interpreted relative to previous state
+  #
+  #    - Grade: `+2` means "2 steps up from last note"
+  #    - Duration: `_2` means "double the base duration"
+  #
+  # 2. **Stateful Processing**: Decoders maintain `@last` state for differential interpretation
+  #
+  # 3. **Subcontexts**: Create independent decoder contexts for nested structures
+  #
+  # 4. **Transcription Integration**: Optional transcriptor for post-processing (ornaments, etc.)
+  #
+  # ## Processing Pipeline
+  #
+  # ```ruby
+  # Neuma Input → process() → apply() → Transcriptor → GDV Output
+  #                  ↓           ↓
+  #              Prepare     Apply to
+  #              attributes   last state
+  # ```
+  #
+  # ## Neuma Notation
+  #
+  # Neumas are text-based musical notation:
+  # ```ruby
+  # "0 +2 +2 -1"        # Grade sequence (scale degrees)
+  # "_ _2 _/2"          # Duration modifiers
+  # ".st .tr .mor"      # Articulation/ornament modifiers
+  # "(+1_/4)+2_"        # Appogiatura (grace note) + main note
+  # ```
+  #
+  # @example Basic usage
+  #
+  # Decoders are used by the neuma parsing system:
+  # ```ruby
+  # decoder = Musa::Neumas::Decoders::NeumaDecoder.new(
+  #   scale,
+  #   base_duration: 1/4r,
+  #   transcriptor: transcriptor
+  # )
+  #
+  # # Parse and decode neuma string
+  # neumas = "0 +2 +2 -1 0".to_neumas
+  # neumas.each { |neuma| decoder.decode(neuma) }
+  # ```
+  #
+  # @see Musa::Neumas Neuma notation system
+  # @see Musa::Datasets::GDV Absolute GDV format
+  # @see Musa::Datasets::GDVd Differential GDVD format
+  # @see Musa::Neumas::Decoders::NeumaDecoder
+  # @see Musa::Neumas::Decoders::NeumaDifferentialDecoder
+  # @see Musa::Transcription
+  #
+  # @api public
   module Decoders
+    # Abstract base decoder class.
+    #
+    # Defines the basic decoder interface. All decoders must implement:
+    #
+    # - `decode(element)` - Main decoding method
+    # - `subcontext` - Create independent decoder context
+    #
+    # ## Subcontexts
+    #
+    # Subcontexts allow creating independent decoder instances for nested
+    # structures (like grace notes) that need their own state tracking.
+    #
+    # @api public
     class ProtoDecoder
+      # Creates subcontext decoder.
+      #
+      # Returns independent decoder instance for nested decoding.
+      # Default implementation returns self (stateless).
+      #
+      # @return [ProtoDecoder] subcontext decoder instance
+      #
+      # @api public
       def subcontext
         self
       end
 
+      # Decodes element to musical event.
+      #
+      # Abstract method - must be implemented by subclasses.
+      #
+      # @param _element [Object] element to decode
+      #
+      # @return [Hash] decoded musical event
+      #
+      # @raise [NotImplementedError] if not overridden
+      #
+      # @api public
       def decode(_element)
         raise NotImplementedError
       end
     end
 
+    # Differential decoder base class.
+    #
+    # Adds `process` step to decoding pipeline for preparing/transforming
+    # input before final decoding. Useful for setting default values,
+    # normalizing formats, etc.
+    #
+    # ## Pipeline
+    #
+    # ```ruby
+    # input → process(input) → decode(processed)
+    # ```
+    #
+    # @api public
     class DifferentialDecoder < ProtoDecoder
+      # Decodes element after processing.
+      #
+      # Calls `process` to prepare element, then returns processed result.
+      #
+      # @param gdvd [Hash] GDVD (Grade-Duration-Velocity-Differential) attributes
+      #
+      # @return [Hash] processed attributes
+      #
+      # @api public
       def decode(gdvd)
         process gdvd
       end
 
+      # Processes/prepares attributes for decoding.
+      #
+      # Abstract method - must be implemented by subclasses to transform
+      # input attributes (set defaults, normalize, etc.).
+      #
+      # @param _gdvd [Hash] GDVD attributes
+      #
+      # @return [Hash] processed attributes
+      #
+      # @raise [NotImplementedError] if not overridden
+      #
+      # @api public
       def process(_gdvd)
         raise NotImplementedError
       end
     end
 
+    # Stateful decoder with differential interpretation and transcription.
+    #
+    # Maintains state (`@base`, `@last`) to interpret each neuma relative to
+    # the previous one. Supports optional transcriptor for post-processing
+    # (expanding ornaments, applying articulations, etc.).
+    #
+    # ## Differential Interpretation
+    #
+    # Each decoded event is interpreted relative to `@last`:
+    #
+    # - Grade changes: `+2` = last_grade + 2
+    # - Duration changes: `_2` = base_duration * 2
+    #
+    # After decoding, `@last` is updated for next event.
+    #
+    # ## Processing Pipeline
+    #
+    # ```ruby
+    # Input → process() → apply(on: @last) → update @last → transcriptor → Output
+    # ```
+    #
+    # @example Stateful decoding
+    #   decoder = Musa::Neumas::Decoders::NeumaDifferentialDecoder.new(
+    #     base_duration: 1/4r
+    #   )
+    #
+    #   # Create mock GDVD object
+    #   gdvd1 = Object.new
+    #   def gdvd1.clone; self; end
+    #   def gdvd1.base_duration=(val); @bd = val; end
+    #
+    #   result = decoder.decode(gdvd1)
+    #   # Returns processed GDVD with base_duration set
+    #
+    # @api public
     class Decoder < DifferentialDecoder
+      # Creates stateful decoder.
+      #
+      # @param base [Hash] base/initial state for differential decoding
+      # @param transcriptor [Transcriptor, nil] optional transcriptor for post-processing
+      #
+      # @example Create decoder with base state
+      #   base_state = { grade: 0, octave: 0, duration: 1/4r, velocity: 1 }
+      #   decoder = Musa::Neumas::Decoders::Decoder.new(base_state)
+      #
+      #   # Decoder maintains state
+      #   decoder.base[:grade]     # => 0
+      #   decoder.base[:duration]  # => 1/4r
+      #
+      # @api public
       def initialize(base, transcriptor: nil)
         @base = base
         @last = base.clone
@@ -30,18 +218,70 @@ module Musa::Neumas
         @transcriptor = transcriptor
       end
 
+      # Transcriptor for post-processing decoded events.
+      #
+      # @return [Transcriptor, nil] transcriptor instance or nil
+      #
+      # @api public
       attr_accessor :transcriptor
+
+      # Base state for decoder.
+      #
+      # @return [Hash] base state
+      #
+      # @api public
       attr_reader :base
 
+      # Sets base state and resets last state.
+      #
+      # @param base [Hash] new base state
+      #
+      # @api public
       def base=(base)
         @base = base
         @last = base.clone
       end
 
+      # Creates independent subcontext decoder.
+      #
+      # Returns new decoder with same base state but independent `@last` tracking.
+      # Used for nested structures like grace notes.
+      #
+      # @return [Decoder] independent decoder instance
+      #
+      # @api public
       def subcontext
         Decoder.new @base
       end
 
+      # Decodes attributes with differential interpretation and transcription.
+      #
+      # Pipeline:
+      # 1. Process attributes
+      # 2. Apply to last state
+      # 3. Update last state
+      # 4. Optional transcription
+      #
+      # @param attributes [Hash] neuma attributes to decode
+      #
+      # @return [Hash, Array<Hash>] decoded event(s), possibly transcribed
+      #
+      # @example Create decoder with transcriptor
+      #   base_state = { grade: 0, octave: 0, duration: 1/4r, velocity: 1 }
+      #
+      #   # Create mock transcriptor
+      #   transcriptor = Object.new
+      #   def transcriptor.transcript(gdv); [gdv, gdv.clone]; end
+      #
+      #   decoder = Musa::Neumas::Decoders::Decoder.new(
+      #     base_state,
+      #     transcriptor: transcriptor
+      #   )
+      #
+      #   # Transcriptor can expand events (e.g., ornaments)
+      #   decoder.transcriptor  # => transcriptor object
+      #
+      # @api public
       def decode(attributes)
         result = apply process(attributes), on: @last
 
@@ -54,6 +294,19 @@ module Musa::Neumas
         end
       end
 
+      # Applies processed attributes to previous state.
+      #
+      # Abstract method - must be implemented by subclasses to define how
+      # differential attributes are applied to produce absolute values.
+      #
+      # @param _action [Hash] processed attributes
+      # @param on [Hash] previous state to apply attributes to
+      #
+      # @return [Hash] resulting absolute event
+      #
+      # @raise [NotImplementedError] if not overridden
+      #
+      # @api public
       def apply(_action, on:)
         raise NotImplementedError
       end

data/lib/musa-dsl/neumas/neuma-gdv-decoder.rb

@@ -2,7 +2,96 @@ require_relative 'neuma-decoder'
 
 module Musa::Neumas
   module Decoders
+    # GDV neuma decoder for converting neumas to Grade-Duration-Velocity events.
+    #
+    # Converts neuma notation (GDVD - differential format) to GDV (absolute format)
+    # using scale information. This decoder is the primary way to transform text-based
+    # neuma notation into playable musical events.
+    #
+    # ## GDVD vs GDV
+    #
+    # - **GDVD** (differential): Relative changes `+2 _2` (up 2 steps, double duration)
+    # - **GDV** (absolute): Absolute values `{grade: 2, duration: 1/2r}` ready for playback
+    #
+    # ## Conversion Process
+    #
+    # ```ruby
+    # Neuma String → Parser → GDVD → NeumaDecoder → GDV → Transcriptor → MIDI/MusicXML
+    # "0 +2 +2 -1"              ↓                      ↓
+    #                   {grade_diff: +2}    {grade: 2, duration: 1/4r}
+    # ```
+    #
+    # ## Scale Integration
+    #
+    # The decoder uses a scale to interpret grade values:
+    # ```ruby
+    # scale = Musa::Scales::Scales.et12[440.0].major[60]
+    # decoder = NeumaDecoder.new(scale)
+    #
+    # # Grade 2 in C major = E (C=0, D=1, E=2)
+    # ```
+    #
+    # ## Appogiatura Handling
+    #
+    # Grace notes (appogiatura) are processed recursively:
+    # ```ruby
+    # "(+1_/4)+2_"  # Grace note +1 with duration 1/4, main note +2
+    # ```
+    #
+    # Both the grace note and main note are converted from GDVD to GDV.
+    #
+    # @example Using with transcriptor
+    #   scale = Musa::Scales::Scales.et12[440.0].major[60]
+    #
+    #   # Create mock transcriptor
+    #   transcriptor = Object.new
+    #   def transcriptor.transcript(gdv); [gdv]; end
+    #
+    #   decoder = Musa::Neumas::Decoders::NeumaDecoder.new(
+    #     scale,
+    #     base_duration: 1/4r,
+    #     transcriptor: transcriptor
+    #   )
+    #
+    #   # Transcriptor will process decoded events
+    #   decoder.transcriptor  # => transcriptor object
+    #
+    # @see Musa::Neumas::Decoders::Decoder
+    # @see Musa::Scales
+    # @see Musa::Transcription
+    #
+    # @api public
     class NeumaDecoder < Decoder # to get a GDV
+      # Creates GDV neuma decoder.
+      #
+      # @param scale [Scale] scale for interpreting grade values
+      # @param base_duration [Rational, nil] base duration unit (default: 1/4)
+      # @param transcriptor [Transcriptor, nil] optional transcriptor for ornaments
+      # @param base [Hash, nil] initial state (auto-created if nil)
+      #
+      # @example Create decoder with scale
+      #   scale = Object.new
+      #   decoder = Musa::Neumas::Decoders::NeumaDecoder.new(
+      #     scale,
+      #     base_duration: 1/4r
+      #   )
+      #
+      #   # Check initial state
+      #   decoder.base[:grade]      # => 0
+      #   decoder.base[:duration]   # => 1/4r
+      #
+      # @example Custom initial state
+      #   scale = Object.new
+      #   decoder = Musa::Neumas::Decoders::NeumaDecoder.new(
+      #     scale,
+      #     base: { grade: 2, octave: 1, duration: 1/8r, velocity: 0.8 }
+      #   )
+      #
+      #   # Verify custom state
+      #   decoder.base[:grade]   # => 2
+      #   decoder.base[:octave]  # => 1
+      #
+      # @api public
       def initialize(scale, base_duration: nil, transcriptor: nil, base: nil)
         @base_duration = base_duration
         @base_duration ||= base[:duration] if base
@@ -15,8 +104,30 @@ module Musa::Neumas
         super base, transcriptor: transcriptor
       end
 
-      attr_accessor :scale, :base_duration
-
+      # Scale for interpreting grade values.
+      #
+      # @return [Scale] scale object
+      #
+      # @api public
+      attr_accessor :scale
+
+      # Base duration unit for duration calculations.
+      #
+      # @return [Rational] base duration (e.g., 1/4 for quarter note)
+      #
+      # @api public
+      attr_accessor :base_duration
+
+      # Processes GDVD attributes before conversion.
+      #
+      # Sets base_duration on GDVD object for duration calculations.
+      # Handles appogiatura (grace note) modifiers recursively.
+      #
+      # @param gdvd [Hash] GDVD attributes
+      #
+      # @return [Hash] processed GDVD with base_duration set
+      #
+      # @api public
       def process(gdvd)
         gdvd = gdvd.clone
 
@@ -34,10 +145,34 @@ module Musa::Neumas
         gdvd
       end
 
+      # Creates independent subcontext decoder.
+      #
+      # Returns new decoder with current `@last` state as base, enabling
+      # independent processing of nested structures (grace notes, etc.).
+      #
+      # @return [NeumaDecoder] subcontext decoder with current state
+      #
+      # @api public
       def subcontext
         NeumaDecoder.new @scale, base_duration: @base_duration, transcriptor: @transcriptor, base: @last
       end
 
+      # Applies GDVD to previous state, producing absolute GDV.
+      #
+      # Converts differential GDVD to absolute GDV using scale. Processes
+      # appogiatura modifiers recursively.
+      #
+      # @param gdvd [Hash] processed GDVD attributes
+      # @param on [Hash] previous GDV state
+      #
+      # @return [Hash] absolute GDV event
+      #
+      # @example Convert differential to absolute
+      #   # Previous: { grade: 0, duration: 1/4r }
+      #   # GDVD: { grade_diff: +2, duration_factor: 2 }
+      #   # Result: { grade: 2, duration: 1/2r, ... }
+      #
+      # @api public
       def apply(gdvd, on:)
         gdv = gdvd.to_gdv @scale, previous: on
 
@@ -47,6 +182,11 @@ module Musa::Neumas
         gdv
       end
 
+      # Returns debug representation.
+      #
+      # @return [String] debug string with last state
+      #
+      # @api public
       def inspect
         "GDV NeumaDecoder: @last = #{@last}"
       end