head_music 9.0.1 → 11.1.0

data/lib/head_music/instruments/instrument.rb

@@ -1,53 +1,136 @@
-# Namespace for instrument definitions, categorization, and configuration
 module HeadMusic::Instruments; end
 
-# A specific musical instrument instance with a selected variant.
-# Represents an actual playable instrument with its transposition and configuration.
+# A musical instrument with parent-based inheritance.
+#
+# Instruments can inherit from parent instruments, allowing for a clean
+# hierarchy where child instruments override specific attributes while
+# inheriting others from their parents.
 #
 # 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
+#   trumpet = HeadMusic::Instruments::Instrument.get("trumpet")
+#   clarinet_in_a = HeadMusic::Instruments::Instrument.get("clarinet_in_a")
+#   clarinet_in_a.parent  # => clarinet
+#   clarinet_in_a.pitch_key  # => "a" (own attribute)
+#   clarinet_in_a.family_key  # => "clarinet" (inherited from parent)
 #
-# 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
+# Attributes:
+#   name_key: the primary identifier for the instrument
+#   parent_key: optional key referencing the parent instrument
+#   family_key: the instrument family (e.g., "clarinet", "trumpet")
+#   pitch_key: the pitch designation (e.g., "b_flat", "a", "c")
+#   alias_name_keys: alternative names for the instrument
+#   range_categories: size/range classifications
+#   staff_schemes: notation schemes (to be moved to NotationStyle later)
 class HeadMusic::Instruments::Instrument
   include HeadMusic::Named
 
-  attr_reader :instrument_type, :variant
+  INSTRUMENTS = YAML.load_file(File.expand_path("instruments.yml", __dir__)).freeze
+
+  attr_reader :name_key, :parent_key, :alias_name_keys, :range_categories, :staff_schemes_data
+
+  class << self
+    # Factory method to get an Instrument instance
+    # @param name [String, Symbol] instrument name (e.g., "clarinet", "clarinet_in_a")
+    # @param variant_key [String, Symbol, nil] DEPRECATED: variant key (for backward compatibility)
+    # @return [Instrument, nil] instrument instance or nil if not found
+    def get(name, variant_key = nil)
+      return name if name.is_a?(self)
+
+      # Handle two-argument form for backward compatibility
+      if variant_key
+        combined_name = "#{name}_#{variant_key}"
+        result = find_valid_instrument(combined_name) || find_valid_instrument(name.to_s)
+      else
+        result = find_valid_instrument(name.to_s) || find_valid_instrument(normalize_variant_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)
+      result
+    end
+
+    def find_valid_instrument(name)
+      instrument = get_by_name(name)
+      instrument&.name_key ? instrument : nil
+    end
+
+    def all
+      HeadMusic::Instruments::InstrumentFamily.all # Ensure families are loaded first
+      INSTRUMENTS.map { |key, _data| get(key) }
+      @all ||= @instances.values.compact.sort_by { |instrument| instrument.name.downcase }
+    end
 
-    type_name, parsed_variant_key = parse_instrument_name(type_or_name)
-    variant_key ||= parsed_variant_key
+    private
 
-    instrument_type = HeadMusic::Instruments::InstrumentType.get(type_name)
-    return nil unless instrument_type&.name_key
+    # Convert shorthand variant names to full form
+    # e.g., "trumpet_in_eb" -> "trumpet_in_e_flat"
+    # e.g., "clarinet_in_bb" -> "clarinet_in_b_flat"
+    def normalize_variant_name(name)
+      name_str = name.to_s
 
