musa-dsl 0.30.2 → 0.40.0

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

@@ -6,11 +6,137 @@ require_relative 'process-time'
 require_relative 'process-pdv'
 require_relative 'process-ps'
 
-module Musa::Datasets 
+module Musa::Datasets
   class Score
+    # MusicXML export for scores.
+    #
+    # ToMXML provides conversion of {Score} objects to MusicXML format,
+    # suitable for import into notation software like MuseScore, Finale,
+    # or Sibelius.
+    #
+    # ## Conversion Process
+    #
+    # 1. Creates MusicXML structure with metadata (title, creators, etc.)
+    # 2. Defines parts (instruments) with clefs and time signatures
+    # 3. Divides score into measures (bars)
+    # 4. Processes events in each measure:
+    #
+    #    - {PDV} events → notes and rests
+    #    - {PS} events → dynamics markings (crescendo, diminuendo)
+    #
+    # 5. Fills gaps with rests
+    #
+    # ## Event Types Supported
+    #
+    # - **{PDV}** (Pitch/Duration/Velocity): Converted to notes or rests
+    # - **{PS}** (Pitch Series): Converted to dynamics markings
+    #
+    # ## Multi-part Scores
+    #
+    # Scores can contain multiple instruments, differentiated by the
+    # :instrument attribute. Each part is rendered separately.
+    #
+    # ## Time Representation
+    #
+    # - Score times are 1-based (first beat is at position 1)
+    # - Each measure represents one bar
+    # - Duration is specified in beats (1.0 = quarter note if beat_type is 4)
+    #
+    # @example Basic single-part score
+    #   score = Musa::Datasets::Score.new
+    #   score.at(1r, add: { pitch: 60, duration: 1.0 }.extend(Musa::Datasets::PDV))
+    #   score.at(2r, add: { pitch: 64, duration: 1.0 }.extend(Musa::Datasets::PDV))
+    #
+    #   mxml = score.to_mxml(
+    #     4, 24,  # 4 beats per bar, 24 ticks per beat
+    #     bpm: 120,
+    #     title: 'My Song',
+    #     creators: { composer: 'John Doe' },
+    #     parts: { piano: { name: 'Piano', clefs: { g: 2 } } }
+    #   )
+    #
+    #   File.write('score.musicxml', mxml.to_xml.string)
+    #
+    # @example Multi-part score
+    #   score = Musa::Datasets::Score.new
+    #   score.at(1r, add: { instrument: :violin, pitch: 67, duration: 1.0 }.extend(Musa::Datasets::PDV))
+    #   score.at(1r, add: { instrument: :cello, pitch: 48, duration: 1.0 }.extend(Musa::Datasets::PDV))
+    #
+    #   mxml = score.to_mxml(
+    #     4, 24,
+    #     parts: {
+    #       violin: { name: 'Violin', clefs: { g: 2 } },
+    #       cello: { name: 'Cello', clefs: { f: 4 } }
+    #     }
+    #   )
+    #
+    # @example With dynamics
+    #   score = Musa::Datasets::Score.new
+    #   score.at(1r, add: { pitch: 60, duration: 2.0 }.extend(Musa::Datasets::PDV))
+    #   score.at(1r, add: { type: :crescendo, duration: 2.0 }.extend(Musa::Datasets::PS))
+    #
+    # @see Musa::MusicXML::Builder MusicXML builder
+    # @see PDV MIDI-style events
+    # @see PS Pitch series for dynamics
     module ToMXML
       using Musa::Extension::InspectNice
 
