musa-dsl 0.30.2 → 0.41.0

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

@@ -7,6 +7,78 @@ require_relative 'score/render'
 require_relative '../core-ext/inspect-nice'
 
 module Musa::Datasets
+  # Time-indexed container for musical events.
+  #
+  # Score organizes musical events along a timeline, storing them at specific
+  # time points and providing efficient queries for time intervals.
+  # Implements `Enumerable` for iteration over time slots.
+  #
+  # ## Purpose
+  #
+  # Score provides:
+  #
+  # - **Time-indexed storage**: Events organized by start time (Rational)
+  # - **Interval queries**: Find events in time ranges ({#between}, {#changes_between})
+  # - **Duration tracking**: Automatically tracks event durations
+  # - **Export formats**: MusicXML export via {ToMXML}
+  # - **Rendering**: MIDI rendering via {Render}
+  # - **Filtering**: Create subsets via {#subset}
+  #
+  # ## Structure
+  #
+  # Internally maintains two structures:
+  #
+  # - **@score**: Hash mapping time → Array of events
+  # - **@indexer**: Array of { start, finish, dataset } for interval queries
+  #
+  # ## Event Requirements
+  #
+  # Events must:
+  #
+  # - Extend {Abs} (absolute values, not deltas)
+  # - Have a :duration key (from {AbsD})
+  #
+  # ## Time Representation
+  #
+  # All times are stored as Rational numbers for exact arithmetic:
+  #
+  #     score.at(0r, add: event)    # At time 0
+  #     score.at(1/4r, add: event)  # At quarter note
+  #
+  # @example Create empty score
+  #   score = Musa::Datasets::Score.new
+  #
+  # @example Create from hash
+  #   score = Score.new({
+  #     0r => [{ pitch: 60, duration: 1.0 }.extend(PDV)],
+  #     1r => [{ pitch: 64, duration: 1.0 }.extend(PDV)]
+  #   })
+  #
+  # @example Add events
+  #   score = Score.new
+  #   gdv1 = { grade: 0, duration: 1.0 }.extend(GDV)
+  #   gdv2 = { grade: 2, duration: 1.0 }.extend(GDV)
+  #   score.at(0r, add: gdv1)
+  #   score.at(1r, add: gdv2)
+  #
+  # @example Query time interval
+  #   events = score.between(0r, 2r)
+  #   # Returns all events starting in [0, 2) or overlapping interval
+  #
+  # @example Filter events
+  #   high_notes = score.subset { |event| event[:pitch] > 60 }
+  #
+  # @example Get all positions
+  #   score.positions  # => [0r, 1r, 2r, ...]
+  #
+  # @example Get duration
+  #   score.duration  # => Latest finish time - 1r
+  #
+  # @see Abs Absolute events (required for score)
+  # @see AbsD Duration events (provides :duration)
+  # @see ToMXML MusicXML export
+  # @see Render MIDI rendering
+  # @see Queriable Query capabilities
   class Score
     include Enumerable
 
@@ -19,6 +91,21 @@ module Musa::Datasets
 
     using Musa::Extension::InspectNice
 
+    # Creates new score.
+    #
+    # @param hash [Hash{Rational => Array<Abs>}, nil] optional initial events
+    #   Hash mapping times to arrays of events
+    #
+    # @raise [ArgumentError] if hash values aren't Arrays
+    #
+    # @example Empty score
+    #   score = Score.new
+    #
+    # @example With initial events
+    #   score = Score.new({
+    #     0r => [{ pitch: 60, duration: 1.0 }.extend(PDV)],
+    #     1r => [{ pitch: 64, duration: 1.0 }.extend(PDV)]
+    #   })
     def initialize(hash = nil)
       raise ArgumentError, "'hash' parameter should be a Hash with time and events information" unless hash.nil? || hash.is_a?(Hash)
 
@@ -36,25 +123,79 @@ module Musa::Datasets
       end
     end
 
+    # Clears all events from score.
+    #
+    # @return [void]
+    #
+    # @example
+    #   score.reset
+    #   score.size  # => 0
     def reset
       @score.clear
       @indexer.clear
     end
 
