Class: Musa::MusicXML::Builder::Internal::PartGroup Private

Inherits:
Object
  • Object
show all
Includes:
Helper, Helper::HeaderToXML
Defined in:
lib/musa-dsl/musicxml/builder/part-group.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.

Part group for bracketing multiple parts together.

PartGroup represents the <part-group> element in the MusicXML part-list section. Part groups visually bracket or brace related parts together (e.g., string sections, choir SATB, piano grand staff).

Usage

Part groups are defined by matching start/stop pairs with the same number:

<part-group number="1" type="start">
  <group-name>Strings</group-name>
  <group-symbol>bracket</group-symbol>
</part-group>
<score-part id="p1">...</score-part>
<score-part id="p2">...</score-part>
<part-group number="1" type="stop" />

Nesting

Groups can be nested using different numbers:

<part-group number="1" type="start" name="Orchestra" />
<part-group number="2" type="start" name="Strings" />
<score-part id="vln1" />
<score-part id="vln2" />
<part-group number="2" type="stop" />
<part-group number="1" type="stop" />

Symbols

Common bracket symbols:

  • bracket: Standard square bracket
  • brace: Curly brace (for piano, organ)
  • line: Simple vertical line
  • square: Square bracket (rare)

Examples:

String quartet grouping

group_start = PartGroup.new(1,
  type: 'start',
  name: "String Quartet",
  symbol: 'bracket'
)

group_start.header_to_xml.string
# => "<part-group number=\"1\" type=\"start\">\n\t<group-name>String Quartet</group-name>\n\t<group-symbol>bracket</group-symbol>\n</part-group>\n"

# `header_to_xml` and not `to_xml`: a part group lives in the
# part-list header, not in the body of the score.
# ... add parts vln1, vln2, vla, vlc ...
group_stop = PartGroup.new(1, type: 'stop')

Piano grand staff

PartGroup.new(1,
  type: 'start',
  symbol: 'brace',
  group_barline: true
).header_to_xml.string
# => "<part-group number=\"1\" type=\"start\">\n\t<group-symbol>brace</group-symbol>\n\t<group-barline>yes</group-barline>\n</part-group>\n"

# `group_barline: true` comes out as the string "yes": MusicXML has no
# booleans, and the builder does the translation.
# ... add parts for right hand and left hand ...
PartGroup.new(1, type: 'stop')

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(number = nil, type:, name: nil, abbreviation: nil, symbol: nil, group_barline: nil, group_time: nil) ⇒ PartGroup

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 part group declaration.

Examples:

Start a bracket group

PartGroup.new(1,
  type: 'start',
  name: "Woodwinds",
  symbol: 'bracket'
)

Stop a group

PartGroup.new(1, type: 'stop')

Parameters:

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

    group number for matching start/stop pairs

  • type (String) —

    'start' or 'stop'

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

    group name displayed on bracket

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

    abbreviated group name

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

    bracket type: 'bracket', 'brace', 'line', 'square'

  • group_barline (Boolean, String, nil) (defaults to: nil) —

    whether barlines connect across group

  • group_time (Boolean, String, nil) (defaults to: nil) —

    whether time signatures are shared



94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
 
# File 'lib/musa-dsl/musicxml/builder/part-group.rb', line 94

def initialize(number = nil, # number
               type:,
               name: nil,
               abbreviation: nil,
               symbol: nil,
               group_barline: nil, # true
               group_time: nil) # true
  @number = number
  @type = type
  @name = name
  @abbreviation = abbreviation
  @symbol = symbol
  @group_barline = group_barline
  @group_time = group_time
end

Instance Attribute Details

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

Abbreviated group name.

Returns:



124
125
126
 
# File 'lib/musa-dsl/musicxml/builder/part-group.rb', line 124

def abbreviation
  @abbreviation
end

#group_barline ⇒ Boolean, ...

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.

Whether barlines connect across the group.

Returns:



132
133
134
 
# File 'lib/musa-dsl/musicxml/builder/part-group.rb', line 132

def group_barline
  @group_barline
end

#group_time ⇒ Boolean, ...

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.

Whether time signatures are shared.

Returns:



136
137
138
 
# File 'lib/musa-dsl/musicxml/builder/part-group.rb', line 136

def group_time
  @group_time
end

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

Group name displayed on bracket.

Returns:



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

def name
  @name
end

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

Group number (for matching start/stop pairs).

Returns:

  • (Integer, nil) 


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

def number
  @number
end

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

Bracket symbol type.

Returns:



128
129
130
 
# File 'lib/musa-dsl/musicxml/builder/part-group.rb', line 128

def symbol
  @symbol
end

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

Type: 'start' or 'stop'.

Returns:



116
117
118
 
# File 'lib/musa-dsl/musicxml/builder/part-group.rb', line 116

def type
  @type
end

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-group XML element for the part-list section.

Parameters:

  • io (IO) —

    output stream

  • indent (Integer) —

    indentation level

  • tabs (String) —

    tab string



146
147
148
149
150
151
152
153
154
155
156
 
# File 'lib/musa-dsl/musicxml/builder/part-group.rb', line 146

def _header_to_xml(io, indent:, tabs:)
  io.puts "#{tabs}<part-group#{ decode_bool_or_string_attribute(@number&.to_i, 'number') } type=\"#{@type}\">"

  io.puts "#{tabs}\t<group-name>#{@name}</group-name>" if @name
  io.puts "#{tabs}\t<group-abbreviation>#{@abbreviation}</group-abbreviation>" if @abbreviation
  io.puts "#{tabs}\t<group-symbol>#{@symbol}</group-symbol>" if @symbol
  io.puts "#{tabs}\t<group-barline>#{decode_bool_or_string_value(@group_barline, 'yes', 'no')}</group-barline>" if @group_barline
  io.puts "#{tabs}\t<group-time>#{decode_bool_or_string_value(@group_time, 'yes', 'no')}</group-time>" if @group_time

  io.puts "#{tabs}</part-group>"
end

#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