Class: Musa::MusicXML::Builder::Internal::Tuplet Private

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

Visual tuplet bracket and number notation.

Tuplet controls the visual appearance of tuplet markings: brackets, numbers, and note type indications. Unlike TimeModification, which affects playback timing, Tuplet is purely visual.

Components

Type

  • start: Begin tuplet bracket/number
  • stop: End tuplet bracket/number

Multiple tuplets can overlap using different number attributes.

Bracket

  • true: Show bracket
  • false/nil: Hide bracket (use number only)

Common practice: show brackets for beam-breaking tuplets, hide for beamed.

Number Display

  • show_number:

    • 'actual': Show only actual number (e.g., "3")
    • 'both': Show ratio (e.g., "3:2")
    • 'none': Hide number

  • show_type:

    • 'actual': Show note type for actual notes
    • 'both': Show note types for both
    • 'none': Hide note types

Actual/Normal Specification

Optional detailed specification of tuplet appearance:

  • actual_number/actual_type/actual_dots: Actual notes representation
  • normal_number/normal_type/normal_dots: Normal notes representation

Typically inferred from TimeModification and note properties.

Typical Usage

Most tuplets only need type (start/stop) and optionally bracket:

Tuplet.new(type: 'start', bracket: true)   # First note of triplet
Tuplet.new(type: 'stop')                   # Last note of triplet

Examples:

Simple triplet bracket (start)

Tuplet.new(type: 'start', bracket: true)

Triplet end

Tuplet.new(type: 'stop')

Tuplet without bracket

Tuplet.new(type: 'start', bracket: false)

Nested tuplets with numbers

Tuplet.new(type: 'start', number: 1, bracket: true)  # Outer
Tuplet.new(type: 'start', number: 2, bracket: true)  # Inner
Tuplet.new(type: 'stop', number: 2)                  # End inner
Tuplet.new(type: 'stop', number: 1)                  # End outer

Custom display (show ratio)

Tuplet.new(type: 'start', show_number: 'both')  # Shows "3:2"

See Also:

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(type:, number: nil, bracket: nil, show_number: nil, show_type: nil, actual_number: nil, actual_type: nil, actual_dots: nil, normal_number: nil, normal_type: nil, normal_dots: nil) ⇒ Tuplet

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 tuplet notation.

Examples:

Start a triplet bracket

Tuplet.new(type: 'start', bracket: true)

End a tuplet

Tuplet.new(type: 'stop')

Quintuplet with ratio display

Tuplet.new(type: 'start', bracket: true, show_number: 'both')

Parameters:

  • type (String) —

    'start' or 'stop'

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

    tuplet number for nesting (default 1)

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

    show bracket

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

    number display: 'actual', 'both', 'none'

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

    note type display: 'actual', 'both', 'none'

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

    actual number for display

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

    actual note type for display

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

    actual dots for display

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

    normal number for display

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

    normal note type for display

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

    normal dots for display



216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
 
# File 'lib/musa-dsl/musicxml/builder/note-complexities.rb', line 216

def initialize(type:, # start / stop
               number: nil, # number
               bracket: nil, # true
               show_number: nil, # actual / both / none
               show_type: nil, # actual / both / none
               actual_number: nil, # number
               actual_type: nil, # quarter / eigth / ...
               actual_dots: nil, # number,
               normal_number: nil, # number
               normal_type: nil, # quarter / eigth / ...
               normal_dots: nil) # number

  @type = type
  @number = number
  @bracket = bracket
  @show_number = show_number
  @show_type = show_type
  @actual_number = actual_number
  @actual_type = actual_type
  @actual_dots = actual_dots
  @normal_number = normal_number
  @normal_type = normal_type
  @normal_dots = normal_dots
end

Instance Attribute Details

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

Actual augmentation dots for display.

Returns:

  • (Integer, nil) 


271
272
273
 
# File 'lib/musa-dsl/musicxml/builder/note-complexities.rb', line 271

