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



171
172
173
174
175
 
# File 'lib/musa-dsl/musicxml/builder/backup-forward.rb', line 171

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) 


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

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) 


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

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) 


183
184
185
 
# File 'lib/musa-dsl/musicxml/builder/backup-forward.rb', line 183

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



197
198
199
200
201
202
203
204
205
 
# File 'lib/musa-dsl/musicxml/builder/backup-forward.rb', line 197

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

File.open('output.xml', 'w') do |f|
  element.to_xml(f)
end

Getting XML as string

xml_string = element.to_xml.string

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