musa-dsl 0.30.2 → 0.40.0

data/lib/musa-dsl/musicxml/builder/backup-forward.rb

@@ -4,31 +4,196 @@ module Musa
   module MusicXML
     module Builder
       module Internal
+        # Timeline rewind for polyphonic music.
+        #
+        # Backup moves the musical timeline backwards by a specified duration,
+        # allowing overlapping musical content to be written sequentially.
+        # This is essential for polyphonic music where multiple voices or staves
+        # play simultaneously.
+        #
+        # ## Use Cases
+        #
+        # **Multiple Voices**: Write voice 1, backup, then write voice 2 starting
+        # at the same timepoint.
+        #
+        # **Multi-Staff Instruments**: Write treble staff notes, backup, then write
+        # bass staff notes for the same measure.
+        #
+        # **Polyphonic Textures**: Layer independent melodic lines that share
+        # temporal alignment.
+        #
+        # ## Duration Units
+        #
+        # Duration is specified in the measure's division units (not note values).
+        # If divisions=4, then duration=8 means 8 divisions = 2 quarter notes = 1 half note.
+        #
+        # Common pattern: backup by the full measure duration to restart from the
+        # beginning of the measure.
+        #
+        # ## Workflow Example
+        #
+        # 1. Write notes for voice 1
+        # 2. Backup to measure start
+        # 3. Write notes for voice 2 (with voice: 2 parameter)
+        # 4. Optionally backup again for additional voices
+        #
+        # @example Piano with simultaneous treble and bass
+        #   measure.pitch 'D', octave: 4, duration: 4, type: 'half'
+        #   measure.pitch 'E', octave: 4, duration: 4, type: 'half'
+        #
+        #   measure.backup 8  # Rewind full measure (8 divisions)
+        #
+        #   measure.pitch 'C', octave: 3, duration: 8, type: 'whole', staff: 2
+        #
+        # @example Two voices on the same staff
+        #   measure.pitch 'C', octave: 5, duration: 2, type: 'quarter', voice: 1
+        #   measure.pitch 'D', octave: 5, duration: 2, type: 'quarter', voice: 1
+        #   measure.pitch 'E', octave: 5, duration: 2, type: 'quarter', voice: 1
+        #   measure.pitch 'F', octave: 5, duration: 2, type: 'quarter', voice: 1
+        #
+        #   measure.backup 8  # Back to measure start
+        #
+        #   measure.pitch 'E', octave: 4, duration: 4, type: 'half', voice: 2
+        #   measure.pitch 'F', octave: 4, duration: 4, type: 'half', voice: 2
+        #
+        # @example Three-voice polyphony
+        #   # Voice 1
+        #   measure.pitch 'G', octave: 5, duration: 8, type: 'whole', voice: 1
+        #
+        #   measure.backup 8
+        #
+        #   # Voice 2
+        #   measure.pitch 'C', octave: 5, duration: 8, type: 'whole', voice: 2
+        #
+        #   measure.backup 8
+        #
+        #   # Voice 3
+        #   measure.pitch 'E', octave: 4, duration: 8, type: 'whole', voice: 3
+        #
+        # @see Forward Forward navigation for skipping time
         class Backup
           include Helper::ToXML
 
+          # Creates a backup (timeline rewind).
+          #
+          # @param duration [Integer] rewind amount in division units
+          #
+          # @example Rewind full measure (divisions=4, 4/4 time)
+          #   Backup.new(8)  # 8 divisions = 2 quarter notes
+          #
+          # @example Rewind half measure
+          #   Backup.new(4)  # 4 divisions = 1 quarter note
           def initialize(duration)
             @duration = duration
           end
 
+          # Duration to rewind in division units.
+          # @return [Integer]
           attr_accessor :duration
 
+          # Generates the backup XML element.
+          #
+          # @param io [IO] output stream
+          # @param indent [Integer] indentation level
+          # @param tabs [String] tab string
+          # @return [void]
+          #
+          # @api private
           def _to_xml(io, indent:, tabs:)
             io.puts "#{tabs}<backup><duration>#{@duration.to_i}</duration></backup>"
           end
         end
 