+    # Gets attribute value.
+    #
+    # Supports accessing natural keys like :duration, :finish.
+    #
+    # @param key [Symbol] attribute name
+    # @return [Object, nil] attribute value
+    #
+    # @api private
     def [](key)
       if NaturalKeys.include?(key) && self.respond_to?(key)
         self.send(key)
       end
     end
 
+    # Returns latest finish time of all events.
+    #
+    # @return [Rational, nil] latest finish time, or nil if score is empty
+    #
+    # @example
+    #   score.at(0r, add: { duration: 2.0 }.extend(AbsD))
+    #   score.finish  # => 2r
     def finish
       @indexer.collect { |i| i[:finish] }.max
     end
 
+    # Returns total duration of score.
+    #
+    # Calculated as finish time minus 1.
+    #
+    # @return [Rational] total duration
+    #
+    # @example
+    #   score.at(0r, add: { duration: 2.0 }.extend(AbsD))
+    #   score.duration  # => 1r (finish 2r - 1r)
     def duration
       (finish || 1r) - 1r
     end
 
+    # Adds event at time or gets time slot.
+    #
+    # Without add parameter, returns array of events at that time.
+    # With add parameter, adds event to that time slot.
+    #
+    # @param time [Numeric] time position (converted to Rational)
+    # @param add [Abs, nil] event to add (must extend {Abs} and have :duration)
+    #
+    # @return [Array<Abs>, nil] time slot if no add, nil if adding
+    #
+    # @raise [ArgumentError] if add is not an Abs dataset
+    #
+    # @example Add event
+    #   gdv = { grade: 0, duration: 1.0 }.extend(GDV)
+    #   score.at(0r, add: gdv)
+    #
+    # @example Get time slot
+    #   events = score.at(0r)  # => Array of events at time 0
+    #
+    # @example Multiple events at same time (chord)
+    #   score.at(0r, add: { pitch: 60, duration: 1.0 }.extend(PDV))
+    #   score.at(0r, add: { pitch: 64, duration: 1.0 }.extend(PDV))
+    #   score.at(0r).size  # => 2
     def at(time, add: nil)
       time = time.rationalize
 
@@ -75,22 +216,88 @@ module Musa::Datasets
       end
     end
 
+    # Returns number of time positions.
+    #
+    # @return [Integer] number of distinct time positions
+    #
+    # @example
+    #   score.at(0r, add: event1)
+    #   score.at(0r, add: event2)  # Same time
+    #   score.at(1r, add: event3)  # Different time
+    #   score.size  # => 2 (two time positions)
     def size
       @score.keys.size
     end
 
+    # Returns all time positions sorted.
+    #
+    # @return [Array<Rational>] sorted time positions
+    #
+    # @example
+    #   score.at(1r, add: event1)
+    #   score.at(0r, add: event2)
+    #   score.positions  # => [0r, 1r]
     def positions
       @score.keys.sort
     end
 
+    # Iterates over time slots in order.
+    #
+    # Yields [time, events] pairs sorted by time.
+    # Implements `Enumerable`.
+    #
+    # @yieldparam time [Rational] time position
+    # @yieldparam events [Array<Abs>] events at that time
+    #
+    # @return [void]
+    #
+    # @example
+    #   score.each do |time, events|
+    #     puts "At #{time}: #{events.size} event(s)"
+    #   end
     def each(&block)
       @score.sort.each(&block)
     end
 
+    # Converts to hash representation.
+    #
+    # @return [Hash{Rational => Array<Abs>}] time → events mapping
+    #
+    # @example
+    #   hash = score.to_h
+    #   # => { 0r => [event1, event2], 1r => [event3] }
     def to_h
       @score.sort.to_h
     end
 