def actual_dots
  @actual_dots
end

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

Actual number for display.

Returns:

  • (Integer, nil) 


263
264
265
 
# File 'lib/musa-dsl/musicxml/builder/note-complexities.rb', line 263

def actual_number
  @actual_number
end

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

Actual note type for display.

Returns:



267
268
269
 
# File 'lib/musa-dsl/musicxml/builder/note-complexities.rb', line 267

def actual_type
  @actual_type
end

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

Show bracket.

Returns:

  • (Boolean, nil) 


251
252
253
 
# File 'lib/musa-dsl/musicxml/builder/note-complexities.rb', line 251

def bracket
  @bracket
end

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

Normal augmentation dots for display.

Returns:

  • (Integer, nil) 


283
284
285
 
# File 'lib/musa-dsl/musicxml/builder/note-complexities.rb', line 283

def normal_dots
  @normal_dots
end

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

Normal number for display.

Returns:

  • (Integer, nil) 


275
276
277
 
# File 'lib/musa-dsl/musicxml/builder/note-complexities.rb', line 275

def normal_number
  @normal_number
end

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

Normal note type for display.

Returns:



279
280
281
 
# File 'lib/musa-dsl/musicxml/builder/note-complexities.rb', line 279

def normal_type
  @normal_type
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.

Tuplet number for nesting.

Returns:

  • (Integer, nil) 


247
248
249
 
# File 'lib/musa-dsl/musicxml/builder/note-complexities.rb', line 247

def number
  @number
end

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

Number display mode.

Returns:



255
256
257
 
# File 'lib/musa-dsl/musicxml/builder/note-complexities.rb', line 255

def show_number
  @show_number
end

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

Note type display mode.

Returns:



259
260
261
 
# File 'lib/musa-dsl/musicxml/builder/note-complexities.rb', line 259

def show_type
  @show_type
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.

Tuplet type ('start' or 'stop').

Returns:



243
244
245
 
# File 'lib/musa-dsl/musicxml/builder/note-complexities.rb', line 243

def type
  @type
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 tuplet XML element.

Parameters:

  • io (IO) —

    output stream

  • indent (Integer) —

    indentation level

  • tabs (String) —

    tab string



293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
 
# File 'lib/musa-dsl/musicxml/builder/note-complexities.rb', line 293

def _to_xml(io, indent:, tabs:)
  io.puts "#{tabs}<tuplet type=\"#{@type}\"" \
"#{decode_bool_or_string_attribute(@number&.to_i, 'number')}" \
"#{decode_bool_or_string_attribute(@bracket, 'bracket', 'yes', 'no')}" \
"#{decode_bool_or_string_attribute(@show_number, 'show-number')}" \
"#{decode_bool_or_string_attribute(@show_type, 'show-type')}" \
">"

  if @actual_number || @actual_type || @actual_dots
    io.puts "#{tabs}\t<tuplet-actual>"

    io.puts "#{tabs}\t\t<tuplet-number>#{@actual_number.to_i}</tuplet-number>" if @actual_number
    io.puts "#{tabs}\t\t<tuplet-type>#{@actual_type}</tuplet-type>" if @actual_type

    @actual_dots&.times do
      io.puts "#{tabs}\t\t<tuplet-dot />"
    end

    io.puts "#{tabs}\t</tuplet-actual>"
  end

  if @normal_number || @normal_type || @normal_dots
    io.puts "#{tabs}\t<tuplet-normal>"

    io.puts "#{tabs}\t\t<tuplet-number>#{@normal_number.to_i}</tuplet-number>" if @normal_number
    io.puts "#{tabs}\t\t<tuplet-type>#{@normal_type}</tuplet-type>" if @normal_type

    @normal_dots&.times do
      io.puts "#{tabs}\t\t<tuplet-dot />"
    end

    io.puts "#{tabs}\t</tuplet-normal>"
  end

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