+        # Timeline advance without producing sound.
+        #
+        # Forward moves the musical timeline forward by a specified duration
+        # without generating notes or rests. It's used for positioning within
+        # multi-voice contexts and creating invisible space.
+        #
+        # ## Use Cases
+        #
+        # **Voice Positioning**: Advance to a specific point in time before
+        # adding notes in a particular voice.
+        #
+        # **Invisible Rests**: Skip time without displaying rest symbols
+        # (useful in multi-voice scenarios where another voice fills the space).
+        #
+        # **Rhythmic Offset**: Start a voice partway through a measure without
+        # explicit rest notation.
+        #
+        # ## Duration Units
+        #
+        # Duration is specified in the measure's division units (not note values).
+        # If divisions=4, then duration=2 means 2 divisions = 1 eighth note.
+        #
+        # ## Voice and Staff
+        #
+        # Optional voice and staff parameters indicate which voice/staff the
+        # forward applies to. This helps notation software correctly position
+        # subsequent notes.
+        #
+        # @example Skip a quarter note in voice 2
+        #   measure.forward 2, voice: 2  # Skip 2 divisions in voice 2
+        #   measure.pitch 'C', octave: 5, duration: 2, type: 'quarter', voice: 2
+        #
+        # @example Offset entry on bass staff
+        #   measure.forward 4, staff: 2  # Skip half measure on bass staff
+        #   measure.pitch 'C', octave: 3, duration: 4, type: 'half', staff: 2
+        #
+        # @example Multi-voice with staggered entries
+        #   # Voice 1 starts immediately
+        #   measure.pitch 'G', octave: 5, duration: 4, type: 'half', voice: 1
+        #
+        #   measure.backup 4  # Return to measure start
+        #
+        #   # Voice 2 starts after quarter note delay
+        #   measure.forward 2, voice: 2  # Skip quarter note
+        #   measure.pitch 'E', octave: 5, duration: 2, type: 'quarter', voice: 2
+        #
+        # @see Backup Backup for timeline rewind
         class Forward
           include Helper::ToXML
 
+          # Creates a forward (timeline advance).
+          #
+          # @param duration [Integer] advance amount in division units
+          # @param voice [Integer, nil] voice number this forward applies to
+          # @param staff [Integer, nil] staff number this forward applies to
+          #
+          # @example Skip quarter note
+          #   Forward.new(2)  # 2 divisions
+          #
+          # @example Skip with voice specification
+          #   Forward.new(4, voice: 2)
+          #
+          # @example Skip on specific staff
+          #   Forward.new(4, staff: 2)
           def initialize(duration, voice: nil, staff: nil)
             @duration = duration
             @voice = voice
             @staff = staff
           end
 
-          attr_accessor :duration, :voice, :staff
+          # Duration to advance in division units.
+          # @return [Integer]
+          attr_accessor :duration
+
+          # Voice number (for multi-voice contexts).
+          # @return [Integer, nil]
+          attr_accessor :voice
+
+          # Staff number (for multi-staff instruments).
+          # @return [Integer, nil]
+          attr_accessor :staff
 
+          # Generates the forward XML element.
+          #
+          # @param io [IO] output stream
+          # @param indent [Integer] indentation level
+          # @param tabs [String] tab string
+          # @return [void]
+          #
+          # @api private
           def _to_xml(io, indent:, tabs:)
             io.puts "#{tabs}<forward>"
 

data/lib/musa-dsl/musicxml/builder/direction.rb

@@ -7,6 +7,69 @@ module Musa
       module Internal
         using Musa::Extension::Arrayfy
 
