Class: Musa::MusicXML::Builder::Internal::Direction Private

Inherits:
Object
  • Object
show all
Extended by:
Extension::AttributeBuilder
Includes:
Extension::With, Helper, ToXML
Defined in:
lib/musa-dsl/musicxml/builder/direction.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.

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.

Examples:

Tempo marking

Direction.new(placement: 'above') do
  metronome beat_unit: 'quarter', per_minute: '120'
  words 'Allegro'
end

Dynamic marking

Direction.new(placement: 'below', dynamics: 'f')

Crescendo hairpin

Direction.new(placement: 'below') do
  wedge 'crescendo'
end

Pedal down

Direction.new(placement: 'below', pedal: 'start')

See Also:

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(placement: nil, voice: nil, staff: nil, offset: nil, **directions) { ... } ⇒ Direction

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 direction.

Examples:

Tempo with metronome

Direction.new(placement: 'above') do
  metronome beat_unit: 'quarter', per_minute: '120'
end

Forte dynamic

Direction.new(placement: 'below', dynamics: 'f')

Multiple directions

Direction.new(placement: 'above') do
  words 'Allegro con brio'
  metronome beat_unit: 'quarter', per_minute: '132'
end

Parameters:

  • placement (String, nil) (defaults to: nil) —

    'above' or 'below' staff

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

    voice number

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

    staff number

  • offset (Numeric, nil) (defaults to: nil) —

    timing offset in divisions

  • directions (Hash) —

    direction types as keyword arguments

Yields:

  • Optional DSL block for adding direction types



102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
 
# File 'lib/musa-dsl/musicxml/builder/direction.rb', line 102

def initialize(placement: nil, # above / below
               voice: nil, # number
               staff: nil,  # number
               offset: nil, # number
               **directions,
               &block)

  @placement = placement

  @types = []
  @voice = voice
  @staff = staff
  @offset = offset

  directions.each_pair do |direction, value|
    send direction, value
  end

  with &block if block_given?
end

Class Method Details

.attr_complex_adder_to_array(name, klass, plural: nil, variable: nil) ⇒ Object Originally defined in module Extension::AttributeBuilder

Creates methods for adding complex objects (with multiple parameters) to an array.

Supports both positional and keyword arguments when creating instances.

Parameters:

  • name (Symbol) —

    singular name.

  • klass (Class) —

    class to instantiate.

  • plural (Symbol, nil) (defaults to: nil) —

    plural name.

  • variable (Symbol, nil) (defaults to: nil) —

    instance variable name.

.attr_complex_adder_to_custom(name, plural: nil, variable: nil) { ... } ⇒ Object Originally defined in module Extension::AttributeBuilder

Creates methods for adding complex objects with custom construction logic.

The block receives parameters and should construct and add the object.

Parameters:

  • name (Symbol) —

    singular name.

  • plural (Symbol, nil) (defaults to: nil) —

    plural name.

  • variable (Symbol, nil) (defaults to: nil) —

    instance variable name.

Yields:

  • Constructor block executed in instance context.

.attr_complex_builder(name, klass, variable: nil, first_parameter: nil) ⇒ Object Originally defined in module Extension::AttributeBuilder

Creates a getter/setter DSL method for complex objects with multiple parameters.

Supports optional first_parameter that's automatically prepended when constructing.

Parameters:

  • name (Symbol) —

    attribute name.

  • klass (Class) —

    class to instantiate.

  • variable (Symbol, nil) (defaults to: nil) —

    instance variable name.

  • first_parameter (Object, nil) (defaults to: nil) —

    parameter automatically prepended to constructor.

.attr_simple_builder(name, klass = nil, variable: nil) ⇒ Object Originally defined in module Extension::AttributeBuilder

Creates a simple getter/setter DSL method for a single value.

Parameters:

  • name (Symbol) —

    attribute name.

  • klass (Class, nil) (defaults to: nil) —

    class to instantiate (nil = use value as-is).

  • variable (Symbol, nil) (defaults to: nil) —

    instance variable name.