+    # Queries events overlapping time interval.
+    #
+    # Returns events that are active (playing) during the interval [start, finish).
+    # Interval uses closed start (included) and open finish (excluded).
+    #
+    # Events are included if they:
+    # - Start before interval finish AND finish after interval start
+    # - OR are instant events (start == finish) at interval instant
+    #
+    # @param closed_interval_start [Rational] interval start (included)
+    # @param open_interval_finish [Rational] interval finish (excluded)
+    #
+    # @return [Array<Hash>] array of event info hashes with:
+    #   - **:start**: Event start time
+    #   - **:finish**: Event finish time
+    #   - **:start_in_interval**: Effective start within interval
+    #   - **:finish_in_interval**: Effective finish within interval
+    #   - **:dataset**: The event dataset
+    #
+    # @example Query bar
+    #   events = score.between(0r, 4r)
+    #   # Returns all events overlapping [0, 4)
+    #
+    # @example Long note spans interval
+    #   score.at(0r, add: { duration: 10.0 }.extend(AbsD))
+    #   events = score.between(2r, 4r)
+    #   # Event included (started before 4, finishes after 2)
+    #   # start_in_interval: 2r, finish_in_interval: 4r
     def between(closed_interval_start, open_interval_finish)
       @indexer
         .select { |i| i[:start] < open_interval_finish && i[:finish] > closed_interval_start ||
@@ -107,6 +314,37 @@ module Musa::Datasets
 
     # TODO hay que implementar un effective_start y effective_finish con el inicio/fin dentro del bar, no absoluto
 
+    # Queries start/finish change events in interval.
+    #
+    # Returns timeline of note-on/note-off style events for the interval.
+    # Useful for real-time rendering or event-based processing.
+    #
+    # Returns events sorted by time, with :finish events before :start
+    # events at the same time (to avoid gaps).
+    #
+    # @param closed_interval_start [Rational] interval start (included)
+    # @param open_interval_finish [Rational] interval finish (excluded)
+    #
+    # @return [Array<Hash>] array of change event hashes with:
+    #   - **:change**: :start or :finish
+    #   - **:time**: When change occurs
+    #   - **:start**: Event start time
+    #   - **:finish**: Event finish time
+    #   - **:start_in_interval**: Effective start within interval
+    #   - **:finish_in_interval**: Effective finish within interval
+    #   - **:time_in_interval**: Effective change time within interval
+    #   - **:dataset**: The event dataset
+    #
+    # @example Get all changes in bar
+    #   changes = score.changes_between(0r, 4r)
+    #   changes.each do |change|
+    #     case change[:change]
+    #     when :start
+    #       puts "Note ON at #{change[:time]}"
+    #     when :finish
+    #       puts "Note OFF at #{change[:time]}"
+    #     end
+    #   end
     def changes_between(closed_interval_start, open_interval_finish)
       (
         #
@@ -161,6 +399,21 @@ module Musa::Datasets
                          dataset: i[:dataset] } }.extend(QueryableByDataset)
     end
 
+    # Collects all values for an attribute.
+    #
+    # Returns set of all unique values across all events.
+    #
+    # @param attribute [Symbol] attribute key
+    #
+    # @return [Set] set of unique values
+    #
+    # @example Get all pitches
+    #   pitches = score.values_of(:pitch)
+    #   # => #<Set: {60, 64, 67}>
+    #
+    # @example Get all grades
+    #   grades = score.values_of(:grade)
+    #   # => #<Set: {0, 2, 4}>
     def values_of(attribute)
       values = Set[]
       @score.each_value do |slot|
@@ -169,6 +422,25 @@ module Musa::Datasets
       values
     end
 
+    # Creates filtered subset of score.
+    #
+    # Returns new Score containing only events matching the condition.
+    #
+    # @yieldparam dataset [Abs] each event dataset
+    # @yieldreturn [Boolean] true to include event
+    #
+    # @return [Score] new filtered score
+    #
+    # @raise [ArgumentError] if no block given
+    #
+    # @example Filter by pitch
+    #   high_notes = score.subset { |event| event[:pitch] > 60 }
+    #
+    # @example Filter by attribute presence
+    #   staccato_notes = score.subset { |event| event[:staccato] }
+    #
+    # @example Filter by grade
+    #   tonic_notes = score.subset { |event| event[:grade] == 0 }
     def subset
       raise ArgumentError, "subset needs a block with the inclusion condition on the dataset" unless block_given?
 
@@ -183,6 +455,13 @@ module Musa::Datasets
       filtered_score
     end
 
+    # Returns formatted string representation.
+    #
+    # Produces multiline representation suitable for inspection.
+    #
+    # @return [String] formatted score representation
+    #
+    # @api private
     def inspect
       s = StringIO.new
 

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

