musa-dsl 0.30.2 → 0.40.0

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

@@ -2,11 +2,93 @@ require_relative 'neuma-decoder'
 
 module Musa::Neumas
   module Decoders
+    # GDVD neuma decoder for preserving differential format.
+    #
+    # Simple decoder that processes GDVD (Grade-Duration-Velocity-Differential) neumas
+    # without converting to absolute GDV format. Useful when you need to work with
+    # differential values directly or perform intermediate processing.
+    #
+    # ## GDVD Format
+    #
+    # GDVD maintains relative/differential values:
+    # ```ruby
+    # {
+    #   grade_diff: +2,        # Relative grade change
+    #   duration_factor: 2,    # Duration multiplier
+    #   velocity_factor: 1.2,  # Velocity multiplier
+    #   modifiers: {...}       # Ornaments, articulations
+    # }
+    # ```
+    #
+    # ## Use Cases
+    #
+    # - **Intermediate processing**: Transform neumas before converting to GDV
+    # - **Pattern analysis**: Analyze melodic intervals without absolute pitch
+    # - **Transposition**: Work with relative values for easy transposition
+    #
+    # ## vs NeumaDecoder
+    #
+    # - **NeumaDifferentialDecoder**: Keeps differential format (GDVD)
+    # - **NeumaDecoder**: Converts to absolute format (GDV) using scale
+    #
+    # @example Process GDVD
+    #   decoder = Musa::Neumas::Decoders::NeumaDifferentialDecoder.new(
+    #     base_duration: 1/4r
+    #   )
+    #
+    #   gdvd = decoder.decode({ grade_diff: +2, duration_factor: 2 })
+    #   # => { grade_diff: +2, duration_factor: 2, base_duration: 1/4r }
+    #   # Still differential, not converted to absolute
+    #
+    # @example Intermediate processing workflow
+    #   # Process neumas in differential format before final conversion
+    #   using Musa::Extension::Neumas
+    #
+    #   neumas = "0 +2 +2 -1 0".to_neumas
+    #   differential_decoder = Musa::Neumas::Decoders::NeumaDifferentialDecoder.new
+    #
+    #   # Process each neuma (keeping differential format)
+    #   gdvds = []
+    #   neumas.i.each do |neuma|
+    #     gdvd = differential_decoder.decode(neuma[:gdvd])
+    #     gdvds << gdvd
+    #   end
+    #
+    #   # GDVD objects still have differential values
+    #   # Can transform them before converting to absolute GDV
+    #
+    # @see Musa::Neumas::Decoders::NeumaDecoder
+    # @see Musa::Neumas::Decoders::DifferentialDecoder
+    #
+    # @api public
     class NeumaDifferentialDecoder < DifferentialDecoder # to get a GDVd
+      # Creates differential GDVD decoder.
+      #
+      # @param base_duration [Rational, nil] base duration unit (default: 1/4)
+      #
+      # @example Create decoder with eighth note base
+      #   decoder = NeumaDifferentialDecoder.new(base_duration: 1/8r)
+      #
+      # @api public
       def initialize(base_duration: nil)
         @base_duration = base_duration || Rational(1,4)
       end
 
+      # Processes GDVD by setting base_duration.
+      #
+      # Clones GDVD and sets base_duration for duration calculations.
+      # Does not convert to absolute values.
+      #
+      # @param gdvd [Hash] GDVD attributes
+      #
+      # @return [Hash] GDVD with base_duration set
+      #
+      # @example Process differential neuma
+      #   gdvd = { grade_diff: +2, duration_factor: 2 }
+      #   result = decoder.process(gdvd)
+      #   # => { grade_diff: +2, duration_factor: 2, base_duration: 1/4r }
+      #
+      # @api public
       def process(gdvd)
         gdvd.clone.tap { |_| _.base_duration = @base_duration }
       end

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

@@ -3,16 +3,74 @@ require_relative 'string-to-neumas'
 using Musa::Extension::Neumas
 
 module Musa
+  # Neuma notation system namespace.
+  #
+  # Contains all neuma-related modules, classes, and functionality.
+  #
+  # @api public
   module Neumas
+    # Base neuma module for serie and parallel structures.
+    #
+    # Mixed into neuma hashes to provide structure-specific methods.
+    # Neumas are extended with either `Neuma::Serie` or `Neuma::Parallel`.
+    #
+    # @api public
     module Neuma
+      # Parallel neuma structure (polyphonic).
+      #
+      # Represents simultaneous musical events (multiple voices, chords).
+      # Contains array of neuma series in `:parallel` key.
+      #
+      # @example Parallel structure
+      #   {
+      #     kind: :parallel,
+      #     parallel: [
+      #       { kind: :serie, serie: melody_neumas },
+      #       { kind: :serie, serie: bass_neumas }
+      #     ]
+      #   }.extend(Musa::Neumas::Neuma::Parallel)
+      #
+      # @api public
       module Parallel
         include Neuma
       end
 