+        # Musical direction container.
+        #
+        # Direction represents performance instructions and expressive markings that
+        # affect interpretation but aren't part of the note structure. Directions
+        # include tempo, dynamics, pedaling, text instructions, and other musical
+        # indications.
+        #
+        # ## Direction Types
+        #
+        # Directions can contain multiple direction-type elements:
+        #
+        # ### Tempo and Metronome
+        # - **Metronome**: Tempo markings (♩ = 120, etc.)
+        # - **Words**: Textual tempo indications ("Allegro", "Adagio")
+        #
+        # ### Dynamics
+        # - **Dynamics**: Dynamic levels (pp, p, mp, mf, f, ff, etc.)
+        # - **Wedge**: Crescendo/diminuendo hairpins
+        #
+        # ### Pedaling
+        # - **Pedal**: Piano pedal markings (start, stop, change)
+        #
+        # ### Text and Symbols
+        # - **Words**: General text directions
+        # - **Bracket**: Analytical brackets
+        # - **Dashes**: Dashed extension lines
+        #
+        # ### Transposition
+        # - **OctaveShift**: 8va/8vb markings
+        #
+        # ## Placement
+        #
+        # Directions can be placed above or below the staff:
+        # - **above**: Above staff (typical for tempo, dynamics)
+        # - **below**: Below staff (typical for pedal markings)
+        #
+        # ## Voice and Staff
+        #
+        # For multi-voice or multi-staff contexts, directions can be associated with
+        # specific voices or staves.
+        #
+        # ## Offset
+        #
+        # Directions can have timing offsets for precise positioning relative to notes.
+        #
+        # @example Tempo marking
+        #   Direction.new(placement: 'above') do
+        #     metronome beat_unit: 'quarter', per_minute: '120'
+        #     words 'Allegro'
+        #   end
+        #
+        # @example Dynamic marking
+        #   Direction.new(placement: 'below', dynamics: 'f')
+        #
+        # @example Crescendo hairpin
+        #   Direction.new(placement: 'below') do
+        #     wedge 'crescendo'
+        #   end
+        #
+        # @example Pedal down
+        #   Direction.new(placement: 'below', pedal: 'start')
+        #
+        # @see Measure Container for directions
         class Direction
           extend Musa::Extension::AttributeBuilder
           include Musa::Extension::With
@@ -14,6 +77,28 @@ module Musa
           include Helper
           include ToXML
 