+      # Converts score to MusicXML.
+      #
+      # Creates complete MusicXML document with metadata, parts, measures,
+      # notes, rests, and dynamics markings.
+      #
+      # @param beats_per_bar [Integer] time signature numerator (e.g., 4 for 4/4)
+      # @param ticks_per_beat [Integer] resolution per beat (typically 24)
+      #
+      # @param bpm [Integer] tempo in beats per minute (default: 90)
+      # @param title [String] work title (default: 'Untitled')
+      # @param creators [Hash{Symbol => String}] creator roles and names
+      #   (default: { composer: 'Unknown' })
+      # @param encoding_date [DateTime, nil] encoding date for metadata
+      # @param parts [Hash{Symbol => Hash}] part definitions
+      #   Each part: { name: String, abbreviation: String, clefs: Hash }
+      #   Clefs: { clef_sign: line_number } (e.g., { g: 2, f: 4 } for piano)
+      # @param logger [Musa::Logger::Logger, nil] logger for debugging
+      # @param do_log [Boolean, nil] enable logging output
+      #
+      # @return [Musa::MusicXML::Builder::ScorePartwise] MusicXML document
+      #
+      # @example Simple piano score
+      #   score = Musa::Datasets::Score.new
+      #   score.at(1r, add: { pitch: 60, duration: 1.0 }.extend(Musa::Datasets::PDV))
+      #
+      #   mxml = score.to_mxml(
+      #     4, 24,
+      #     bpm: 120,
+      #     title: 'Invention',
+      #     creators: { composer: 'J.S. Bach' },
+      #     parts: { piano: { name: 'Piano', clefs: { g: 2, f: 4 } } }
+      #   )
+      #
+      # @example String quartet
+      #   score = Musa::Datasets::Score.new
+      #   score.at(1r, add: { instrument: :vln1, pitch: 67, duration: 1.0 }.extend(Musa::Datasets::PDV))
+      #   score.at(1r, add: { instrument: :vln2, pitch: 64, duration: 1.0 }.extend(Musa::Datasets::PDV))
+      #   score.at(1r, add: { instrument: :vla, pitch: 60, duration: 1.0 }.extend(Musa::Datasets::PDV))
+      #   score.at(1r, add: { instrument: :vc, pitch: 48, duration: 1.0 }.extend(Musa::Datasets::PDV))
+      #
+      #   mxml = score.to_mxml(
+      #     4, 24,
+      #     parts: {
+      #       vln1: { name: 'Violin I', abbreviation: 'Vln. I', clefs: { g: 2 } },
+      #       vln2: { name: 'Violin II', abbreviation: 'Vln. II', clefs: { g: 2 } },
+      #       vla: { name: 'Viola', abbreviation: 'Vla.', clefs: { c: 3 } },
+      #       vc: { name: 'Cello', abbreviation: 'Vc.', clefs: { f: 4 } }
+      #     }
+      #   )
+      #
+      # @example Export to file
+      #   score = Musa::Datasets::Score.new
+      #   score.at(1r, add: { pitch: 60, duration: 1.0 }.extend(Musa::Datasets::PDV))
+      #
+      #   mxml = score.to_mxml(4, 24, parts: { piano: { name: 'Piano' } })
+      #   File.write('output.musicxml', mxml.to_xml.string)
       def to_mxml(beats_per_bar, ticks_per_beat,
                   bpm: nil,
                   title: nil,
@@ -77,6 +203,24 @@ module Musa::Datasets
 
       private
 
+      # Fills a MusicXML part with measures and events.
+      #
+      # Processes each bar (measure) in the score, converting events to
+      # MusicXML notes, rests, and dynamics. Handles:
+      #
+      # - Initial silences (gaps before first event)
+      # - Event processing (PDV → notes, PS → dynamics)
+      # - Ending silences (filling remainder of measure)
+      #
+      # @param part [Musa::MusicXML::Builder::Part] MusicXML part to fill
+      # @param divisions_per_bar [Integer] total divisions in one bar
+      # @param instrument [Symbol, nil] instrument filter (nil for single-part scores)
+      # @param logger [Musa::Logger::Logger] logger for debugging
+      # @param do_log [Boolean] enable logging
+      #
+      # @return [void]
+      #
+      # @api private
       def fill_part(part, divisions_per_bar, instrument, logger, do_log)
         measure = nil
         dynamics_context = nil

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