musa-dsl 0.30.2 → 0.40.0

data/lib/musa-dsl/datasets/e.rb

@@ -1,70 +1,254 @@
 require_relative 'dataset'
 
 module Musa::Datasets
+  # Base module for musical events.
+  #
+  # E (Event) is the base module for all dataset types representing musical events.
+  # It provides validation interface and defines the concept of "natural keys" -
+  # keys that are inherent to the dataset type.
+  #
+  # ## Natural Keys
+  #
+  # Each dataset type defines which keys are "natural" to it (i.e., semantically
+  # meaningful for that type). Keys not in NaturalKeys are considered modifiers
+  # or extensions.
+  #
+  # ## Validation
+  #
+  # Events can be validated to ensure they contain required keys and valid values.
+  # Subclasses should override {#valid?} to implement type-specific validation.
+  #
+  # @example Basic validation
+  #   event = { pitch: 60, duration: 1.0 }.extend(Musa::Datasets::E)
+  #   event.valid?     # => true
+  #   event.validate!  # Returns if valid, raises if not
+  #
+  # @see Abs Absolute value events
+  # @see Delta Delta (incremental) events
   module E
     include Dataset
 
+    # Natural keys for base events (empty).
+    # @return [Array<Symbol>]
     NaturalKeys = [].freeze
 
-    # TODO implement valid? in all 'subclasses'. This implies recollecting from other places where validations are done and refactoring
-    # TODO should valid? and validate! be on Dataset instead of E? P dataset inherits from Dataset but probably it could be validated
+    # Checks if event is valid.
     #
+    # Base implementation always returns true. Subclasses should override
+    # to implement specific validation logic.
+    #
+    # @return [Boolean] true if valid
+    #
+    # @example
+    #   event.valid?  # => true
     def valid?
       true
     end
 
+    # Validates event, raising if invalid.
+    #
+    # @raise [RuntimeError] if event is not valid
+    # @return [void]
+    #
+    # @example
+    #   event.validate!  # Raises if invalid
     def validate!
       raise RuntimeError, "Invalid dataset #{self}" unless valid?
     end
   end
 
+  # Events with absolute values.
+  #
+  # Abs (Absolute) represents events where all values are absolute (not relative).
+  # Examples: actual MIDI pitch 60, duration 1.0 seconds, velocity 64.
+  #
+  # Contrast with {Delta} where values are incremental.
+  #
+  # @see Delta Incremental events
+  # @see AbsI Absolute indexed (arrays)
+  # @see AbsTimed Absolute with time
+  # @see AbsD Absolute with duration
   module Abs
     include E
   end
 
+  # Events with delta (incremental) values.
+  #
+  # Delta represents events where values are incremental changes from a previous
+  # state. Examples: pitch +2 semitones, duration +0.5 beats, velocity -10.
+  #
+  # Delta encoding is efficient for sequences where consecutive events have
+  # similar values.
+  #
+  # @example Delta vs Absolute
+  #   # Absolute encoding (3 events)
+  #   { pitch: 60, duration: 1.0 }
+  #   { pitch: 62, duration: 1.0 }
+  #   { pitch: 64, duration: 1.0 }
+  #
+  #   # Delta encoding (same 3 events)
+  #   { abs_pitch: 60, abs_duration: 1.0 }  # First event absolute
+  #   { delta_pitch: +2 }                    # Duration unchanged
+  #   { delta_pitch: +2 }                    # Duration unchanged
+  #
+  # @see Abs Absolute events
+  # @see DeltaD Delta with duration
   module Delta
     include E
   end
 
+  # Absolute indexed events (array-based).
+  #
+  # AbsI represents absolute events stored in indexed structures (arrays).
+  # Used by {V} and {PackedV} modules.
+  #
+  # @see Abs Parent absolute module
+  # @see V Value arrays
+  # @see PackedV Packed value hashes
   module AbsI
     include Abs
   end
 