.attr_tuple_adder_to_array(name, klass, plural: nil, variable: nil) ⇒ Object Originally defined in module Extension::AttributeBuilder

Creates methods for adding id/value tuples to an array collection.

Similar to attr_tuple_adder_to_hash but stores items in an array instead of hash. Useful when order matters or duplicates are allowed.

Parameters:

  • name (Symbol) —

    singular name for the item.

  • klass (Class) —

    class to instantiate.

  • plural (Symbol, nil) (defaults to: nil) —

    plural name.

  • variable (Symbol, nil) (defaults to: nil) —

    instance variable name.

.attr_tuple_adder_to_hash(name, klass, plural: nil, variable: nil) ⇒ Object Originally defined in module Extension::AttributeBuilder

Creates methods for adding id/value tuples to a hash collection.

Generates:

  • add_#{name}(id, parameter) → creates instance and adds to hash
  • #{plural}(**parameters) → batch add or retrieve hash

Parameters:

  • name (Symbol) —

    singular name for the item.

  • klass (Class) —

    class to instantiate (receives id, parameter).

  • plural (Symbol, nil) (defaults to: nil) —

    plural name (defaults to name + 's').

  • variable (Symbol, nil) (defaults to: nil) —

    instance variable name (defaults to '@' + plural).

.attr_tuple_builder(name, klass, variable: nil) ⇒ Object Originally defined in module Extension::AttributeBuilder

Creates a getter/setter DSL method for a single id/value tuple.

Parameters:

  • name (Symbol) —

    attribute name.

  • klass (Class) —

    class to instantiate.

  • variable (Symbol, nil) (defaults to: nil) —

    instance variable name.

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 direction XML element.

Parameters:

  • io (IO) —

    output stream

  • indent (Integer) —

    indentation level

  • tabs (String) —

    tab string



179
180
181
182
183
184
185
186
187
188
189
190
191
 
# File 'lib/musa-dsl/musicxml/builder/direction.rb', line 179

def _to_xml(io, indent:, tabs:)
  io.puts "#{tabs}<direction#{ decode_bool_or_string_attribute(@placement, 'placement') }>"

  @types.each do |type|
    type.to_xml(io, indent: indent + 1)
  end

  io.puts "#{tabs}\t<offset sound=\"no\">#{@offset.to_f.round(2)}</offset>" if @offset
  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}</direction>"
end

#offset ⇒ Numeric?

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.

Offset builder/setter.

Returns:

  • (Numeric, nil) 


133
 
# File 'lib/musa-dsl/musicxml/builder/direction.rb', line 133

attr_simple_builder :offset

#placement ⇒ String?

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.

Placement builder/setter ('above' or 'below').

Returns:



137
 
# File 'lib/musa-dsl/musicxml/builder/direction.rb', line 137

attr_simple_builder :placement

#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 builder/setter.

Returns:

  • (Integer, nil) 


129
 
# File 'lib/musa-dsl/musicxml/builder/direction.rb', line 129

attr_simple_builder :staff

#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 builder/setter.

Returns:

  • (Integer, nil) 


125
 
# File 'lib/musa-dsl/musicxml/builder/direction.rb', line 125

attr_simple_builder :voice

#with(*value_parameters, keep_block_context: nil, **key_parameters, &block) ⇒ Object Originally defined in module Extension::With

Note:

The _ parameter is special: when present, it signals "keep caller's context" and receives self (the object) as its value.

Note:

Uses SmartProcBinder internally to handle parameter matching.

Executes a block with flexible context and parameter handling.

Parameters:

  • value_parameters (Array) —

    positional parameters to pass to block.

  • keep_block_context (Boolean, nil) (defaults to: nil) —

    explicit control of context switching:

    • true: always keep caller's context
    • false: always use object's context
    • nil: auto-detect based on _ parameter
  • key_parameters (Hash) —

    keyword parameters to pass to block.

  • block (Proc) —

    block to execute.

Returns:

  • (Object) —

    result of block execution.