Class: Musa::MusicXML::Builder::Internal::Key Private

Inherits:
Object
  • Object
show all
Includes:
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.

Key signature specification.

Key represents a key signature in terms of the circle of fifths and mode. For multi-staff parts (like piano), the number attribute specifies which staff the key signature applies to.

Circle of Fifths

The fifths attribute uses the circle of fifths representation:

  • Negative values: flats (C♭ major = -7, F major = -1)
  • Zero: C major / A minor
  • Positive values: sharps (G major = +1, C♯ major = +7)

Common keys:

  • -7: C♭, -6: G♭, -5: D♭, -4: A♭, -3: E♭, -2: B♭, -1: F
  • 0: C (major) / A (minor)
  • +1: G, +2: D, +3: A, +4: E, +5: B, +6: F♯, +7: C♯

Examples:

C major

Key.new(fifths: 0)

D major (2 sharps)

Key.new(fifths: 2, mode: 'major')

B♭ minor (5 flats)

Key.new(fifths: -5, mode: 'minor')

Piano - different keys per staff

Key.new(1, fifths: 0)  # Treble clef: C major
Key.new(2, fifths: 0)  # Bass clef: C major

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(number = nil, cancel: nil, fifths:, mode: nil) ⇒ 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.

Creates a key signature.

Examples:

G major

Key.new(fifths: 1, mode: 'major')

E minor

Key.new(fifths: 1, mode: 'minor')



56
57
58
59
60
61
62
 
# File 'lib/musa-dsl/musicxml/builder/attributes.rb', line 56

def initialize(number = nil, cancel: nil, fifths:, mode: nil)
  @number = number

  @cancel = cancel
  @fifths = fifths
  @mode = mode
end

Instance Attribute Details

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

Number of accidentals to cancel.



70
71
72
 
# File 'lib/musa-dsl/musicxml/builder/attributes.rb', line 70

def cancel
  @cancel
end

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

Circle of fifths position (-7 to +7).



74
75
76
 
# File 'lib/musa-dsl/musicxml/builder/attributes.rb', line 74

def fifths
  @fifths
end

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

Mode ('major' or 'minor').



78
79
80
 
# File 'lib/musa-dsl/musicxml/builder/attributes.rb', line 78

def mode
  @mode
end

#number ⇒ Integer? (readonly)

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 number (for multi-staff instruments).



66
67
68
 
# File 'lib/musa-dsl/musicxml/builder/attributes.rb', line 66

def number
  @number
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 key signature XML element.



88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
 
# File 'lib/musa-dsl/musicxml/builder/attributes.rb', line 88

def _to_xml(io, indent:, tabs:)
  io ||= StringIO.new
  indent ||= 0

  tabs = "\t" * indent

  io.puts "#{tabs}<key#{" number=\"#{@number.to_i}\"" if @number}>"

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

  io.puts "#{tabs}</key>"

  io
end

#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