+  # Absolute events with time component.
+  #
+  # AbsTimed represents absolute events that occur at a specific time point.
+  # The `:time` key indicates when the event occurs.
+  #
+  # ## Natural Keys
+  #
+  # - **:time**: Absolute time position
+  #
+  # @example Timed event
+  #   { time: 0.0, value: { pitch: 60 } }.extend(AbsTimed)
+  #   { time: 1.0, value: { pitch: 64 } }.extend(AbsTimed)
+  #
+  # @see Abs Parent absolute module
+  # @see P Pitch series (produces AbsTimed)
   module AbsTimed
     include Abs
 
+    # Natural keys including time.
+    # @return [Array<Symbol>]
     NaturalKeys = (NaturalKeys + [:time]).freeze
   end
 
+  # Delta indexed events (array-based deltas).
+  #
+  # DeltaI represents delta events stored in indexed structures.
+  #
+  # @see Delta Parent delta module
   module DeltaI
     include Delta
   end
 
+  # Absolute events with duration.
+  #
+  # AbsD represents absolute events that have duration - they occupy a time span
+  # rather than occurring at a single instant.
+  #
+  # ## Natural Keys
+  #
+  # - **:duration**: Total duration of the event process
+  # - **:note_duration**: Actual note duration (may differ for staccato, etc.)
+  # - **:forward_duration**: Time until next event (may be 0 for simultaneous events)
+  #
+  # ## Duration Types
+  #
+  # **duration**: How long the event process lasts (note playing, dynamics change, etc.)
+  #
+  # **note_duration**: Actual note length. For staccato, this is shorter than duration.
+  # Defaults to duration if not specified.
+  #
+  # **forward_duration**: Time to wait before next event. Can be:
+  #
+  # - Same as duration (default): next event starts when this one ends
+  # - Less than duration: events overlap
+  # - Zero: next event starts simultaneously
+  # - More than duration: gap/rest before next event
+  #
+  # @example Basic duration
+  #   { pitch: 60, duration: 1.0 }.extend(AbsD)
+  #   event.duration          # => 1.0
+  #   event.note_duration     # => 1.0 (defaults to duration)
+  #   event.forward_duration  # => 1.0 (defaults to duration)
+  #
+  # @example Staccato note
+  #   { pitch: 60, duration: 1.0, note_duration: 0.5 }.extend(AbsD)
+  #   # Note sounds for 0.5, but next event waits 1.0
+  #
+  # @example Simultaneous events
+  #   { pitch: 60, duration: 1.0, forward_duration: 0 }.extend(AbsD)
+  #   # Next event starts immediately (chord)
+  #
+  # @see Abs Parent absolute module
+  # @see PS Pitch series with duration
+  # @see PDV Pitch/Duration/Velocity
+  # @see GDV Grade/Duration/Velocity
   module AbsD
     include Abs
 
+    # Natural keys including duration variants.
+    # @return [Array<Symbol>]
     NaturalKeys = (NaturalKeys +
                    [:duration, # duration of the process (note reproduction, dynamics evolution, etc)
                     :note_duration, # duration of the note (a staccato note is effectively shorter than elapsed duration until next note)
                     :forward_duration # duration to wait until next event (if 0 means the next event should be executed at the same time than this one)
                    ]).freeze
 
+    # Returns forward duration (time until next event).
+    #
+    # Defaults to `:duration` if `:forward_duration` not specified.
+    #
+    # @return [Numeric] forward duration
+    #
+    # @example
+    #   event.forward_duration  # => 1.0
     def forward_duration
       self[:forward_duration] || self[:duration]
     end
 
+    # Returns actual note duration.
+    #
+    # Defaults to `:duration` if `:note_duration` not specified.
+    #
+    # @return [Numeric] note duration
+    #
+    # @example
+    #   event.note_duration  # => 0.5 (staccato)
     def note_duration
       self[:note_duration] || self[:duration]
     end
 
+    # Returns event duration.
+    #
+    # @return [Numeric] duration
+    #
+    # @example
+    #   event.duration  # => 1.0
     def duration
       self[:duration]
     end
 
