Class: Musa::MusicXML::Builder::Internal::Attributes Private

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

Attributes represents the <attributes> element in MusicXML, which contains key signatures, time signatures, clefs, and timing divisions. This element typically appears at the beginning of a measure to establish or change the musical context.

Timing Resolution (Divisions)

The divisions parameter sets the timing resolution for note durations in the measure. It represents how many divisions per quarter note:

  • divisions=1: Quarter note = 1 unit (limited precision)
  • divisions=2: Eighth notes possible
  • divisions=4: Sixteenth notes possible
  • divisions=8: Thirty-second notes possible
  • divisions=24: Common choice (supports triplets and quintuplets)

Note durations are expressed as multiples of this division unit.

Single-Staff vs Multi-Staff

For single-staff instruments (violin, flute), one key/time/clef suffices. For multi-staff instruments (piano, organ, harp), different attributes can be specified per staff using the staff number parameter.

The <staves> element is automatically generated based on the maximum number of keys, times, or clefs defined.

Usage Styles

Two equivalent approaches:

Constructor parameters (convenient for simple cases):

Attributes.new(
  divisions: 4,
  key_fifths: 0,
  time_beats: 4, time_beat_type: 4,
  clef_sign: 'G', clef_line: 2
)

DSL with explicit elements (flexible for multi-staff):

Attributes.new do
  divisions 4
  key fifths: 0
  time beats: 4, beat_type: 4
  clef sign: 'G', line: 2
end

Examples:

Simple single-staff attributes

Attributes.new(
  divisions: 4,
  key_fifths: 1,        # G major
  time_beats: 4, time_beat_type: 4,
  clef_sign: 'G', clef_line: 2
)

Piano with different keys per staff

Attributes.new do
  divisions 4
  key 1, fifths: 0      # Treble: C major
  key 2, fifths: -1     # Bass: F major
  time beats: 3, beat_type: 4
  clef 1, sign: 'G', line: 2
  clef 2, sign: 'F', line: 4
end

Change key signature mid-score

Attributes.new do
  key cancel: 2, fifths: -1  # From D major (2♯) to F major (1♭)
end

High timing resolution for complex rhythms

Attributes.new(divisions: 24)  # Supports triplets, quintuplets

See Also:

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(divisions: nil, key_cancel: nil, key_fifths: nil, key_mode: nil, time_senza_misura: nil, time_beats: nil, time_beat_type: nil, clef_sign: nil, clef_line: nil, clef_octave_change: nil) { ... } ⇒ Attributes

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 musical attributes container.

Examples:

Constructor parameters approach

Attributes.new(
  divisions: 4,
  key_fifths: 2,  # D major
  time_beats: 6, time_beat_type: 8,
  clef_sign: 'G', clef_line: 2
)

DSL block approach

Attributes.new do
  divisions 4
  key fifths: -3, mode: 'minor'  # C minor
  time beats: 4, beat_type: 4
  clef sign: 'F', line: 4
end

Multi-staff piano

Attributes.new do
  divisions 8
  key 1, fifths: 0
  key 2, fifths: 0
  time beats: 3, beat_type: 4
  clef 1, sign: 'G', line: 2
  clef 2, sign: 'F', line: 4
end

Parameters:

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

    timing resolution (divisions per quarter note)

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

    accidentals to cancel from previous key

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

    key signature (circle of fifths: -7 to +7)

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

    mode ('major' or 'minor')

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

    unmeasured time

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

    time signature numerator

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

    time signature denominator

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

    clef sign ('G', 'F', 'C', 'percussion', 'TAB')

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

    clef staff line (1-5)

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

    clef octave transposition

Yields:

  • Optional DSL block for adding elements explicitly



506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
 
# File 'lib/musa-dsl/musicxml/builder/attributes.rb', line 506