-    variant = find_variant(instrument_type, variant_key)
-    new(instrument_type, variant)
+      # Match patterns like "_in_eb" or "_in_bb" at the end (flat)
+      flat_pattern = /^(.+)_in_([a-g])b$/i
+      sharp_pattern = %r{^(.+)_in_([a-g])\#$}i
+
+      if name_str =~ flat_pattern
+        instrument = Regexp.last_match(1)
+        note = Regexp.last_match(2).downcase
+        "#{instrument}_in_#{note}_flat"
+      elsif name_str =~ sharp_pattern
+        instrument = Regexp.last_match(1)
+        note = Regexp.last_match(2).downcase
+        "#{instrument}_in_#{note}_sharp"
+      else
+        name_str
+      end
+    end
   end
 
-  def initialize(instrument_type, variant)
-    @instrument_type = instrument_type
-    @variant = variant
-    initialize_name
+  # Parent instrument (for inheritance)
+  def parent
+    return nil unless parent_key
+
+    @parent ||= self.class.get(parent_key)
   end
 
-  # Delegations to instrument_type
-  delegate :name_key, :family_key, :family, :orchestra_section_key, :classification_keys,
-    :alias_name_keys, :variants, :translation, to: :instrument_type
+  # Attributes with parent chain resolution
+
+  def family_key
+    @family_key || parent&.family_key
+  end
+
+  def pitch_key
+    @pitch_key || parent&.pitch_key
+  end
 
-  # Delegations to variant
-  delegate :pitch_designation, :staff_schemes, :default_staff_scheme, to: :variant
+  def family
+    return unless family_key
+
+    HeadMusic::Instruments::InstrumentFamily.get(family_key)
+  end
+
+  def orchestra_section_key
+    family&.orchestra_section_key
+  end
+
+  def classification_keys
+    family&.classification_keys || []
+  end
+
+  # Pitch designation as a Spelling object (for backward compatibility)
+  def pitch_designation
+    return nil unless pitch_key
+
+    @pitch_designation ||= HeadMusic::Rudiment::Spelling.get(pitch_key_to_designation)
+  end
+
+  # Staff schemes (notation concern - kept for backward compatibility)
+  def staff_schemes
+    @staff_schemes ||= build_staff_schemes
+  end
+
+  def default_staff_scheme
+    @default_staff_scheme ||=
+      staff_schemes.find(&:default?) || staff_schemes.first
+  end
 
   def default_staves
     default_staff_scheme&.staves || []
@@ -85,77 +168,163 @@ class HeadMusic::Instruments::Instrument
     default_clefs.any?
   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 ==(other)
     return false unless other.is_a?(self.class)
 
-    instrument_type == other.instrument_type && variant == other.variant
+    name_key == other.name_key
   end
 
   def to_s
     name
   end
 
+  # For backward compatibility with code that expects variants
+  def variants
+    []
+  end
+
+  def default_variant
+    nil
+  end
+
+  # Collect all instrument_configurations from self and ancestors
+  def instrument_configurations
+    own_configs = HeadMusic::Instruments::InstrumentConfiguration.for_instrument(name_key)
+    parent_configs = parent&.instrument_configurations || []
+    own_configs + parent_configs
+  end
+
+  def stringing
+    @stringing ||= HeadMusic::Instruments::Stringing.for_instrument(self) || parent&.stringing
+  end
+
+  def alternate_tunings
+    own_tunings = HeadMusic::Instruments::AlternateTuning.for_instrument(name_key)
+    return own_tunings if own_tunings.any?
+
+    parent&.alternate_tunings || []
+  end
+
+  private_class_method :new
+
   private
 
-  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}"
+  def initialize(name)
+    record = record_for_name(name)
+    if record
+      initialize_data_from_record(record)
     else
-      variant_name = variant.key.to_s.tr("_", " ")
-      self.name = "#{instrument_type.name} (#{variant_name})"
+      # Mark as invalid - will be filtered out by get_by_name
+      @name_key = nil
+      self.name = name.to_s
     end
   end
 
-  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}"
+  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
-      [type_name, variant_key]
+    end
+    nil
+  end
+
+  def initialize_data_from_record(record)
+    @name_key = record["name_key"].to_sym
+    @parent_key = record["parent_key"]&.to_sym
+    @family_key = record["family_key"]
+    @pitch_key = record["pitch_key"]
+    @alias_name_keys = record["alias_name_keys"] || []
+    @range_categories = record["range_categories"] || []
+    @staff_schemes_data = record["staff_schemes"] || {}
+
+    initialize_name
+  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
-      [name_str, nil]
+      # Fall back to inferred name
+      self.name = inferred_name
     end
   end
 
-  def self.find_variant(instrument_type, variant_key)
-    return instrument_type.default_variant unless variant_key
+  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("#", "♯")
+  end
 