+    # Checks if thing can be converted to AbsD.
+    #
+    # @param thing [Object] object to check
+    # @return [Boolean] true if compatible
+    #
+    # @example
+    #   AbsD.is_compatible?({ duration: 1.0 })  # => true
+    #   AbsD.is_compatible?({ pitch: 60 })      # => false
     def self.is_compatible?(thing)
       thing.is_a?(AbsD) || thing.is_a?(Hash) && thing.has_key?(:duration)
     end
 
+    # Converts thing to AbsD if possible.
+    #
+    # @param thing [Object] object to convert
+    # @return [AbsD] AbsD dataset
+    # @raise [ArgumentError] if thing cannot be converted
+    #
+    # @example
+    #   AbsD.to_AbsD({ duration: 1.0 })  # => AbsD dataset
     def self.to_AbsD(thing)
       if thing.is_a?(AbsD)
         thing

data/lib/musa-dsl/datasets/gdv.rb

@@ -5,6 +5,136 @@ require_relative 'pdv'
 require_relative 'helper'
 
 module Musa::Datasets
+  # Score-style musical events with scale degrees.
+  #
+  # GDV (Grade/Duration/Velocity) represents musical events using score notation
+  # with scale degrees, octaves, and dynamics. Extends {AbsD} for duration support.
+  #
+  # ## Purpose
+  #
+  # GDV is the score representation layer of the dataset framework:
+  #
+  # - Uses scale degrees (grade) instead of absolute pitches
+  # - Uses dynamics markings (velocity -5 to +4) instead of MIDI velocity
+  # - Human-readable and musically meaningful
+  # - Independent of specific tuning or scale
+  #
+  # Contrast with {PDV} which uses MIDI absolute pitches and velocities.
+  #
+  # ## Natural Keys
+  #
+  # - **:grade**: Scale degree (integer, 0-based)
+  # - **:sharps**: Chromatic alteration (integer, positive = sharp, negative = flat)
+  # - **:octave**: Octave offset (integer, 0 = base octave)
+  # - **:velocity**: Dynamics (-3 to +4, where 0 = mp, 1 = mf)
+  # - **:silence**: Indicates rest (boolean or symbol)
+  # - **:duration**: Event duration (from {AbsD})
+  # - **:note_duration**, **:forward_duration**: Additional duration keys (from {AbsD})
+  #
+  # ## Pitch Representation
+  #
+  # Pitches are specified as:
+  #
+  # - **grade**: Position in scale (0 = first note, 1 = second note, etc.)
+  # - **octave**: Octave offset (0 = base, 1 = up one octave, -1 = down one octave)
+  # - **sharps**: Chromatic alteration (1 = sharp, -1 = flat, 2 = double sharp, etc.)
+  #
+  # Example in C major scale:
+  #
+  # - C4 = { grade: 0, octave: 0 }
+  # - D4 = { grade: 1, octave: 0 }
+  # - C5 = { grade: 0, octave: 1 }
+  # - C#4 = { grade: 0, octave: 0, sharps: 1 }
+  #
+  # ## Velocity (Dynamics)
+  #
+  # Velocity represents musical dynamics in range -3 to +4:
+  #
+  #     -3: ppp (pianississimo)
+  #     -2: pp  (pianissimo)
+  #     -1: p   (piano)
+  #      0: mp  (mezzo-piano)
+  #     +1: mf  (mezzo-forte)
+  #     +2: f   (forte)
+  #     +3: ff  (fortissimo)
+  #     +4: fff (fortississimo)
+  #
+  # ## Conversions
+  #
+  # ### To PDV (MIDI)
+  #
+  # Converts score notation to MIDI using a scale:
+  #
+  #     gdv = { grade: 0, octave: 0, duration: 1.0, velocity: 0 }.extend(GDV)
+  #     scale = Musa::Scales::Scales.et12[440.0].major[60]
+  #     pdv = gdv.to_pdv(scale)
+  #     # => { pitch: 60, duration: 1.0, velocity: 64 }
+  #
+  # ### To GDVd (Delta Encoding)
+  #
+  # Converts to delta encoding for efficient storage:
+  #
+  #     gdv1 = { grade: 0, octave: 0, duration: 1.0, velocity: 0 }.extend(GDV)
+  #     gdv2 = { grade: 2, octave: 0, duration: 1.0, velocity: 1 }.extend(GDV)
+  #     gdvd = gdv2.to_gdvd(scale, previous: gdv1)
+  #     # => { delta_grade: 2, delta_velocity: 1 }
+  #
+  # ### To Neuma Notation
+  #
+  # Converts to Neuma string format for serialization:
+  #
+  #     gdv = { grade: 0, duration: 1.0, velocity: 0 }.extend(GDV)
+  #     gdv.base_duration = 1/4r
+  #     gdv.to_neuma  # => "(0 4 mp)"
+  #
+  # ## MIDI Velocity Mapping
+  #
+  # Dynamics are mapped to MIDI velocities using interpolation:
+  #
+  #     -3 (ppp) →  16
+  #     -2 (pp)  →  33
+  #     -1 (p)   →  49
+  #      0 (mp)  →  64
+  #     +1 (mf)  →  80
+  #     +2 (f)   →  96
+  #     +3 (ff)  → 112
+  #     +4 (fff) → 127
+  #
+  # @example Basic score event
+  #   gdv = { grade: 0, octave: 0, duration: 1.0, velocity: 0 }.extend(Musa::Datasets::GDV)
+  #   gdv.base_duration = 1/4r
+  #   # First scale degree, base octave, 1 beat, mp dynamics
+  #
+  # @example Chromatic alteration
+  #   gdv = { grade: 0, octave: 0, sharps: 1, duration: 1.0 }.extend(GDV)
+  #   # First scale degree sharp (C# in C major)
+  #
+  # @example Silence (rest)
+  #   gdv = { grade: :silence, duration: 1.0 }.extend(GDV)
+  #   # Rest for 1 beat
+  #
+  # @example Convert to MIDI
+  #   gdv = { grade: 0, octave: 0, duration: 1.0, velocity: 0 }.extend(GDV)
+  #   scale = Musa::Scales::Scales.et12[440.0].major[60]
+  #   pdv = gdv.to_pdv(scale)
+  #   # => { pitch: 60, duration: 1.0, velocity: 64 }
+  #
+  # @example Convert to delta encoding
+  #   gdv1 = { grade: 0, duration: 1.0, velocity: 0 }.extend(GDV)
+  #   gdv2 = { grade: 2, duration: 1.0, velocity: 1 }.extend(GDV)
+  #   scale = Musa::Scales::Scales.et12[440.0].major[60]
+  #   gdvd = gdv2.to_gdvd(scale, previous: gdv1)
+  #   # => { delta_grade: 2, delta_velocity: 1 }
+  #
+  # @example Convert to Neuma notation
+  #   gdv = { grade: 0, octave: 1, duration: 1.0, velocity: 2 }.extend(GDV)
+  #   gdv.base_duration = 1/4r
+  #   gdv.to_neuma  # => "(0 o1 4 ff)"
+  #
+  # @see PDV MIDI-style representation
+  # @see GDVd Delta encoding
+  # @see AbsD Absolute duration events
+  # @see Helper String formatting utilities
   module GDV
     using Musa::Extension::InspectNice
 