@@ -2,9 +2,97 @@ require_relative 'dataset'
 require_relative 'packed-v'
 
 module Musa::Datasets
+  # Array-based dataset with named key conversion.
+  #
+  # V (Value) represents datasets stored as arrays (indexed values).
+  # Extends {AbsI} for absolute indexed events.
+  #
+  # ## Purpose
+  #
+  # V provides efficient array-based storage for ordered values and conversion
+  # to named key-value pairs ({PackedV}). This is useful for:
+  #
+  # - Compact storage of sequential values
+  # - Converting between array and hash representations
+  # - Filtering default values during conversion
+  #
+  # ## Conversion to PackedV
+  #
+  # The {#to_packed_V} method converts arrays to hashes using a mapper that
+  # defines the correspondence between array indices and hash keys.
+  #
+  # ### Array Mapper
+  #
+  # Array mapper defines key names for each position. Position i maps to mapper[i].
+  #
+  #     v = [3, 2, 1].extend(Musa::Datasets::V)
+  #     pv = v.to_packed_V([:c, :b, :a])
+  #     # => { c: 3, b: 2, a: 1 }
+  #
+  # - `nil` mapper entries skip that position
+  # - `nil` values skip that position
+  #
+  # ### Hash Mapper
+  #
+  # Hash mapper defines both key names (keys) and default values (values).
+  # Position i maps to key mapper.keys[i] with default mapper.values[i].
+  #
+  #     v = [3, 2, 1, 400].extend(Musa::Datasets::V)
+  #     pv = v.to_packed_V({ c: 100, b: 200, a: 300, d: 400 })
+  #     # => { c: 3, b: 2, a: 1 }
+  #     # d: 400 omitted because it equals default
+  #
+  # Values matching their defaults are omitted for compression.
+  #
+  # @example Basic array to hash conversion
+  #   v = [60, 1.0, 64].extend(Musa::Datasets::V)
+  #   pv = v.to_packed_V([:pitch, :duration, :velocity])
+  #   # => { pitch: 60, duration: 1.0, velocity: 64 }
+  #
+  # @example With nil mapper (skip position)
+  #   v = [3, 2, 1].extend(Musa::Datasets::V)
+  #   pv = v.to_packed_V([:c, nil, :a])
+  #   # => { c: 3, a: 1 }
+  #   # Position 1 (value 2) skipped
+  #
+  # @example With nil value (skip position)
+  #   v = [3, nil, 1].extend(Musa::Datasets::V)
+  #   pv = v.to_packed_V([:c, :b, :a])
+  #   # => { c: 3, a: 1 }
+  #   # Position 1 (nil value) skipped
+  #
+  # @example Hash mapper with defaults (compression)
+  #   v = [3, 2, 1, 400].extend(Musa::Datasets::V)
+  #   pv = v.to_packed_V({ c: 100, b: 200, a: 300, d: 400 })
+  #   # => { c: 3, b: 2, a: 1 }
+  #   # d omitted because value 400 equals default 400
+  #
+  # @example Partial mapper (fewer keys than values)
+  #   v = [3, 2, 1].extend(Musa::Datasets::V)
+  #   pv = v.to_packed_V([:c, :b])
+  #   # => { c: 3, b: 2 }
+  #   # Position 2 (value 1) skipped - no mapper
+  #
+  # @see PackedV Hash-based dataset (inverse)
+  # @see AbsI Parent absolute indexed module
   module V
     include AbsI
 
+    # Converts array to packed hash (PackedV).
+    #
+    # @param mapper [Array<Symbol>, Hash{Symbol => Object}] key mapping
+    #   - Array: maps indices to keys (nil skips)
+    #   - Hash: maps indices to keys (keys) with defaults (values)
+    #
+    # @return [PackedV] packed hash dataset
+    #
+    # @raise [ArgumentError] if mapper is not Array or Hash
+    #
+    # @example Array mapper
+    #   v.to_packed_V([:pitch, :duration])
+    #
+    # @example Hash mapper with defaults
+    #   v.to_packed_V({ pitch: 60, duration: 1.0 })
     def to_packed_V(mapper)
       case mapper
       when Hash