musa-dsl 0.30.2 → 0.41.0

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

@@ -1,3 +1,112 @@
+# Musical dataset framework for MusaDSL.
+#
+# The Datasets module provides a comprehensive framework for representing and transforming
+# musical events and data structures. It supports multiple representations (MIDI-style,
+# score-style, serialized formats) and conversions between them.
+#
+# ## Architecture
+#
+# The framework consists of several layers:
+#
+# ### 1. Event Types ({E})
+#
+# Hierarchy of event types defining absolute vs. delta encoding:
+#
+# - **{E}**: Base event module
+# - **{Abs}**: Absolute values (actual pitch, duration, etc.)
+# - **{Delta}**: Delta values (incremental changes)
+# - **{AbsI}**: Absolute indexed (array-based)
+# - **{AbsTimed}**: Absolute with time component
+# - **{AbsD}**: Absolute with duration
+# - **{DeltaD}**: Delta duration (absolute/delta/factor)
+#
+# ### 2. Data Structures
+#
+# Basic container types:
+#
+# - **{V}**: Value array - simple ordered values
+# - **{PackedV}**: Packed value hash - named key-value pairs
+# - **{P}**: Pitch series - alternating values and durations
+#
+# ### 3. Musical Datasets
+#
+# Domain-specific musical representations:
+#
+# - **{PS}**: Pitch series (from/to/duration for glissandi)
+# - **{PDV}**: Pitch/Duration/Velocity (MIDI-style representation)
+# - **{GDV}**: Grade/Duration/Velocity (score-style with scale degrees)
+# - **{GDVd}**: Grade/Duration/Velocity delta (incremental encoding)
+#
+# ### 4. Score Container
+#
+# - **{Score}**: Time-indexed container for musical events
+#
+# ## Basic Usage
+#
+#     # Create a packed value (hash)
+#     pv = { a: 1, b: 2, c: 3 }.extend(Musa::Datasets::PackedV)
+#
+#     # Convert to array
+#     v = pv.to_V([:c, :b, :a])  # => [3, 2, 1]
+#
+#     # Create pitch series
+#     p = [60, 4, 64, 8, 67].extend(Musa::Datasets::P)
+#     # [pitch, duration, pitch, duration, pitch]
+#
+#     # Convert to timed series
+#     timed = p.to_timed_serie
+#
+# ## Conversion Patterns
+#
+# The framework supports rich conversions:
+#
+# - PackedV ↔ V (hash to array and vice versa)
+# - P → PS (pitch series to glissando segments)
+# - PDV ↔ GDV (MIDI to score notation)
+# - GDV ↔ GDVd (absolute to delta encoding)
+# - GDV → Neuma (score notation string format)
+#
+# @example MIDI-style pitch/duration/velocity
+#   pdv = { pitch: 60, duration: 1.0, velocity: 64 }.extend(Musa::Datasets::PDV)
+#   pdv.base_duration = 1/4r
+#
+#   # Convert to score notation using scale
+#   scale = Musa::Scales::Scales.et12[440.0].major[60]
+#   gdv = pdv.to_gdv(scale)  # Uses scale degrees
+#
+# @example Score-style grade/duration/velocity
+#   gdv = { grade: 0, duration: 1.0, velocity: 0 }.extend(Musa::Datasets::GDV)
+#   gdv.base_duration = 1/4r
+#
+#   # Convert to MIDI using scale
+#   scale = Musa::Scales::Scales.et12[440.0].major[60]
+#   pdv = gdv.to_pdv(scale)  # Converts to MIDI pitches
+#
+# @example Delta encoding for compression
+#   scale = Musa::Scales::Scales.et12[440.0].major[60]
+#   gdv1 = { grade: 0, duration: 1.0, velocity: 0 }.extend(Musa::Datasets::GDV)
+#   gdv2 = { grade: 2, duration: 1.0, velocity: 1 }.extend(Musa::Datasets::GDV)
+#
+#   gdvd = gdv2.to_gdvd(scale, previous: gdv1)
+#   # => { delta_grade: 2, delta_velocity: 1 }
+#   # Duration unchanged, so omitted
+#
+# @example Score container
+#   score = Musa::Datasets::Score.new
+#   score.at(0, add: { grade: 0, duration: 1.0 }.extend(Musa::Datasets::GDV))
+#   score.at(1, add: { grade: 2, duration: 1.0 }.extend(Musa::Datasets::GDV))
+#
+# @see E Base event type
+# @see PDV MIDI-style representation
+# @see GDV Score-style representation
+# @see Score Event container
 module Musa::Datasets