@@ -12,14 +142,60 @@ module Musa::Datasets
 
     include Helper
 
+    # Natural keys for score events.
+    # @return [Array<Symbol>]
     NaturalKeys = (NaturalKeys + [:grade, :sharps, :octave, :velocity, :silence]).freeze
 
+    # Base duration for time calculations.
+    # @return [Rational]
     attr_accessor :base_duration
 
+    # MIDI velocity mapping for dynamics.
+    #
+    # Maps dynamics values (-5 to +4) to MIDI velocities (0-127).
+    # Used for interpolation in {#to_pdv}.
+    #
+    # @return [Array<Integer>] MIDI velocity breakpoints
+    # @api private
     # TODO create a customizable MIDI velocity to score dynamics bidirectional conversor
     # ppp = 16 ... fff = 127 (-5 ... 4) the standard used by Musescore 3 and others starts at ppp = 16
     VELOCITY_MAP = [1, 8, 16, 33, 49, 64, 80, 96, 112, 127].freeze
 
+    # Converts to PDV (MIDI representation).
+    #
+    # Translates score notation to MIDI using a scale:
+    # - Scale degree → MIDI pitch (via scale lookup)
+    # - Dynamics → MIDI velocity (via interpolation)
+    # - Duration values copied
+    # - Additional keys preserved
+    #
+    # @param scale [Musa::Scales::Scale] reference scale for pitch conversion
+    #
+    # @return [PDV] MIDI representation dataset
+    #
+    # @example Basic conversion
+    #   gdv = { grade: 0, octave: 0, duration: 1.0, velocity: 0 }.extend(GDV)
+    #   scale = Musa::Scales::Scales.et12[440.0].major[60]
+    #   pdv = gdv.to_pdv(scale)
+    #   # => { pitch: 60, duration: 1.0, velocity: 64 }
+    #
+    # @example Chromatic note
+    #   gdv = { grade: 0, octave: 0, sharps: 1, duration: 1.0 }.extend(GDV)
+    #   scale = Musa::Scales::Scales.et12[440.0].major[60]
+    #   pdv = gdv.to_pdv(scale)
+    #   # => { pitch: 61, duration: 1.0 }
+    #
+    # @example Silence
+    #   gdv = { grade: :silence, duration: 1.0 }.extend(GDV)
+    #   scale = Musa::Scales::Scales.et12[440.0].major[60]
+    #   pdv = gdv.to_pdv(scale)
+    #   # => { pitch: :silence, duration: 1.0 }
+    #
+    # @example Dynamics interpolation
+    #   gdv = { grade: 0, velocity: 0.5 }.extend(GDV)
+    #   scale = Musa::Scales::Scales.et12[440.0].major[60]
+    #   pdv = gdv.to_pdv(scale)
+    #   # velocity 0.5 interpolates between mf (64) and f (80)
     def to_pdv(scale)
       pdv = {}.extend PDV
       pdv.base_duration = @base_duration
