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

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

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, &block) ⇒ 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')

Parameters:

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

    staff number (for multi-staff parts)

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

    number of accidentals to cancel from previous key

  • fifths (Integer) —

    circle of fifths position (-7 to +7)

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

    'major' or 'minor'



58
59
60
61
62
63
64
65
66
 
# File 'lib/musa-dsl/musicxml/builder/attributes.rb', line 58

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

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

  with &block if block_given?
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.

Returns:

  • (Integer, nil) 


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

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

Returns:

  • (Integer) 


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

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').

Returns:



82
83
84
 
# File 'lib/musa-dsl/musicxml/builder/attributes.rb', line 82

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

Returns:

  • (Integer, nil) 


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

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.

Parameters:

  • io (IO) —

    output stream

  • indent (Integer) —

    indentation level

  • tabs (String) —

    tab string



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

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

element = Measure.new(1, divisions: 2)
File.open('output.xml', 'w') do |f|
  element.to_xml(f)
end

Getting XML as string

xml_string = element.to_xml.string
xml_string.start_with?('<measure')  # => true

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.