head_music 17.2.0 → 17.4.0

data/lib/head_music/content/placement.rb

@@ -7,6 +7,13 @@ class HeadMusic::Content::Placement
 
   attr_reader :voice, :position, :rhythmic_value, :sounds
 
+  # Authored beam grouping relative to the previous placement, set after
+  # construction (the Bar-style side-metadata pattern). Tri-state: nil = use
+  # the meter-derived default, true = force a beam break before this placement,
+  # false = force a beam join to the previous placement. Consumed by the
+  # MusicXML writer, which prefers it over the default grouping.
+  attr_accessor :beam_break_before
+
   delegate :composition, to: :voice
   delegate :spelling, to: :pitch, allow_nil: true
 
@@ -85,11 +92,13 @@ class HeadMusic::Content::Placement
   end
 
   def to_h
-    {
+    hash = {
       "position" => position.to_s,
       "rhythmic_value" => rhythmic_value.to_s,
       "sounds" => sounds.map { |sound| sound_datum(sound) }
     }
+    hash["beam_break_before"] = beam_break_before unless beam_break_before.nil?
+    hash
   end
 
   private
@@ -120,47 +129,7 @@ class HeadMusic::Content::Placement
     @voice = voice
     ensure_position(position)
     @rhythmic_value = HeadMusic::Rudiment::RhythmicValue.get(rhythmic_value)
-    @sounds = ensure_sounds(sound_or_sounds)
-  end
-
-  def ensure_sounds(sound_or_sounds)
-    return [].freeze if sound_or_sounds.nil?
-
-    values = sound_or_sounds.is_a?(Array) ? sound_or_sounds : [sound_or_sounds]
-    values.map { |value| resolve_sound(value) }.uniq.freeze
-  end
-
-  def resolve_sound(value)
-    return value if value.is_a?(HeadMusic::Rudiment::UnpitchedSound)
-    return HeadMusic::Rudiment::UnpitchedSound.get(value) if value.is_a?(HeadMusic::Instruments::Instrument)
-
-    pitch = HeadMusic::Rudiment::Pitch.get(value)
-    return pitch if pitch
-
-    unpitched_sound(value) || raise(ArgumentError, unknown_sound_message(value))
-  end
-
-  # A bare name resolves to a percussive hit only on an unpitched instrument;
-  # naming a pitched instrument is ambiguous, so it raises instead.
-  # UnpitchedSound.get(nil) is the generic sound, so nil is excluded here to
-  # preserve nil-as-rest at the argument level and nil-raises inside arrays.
-  def unpitched_sound(value)
-    return nil if value.nil?
-
-    sound = HeadMusic::Rudiment::UnpitchedSound.get(value)
-    return nil unless sound&.instrument
-    return nil if sound.instrument.pitched?
-
-    sound
-  end
-
-  def unknown_sound_message(value)
-    if HeadMusic::Instruments::Instrument.get(value)&.pitched?
-      "#{value.inspect} is a pitched instrument; place a pitch such as \"D4\", " \
-        "or pass HeadMusic::Rudiment::UnpitchedSound.get(#{value.inspect}) for a percussive hit"
-    else
-      "unknown sound: #{value.inspect}"
-    end
+    @sounds = HeadMusic::Content::SoundResolver.resolve(sound_or_sounds)
   end
 
   def ensure_position(position)

data/lib/head_music/content/sound_resolver.rb

@@ -0,0 +1,54 @@
+# A module for musical content
+module HeadMusic::Content; end
+
+# Resolves the raw sound argument(s) passed to Placement.new into a frozen,
+# de-duplicated array of sound objects. Each value may be a Pitch, an
+# UnpitchedSound, an Instrument (resolved to its percussive hit), or a name
+# resolvable to one of those; an unresolvable name raises with guidance.
+class HeadMusic::Content::SoundResolver
+  def self.resolve(sound_or_sounds)
+    new.resolve(sound_or_sounds)
+  end
+
+  def resolve(sound_or_sounds)
+    return [].freeze if sound_or_sounds.nil?
+
+    values = sound_or_sounds.is_a?(Array) ? sound_or_sounds : [sound_or_sounds]
+    values.map { |value| resolve_sound(value) }.uniq.freeze
+  end
+
+  private
+
+  def resolve_sound(value)
+    return value if value.is_a?(HeadMusic::Rudiment::UnpitchedSound)
+    return HeadMusic::Rudiment::UnpitchedSound.get(value) if value.is_a?(HeadMusic::Instruments::Instrument)
+
+    pitch = HeadMusic::Rudiment::Pitch.get(value)
+    return pitch if pitch
+
+    unpitched_sound(value) || raise(ArgumentError, unknown_sound_message(value))
+  end
+
+  # A bare name resolves to a percussive hit only on an unpitched instrument;
+  # naming a pitched instrument is ambiguous, so it raises instead.
+  # UnpitchedSound.get(nil) is the generic sound, so nil is excluded here to
+  # preserve nil-as-rest at the argument level and nil-raises inside arrays.
+  def unpitched_sound(value)
+    return nil if value.nil?
+
+    sound = HeadMusic::Rudiment::UnpitchedSound.get(value)
+    return nil unless sound&.instrument
+    return nil if sound.instrument.pitched?
+
+    sound
+  end
+
+  def unknown_sound_message(value)
+    if HeadMusic::Instruments::Instrument.get(value)&.pitched?
+      "#{value.inspect} is a pitched instrument; place a pitch such as \"D4\", " \
+        "or pass HeadMusic::Rudiment::UnpitchedSound.get(#{value.inspect}) for a percussive hit"
+    else
+      "unknown sound: #{value.inspect}"
+    end
+  end
+end

data/lib/head_music/content/voice/melodic_line.rb

@@ -0,0 +1,32 @@
+class HeadMusic::Content::Voice
+  # The melodic view of a voice: its notes read as the sequence of consecutive
+  # pairs, the interval spanned by each pair, and the leaps among them. Built
+  # from an ordered list of notes and memoizes the pairs, so callers sharing a
+  # MelodicLine see the same pair objects.
+  class MelodicLine
+    attr_reader :notes
+
+    def initialize(notes)
+      @notes = notes
+    end
+
+    def melodic_note_pairs
+      @melodic_note_pairs ||= notes.each_cons(2).map do |first_note, second_note|
+        MelodicNotePair.new(first_note, second_note)
+      end
+    end
+
+    def melodic_intervals
+      @melodic_intervals ||=
+        melodic_note_pairs.map { |note_pair| HeadMusic::Analysis::MelodicInterval.new(*note_pair.notes) }
+    end
+
+    def leaps
+      melodic_note_pairs.select(&:leap?)
+    end
+
+    def large_leaps
+      melodic_note_pairs.select(&:large_leap?)
+    end
+  end
+end

data/lib/head_music/content/voice/melodic_note_pair.rb

@@ -0,0 +1,33 @@
+class HeadMusic::Content::Voice
+  # A pair of consecutive notes in a melodic line, used to analyze intervals and leaps.
+  class MelodicNotePair
+    attr_reader :first_note, :second_note
+
+    delegate(
+      :octave?, :unison?,
+      :perfect?,
+      :step?, :leap?, :large_leap?,
+      :ascending?, :descending?, :repetition?,
+      :spans?,
+      :spells_consonant_triad_with?,
+      to: :melodic_interval
+    )
+
+    def initialize(first_note, second_note)
+      @first_note = first_note
+      @second_note = second_note
+    end
+
+    def notes
+      @notes ||= [first_note, second_note]
+    end
+
+    def pitches
+      @pitches ||= notes.map(&:pitch)
+    end
+
+    def melodic_interval
+      @melodic_interval ||= HeadMusic::Analysis::MelodicInterval.new(*notes)
+    end
+  end
+end

data/lib/head_music/content/voice.rb

@@ -62,24 +62,11 @@ class HeadMusic::Content::Voice
     HeadMusic::Analysis::DiatonicInterval.new(lowest_pitch, highest_pitch)
   end
 
-  def melodic_note_pairs
-    @melodic_note_pairs ||= notes.each_cons(2).map do |first_note, second_note|
-      HeadMusic::Content::Voice::MelodicNotePair.new(first_note, second_note)
-    end
-  end
-
-  def melodic_intervals
-    @melodic_intervals ||=
-      melodic_note_pairs.map { |note_pair| HeadMusic::Analysis::MelodicInterval.new(*note_pair.notes) }
+  def melodic_line
+    @melodic_line ||= MelodicLine.new(notes)
   end
 
-  def leaps
-    melodic_note_pairs.select(&:leap?)
-  end
-
-  def large_leaps
-    melodic_note_pairs.select(&:large_leap?)
-  end
+  delegate :melodic_note_pairs, :melodic_intervals, :leaps, :large_leaps, to: :melodic_line
 
   def cantus_firmus?
     role.to_s =~ /cantus.?firmus/i
@@ -129,10 +116,12 @@ class HeadMusic::Content::Voice
     first = placements.first
     return unless first
 
-    return [bar_start_position(first), first] unless first.position.count == 1 && first.position.tick.zero?
+    first_position = first.position
+    return [bar_start_position(first), first] unless first_position.count == 1 && first_position.tick.zero?
 
     placements.each_cons(2) do |previous, current|
-      return [previous.next_position, current] unless current.position == previous.next_position
+      expected_position = previous.next_position
+      return [expected_position, current] unless current.position == expected_position
     end
     nil
   end
@@ -170,44 +159,4 @@ class HeadMusic::Content::Voice
   def pitches_string
     pitches.first(10).map(&:to_s).join(" ")
   end
-
-  # A pair of consecutive notes in a melodic line, used to analyze intervals and leaps.
-  class MelodicNotePair
-    attr_reader :first_note, :second_note
-
-    delegate(
-      :octave?, :unison?,
-      :perfect?,
-      :step?, :leap?, :large_leap?,
-      :ascending?, :descending?, :repetition?,
-      :spans?,
-      to: :melodic_interval
-    )
-
-    def initialize(first_note, second_note)
-      @first_note = first_note
-      @second_note = second_note
-    end
-
-    def notes
-      @notes ||= [first_note, second_note]
-    end
-
-    def pitches
-      @pitches ||= notes.map(&:pitch)
-    end
-
-    def melodic_interval
-      @melodic_interval ||= HeadMusic::Analysis::MelodicInterval.new(*notes)
-    end
-
-    def spells_consonant_triad_with?(other_note_pair)
-      return false if step? || other_note_pair.step?
-
-      combined_pitches = (pitches + other_note_pair.pitches).uniq
-      return false if combined_pitches.length < 3
-
-      HeadMusic::Analysis::PitchCollection.new(combined_pitches).consonant_triad?
-    end
-  end
 end

data/lib/head_music/instruments/alternate_tuning.rb

@@ -14,10 +14,14 @@ module HeadMusic::Instruments; end
 #   - Missing elements are treated as 0 (no change)
 #   - Extra elements are ignored
 class HeadMusic::Instruments::AlternateTuning
+  include HeadMusic::ValueEquality
+
   TUNINGS = YAML.load_file(File.expand_path("alternate_tunings.yml", __dir__)).freeze
 
   attr_reader :instrument_key, :name_key, :semitones
 
+  value_equality :instrument_key, :name_key
+
   class << self
     # Get an alternate tuning by instrument and name
     # @param instrument [HeadMusic::Instruments::Instrument, String, Symbol] The instrument
@@ -90,12 +94,6 @@ class HeadMusic::Instruments::AlternateTuning
     stringing.pitches_with_tuning(self)
   end
 
-  def ==(other)
-    return false unless other.is_a?(self.class)
-
-    instrument_key == other.instrument_key && name_key == other.name_key
-  end
-
   def to_s
     "#{name} (#{instrument_key})"
   end

data/lib/head_music/instruments/catalog_lookup.rb

@@ -0,0 +1,18 @@
+module HeadMusic::Instruments; end
+
+# Shared lookup of a catalog entry's key by a localized (translated) name.
+# Including classes provide #catalog, a Hash of name_key => record whose keys
+# match the I18n keys under "head_music.instruments".
+module HeadMusic::Instruments::CatalogLookup
+  private
+
+  def key_for_name(name)
+    catalog.each do |key, _data|
+      I18n.config.available_locales.each do |locale|
+        translation = I18n.t("head_music.instruments.#{key}", locale: locale)
+        return key if translation.downcase == name.downcase
+      end
+    end
+    nil
+  end
+end

data/lib/head_music/instruments/instrument.rb

@@ -114,62 +114,27 @@ class HeadMusic::Instruments::Instrument
     HeadMusic::Notation::NotationStyle.get(style).notation_for(self)
   end
 
-  # Staff schemes are a notation concern; they now live in NotationStyle.
-  # These methods remain for backward compatibility and delegate to the
-  # default style. Referenced only inside method bodies, because the Notation
-  # module loads after Instruments (see head_music.rb load order).
-  def staff_schemes
-    [default_staff_scheme]
-  end
-
-  def default_staff_scheme
-    @default_staff_scheme ||= HeadMusic::Instruments::StaffScheme.new(
-      key: "default",
-      instrument: self,
-      list: default_notation_staves_data
-    )
-  end
-
-  def default_staves
-    default_staff_scheme.staves
-  end
-
-  def default_clefs
-    default_staves&.map(&:clef) || []
-  end
-
-  def sounding_transposition
-    default_staves&.first&.sounding_transposition || 0
-  end
+  # Staff schemes are a notation concern; StaffProfile projects the default
+  # NotationStyle onto the staff-derived properties below. These delegators
+  # remain because callers ask an instrument directly whether it transposes,
+  # how many staves it uses, and so on.
+  delegate(
+    :staff_schemes, :default_staff_scheme, :default_staves, :default_clefs,
+    :sounding_transposition, :transposing?, :transposing_at_the_octave?,
+    :single_staff?, :multiple_staves?, :pitched?,
+    to: :staff_profile
+  )
 
   alias_method :default_sounding_transposition, :sounding_transposition
 
-  def transposing?
-    sounding_transposition != 0
-  end
-
-  def transposing_at_the_octave?
-    transposing? && sounding_transposition % 12 == 0
-  end
-
-  def single_staff?
-    default_staves.length == 1
-  end
-
-  def multiple_staves?
-    default_staves.length > 1
-  end
-
-  def pitched?
-    return false if default_clefs.compact.uniq == [HeadMusic::Rudiment::Clef.get("neutral_clef")]
-
-    default_clefs.any?
+  def staff_profile
+    @staff_profile ||= HeadMusic::Instruments::StaffProfile.new(self)
   end
 
   def translation(locale = :en)
     return name unless name_key
 
-    I18n.translate(name_key, scope: %i[head_music instruments], locale: locale, default: name)
+    HeadMusic::Instruments::InstrumentName.translate(name_key, locale: locale, default: name)
   end
 
   def ==(other)
@@ -214,7 +179,7 @@ class HeadMusic::Instruments::Instrument
   private
 
   def initialize(name)
-    record = record_for_name(name)
+    record = HeadMusic::Instruments::InstrumentCatalog.new(INSTRUMENTS).record_for(name)
     if record
       initialize_data_from_record(record)
     else
@@ -224,39 +189,6 @@ class HeadMusic::Instruments::Instrument
     end
   end
 
-  def record_for_name(name)
-    record_for_key(HeadMusic::Utilities::HashKey.for(name)) ||
-      record_for_key(key_for_name(name)) ||
-      record_for_alias(name)
-  end
-
-  def key_for_name(name)
-    INSTRUMENTS.each do |key, _data|
-      I18n.config.available_locales.each do |locale|
-        translation = I18n.t("head_music.instruments.#{key}", locale: locale)
-        return key if translation.downcase == name.downcase
-      end
-    end
-    nil
-  end
-
-  def record_for_key(key)
-    INSTRUMENTS.each do |name_key, data|
-      return data.merge("name_key" => name_key) if name_key.to_s == key.to_s
-    end
-    nil
-  end
-
-  def record_for_alias(name)
-    normalized_name = HeadMusic::Utilities::HashKey.for(name).to_s
-    INSTRUMENTS.each do |name_key, data|
-      data["alias_name_keys"]&.each do |alias_key|
-        return data.merge("name_key" => name_key) if HeadMusic::Utilities::HashKey.for(alias_key).to_s == normalized_name
-      end
-    end
-    nil
-  end
-
   def initialize_data_from_record(record)
     @name_key = record["name_key"].to_sym
     @parent_key = record["parent_key"]&.to_sym
@@ -269,34 +201,9 @@ class HeadMusic::Instruments::Instrument
   end
 
   def initialize_name
-    # Try to get a translation first
-    base_name = I18n.translate(name_key, scope: "head_music.instruments", locale: "en", default: nil)
-
-    if base_name
-      # Use the translation as-is
-      self.name = base_name
-    elsif parent_key && pitch_key
-      # Build name from parent + pitch for child instruments
-      pitch_name = format_pitch_name(pitch_key_to_designation)
-      self.name = "#{parent_translation} in #{pitch_name}"
-    else
-      # Fall back to inferred name
-      self.name = inferred_name
-    end
-  end
-
-  def parent_translation
-    return nil unless parent_key
-
-    I18n.translate(parent_key, scope: "head_music.instruments", locale: "en", default: parent_key.to_s.tr("_", " "))
-  end
-
-  def inferred_name
-    name_key.to_s.tr("_", " ")
-  end
-
-  def format_pitch_name(pitch_designation)
-    pitch_designation.to_s.tr("b", "♭").tr("#", "♯")
+    self.name = HeadMusic::Instruments::InstrumentName.new(
+      name_key: name_key, parent_key: parent_key, pitch_designation: pitch_key_to_designation
+    ).to_s
   end
 
   # Convert pitch_key (e.g., "b_flat") to designation format (e.g., "Bb")
@@ -313,11 +220,4 @@ class HeadMusic::Instruments::Instrument
       pitch_key_str.upcase
     end
   end
-
-  # The raw staff-attribute list for this instrument's default notation,
-  # resolved from the default NotationStyle.
-  def default_notation_staves_data
-    notation = HeadMusic::Notation::NotationStyle.default.notation_for(self)
-    (notation&.staves || []).map(&:attributes)
-  end
 end

data/lib/head_music/instruments/instrument_catalog.rb

@@ -0,0 +1,48 @@
+# A module for musical instruments and their properties
+module HeadMusic::Instruments; end
+
+# Finds an instrument's catalog record by key, localized name, or alias.
+# Wraps the instruments.yml data (a Hash of name_key => record) so an
+# Instrument need not know how a raw record is located, only how to build
+# itself from one.
+class HeadMusic::Instruments::InstrumentCatalog
+  include HeadMusic::Instruments::CatalogLookup
+
+  def initialize(records)
+    @records = records
+  end
+
+  # The record matching a name given as a key, a localized (translated) name,
+  # or an alias, with its own name_key merged in; nil when nothing matches.
+  def record_for(name)
+    record_for_key(HeadMusic::Utilities::HashKey.for(name)) ||
+      record_for_key(key_for_name(name)) ||
+      record_for_alias(name)
+  end
+
+  private
+
+  attr_reader :records
+
+  # CatalogLookup hook: the hash its #key_for_name searches by translation.
+  def catalog
+    records
+  end
+
+  def record_for_key(key)
+    records.each do |name_key, data|
+      return data.merge("name_key" => name_key) if name_key.to_s == key.to_s
+    end
+    nil
+  end
+
+  def record_for_alias(name)
+    normalized_name = HeadMusic::Utilities::HashKey.for(name).to_s
+    records.each do |name_key, data|
+      data["alias_name_keys"]&.each do |alias_key|
+        return data.merge("name_key" => name_key) if HeadMusic::Utilities::HashKey.for(alias_key).to_s == normalized_name
+      end
+    end
+    nil
+  end
+end

data/lib/head_music/instruments/instrument_configuration.rb

@@ -7,10 +7,14 @@ module HeadMusic::Instruments; end
 #   - Trumpet "mute" configuration with options: open (default), straight, cup, harmon
 #   - Bass trombone "f_attachment" with options: disengaged (default), engaged
 class HeadMusic::Instruments::InstrumentConfiguration
+  include HeadMusic::ValueEquality
+
   CONFIGURATIONS = YAML.load_file(File.expand_path("instrument_configurations.yml", __dir__)).freeze
 
   attr_reader :name_key, :instrument_key, :options
 
+  value_equality :name_key, :instrument_key
+
   class << self
     def for_instrument(instrument_key)
       instrument_key = instrument_key.to_s
@@ -40,12 +44,6 @@ class HeadMusic::Instruments::InstrumentConfiguration
     options.find { |opt| opt.name_key == option_key.to_sym }
   end
 
-  def ==(other)
-    return false unless other.is_a?(self.class)
-
-    name_key == other.name_key && instrument_key == other.instrument_key
-  end
-
   def to_s
     name_key.to_s
   end

data/lib/head_music/instruments/instrument_family.rb

@@ -17,6 +17,7 @@ module HeadMusic::Instruments; end
 # @see HeadMusic::Instruments::Instrument
 class HeadMusic::Instruments::InstrumentFamily
   include HeadMusic::Named
+  include HeadMusic::Instruments::CatalogLookup
 
   INSTRUMENT_FAMILIES =
     YAML.load_file(File.expand_path("instrument_families.yml", __dir__)).freeze
@@ -52,14 +53,8 @@ class HeadMusic::Instruments::InstrumentFamily
       record_for_key(key_for_name(name))
   end
 
-  def key_for_name(name)
-    INSTRUMENT_FAMILIES.each do |key, _data|
-      I18n.config.available_locales.each do |locale|
-        translation = I18n.t("head_music.instruments.#{key}", locale: locale)
-        return key if translation.downcase == name.downcase
-      end
-    end
-    nil
+  def catalog
+    INSTRUMENT_FAMILIES
   end
 
   def record_for_key(key)

data/lib/head_music/instruments/instrument_name.rb

@@ -0,0 +1,49 @@
+# A module for musical instruments and their properties
+module HeadMusic::Instruments; end
+
+# Builds an instrument's localized display name from its catalog keys.
+#
+# The name is, in order of preference:
+#   1. an explicit translation of the instrument's own key,
+#   2. a name composed from the parent instrument and pitch for a child
+#      instrument (e.g. "Clarinet in B♭"), or
+#   3. a plain inference from the key ("bass_clarinet" -> "bass clarinet").
+class HeadMusic::Instruments::InstrumentName
+  # Localized name for an instrument key under the head_music.instruments scope.
+  def self.translate(key, locale: "en", default: nil)
+    I18n.translate(key, scope: %i[head_music instruments], locale: locale, default: default)
+  end
+
+  def initialize(name_key:, parent_key:, pitch_designation:)
+    @name_key = name_key
+    @parent_key = parent_key
+    @pitch_designation = pitch_designation
+  end
+
+  def to_s
+    self.class.translate(name_key) || child_instrument_name || inferred_name
+  end
+
+  private
+
+  attr_reader :name_key, :parent_key, :pitch_designation
+
+  # Name built from parent + pitch for child instruments, e.g. "Clarinet in B♭".
+  def child_instrument_name
+    return nil unless parent_key && pitch_designation
+
+    "#{parent_translation} in #{format_pitch_name(pitch_designation)}"
+  end
+
+  def parent_translation
+    self.class.translate(parent_key, default: parent_key.to_s.tr("_", " "))
+  end
+
+  def inferred_name
+    name_key.to_s.tr("_", " ")
+  end
+
+  def format_pitch_name(pitch_designation)
+    pitch_designation.to_s.tr("b", "♭").tr("#", "♯")
+  end
+end