@@ -50,7 +226,7 @@ module Musa::Datasets
                 else
                   self[:velocity] < -5 ? -5 : 4
                 end
-        
+
         index_min = index.floor
         index_max = index.ceil
 
@@ -65,6 +241,51 @@ module Musa::Datasets
       pdv
     end
 
+    # Converts to Neuma notation string.
+    #
+    # Neuma is a compact text format for score notation. Format:
+    #
+    #     (grade[sharps] [octave] [duration] [velocity] [modifiers...])
+    #
+    # - **grade**: Scale degree number (0, 1, 2...) or 'silence' for rests
+    # - **sharps**: '#' for sharp, '_' for flat (e.g., "0#" = first degree sharp)
+    # - **octave**: 'o' + number (e.g., "o1" = up one octave, "o-1" = down one)
+    # - **duration**: Number of base_duration units
+    # - **velocity**: Dynamics string (ppp, pp, p, mp, mf, f, ff, fff)
+    # - **modifiers**: Additional key-value pairs (e.g., "staccato")
+    #
+    # @return [String] Neuma notation
+    #
+    # @example Basic note
+    #   gdv = { grade: 0, duration: 1.0, velocity: 0 }.extend(GDV)
+    #   gdv.base_duration = 1/4r
+    #   gdv.to_neuma  # => "(0 4 mf)"
+    #   # grade 0, duration 4 quarters, mf dynamics
+    #
+    # @example With octave
+    #   gdv = { grade: 2, octave: 1, duration: 0.5, velocity: 2 }.extend(GDV)
+    #   gdv.base_duration = 1/4r
+    #   gdv.to_neuma  # => "(2 o1 2 ff)"
+    #
+    # @example Sharp note
+    #   gdv = { grade: 0, sharps: 1, duration: 1.0 }.extend(GDV)
+    #   gdv.base_duration = 1/4r
+    #   gdv.to_neuma  # => "(0# 4)"
+    #
+    # @example Flat note
+    #   gdv = { grade: 1, sharps: -1, duration: 1.0 }.extend(GDV)
+    #   gdv.base_duration = 1/4r
+    #   gdv.to_neuma  # => "(1_ 4)"
+    #
+    # @example Silence
+    #   gdv = { grade: :silence, duration: 1.0 }.extend(GDV)
+    #   gdv.base_duration = 1/4r
+    #   gdv.to_neuma  # => "(silence 4)"
+    #
+    # @example With modifiers
+    #   gdv = { grade: 0, duration: 1.0, staccato: true }.extend(GDV)
+    #   gdv.base_duration = 1/4r
+    #   gdv.to_neuma  # => "(0 4 staccato)"
     def to_neuma
       @base_duration ||= Rational(1, 4)
 
