Class: Musa::MusicXML::Builder::Internal::Part

Inherits:
Object
  • Object
show all
Extended by:
Extension::AttributeBuilder
Includes:
Extension::With, Helper::HeaderToXML, Helper::ToXML
Defined in:
lib/musa-dsl/musicxml/builder/part.rb

Overview

Individual part (instrument/voice) in a score.

Part represents a single instrument or voice in the score, containing a sequence of measures with musical content. Each part has a unique identifier, full name, and optional abbreviation.

Structure

A part contains:

  • Header: Declared in <part-list> with <score-part>
  • Content: Sequence of <measure> elements with notes, dynamics, etc.

Usage

Parts are typically created via ScorePartwise#part or ScorePartwise#add_part. Measures are added sequentially, automatically numbered starting from 1.

Examples:

Creating a part with measures

part = Part.new(:p1, name: "Violin I", abbreviation: "Vln. I") do
  measure do
    attributes do
      divisions 4
      key fifths: 1  # G major
      time beats: 4, beat_type: 4
      clef sign: 'G', line: 2
    end
    pitch 'D', octave: 5, duration: 4, type: 'quarter'
  end

  measure do
    pitch 'E', octave: 5, duration: 4, type: 'quarter'
    pitch 'F', octave: 5, duration: 4, type: 'quarter', alter: 1
  end
end

See Also:

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(id, name:, abbreviation: nil, **first_measure_attributes) { ... } ⇒ Part

Creates a new part.

Examples:

With abbreviation

Part.new(:p1, name: "Violoncello", abbreviation: "Vc.")

With first measure attributes

Part.new(:p1,
  name: "Flute",
  divisions: 4,
  key_fifths: 0,
  time_beats: 3, time_beat_type: 4
)

With DSL block

Part.new(:p1, name: "Clarinet") do
  measure do
    # measure content
  end
end

Parameters:

  • id (Symbol, String) —

    unique part identifier (referenced in <part> elements)

  • name (String) —

    full part name (e.g., "Violin I", "Piano")

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

    abbreviated name for subsequent systems

  • first_measure_attributes (Hash) —

    optional attributes for auto-created first measure

Yields:

  • Optional DSL block for adding measures



80
81
82
83
84
85
86
87
88
89
90
91
92
 
# File 'lib/musa-dsl/musicxml/builder/part.rb', line 80

def initialize(id, name:, abbreviation: nil, **first_measure_attributes, &block)
  @id = id
  @name = name
  @abbreviation = abbreviation

  @measures = []

  unless first_measure_attributes.empty?
    add_measure **first_measure_attributes
  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

#_header_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 part declaration for the part-list section.

Creates a <score-part> element with part name and optional abbreviation.

Parameters:

  • io (IO) —

    output stream

  • indent (Integer) —

    indentation level

  • tabs (String) —

    tab string



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

def _header_to_xml(io, indent:, tabs:)
  io.puts "#{tabs}<score-part id=\"#{@id}\">"
  io.puts "#{tabs}\t<part-name>#{@name}</part-name>"
  io.puts "#{tabs}\t<part-abbreviation>#{@abbreviation}</part-abbreviation>" if @abbreviation
  io.puts "#{tabs}</score-part>"
end

#_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 part content with all measures.

Creates a <part> element containing all measures in sequence.

Parameters:

  • io (IO) —

    output stream

  • indent (Integer) —

    indentation level

  • tabs (String) —

    tab string



195
196
197
198
199
200
201
 
# File 'lib/musa-dsl/musicxml/builder/part.rb', line 195

def _to_xml(io, indent:, tabs:)
  io.puts "#{tabs}<part id=\"#{@id}\">"
  @measures.each do |measure|
    measure.to_xml(io, indent: indent + 1)
  end
  io.puts "#{tabs}</part>"
end

#abbreviation(value) ⇒ Object #abbreviation=(value) ⇒ Object

Part abbreviation builder/setter.

Overloads:

  • #abbreviation(value) ⇒ Object

    Sets abbreviation via DSL

    Parameters:

    • value (String) —

      abbreviated name

  • #abbreviation=(value) ⇒ Object

    Sets abbreviation via assignment

    Parameters:

    • value (String) —

      abbreviated name



122
 
# File 'lib/musa-dsl/musicxml/builder/part.rb', line 122

attr_simple_builder :abbreviation

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

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's header representation to MusicXML.

Used for elements that appear in the <part-list> section, such as <score-part> and <part-group> declarations.

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

#id(value) ⇒ Object #id=(value) ⇒ Object

Part ID builder/setter.

Overloads:

  • #id(value) ⇒ Object

    Sets part ID via DSL

    Parameters:

    • value (Symbol, String) —

      part identifier

  • #id=(value) ⇒ Object

    Sets part ID via assignment

    Parameters:

    • value (Symbol, String) —

      part identifier



102
 
# File 'lib/musa-dsl/musicxml/builder/part.rb', line 102

attr_simple_builder :id

#measure { ... } ⇒ Measure

Adds a measure to the part.

Measures are automatically numbered sequentially starting from 1. The first measure typically contains attributes (key, time, clef, divisions).

Examples:

First measure with attributes

part.add_measure(
  divisions: 4,
  key_fifths: 2,  # D major
  time_beats: 4, time_beat_type: 4,
  clef_sign: 'G', clef_line: 2
)

Measure with DSL block

part.measure do
  pitch 'C', octave: 4, duration: 4, type: 'quarter'
  rest duration: 4, type: 'quarter'
end

Yields:

  • Optional DSL block for measure content

Returns:

  • (Measure) —

    the created measure



155
156
157
158
159
160
161
162
163
164
165
166
 
# File 'lib/musa-dsl/musicxml/builder/part.rb', line 155

attr_complex_adder_to_custom :measure, variable: :@measures do
| 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 |

  Measure.new(@measures.size + 1,
              divisions: divisions,
              key_cancel: key_cancel, key_fifths: key_fifths, key_mode: key_mode,
              time_senza_misura: time_senza_misura, time_beats: time_beats, time_beat_type: time_beat_type,
              clef_sign: clef_sign, clef_line: clef_line, clef_octave_change: clef_octave_change).tap { |measure| @measures << measure }
end

#name(value) ⇒ Object #name=(value) ⇒ Object

Part name builder/setter.

Overloads:

  • #name(value) ⇒ Object

    Sets part name via DSL

    Parameters:

    • value (String) —

      part name

  • #name=(value) ⇒ Object

    Sets part name via assignment

    Parameters:

    • value (String) —

      part name



112
 
# File 'lib/musa-dsl/musicxml/builder/part.rb', line 112

attr_simple_builder :name

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