+      # Serie neuma structure (monophonic).
+      #
+      # Represents sequential musical events (single voice melody).
+      # Contains array of neuma objects in `:serie` key.
+      #
+      # @example Serie structure
+      #   {
+      #     kind: :serie,
+      #     serie: [neuma1, neuma2, neuma3]
+      #   }.extend(Musa::Neumas::Neuma::Serie)
+      #
+      # @api public
       module Serie
         include Neuma
       end
 
+      # Creates parallel structure with another neuma.
+      #
+      # Combines this neuma with another into parallel (polyphonic) structure.
+      # If already parallel, adds to existing parallel array.
+      #
+      # @param other [String, Neuma] neuma to parallelize with
+      #
+      # @return [Parallel] parallel neuma structure
+      #
+      # @raise [ArgumentError] if other cannot be converted
+      #
+      # @example Create parallel from neumas
+      #   melody = "0 +2 +4".to_neumas
+      #   bass = "-7 -5 -3".to_neumas
+      #   harmony = melody | bass
+      #
+      # @example Chain multiple parallels
+      #   satb = soprano | alto | tenor | bass
+      #
+      # @api public
       def |(other)
         if is_a?(Parallel)
           clone.tap { |_| _[:parallel] << convert_to_parallel_element(other) }.extend(Parallel)
@@ -25,6 +83,15 @@ module Musa
 
       private
 
+      # Converts element to parallel-compatible format.
+      #
+      # @param e [String, Neuma] element to convert
+      #
+      # @return [Hash] neuma serie structure
+      #
+      # @raise [ArgumentError] if cannot convert
+      #
+      # @api private
       def convert_to_parallel_element(e)
         case e
         when String then { kind: :serie, serie: e.to_neumas }.extend(Neuma)

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

@@ -1,9 +1,240 @@
+# String refinement for parsing neuma notation.
+#
+# Adds methods to String class for converting text-based neuma notation into
+# structured neuma objects. Uses Neumalang parser to process the notation.
+#
+# ## Neuma Notation Syntax
+#
+# Neuma notation is a compact text format for musical sequences:
+#
+# ### Grade (Pitch)
+# ```ruby
+# "0"         # Absolute grade 0
+# "+2"        # Up 2 scale steps
+# "-1"        # Down 1 scale step
+# "^3"        # Up 3 octaves
+# "v1"        # Down 1 octave
+# ```
+#
+# ### Duration
+# ```ruby
+# "_"         # Base duration
+# "_2"        # Double duration (half note if base is quarter)
+# "_/2"       # Half duration (eighth note if base is quarter)
+# "_3/2"      # 1.5x duration (dotted)
+# ```
+#
+# ### Ornaments & Articulations
+# ```ruby
+# ".tr"       # Trill
+# ".mor"      # Mordent
+# ".turn"     # Turn
+# ".st"       # Staccato
+# ```
+#
+# ### Grace Notes (Appogiatura)
+# ```ruby
+# "(+1_/4)+2_"   # Grace note +1 (1/4 duration) before main note +2
+# ```
+#
+# ### Complete Examples
+# ```ruby
+# "0 +2 +2 -1 0"              # Simple melodic sequence
+# "+2_ +2_2 +1_/2"            # With duration variations
+# "+2.tr +3.mor -1.st"        # With ornaments
+# "(+1_/4)+2_ +2_"            # With appogiatura
+# ```
+#
+# ## Parallel Notation
+#
+# Use `|` operator to create parallel (polyphonic) structures:
+# ```ruby
+# "0 +2 +4" | "+7 +5 +7"      # Two voices in parallel
+# ```
+#
+# ## Usage with Refinement
+#
+# This is a refinement - must be activated with `using`:
+# ```ruby
+# using Musa::Extension::Neumas
+#
+# melody = "0 +2 +2 -1 0".to_neumas
+# # or shorter:
+# melody = "0 +2 +2 -1 0".n
+# ```
+#
+# ## Integration with Decoders
+#
+# Parsed neumas contain GDVD (differential) data:
+# ```ruby
+# using Musa::Extension::Neumas
+#
+# neumas = "0 +2 +2 -1 0".to_neumas
+#
+# # Access parsed differential values
+# neumas.i.each do |neuma|
+#   puts "GDVD: #{neuma[:gdvd].inspect}"
+# end
+# ```
+#
+# @example Basic parsing
+#   using Musa::Extension::Neumas
+#
+#   melody = "0 +2 +2 -1 0".to_neumas
+#   # Returns series of GDVD hashes
+#
+# @example With ornaments
+#   using Musa::Extension::Neumas
+#
+#   ornate = "+2.tr +3.mor -1.st".to_neumas
+#
+# @example Parallel voices
+#   using Musa::Extension::Neumas
+#
+#   harmony = "0 +2 +4" | "+7 +5 +7"
+#
+# @example Convert to generative node
+#   using Musa::Extension::Neumas
+#
+#   node = "0 +2 +2 -1 0".nn  # to_neumas_to_node
+#
+# @see Musa::Neumalang
+# @see Musa::Neumas::Decoders::NeumaDecoder
+# @see Musa::Generative
+#
+# @api public
 require_relative '../neumalang'
 require_relative '../generative/generative-grammar'
 
 module Musa
   module Extension