@@ -80,7 +301,7 @@ module Musa::Datasets
           if self[:sharps] > 0
             attributes[c] += '#' * self[:sharps]
           elsif self[:sharps] < 0
-            attributes[c] += '_' * self[:sharps]
+            attributes[c] += '_' * self[:sharps].abs
           end
         end
       end
@@ -98,12 +319,68 @@ module Musa::Datasets
       '(' + attributes.join(' ') + ')'
     end
 
+    # Converts velocity number to dynamics string.
+    #
+    # Maps numeric velocity (-3 to +4) to standard dynamics markings.
+    #
+    # @param x [Integer] velocity value
+    # @return [String] dynamics marking
+    #
+    # @example
+    #   velocity_of(-3)  # => "ppp"
+    #   velocity_of(0)   # => "mp"
+    #   velocity_of(1)   # => "mf"
+    #   velocity_of(4)   # => "fff"
+    #
+    # @api private
     def velocity_of(x)
       %w[ppp pp p mp mf f ff fff][x + 3]
     end
 
     private :velocity_of
 
+    # Converts to GDVd (delta encoding).
+    #
+    # Creates delta-encoded representation relative to a previous event.
+    # Only changed values are included, making the representation compact.
+    #
+    # Without previous event (first in sequence):
+    # - Uses abs_ keys for all values
+    #
+    # With previous event:
+    # - Uses delta_ keys for changed values
+    # - Omits unchanged values
+    # - Uses abs_ keys when changing from nil to value
+    #
+    # @param scale [Musa::Scales::Scale] reference scale for grade calculation
+    # @param previous [GDV, nil] previous event for delta calculation
+    #
+    # @return [GDVd] delta-encoded dataset
+    #
+    # @example First event (no previous)
+    #   gdv = { grade: 0, duration: 1.0, velocity: 0 }.extend(GDV)
+    #   gdvd = gdv.to_gdvd(scale)
+    #   # => { abs_grade: 0, abs_duration: 1.0, abs_velocity: 0 }
+    #
+    # @example Changed values
+    #   gdv1 = { grade: 0, duration: 1.0, velocity: 0 }.extend(GDV)
+    #   gdv2 = { grade: 2, duration: 1.0, velocity: 1 }.extend(GDV)
+    #   gdvd = gdv2.to_gdvd(scale, previous: gdv1)
+    #   # => { delta_grade: 2, delta_velocity: 1 }
+    #   # duration unchanged, so omitted
+    #
+    # @example Unchanged values
+    #   gdv1 = { grade: 0, duration: 1.0, velocity: 0 }.extend(GDV)
+    #   gdv2 = { grade: 0, duration: 1.0, velocity: 0 }.extend(GDV)
+    #   gdvd = gdv2.to_gdvd(scale, previous: gdv1)
+    #   # => {}
+    #   # Everything unchanged
+    #
+    # @example Chromatic alteration
+    #   gdv1 = { grade: 0, octave: 0 }.extend(GDV)
+    #   gdv2 = { grade: 0, octave: 0, sharps: 1 }.extend(GDV)
+    #   gdvd = gdv2.to_gdvd(scale, previous: gdv1)
+    #   # => { delta_sharps: 1 }
     def to_gdvd(scale, previous: nil)
       gdvd = {}.extend GDVd
       gdvd.base_duration = @base_duration