head_music 8.3.0 → 9.0.1

data/lib/head_music/instruments/instrument.rb

@@ -1,67 +1,74 @@
 # Namespace for instrument definitions, categorization, and configuration
 module HeadMusic::Instruments; end
 
-# A musical instrument.
-# An instrument object can be assigned to a staff object.
-# Attributes:
-#   name_key: the name of the instrument
-#   alias_name_keys: an array of alternative names for the instrument
-#   orchestra_section_key: the section of the orchestra (e.g. "strings")
-#   family_key: the key for the family of the instrument (e.g. "saxophone")
-#   classification_keys: an array of classification_keys
-#   default_clefs: the default clef or system of clefs for the instrument
-#     - [treble] for instruments that use the treble clef
-#     - [treble, bass] for instruments that use the grand staff
-#   variants:
-#     a hash of default and alternative pitch designations
-# Associations:
-#   family: the family of the instrument (e.g. "saxophone")
-#   orchestra_section: the section of the orchestra (e.g. "strings")
+# A specific musical instrument instance with a selected variant.
+# Represents an actual playable instrument with its transposition and configuration.
+#
+# Examples:
+#   trumpet_in_c = HeadMusic::Instruments::Instrument.get("trumpet_in_c")
+#   trumpet_in_c = HeadMusic::Instruments::Instrument.get("trumpet", "in_c")
+#   clarinet = HeadMusic::Instruments::Instrument.get("clarinet")  # uses default Bb variant
+#
+# Attributes accessible via delegation to instrument_type and variant:
+#   name: display name including variant (e.g. "Trumpet in C")
+#   transposition: sounding transposition in semitones
+#   clefs: array of clefs for this instrument
+#   pitch_designation: the pitch designation for transposing instruments
 class HeadMusic::Instruments::Instrument
   include HeadMusic::Named
 
-  INSTRUMENTS = YAML.load_file(File.expand_path("instruments.yml", __dir__)).freeze
+  attr_reader :instrument_type, :variant
 
-  def self.get(name)
-    get_by_name(name)
-  end
+  # Factory method to get an Instrument instance
+  # @param type_or_name [String, Symbol] instrument type name or full name with variant
+  # @param variant_key [String, Symbol, nil] optional variant key if not included in name
+  # @return [Instrument] instrument instance with specified or default variant
+  def self.get(type_or_name, variant_key = nil)
+    return type_or_name if type_or_name.is_a?(self)
 
-  def self.all
-    HeadMusic::Instruments::InstrumentFamily.all
-    @all ||=
-      INSTRUMENTS.map { |key, _data| get(key) }.sort_by { |instrument| instrument.name.downcase }
-  end
+    type_name, parsed_variant_key = parse_instrument_name(type_or_name)
+    variant_key ||= parsed_variant_key
 
-  attr_reader(
-    :name_key, :alias_name_keys,
-    :family_key, :orchestra_section_key,
-    :variants, :classification_keys
-  )
+    instrument_type = HeadMusic::Instruments::InstrumentType.get(type_name)
+    return nil unless instrument_type&.name_key
 
-  def ==(other)
-    to_s == other.to_s
+    variant = find_variant(instrument_type, variant_key)
+    new(instrument_type, variant)
+  end
+
+  def initialize(instrument_type, variant)
+    @instrument_type = instrument_type
+    @variant = variant
+    initialize_name
   end
 
-  def translation(locale = :en)
-    return name unless name_key
+  # Delegations to instrument_type
+  delegate :name_key, :family_key, :family, :orchestra_section_key, :classification_keys,
+    :alias_name_keys, :variants, :translation, to: :instrument_type
 
-    I18n.translate(name_key, scope: %i[head_music instruments], locale: locale, default: name)
+  # Delegations to variant
+  delegate :pitch_designation, :staff_schemes, :default_staff_scheme, to: :variant
+
+  def default_staves
+    default_staff_scheme&.staves || []
   end
 
-  def family
-    return unless family_key
+  def default_clefs
+    default_staves&.map(&:clef) || []
+  end
 
