Class: Musa::MusicXML::Builder::Internal::Forward Private

Inherits:
Object
  • Object
show all
Includes:
Helper::ToXML
Defined in:
lib/musa-dsl/musicxml/builder/backup-forward.rb

Overview

This class is part of a private API. You should avoid using this class if possible, as it may be removed or be changed in the future.

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.

Examples:

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

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

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 Also:

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(duration, voice: nil, staff: nil) ⇒ Forward

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Creates a forward (timeline advance).

Examples:

Skip quarter note

Forward.new(2)  # 2 divisions

Skip with voice specification

Forward.new(4, voice: 2)

Skip on specific staff

Forward.new(4, staff: 2)

Parameters:

  • duration (Integer) —

    advance amount in division units

  • voice (Integer, nil) (defaults to: nil) —

    voice number this forward applies to

  • staff (Integer, nil) (defaults to: nil) —

    staff number this forward applies to



178
179
180
181
182
 
# File 'lib/musa-dsl/musicxml/builder/backup-forward.rb', line 178

def initialize(duration, voice: nil, staff: nil)
  @duration = duration
  @voice = voice
  @staff = staff
end

Instance Attribute Details

#duration ⇒ Integer

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Duration to advance in division units.

Returns:

  • (Integer) 


186
187
188
 
# File 'lib/musa-dsl/musicxml/builder/backup-forward.rb', line 186

def duration
  @duration
end

#staff ⇒ Integer?

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Staff number (for multi-staff instruments).

Returns:

  • (Integer, nil) 


194
195
196
 
# File 'lib/musa-dsl/musicxml/builder/backup-forward.rb', line 194

def staff
  @staff
end

#voice ⇒ Integer?

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Voice number (for multi-voice contexts).

Returns:

  • (Integer, nil) 


190
191
192
 
# File 'lib/musa-dsl/musicxml/builder/backup-forward.rb', line 190

def voice
  @voice
end

Instance Method Details

#_to_xml(io, indent:, tabs:) ⇒ void

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

This method returns an undefined value.

Generates the forward XML element.

Parameters:

  • io (IO) —

    output stream

  • indent (Integer) —

    indentation level

  • tabs (String) —

    tab string



204
205
206
207
208
209
210
211
212
 
# File 'lib/musa-dsl/musicxml/builder/backup-forward.rb', line 204

def _to_xml(io, indent:, tabs:)
  io.puts "#{tabs}<forward>"

  io.puts "#{tabs}\t<duration>#{@duration.to_i}</duration>"
  io.puts "#{tabs}\t<voice>#{@voice.to_i}</voice>" if @voice
  io.puts "#{tabs}\t<staff>#{@staff.to_i}</staff>" if @staff

  io.puts "#{tabs}</forward>"
end

#to_xml(io = nil, indent: nil) ⇒ IO, StringIO Originally defined in module Helper::ToXML

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Converts the object to MusicXML format.

This method sets up the IO stream and indentation, then delegates to the private _to_xml method for actual XML generation.

Examples:

Writing to file

element = Measure.new(1, divisions: 2)
File.open('output.xml', 'w') do |f|
  element.to_xml(f)
end

Getting XML as string

xml_string = element.to_xml.string
xml_string.start_with?('<measure')  # => true

Parameters:

  • io (IO, StringIO, nil) (defaults to: nil) —

    output stream (creates StringIO if nil)

  • indent (Integer, nil) (defaults to: nil) —

    indentation level (default: 0)

Returns:

  • (IO, StringIO) —

    the io parameter, containing the XML output