+  # Base marker module for dataset types.
+  #
+  # Dataset is a simple marker module included by various dataset types
+  # to indicate they are part of the dataset framework.
+  #
+  # @see E Event base module
+  # @see P Pitch series dataset
   module Dataset; end
 end

data/lib/musa-dsl/datasets/delta-d.rb

@@ -1,9 +1,87 @@
 require_relative 'e'
 
 module Musa::Datasets
+  # Delta events with flexible duration encoding.
+  #
+  # DeltaD (Delta Duration) extends {Delta} events with three different ways to
+  # specify duration changes in delta-encoded sequences. This provides flexibility
+  # for efficient encoding of musical sequences.
+  #
+  # ## Duration Encoding Modes
+  #
+  # **:abs_duration** - Absolute duration override
+  #
+  # Sets duration to an absolute value, regardless of previous duration.
+  # Use when duration changes to a completely different value.
+  #
+  #     { abs_duration: 2.0 }
+  #     # Sets duration to 2.0, ignoring previous
+  #
+  # **:delta_duration** - Incremental duration change
+  #
+  # Adds or subtracts from the previous duration value.
+  # Use for small adjustments to duration.
+  #
+  #     { delta_duration: 0.5 }   # Add 0.5 to previous
+  #     { delta_duration: -0.25 } # Subtract 0.25 from previous
+  #
+  # **:factor_duration** - Multiplicative duration factor
+  #
+  # Multiplies previous duration by a factor.
+  # Use for proportional changes (doubling, halving, etc.).
+  #
+  #     { factor_duration: 2 }    # Double previous duration
+  #     { factor_duration: 0.5 }  # Half previous duration
+  #
+  # ## Natural Keys
+  #
+  # - **:abs_duration**: Absolute duration value
+  # - **:delta_duration**: Duration increment/decrement
+  # - **:factor_duration**: Duration multiplication factor
+  #
+  # Only one duration key should be present at a time.
+  #
+  # ## Usage in Delta Encoding
+  #
+  # Used by {GDVd} for efficient delta encoding of musical sequences:
+  #
+  # @example Different duration encoding modes
+  #   previous = { duration: 1.0 }
+  #
+  #   # Absolute: set to specific value
+  #   delta1 = { abs_duration: 2.0 }.extend(DeltaD)
+  #   # Result: duration becomes 2.0
+  #
+  #   # Delta: add to previous
+  #   delta2 = { delta_duration: 0.5 }.extend(DeltaD)
+  #   # Result: duration becomes 1.5 (was 1.0)
+  #
+  #   # Factor: multiply previous
+  #   delta3 = { factor_duration: 2 }.extend(DeltaD)
+  #   # Result: duration becomes 2.0 (was 1.0)
+  #
+  # @example Neuma notation representation
+  #   # Absolute duration
+  #   { abs_duration: 1.5 } => "1.5"
+  #
+  #   # Delta duration
+  #   { delta_duration: 0.5 }  => "+0.5"
+  #   { delta_duration: -0.5 } => "-0.5"
+  #
+  #   # Factor duration
+  #   { factor_duration: 2 } => "*2"
+  #
+  # @see Delta Parent delta module
+  # @see GDVd Grade/Duration/Velocity delta encoding
+  # @see AbsD Absolute duration events
   module DeltaD
     include Delta
 
+    # Natural keys for delta duration encoding.
+    #
+    # Only one of these keys should be present in a delta event.
+    #
+    # @return [Array<Symbol>] natural duration keys
     NaturalKeys = [:abs_duration, # absolute duration
                    :delta_duration, # incremental duration
                    :factor_duration # multiplicative factor duration

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