-    HeadMusic::Instruments::InstrumentFamily.get(family_key)
+  def sounding_transposition
+    default_staves&.first&.sounding_transposition || 0
   end
 
-  # Returns true if the instrument sounds at a different pitch than written.
+  alias_method :default_sounding_transposition, :sounding_transposition
+
   def transposing?
-    default_sounding_transposition != 0
+    sounding_transposition != 0
   end
 
-  # Returns true if the instrument sounds at a different register than written.
   def transposing_at_the_octave?
-    transposing? && default_sounding_transposition % 12 == 0
+    transposing? && sounding_transposition % 12 == 0
   end
 
   def single_staff?
@@ -78,94 +85,77 @@ class HeadMusic::Instruments::Instrument
     default_clefs.any?
   end
 
-  def default_variant
-    variants.find(&:default?) || variants.first
-  end
-
-  delegate :default_staff_scheme, to: :default_variant
+  def ==(other)
+    return false unless other.is_a?(self.class)
 
-  def default_staves
-    default_staff_scheme&.staves || []
+    instrument_type == other.instrument_type && variant == other.variant
   end
 
-  def default_clefs
-    default_staves&.map(&:clef) || []
+  def to_s
+    name
   end
 
-  def default_sounding_transposition
-    default_staves&.first&.sounding_transposition || 0
-  end
-
-  private_class_method :new
-
   private
 
-  def initialize(name)
-    record = record_for_name(name)
-    if record
-      initialize_data_from_record(record)
+  def initialize_name
+    if variant.default? || !pitch_designation
+      self.name = instrument_type.name
+    elsif pitch_designation
+      pitch_name = format_pitch_name(pitch_designation)
+      self.name = "#{instrument_type.name} in #{pitch_name}"
     else
-      self.name = name.to_s
+      variant_name = variant.key.to_s.tr("_", " ")
+      self.name = "#{instrument_type.name} (#{variant_name})"
     end
   end
 