+    # Namespace for neuma-related refinements.
+    #
+    # Contains refinements for String and Array to support neuma notation.
+    #
+    # ## Methods Added
+    #
+    # ### String
+    # - {String#to_neumas} - Parses neuma notation string to structured neumas
+    # - {String#to_neumas_to_node} - Parses neuma notation and converts to generative node
+    # - {String#|} - Creates parallel neuma structure
+    # - {String#neumas} - Alias for to_neumas
+    # - {String#n} - Short alias for to_neumas
+    # - {String#nn} - Short alias for to_neumas_to_node
+    #
+    # @api public
     module Neumas
+      # String refinement adding neuma parsing methods.
+      #
+      # Must be activated with `using Musa::Extension::Neumas`.
+      #
+      # @api public
+      #
+      # @!method to_neumas(decode_with: nil, debug: nil)
+      #   Parses neuma notation string to structured neumas.
+      #
+      #   Uses Neumalang parser to convert text notation into GDVD (differential)
+      #   neuma objects that can be decoded to GDV events.
+      #
+      #   @note This method is added to String via refinement. Requires `using Musa::Extension::Neumas`.
+      #
+      #   @param decode_with [Decoder, nil] optional decoder to apply immediately
+      #   @param debug [Boolean, nil] enable debug output from parser
+      #
+      #   @return [Serie, Array] parsed neuma series or array
+      #
+      #   @example Parse simple melody
+      #     using Musa::Extension::Neumas
+      #     neumas = "0 +2 +2 -1 0".to_neumas
+      #
+      #   @example Parse with immediate decoding
+      #     using Musa::Extension::Neumas
+      #     # Create a simple decoder
+      #     decoder = Musa::Neumas::Decoders::NeumaDifferentialDecoder.new
+      #     result = "0 +2 +2 -1 0".to_neumas(decode_with: decoder)
+      #
+      #   @example Parse with debug
+      #     using Musa::Extension::Neumas
+      #     neumas = "0 +2 +2".to_neumas(debug: true)
+      #
+      #   @api public
+      class ::String; end
+
+      # @!method to_neumas_to_node(decode_with: nil, debug: nil)
+      #   Parses neuma notation and converts to generative node.
+      #
+      #   Combines parsing with node conversion for use in generative grammars.
+      #
+      #   @note This method is added to String via refinement. Requires `using Musa::Extension::Neumas`.
+      #
+      #   @param decode_with [Decoder, nil] optional decoder to apply
+      #   @param debug [Boolean, nil] enable debug output
+      #
+      #   @return [Node] generative node structure
+      #
+      #   @example Convert to node for generative grammar
+      #     using Musa::Extension::Neumas
+      #     node = "0 +2 +2 -1 0".to_neumas_to_node
+      #
+      #   @see Musa::Generative
+      #
+      #   @api public
+      class ::String; end
+
+      # @!method |(other)
+      #   Creates parallel neuma structure.
+      #
+      #   Combines two neuma strings into parallel (polyphonic) structure.
+      #   Both voices are parsed and wrapped in parallel container.
+      #
+      #   @note This method is added to String via refinement. Requires `using Musa::Extension::Neumas`.
+      #
+      #   @param other [String] second neuma string to parallelize
+      #
+      #   @return [Hash] parallel neuma structure with two series
+      #
+      #   @raise [ArgumentError] if other is not a String
+      #
+      #   @example Two-voice harmony
+      #     using Musa::Extension::Neumas
+      #
+      #     melody = "0 +2 +4 +5"
+      #     bass = "-7 -5 -3 -1"
+      #     harmony = melody | bass
+      #
+      #   @api public
+      class ::String; end
+
+      # @!method neumas(decode_with: nil, debug: nil)
+      #   Alias for `to_neumas`.
+      #
+      #   @note This method is added to String via refinement. Requires `using Musa::Extension::Neumas`.
+      #
+      #   @see String#to_neumas
+      #
+      #   @api public
+      class ::String; end
+
+      # @!method n(decode_with: nil, debug: nil)
+      #   Short alias for `to_neumas`.
+      #
+      #   @note This method is added to String via refinement. Requires `using Musa::Extension::Neumas`.
+      #
+      #   @see String#to_neumas
+      #
+      #   @api public
+      class ::String; end
+
+      # @!method nn(decode_with: nil, debug: nil)
+      #   Short alias for `to_neumas_to_node`.
+      #
+      #   @note This method is added to String via refinement. Requires `using Musa::Extension::Neumas`.
+      #
+      #   @see String#to_neumas_to_node
+      #
+      #   @api public
+      class ::String; end
+
       refine String do
         def to_neumas(decode_with: nil, debug: nil)
           Musa::Neumalang::Neumalang.parse(self, decode_with: decode_with, debug: debug)
@@ -24,9 +255,10 @@ module Musa
           end
         end
 
-
         alias_method :neumas, :to_neumas
+
         alias_method :n, :to_neumas
+
         alias_method :nn, :to_neumas_to_node
       end
     end