def initialize(divisions: nil,
               key_cancel: nil, key_fifths: nil, key_mode: nil,
               time_senza_misura: nil, time_beats: nil, time_beat_type: nil,
               clef_sign: nil, clef_line: nil, clef_octave_change: nil,
               &block)

  @divisions = divisions

  @keys = []
  @times = []
  @clefs = []

  add_key cancel: key_cancel, fifths: key_fifths, mode: key_mode if key_fifths
  add_time senza_misura: time_senza_misura, beats: time_beats, beat_type: time_beat_type if time_senza_misura || (time_beats && time_beat_type)
  add_clef sign: clef_sign, line: clef_line, octave_change: clef_octave_change if clef_sign

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

Automatically determines the number of staves based on the maximum count of keys, times, or clefs. Outputs divisions, keys, times, staves count (if > 1), and clefs.

Parameters:

  • io (IO) —

    output stream

  • indent (Integer) —

    indentation level

  • tabs (String) —

    tab string



609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
 
# File 'lib/musa-dsl/musicxml/builder/attributes.rb', line 609

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

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

  @keys.each do |key|
    key.to_xml(io, indent: indent + 1)
  end

  @times.each do |time|
    time.to_xml(io, indent: indent + 1)
  end

  staves = [@keys.size, @times.size, @clefs.size].max
  io.puts "#{tabs}\t<staves>#{staves}</staves>" if staves > 1

  @clefs.each do |clef|
    clef.to_xml(io, indent: indent + 1)
  end

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

#clef { ... } ⇒ Clef

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.

Adds a clef.

Multiple clefs are needed for multi-staff parts (piano, organ, harp).

Examples:

Single clef

attributes.add_clef(sign: 'G', line: 2)

Piano (two staves)

attributes.add_clef(1, sign: 'G', line: 2)  # Treble
attributes.add_clef(2, sign: 'F', line: 4)  # Bass

Yields:

  • Optional DSL block for configuring the clef

Returns:

  • (Clef) —

    the created clef



595
 
# File 'lib/musa-dsl/musicxml/builder/attributes.rb', line 595

attr_complex_adder_to_array :clef, Clef

#divisions(value) ⇒ Object #divisions=(value) ⇒ Object

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.

Timing divisions builder/setter.

Sets or updates the divisions per quarter note. Higher values provide finer timing resolution for complex rhythms.

Examples:

attributes.divisions 24  # High resolution for triplets

Overloads:

  • #divisions(value) ⇒ Object

    Sets divisions via DSL

    Parameters:

    • value (Integer) —

      divisions per quarter note

  • #divisions=(value) ⇒ Object

    Sets divisions via assignment

    Parameters:

    • value (Integer) —

      divisions per quarter note



539
 
# File 'lib/musa-dsl/musicxml/builder/attributes.rb', line 539

attr_simple_builder :divisions

#key { ... } ⇒ Key

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.

Adds a key signature.

Multiple keys can be added for multi-staff parts where each staff has a different key signature.

Examples:

Single key

attributes.add_key(fifths: 2)  # D major

Multi-staff with different keys

attributes.add_key(1, fifths: 0)   # Treble: C major
attributes.add_key(2, fifths: -1)  # Bass: F major

Yields:

  • Optional DSL block for configuring the key

Returns:

  • (Key) —

    the created key signature



558
 
# File 'lib/musa-dsl/musicxml/builder/attributes.rb', line 558

attr_complex_adder_to_array :key, Key

#time { ... } ⇒ Time

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.

Adds a time signature.

Multiple time signatures can be added for multi-staff parts where each staff has a different meter (polyrhythm).

Examples:

Single time signature

attributes.add_time(beats: 4, beat_type: 4)

Polyrhythm (different meters per staff)

attributes.add_time(1, beats: 3, beat_type: 4)  # Treble: 3/4
attributes.add_time(2, beats: 6, beat_type: 8)  # Bass: 6/8

Yields:

  • Optional DSL block for configuring the time signature

Returns:

  • (Time) —

    the created time signature



577
 
# File 'lib/musa-dsl/musicxml/builder/attributes.rb', line 577

attr_complex_adder_to_array :time, Time

#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

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