-  def record_for_name(name)
-    record_for_key(HeadMusic::Utilities::HashKey.for(name)) ||
-      record_for_key(key_for_name(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
+  def format_pitch_name(pitch_designation)
+    # Format the pitch designation for display
+    # e.g. "Bb" -> "B♭", "C" -> "C", "Eb" -> "E♭"
+    pitch_designation.to_s.gsub("b", "♭").gsub("#", "♯")
+  end
+
+  def self.parse_instrument_name(name)
+    name_str = name.to_s
+
+    # Check for variant patterns like "trumpet_in_e_flat"
+    if name_str =~ /(.+)_in_([a-g])_(flat|sharp)$/i
+      type_name = Regexp.last_match(1)
+      note = Regexp.last_match(2).downcase
+      accidental = Regexp.last_match(3)
+      variant_key = :"in_#{note}_#{accidental}"
+      [type_name, variant_key]
+    # Check for variant patterns like "trumpet_in_c" or "clarinet_in_a" or "trumpet_in_eb"
+    elsif name_str =~ /(.+)_in_([a-g][b#]?)$/i
+      type_name = Regexp.last_match(1)
+      variant_note = Regexp.last_match(2).downcase
+      # Convert "eb" to "e_flat", "bb" to "b_flat", etc.
+      if variant_note.end_with?("b") && variant_note.length == 2
+        note_letter = variant_note[0]
+        variant_key = :"in_#{note_letter}_flat"
+      elsif variant_note.end_with?("#") && variant_note.length == 2
+        note_letter = variant_note[0]
+        variant_key = :"in_#{note_letter}_sharp"
+      else
+        variant_key = :"in_#{variant_note}"
       end
+      [type_name, variant_key]
+    else
+      [name_str, nil]
     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 self.find_variant(instrument_type, variant_key)
+    return instrument_type.default_variant unless variant_key
 
-  def initialize_data_from_record(record)
-    initialize_family(record)
-    inherit_family_attributes(record)
-    initialize_names(record)
-    initialize_attributes(record)
-  end
+    # Convert to symbol for comparison
+    variant_sym = variant_key.to_sym
 
-  def initialize_family(record)
-    @family_key = record["family_key"]
-    @family = HeadMusic::Instruments::InstrumentFamily.get(family_key)
+    # Find the variant by key
+    variants = instrument_type.variants || []
+    variant = variants.find { |v| v.key == variant_sym }
+    variant || instrument_type.default_variant
   end
 
-  def inherit_family_attributes(record)
-    return unless family
-
-    @orchestra_section_key = family.orchestra_section_key
-    @classification_keys = family.classification_keys || []
-  end
-
-  def initialize_names(record)
-    @name_key = record["name_key"].to_sym
-    self.name = I18n.translate(name_key, scope: "head_music.instruments", locale: "en", default: inferred_name)
-    @alias_name_keys = record["alias_name_keys"] || []
-  end
-
-  def initialize_attributes(record)
-    @orchestra_section_key ||= record["orchestra_section_key"]
-    @classification_keys = [@classification_keys, record["classification_keys"]].flatten.compact.uniq
-    @variants =
-      (record["variants"] || {}).map do |key, attributes|
-        HeadMusic::Instruments::Variant.new(key, attributes)
-      end
-  end
-
-  def inferred_name
-    name_key.to_s.tr("_", " ")
-  end
+  private_class_method :parse_instrument_name, :find_variant
 end

data/lib/head_music/instruments/instrument_family.rb

@@ -3,8 +3,19 @@ module HeadMusic::Instruments; end
 
 # An *InstrumentFamily* is a species of instrument
 # that may exist in a variety of keys or other variations.
-# For example, _saxophone_ is an instrument family, while
-# _alto saxophone_ and _baritone saxophone_ are specific instruments.
+# For example:
+# - _saxophone_ is an instrument family, while
+#   _alto saxophone_ and _baritone saxophone_ are specific instruments.
+# - _oboe_ is an instrument family, while
+#   _oboe d'amore_ and _English horn_ are specific instruments.
+#
+# Instrument families are categorized by:
+# - orchestra section (e.g. woodwind, brass, percussion, strings)
+# - classification (e.g. bowed string, plucked string, double reed, single reed, brass, keyboard, electronic, percussion)
+#
+# Instrument families are defined in `lib/head_music/instruments/instrument_families.yml`.
+#
+# @see HeadMusic::Instruments::InstrumentType
 class HeadMusic::Instruments::InstrumentFamily
   include HeadMusic::Named
 

data/lib/head_music/instruments/instrument_type.rb

@@ -0,0 +1,188 @@
+# Namespace for instrument definitions, categorization, and configuration
+module HeadMusic::Instruments; end
+
+# A musical instrument type representing a catalog entry.
+# An instrument type defines the base characteristics and available variants for an instrument.
+# Attributes:
+#   name_key: the name of the instrument type
+#   alias_name_keys: an array of alternative names for the instrument type
+#   orchestra_section_key: the section of the orchestra (e.g. "strings")
+#   family_key: the key for the family of the instrument (e.g. "saxophone")
+#   classification_keys: an array of classification_keys
+#   default_clefs: the default clef or system of clefs for the instrument type
+#     - [treble] for instruments that use the treble clef
+#     - [treble, bass] for instruments that use the grand staff
+#   variants:
+#     a hash of default and alternative pitch designations
+# Associations:
+#   family: the family of the instrument (e.g. "saxophone")
+#   orchestra_section: the section of the orchestra (e.g. "strings")
+class HeadMusic::Instruments::InstrumentType
+  include HeadMusic::Named
+
+  INSTRUMENTS = YAML.load_file(File.expand_path("instruments.yml", __dir__)).freeze
+
+  def self.get(name)
+    get_by_name(name)
+  end
+
+  def self.all
+    HeadMusic::Instruments::InstrumentFamily.all
+    @all ||=
+      INSTRUMENTS.map { |key, _data| get(key) }.sort_by { |instrument| instrument.name.downcase }
+  end
+
+  attr_reader(
+    :name_key, :alias_name_keys,
+    :family_key, :orchestra_section_key,
+    :variants, :classification_keys
+  )
+
+  def ==(other)
+    to_s == other.to_s
+  end
+
+  def translation(locale = :en)
+    return name unless name_key
+
+    I18n.translate(name_key, scope: %i[head_music instruments], locale: locale, default: name)
+  end
+
+  def family
+    return unless family_key
+
+    HeadMusic::Instruments::InstrumentFamily.get(family_key)
+  end
+
+  # Returns true if the instrument sounds at a different pitch than written.
+  def transposing?
+    default_sounding_transposition != 0
+  end
+
+  # Returns true if the instrument sounds at a different register than written.
+  def transposing_at_the_octave?
+    transposing? && default_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?
+  end
+
+  def default_variant
+    variants&.find(&:default?) || variants&.first
+  end
+
+  def default_instrument
+    @default_instrument ||= HeadMusic::Instruments::Instrument.new(self, default_variant)
+  end
+
+  def default_staff_scheme
+    default_variant&.default_staff_scheme
+  end
+
+  def default_staves
+    default_staff_scheme&.staves || []
+  end
+
+  def default_clefs
+    default_staves&.map(&:clef) || []
+  end
+
+  def default_sounding_transposition
+    default_staves&.first&.sounding_transposition || 0
+  end
+
+  private_class_method :new
+
+  private
+
+  def initialize(name)
+    record = record_for_name(name)
+    if record
+      initialize_data_from_record(record)
+    else
+      self.name = name.to_s
+    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)
+    initialize_family(record)
+    inherit_family_attributes(record)
+    initialize_names(record)
+    initialize_attributes(record)
+  end
+
+  def initialize_family(record)
+    @family_key = record["family_key"]
+    @family = HeadMusic::Instruments::InstrumentFamily.get(family_key)
+  end
+
+  def inherit_family_attributes(record)
+    return unless family
+
+    @orchestra_section_key = family.orchestra_section_key
+    @classification_keys = family.classification_keys || []
+  end
+
+  def initialize_names(record)
+    @name_key = record["name_key"].to_sym
+    self.name = I18n.translate(name_key, scope: "head_music.instruments", locale: "en", default: inferred_name)
+    @alias_name_keys = record["alias_name_keys"] || []
+  end
+
+  def initialize_attributes(record)
+    @orchestra_section_key ||= record["orchestra_section_key"]
+    @classification_keys = [@classification_keys, record["classification_keys"]].flatten.compact.uniq
+    @variants =
+      (record["variants"] || {}).map do |key, attributes|
+        HeadMusic::Instruments::Variant.new(key, attributes)
+      end
+  end
+
+  def inferred_name
+    name_key.to_s.tr("_", " ")
+  end
+end

data/lib/head_music/instruments/score_order.rb

@@ -0,0 +1,139 @@
+module HeadMusic::Instruments; end
+
+class HeadMusic::Instruments::ScoreOrder
+  include HeadMusic::Named
+
+  SCORE_ORDERS = YAML.load_file(File.expand_path("score_orders.yml", __dir__)).freeze
+
+  DEFAULT_ENSEMBLE_TYPE_KEY = :orchestral
+
+  attr_reader :ensemble_type_key, :sections
+
+  # Factory method to get a ScoreOrder instance for a specific ensemble type
+  def self.get(ensemble_type)
+    @instances ||= {}
+    key = HeadMusic::Utilities::HashKey.for(ensemble_type)
+    return unless SCORE_ORDERS.key?(key.to_s)
+
+    @instances[key] ||= new(key)
+  end
+
+  # Convenience method to order instruments in orchestral order
+  def self.in_orchestral_order(instruments)
+    get(:orchestral).order(instruments)
+  end
+
+  # Convenience method to order instruments in concert band order
+  def self.in_band_order(instruments)
+    get(:band).order(instruments)
+  end
+
+  # Accepts a list of instruments and orders them according to this ensemble type's conventions
+  def order(instruments)
+    valid_inputs = instruments.compact.reject { |i| i.respond_to?(:empty?) && i.empty? }
+    instrument_objects = valid_inputs.map { |i| normalize_to_instrument(i) }.compact
+
+    # Build ordering index
+    ordering_index = build_ordering_index
+
+    # Separate known and unknown instruments
+    known_instruments = []
+    unknown_instruments = []
+
+    instrument_objects.each do |instrument|
+      position_info = find_position_with_transposition(instrument, ordering_index)
+      if position_info
+        known_instruments << [instrument, position_info]
+      else
+        unknown_instruments << instrument
+      end
+    end
+
+    # Sort known instruments by position (primary) and transposition (secondary)
+    sorted_known = known_instruments.sort_by { |_, pos_info|
+      [pos_info[:position], -pos_info[:transposition]]
+    }.map(&:first)
+    sorted_known + unknown_instruments.sort_by(&:to_s)
+  end
+
+  private_class_method :new
+
+  private
+
+  def initialize(ensemble_type_key = DEFAULT_ENSEMBLE_TYPE_KEY)
+    @ensemble_type_key = ensemble_type_key.to_sym
+    data = SCORE_ORDERS[ensemble_type_key.to_s]
+
+    @sections = data["sections"] || []
+    self.name = data["name"] || ensemble_type_key.to_s.tr("_", " ").capitalize
+  end
+
+  def normalize_to_instrument(input)
+    # Return if already an Instrument instance
+    return input if input.is_a?(HeadMusic::Instruments::Instrument)
+
+    # Return InstrumentType instances as-is for backward compatibility (duck typing)
+    return input.default_instrument if input.is_a?(HeadMusic::Instruments::InstrumentType)
+
+    # Return other objects that respond to required methods (mock objects, etc.)
+    return input if input.respond_to?(:name_key) && input.respond_to?(:family_key)
+
+    # Create an Instrument instance for string inputs
+    HeadMusic::Instruments::Instrument.get(input) || HeadMusic::Instruments::InstrumentType.get(input)
+  end
+
+  # Builds an index mapping instrument names to their position in the order
+  def build_ordering_index
+    index = {}
+    position = 0
+
+    sections.each do |section|
+      instruments = section["instruments"] || []
+      instruments.each do |instrument_key|
+        # Store position for this instrument key
+        index[instrument_key.to_s] = position
+        position += 1
+      end
+    end
+
+    index
+  end
+
+  # Finds the position of an instrument in the ordering
+  def find_position(instrument, ordering_index)
+    # Try exact match with name_key
+    return ordering_index[instrument.name_key.to_s] if instrument.name_key && ordering_index.key?(instrument.name_key.to_s)
+
+    # Try matching by family + range category (e.g., alto_saxophone -> saxophone family)
+    if instrument.family_key
+      family_base = instrument.family_key.to_s
+      instrument_key = instrument.name_key.to_s
+
+      # Check if this is a variant of a family (e.g., alto_saxophone)
+      if instrument_key.include?(family_base)
+        # Look for the specific variant first
+        return ordering_index[instrument_key] if ordering_index.key?(instrument_key)
+
+        # Fall back to generic family instrument if listed
+        return ordering_index[family_base] if ordering_index.key?(family_base)
+      end
+    end
+
+    # Try normalized name (lowercase, underscored)
+    normalized = instrument.name.downcase.tr(" ", "_").tr("-", "_")
+    return ordering_index[normalized] if ordering_index.key?(normalized)
+
+    nil
+  end
+
+  # Finds the position and transposition information for an instrument
+  def find_position_with_transposition(instrument, ordering_index)
+    position = find_position(instrument, ordering_index)
+    return nil unless position
+
+    # Get the sounding transposition for secondary sorting
+    transposition = instrument.default_sounding_transposition || 0
+
+    {position: position, transposition: transposition}
+  end
+end