+          # Creates a direction.
+          #
+          # @param placement [String, nil] 'above' or 'below' staff
+          # @param voice [Integer, nil] voice number
+          # @param staff [Integer, nil] staff number
+          # @param offset [Numeric, nil] timing offset in divisions
+          # @param directions [Hash] direction types as keyword arguments
+          # @yield Optional DSL block for adding direction types
+          #
+          # @example Tempo with metronome
+          #   Direction.new(placement: 'above') do
+          #     metronome beat_unit: 'quarter', per_minute: '120'
+          #   end
+          #
+          # @example Forte dynamic
+          #   Direction.new(placement: 'below', dynamics: 'f')
+          #
+          # @example Multiple directions
+          #   Direction.new(placement: 'above') do
+          #     words 'Allegro con brio'
+          #     metronome beat_unit: 'quarter', per_minute: '132'
+          #   end
           def initialize(placement: nil, # above / below
                          voice: nil, # number
                          staff: nil,  # number
@@ -35,20 +120,62 @@ module Musa
             with &block if block_given?
           end
 
+          # Voice builder/setter.
+          # @return [Integer, nil]
           attr_simple_builder :voice
+
+          # Staff builder/setter.
+          # @return [Integer, nil]
           attr_simple_builder :staff
+
+          # Offset builder/setter.
+          # @return [Numeric, nil]
           attr_simple_builder :offset
+
+          # Placement builder/setter ('above' or 'below').
+          # @return [String, nil]
           attr_simple_builder :placement
 
+          # Adds a metronome marking.
+          # @see Metronome
           attr_complex_adder_to_custom(:metronome) { |*p, **kp, &b| Metronome.new(*p, **kp, &b).tap { |t| @types << t } }
+
+          # Adds a wedge (crescendo/diminuendo hairpin).
+          # @see Wedge
           attr_complex_adder_to_custom(:wedge) { |*p, **kp, &b| Wedge.new(*p, **kp, &b).tap { |t| @types << t } }
+
+          # Adds dynamics marking.
+          # @see Dynamics
           attr_complex_adder_to_custom(:dynamics) { |*p, **kp, &b| Dynamics.new(*p, **kp, &b).tap { |t| @types << t } }
+
+          # Adds pedal marking.
+          # @see Pedal
           attr_complex_adder_to_custom(:pedal) { |*p, **kp, &b| Pedal.new(*p, **kp, &b).tap { |t| @types << t } }
+
+          # Adds bracket.
+          # @see Bracket
           attr_complex_adder_to_custom(:bracket) { |*p, **kp, &b| Bracket.new(*p, **kp, &b).tap { |t| @types << t } }
+
+          # Adds dashes.
+          # @see Dashes
           attr_complex_adder_to_custom(:dashes) { |*p, **kp, &b| Dashes.new(*p, **kp, &b).tap { |t| @types << t } }
+
+          # Adds text words.
+          # @see Words
           attr_complex_adder_to_custom(:words) { |*p, **kp, &b| Words.new(*p, **kp, &b).tap { |t| @types << t } }
+
+          # Adds octave shift (8va/8vb).
+          # @see OctaveShift
           attr_complex_adder_to_custom(:octave_shift) { |*p, **kp, &b| OctaveShift.new(*p, **kp, &b).tap { |t| @types << t } }
 
+          # Generates the direction XML element.
+          #
+          # @param io [IO] output stream
+          # @param indent [Integer] indentation level
+          # @param tabs [String] tab string
+          # @return [void]
+          #
+          # @api private
           def _to_xml(io, indent:, tabs:)
             io.puts "#{tabs}<direction#{ decode_bool_or_string_attribute(@placement, 'placement') }>"
 
@@ -87,6 +214,16 @@ module Musa
 
         private_constant :DirectionType
 
+        # Metronome tempo marking direction type.
+        #
+        # Represents tempo markings with beat unit and metronome value (e.g., ♩ = 120).
+        # Supports dotted beat units.
+        #
+        # @example Quarter note = 120 BPM
+        #   metronome beat_unit: 'quarter', per_minute: '120'
+        #
+        # @example Dotted eighth = 90
+        #   metronome beat_unit: 'eighth', beat_unit_dots: 1, per_minute: '90'
         class Metronome < DirectionType
           include Helper
 
@@ -121,6 +258,19 @@ module Musa
           end
         end
 
+        # Wedge hairpin direction type for crescendo/diminuendo.
+        #
+        # Represents dynamic hairpins (crescendo <, diminuendo >).
+        # Supports niente (to/from nothing) hairpins.
+        #
+        # @example Crescendo
+        #   wedge 'crescendo'
+        #
+        # @example Diminuendo to nothing
+        #   wedge 'diminuendo', niente: true
+        #
+        # @example Stop wedge
+        #   wedge 'stop'
         class Wedge < DirectionType
           include Helper
 
@@ -141,6 +291,16 @@ module Musa
           end
         end
 
+        # Dynamic marking direction type.
+        #
+        # Represents dynamic levels (pp, p, mp, mf, f, ff, fff, etc.).
+        # Can specify multiple dynamics for compound markings.
+        #
+        # @example Single dynamic
+        #   dynamics 'f'
+        #
+        # @example Multiple dynamics (sforzando-forte)
+        #   dynamics ['sf', 'f']
         class Dynamics < DirectionType
           def initialize(value, # pp / ppp / ... or array of
                          &block)
@@ -161,6 +321,19 @@ module Musa
           end
         end
 
+        # Piano sustain pedal marking direction type.
+        #
+        # Represents pedal down/up markings. Supports start, stop, change,
+        # and continue types with optional line display.
+        #
+        # @example Pedal down
+        #   pedal 'start', line: true
+        #
+        # @example Pedal up
+        #   pedal 'stop'
+        #
+        # @example Pedal change
+        #   pedal 'change'
         class Pedal < DirectionType
           include Helper
 
@@ -182,6 +355,16 @@ module Musa
           end
         end
 
+        # Bracket direction type for analytical markings.
+        #
+        # Represents brackets used for grouping or analytical notation.
+        # Supports different line types and end styles.
+        #
+        # @example Start bracket
+        #   bracket 'start', line_end: 'down', line_type: 'solid'
+        #
+        # @example Stop bracket
+        #   bracket 'stop', line_end: 'up'
         class Bracket < DirectionType
           include Helper
 
@@ -206,6 +389,15 @@ module Musa
           end
         end
 
+        # Dashed line direction type.
+        #
+        # Represents dashed extension lines for text or other markings.
+        #
+        # @example Start dashed line
+        #   dashes 'start'
+        #
+        # @example Stop dashed line
+        #   dashes 'stop'
         class Dashes < DirectionType
           def initialize(type, # start / stop / continue
                          &block)
@@ -222,6 +414,16 @@ module Musa
           end
         end
 
+        # Text words direction type.
+        #
+        # Represents textual performance instructions or expressions.
+        # Can contain multiple text strings.
+        #
+        # @example Single text
+        #   words 'Allegro'
+        #
+        # @example Multiple texts
+        #   words ['con', 'brio']
         class Words < DirectionType
           def initialize(value, # string | Array of string
                          &block)
@@ -240,6 +442,19 @@ module Musa
           end
         end
 
+        # Octave shift direction type for 8va/8vb markings.
+        #
+        # Represents octave transposition markings (8va, 8vb, 15ma, 15mb).
+        # Type indicates up/down/stop/continue, size indicates octaves (8 or 15).
+        #
+        # @example Start 8va
+        #   octave_shift 'up', size: 8
+        #
+        # @example Start 8vb
+        #   octave_shift 'down', size: 8
+        #
+        # @example Stop octave shift
+        #   octave_shift 'stop'
         class OctaveShift < DirectionType
           include Helper
 
@@ -261,58 +476,86 @@ module Musa
           end
         end
 
+        # Accordion registration direction type (not implemented).
+        # @api private
         class AccordionRegistration < DirectionType
           include Helper::NotImplemented
         end
 
+        # Coda symbol direction type (not implemented).
+        # @api private
         class Coda < DirectionType
           include Helper::NotImplemented
         end
 
+        # Damp (mute) marking direction type (not implemented).
+        # @api private
         class Damp < DirectionType
           include Helper::NotImplemented
         end
 
+        # Damp all strings marking direction type (not implemented).
+        # @api private
         class DampAll < DirectionType
           include Helper::NotImplemented
         end
 
+        # Eye glasses symbol direction type (not implemented).
+        # @api private
         class EyeGlasses < DirectionType
           include Helper::NotImplemented
         end
 
+        # Harp pedals diagram direction type (not implemented).
+        # @api private
         class HarpPedals < DirectionType
           include Helper::NotImplemented
         end
 
+        # Embedded image direction type (not implemented).
+        # @api private
         class Image < DirectionType
           include Helper::NotImplemented
         end
 
+        # Custom/other direction type (not implemented).
+        # @api private
         class OtherDirection < DirectionType
           include Helper::NotImplemented
         end
 
+        # Percussion notation direction type (not implemented).
+        # @api private
         class Percussion < DirectionType
           include Helper::NotImplemented
         end
 
+        # Principal voice marking direction type (not implemented).
+        # @api private
         class PrincipalVoice < DirectionType
           include Helper::NotImplemented
         end
 
+        # Rehearsal mark direction type (not implemented).
+        # @api private
         class Rehearsal < DirectionType
           include Helper::NotImplemented
         end
 
+        # Scordatura (altered tuning) direction type (not implemented).
+        # @api private
         class Scordatura < DirectionType
           include Helper::NotImplemented
         end
 
+        # Segno symbol direction type (not implemented).
+        # @api private
         class Segno < DirectionType
           include Helper::NotImplemented
         end
 
+        # String mute marking direction type (not implemented).
+        # @api private
         class StringMute < DirectionType
           include Helper::NotImplemented
         end