-    # Convert to symbol for comparison
-    variant_sym = variant_key.to_sym
+  # Convert pitch_key (e.g., "b_flat") to designation format (e.g., "Bb")
+  def pitch_key_to_designation
+    return nil unless pitch_key
 
-    # Find the variant by key
-    variants = instrument_type.variants || []
-    variant = variants.find { |v| v.key == variant_sym }
-    variant || instrument_type.default_variant
+    key = pitch_key.to_s
+    if key.end_with?("_flat")
+      "#{key[0].upcase}b"
+    elsif key.end_with?("_sharp")
+      "#{key[0].upcase}#"
+    else
+      key.upcase
+    end
   end
 
-  private_class_method :parse_instrument_name, :find_variant
+  def build_staff_schemes
+    return parent&.staff_schemes || [] if staff_schemes_data.empty?
+
+    staff_schemes_data.map do |key, list|
+      HeadMusic::Instruments::StaffScheme.new(
+        key: key,
+        instrument: self,
+        list: list
+      )
+    end
+  end
 end

data/lib/head_music/instruments/instrument_configuration.rb

@@ -0,0 +1,66 @@
+module HeadMusic::Instruments; end
+
+# A configurable aspect of an instrument, such as a leadpipe, mute, or attachment.
+#
+# Examples:
+#   - Piccolo trumpet "leadpipe" configuration with options: b_flat (default), a
+#   - Trumpet "mute" configuration with options: open (default), straight, cup, harmon
+#   - Bass trombone "f_attachment" with options: disengaged (default), engaged
+class HeadMusic::Instruments::InstrumentConfiguration
+  CONFIGURATIONS = YAML.load_file(File.expand_path("instrument_configurations.yml", __dir__)).freeze
+
+  attr_reader :name_key, :instrument_key, :options
+
+  class << self
+    def for_instrument(instrument_key)
+      instrument_key = instrument_key.to_s
+      return [] unless CONFIGURATIONS.key?(instrument_key)
+
+      CONFIGURATIONS[instrument_key].map do |config_name, config_data|
+        new(
+          name_key: config_name,
+          instrument_key: instrument_key,
+          options_data: config_data["options"] || {}
+        )
+      end
+    end
+  end
+
+  def initialize(name_key:, instrument_key:, options_data: {})
+    @name_key = name_key.to_sym
+    @instrument_key = instrument_key.to_sym
+    @options = build_options(options_data)
+  end
+
+  def default_option
+    @default_option ||= options.find(&:default?) || options.first
+  end
+
+  def option(option_key)
+    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
+
+  private
+
+  def build_options(options_data)
+    options_data.map do |option_name, option_attrs|
+      attrs = option_attrs || {}
+      HeadMusic::Instruments::InstrumentConfigurationOption.new(
+        name_key: option_name,
+        default: attrs["default"],
+        transposition_semitones: attrs["transposition_semitones"],
+        lowest_pitch_semitones: attrs["lowest_pitch_semitones"]
+      )
+    end
+  end
+end

data/lib/head_music/instruments/instrument_configuration_option.rb

@@ -0,0 +1,38 @@
+module HeadMusic::Instruments; end
+
+# An option for an instrument configuration.
+#
+# Examples:
+#   - Piccolo trumpet leadpipe: "a" option with transposition_semitones: -1
+#   - Bass trombone F attachment: "engaged" option with lowest_pitch_semitones: -6
+#   - Trumpet mute: "straight", "cup", "harmon" options (no pitch effects)
+class HeadMusic::Instruments::InstrumentConfigurationOption
+  attr_reader :name_key, :default, :transposition_semitones, :lowest_pitch_semitones
+
+  def initialize(name_key:, default: false, transposition_semitones: nil, lowest_pitch_semitones: nil)
+    @name_key = name_key.to_sym
+    @default = default
+    @transposition_semitones = transposition_semitones
+    @lowest_pitch_semitones = lowest_pitch_semitones
+  end
+
+  def default?
+    @default == true
+  end
+
+  def affects_transposition?
+    !transposition_semitones.nil?
+  end
+
+  def affects_range?
+    !lowest_pitch_semitones.nil?
+  end
+
+  def ==(other)
+    to_s == other.to_s
+  end
+
+  def to_s
+    name_key.to_s
+  end
+end