head_music 8.3.0 → 9.0.1

data/lib/head_music/rudiment/mode.rb

@@ -0,0 +1,92 @@
+# A module for music rudiments
+module HeadMusic::Rudiment; end
+
+# Represents a musical mode (church modes)
+class HeadMusic::Rudiment::Mode < HeadMusic::Rudiment::DiatonicContext
+  include HeadMusic::Named
+
+  MODES = %i[ionian dorian phrygian lydian mixolydian aeolian locrian].freeze
+
+  attr_reader :mode_name
+
+  def self.get(identifier)
+    return identifier if identifier.is_a?(HeadMusic::Rudiment::Mode)
+
+    @modes ||= {}
+    tonic_spelling, mode_name = parse_identifier(identifier)
+    hash_key = HeadMusic::Utilities::HashKey.for(identifier)
+    @modes[hash_key] ||= new(tonic_spelling, mode_name)
+  end
+
+  def self.parse_identifier(identifier)
+    identifier = identifier.to_s.strip
+    parts = identifier.split(/\s+/)
+    tonic_spelling = parts[0]
+    mode_name = parts[1] || "ionian"
+    [tonic_spelling, mode_name]
+  end
+
+  def initialize(tonic_spelling, mode_name = :ionian)
+    super(tonic_spelling)
+    @mode_name = mode_name.to_s.downcase.to_sym
+    raise ArgumentError, "Mode must be one of: #{MODES.join(", ")}" unless MODES.include?(@mode_name)
+  end
+
+  def scale_type
+    @scale_type ||= HeadMusic::Rudiment::ScaleType.get(mode_name)
+  end
+
+  def relative_major
+    case mode_name
+    when :ionian
+      return HeadMusic::Rudiment::Key.get("#{tonic_spelling} major")
+    when :dorian
+      relative_pitch = tonic_pitch + -2
+    when :phrygian
+      relative_pitch = tonic_pitch + -4
+    when :lydian
+      relative_pitch = tonic_pitch + -5
+    when :mixolydian
+      relative_pitch = tonic_pitch + -7
+    when :aeolian
+      relative_pitch = tonic_pitch + -9
+    when :locrian
+      relative_pitch = tonic_pitch + -11
+    end
+
+    HeadMusic::Rudiment::Key.get("#{relative_pitch.spelling} major")
+  end
+
+  def relative
+    relative_major
+  end
+
+  def parallel
+    # Return the parallel major or minor key
+    case mode_name
+    when :ionian
+      HeadMusic::Rudiment::Key.get("#{tonic_spelling} major")
+    when :aeolian
+      HeadMusic::Rudiment::Key.get("#{tonic_spelling} minor")
+    when :dorian, :phrygian
+      HeadMusic::Rudiment::Key.get("#{tonic_spelling} minor")
+    when :lydian, :mixolydian
+      HeadMusic::Rudiment::Key.get("#{tonic_spelling} major")
+    when :locrian
+      HeadMusic::Rudiment::Key.get("#{tonic_spelling} minor")
+    end
+  end
+
+  def name
+    "#{tonic_spelling} #{mode_name}"
+  end
+
+  def to_s
+    name
+  end
+
+  def ==(other)
+    other = self.class.get(other)
+    tonic_spelling == other.tonic_spelling && mode_name == other.mode_name
+  end
+end

data/lib/head_music/rudiment/musical_symbol.rb

@@ -2,7 +2,7 @@
 module HeadMusic::Rudiment; end
 
 # A symbol is a mark or sign that signifies a particular rudiment of music
-class HeadMusic::Rudiment::MusicalSymbol
+class HeadMusic::Rudiment::MusicalSymbol < HeadMusic::Rudiment::Base
   attr_reader :ascii, :unicode, :html_entity
 
   def initialize(ascii: nil, unicode: nil, html_entity: nil)

data/lib/head_music/rudiment/note.rb

@@ -0,0 +1,112 @@
+# A module for music rudiments
+module HeadMusic::Rudiment; end
+
+# A Note is a fundamental musical element consisting of a pitch and a duration.
+# This is the rudiment version, representing the abstract concept of a note
+# independent of its placement in a composition.
+#
+# For notes placed within a composition context, see HeadMusic::Content::Note
+class HeadMusic::Rudiment::Note < HeadMusic::Rudiment::RhythmicElement
+  include HeadMusic::Named
+
+  attr_reader :pitch
+
+  delegate :spelling, :register, :letter_name, :alteration, to: :pitch
+  delegate :sharp?, :flat?, :natural?, to: :pitch
+  delegate :pitch_class, :midi_note_number, :frequency, to: :pitch
+
+  # Regex pattern for parsing note strings like "C#4 quarter" or "Eb3 dotted half"
+  # Extract the core pattern from Spelling::MATCHER without anchors
+  PITCH_PATTERN = /([A-G])(#{HeadMusic::Rudiment::Alteration::PATTERN.source}?)(-?\d+)?/i
+  MATCHER = /^\s*(#{PITCH_PATTERN.source})\s+(.+)$/i
+
+  def self.get(pitch, rhythmic_value = nil)
+    return pitch if pitch.is_a?(HeadMusic::Rudiment::Note)
+
+    if rhythmic_value.nil? && pitch.is_a?(String)
+      # Try to parse as "pitch rhythmic_value" format (e.g., "F#4 dotted-quarter")
+      match = pitch.match(MATCHER)
+      if match
+        pitch_str = match[1] # The full pitch part
+        rhythmic_value_str = match[5] # The rhythmic value part
+
+        pitch_obj = HeadMusic::Rudiment::Pitch.get(pitch_str)
+        rhythmic_value_obj = HeadMusic::Rudiment::RhythmicValue.get(rhythmic_value_str)
+
+        return fetch_or_create(pitch_obj, rhythmic_value_obj) if pitch_obj && rhythmic_value_obj
+      end
+
+      # If parsing fails, treat it as just a pitch with default quarter note
+      pitch_obj = HeadMusic::Rudiment::Pitch.get(pitch)
+      return fetch_or_create(pitch_obj, HeadMusic::Rudiment::RhythmicValue.get(:quarter)) if pitch_obj
+
+      nil
+    else
+      pitch = HeadMusic::Rudiment::Pitch.get(pitch)
+      rhythmic_value = HeadMusic::Rudiment::RhythmicValue.get(rhythmic_value || :quarter)
+      fetch_or_create(pitch, rhythmic_value)
+    end
+  end
+
+  def self.fetch_or_create(pitch, rhythmic_value)
+    @notes ||= {}
+    hash_key = [pitch.to_s, rhythmic_value.to_s].join("_")
+    @notes[hash_key] ||= new(pitch, rhythmic_value)
+  end
+
+  def initialize(pitch, rhythmic_value)
+    super(rhythmic_value)
+    @pitch = pitch
+  end
+
+  # Make new public for this concrete class
+  public_class_method :new
+
+  def name
+    "#{pitch} #{rhythmic_value}"
+  end
+
+  def to_s
+    name
+  end
+
+  def ==(other)
+    other = HeadMusic::Rudiment::Note.get(other)
+    super && pitch == other.pitch
+  end
+
+  def <=>(other)
+    return nil unless other.is_a?(HeadMusic::Rudiment::RhythmicElement)
+    return super unless other.is_a?(self.class)
+
+    [rhythmic_value, pitch] <=> [other.rhythmic_value, other.pitch]
+  end
+
+  # Transpose the note up by an interval or semitones
+  def +(other)
+    new_pitch = pitch + other
+    self.class.get(new_pitch, rhythmic_value)
+  end
+
+  # Transpose the note down by an interval or semitones
+  def -(other)
+    new_pitch = pitch - other
+    self.class.get(new_pitch, rhythmic_value)
+  end
+
+  # Override to maintain pitch when changing rhythmic value
+  def with_rhythmic_value(new_rhythmic_value)
+    self.class.get(pitch, new_rhythmic_value)
+  end
+
+  # Change the pitch while keeping the same rhythmic value
+  def with_pitch(new_pitch)
+    self.class.get(new_pitch, rhythmic_value)
+  end
+
+  def sounded?
+    true
+  end
+
+  private_class_method :fetch_or_create
+end

data/lib/head_music/rudiment/pitch/parser.rb

@@ -0,0 +1,52 @@
+class HeadMusic::Rudiment::Pitch::Parser
+  attr_reader :identifier, :letter_name, :alteration, :register
+
+  LetterName = HeadMusic::Rudiment::LetterName
+  Alteration = HeadMusic::Rudiment::Alteration
+  Spelling = HeadMusic::Rudiment::Spelling
+  Register = HeadMusic::Rudiment::Register
+  Pitch = HeadMusic::Rudiment::Pitch
+
+  # Pattern that handles negative registers (e.g., -1) and positive registers
+  # Anchored to match complete pitch strings only
+  PATTERN = /\A(#{LetterName::PATTERN})?(#{Alteration::PATTERN.source})?(-?\d+)?\z/
+
+  # Parse a pitch identifier and return a Pitch object
+  # Returns nil if the identifier cannot be parsed into a valid pitch
+  def self.parse(identifier)
+    return nil if identifier.nil?
+    new(identifier).pitch
+  end
+
+  def initialize(identifier)
+    @identifier = identifier.to_s.strip
+    parse_components
+  end
+
+  def pitch
+    return unless spelling
+    # Default to register 4 if not provided (matching old behavior)
+    # Convert Register object to integer for fetch_or_create
+    reg = register ? register.to_i : Register::DEFAULT
+
+    @pitch ||= Pitch.fetch_or_create(spelling, reg)
+  end
+
+  def spelling
+    return unless letter_name
+
+    @spelling ||= Spelling.new(letter_name, alteration)
+  end
+
+  private
+
+  def parse_components
+    match = identifier.match(PATTERN)
+
+    if match
+      @letter_name = LetterName.get(match[1].upcase) unless match[1].to_s.empty?
+      @alteration = Alteration.get(match[2] || "") unless match[2].to_s.empty?
+      @register = Register.get(match[3]&.to_i) unless match[3].to_s.empty?
+    end
+  end
+end

data/lib/head_music/rudiment/pitch.rb

@@ -1,8 +1,7 @@
-# A module for music rudiments
 module HeadMusic::Rudiment; end
 
 # A pitch is a named frequency represented by a spelling and a register.
-class HeadMusic::Rudiment::Pitch
+class HeadMusic::Rudiment::Pitch < HeadMusic::Rudiment::Base
   include Comparable
 
   attr_reader :spelling, :register
@@ -29,6 +28,8 @@ class HeadMusic::Rudiment::Pitch
   #   - a name string, such as 'Ab4'
   #   - a number corresponding to the midi note number
   def self.get(value)
+    return value if value.is_a?(HeadMusic::Rudiment::Pitch)
+
     from_pitch_class(value) ||
       from_name(value) ||
       from_number(value)
@@ -51,7 +52,7 @@ class HeadMusic::Rudiment::Pitch
   def self.from_name(name)
     return nil unless name == name.to_s
 
-    fetch_or_create(HeadMusic::Rudiment::Spelling.get(name), HeadMusic::Rudiment::Register.get(name).to_i)
+    Parser.parse(name)
   end
 
   def self.from_number(number)
@@ -114,7 +115,7 @@ class HeadMusic::Rudiment::Pitch
   end
 
   def natural
-    HeadMusic::Rudiment::Pitch.get(to_s.gsub(HeadMusic::Rudiment::Alteration.matcher, ""))
+    HeadMusic::Rudiment::Pitch.get(to_s.gsub(HeadMusic::Rudiment::Alteration::PATTERN, ""))
   end
 
   def +(other)
@@ -167,8 +168,6 @@ class HeadMusic::Rudiment::Pitch
     letter_name_steps_to(other) + 7 * octave_changes_to(other)
   end
 
-  private_class_method :new
-
   private
 
   def octave_changes_to(other)

data/lib/head_music/rudiment/pitch_class.rb

@@ -2,7 +2,7 @@
 module HeadMusic::Rudiment; end
 
 # A pitch class is a set of pitches separated by octaves.
-class HeadMusic::Rudiment::PitchClass
+class HeadMusic::Rudiment::PitchClass < HeadMusic::Rudiment::Base
   include Comparable
 
   attr_reader :number, :spelling

data/lib/head_music/rudiment/quality.rb

@@ -2,7 +2,7 @@
 module HeadMusic::Rudiment; end
 
 # A quality is a categorization of an interval.
-class HeadMusic::Rudiment::Quality
+class HeadMusic::Rudiment::Quality < HeadMusic::Rudiment::Base
   SHORTHAND = {
     perfect: "P",
     major: "M",

data/lib/head_music/rudiment/reference_pitch.rb

@@ -3,7 +3,7 @@ module HeadMusic::Rudiment; end
 
 # A reference pitch has a pitch and a frequency
 # With no arguments, it assumes that A4 = 440.0 Hz
-class HeadMusic::Rudiment::ReferencePitch
+class HeadMusic::Rudiment::ReferencePitch < HeadMusic::Rudiment::Base
   include HeadMusic::Named
 
   DEFAULT_PITCH_NAME = "A4"

data/lib/head_music/rudiment/register.rb

@@ -6,9 +6,12 @@ module HeadMusic::Rudiment; end
 # A pitch is a spelling plus a register. For example, C4 is middle C and C5 is the C one octave higher.
 # The number changes between the letter names B and C regardless of sharps and flats,
 # so as an extreme example, Cb5 is actually a semitone below B#4.
-class HeadMusic::Rudiment::Register
+class HeadMusic::Rudiment::Register < HeadMusic::Rudiment::Base
   include Comparable
 
+  AUDIBLE_REGISTERS = (0..10).map.freeze
+  PATTERN = Regexp.union(AUDIBLE_REGISTERS.map(&:to_s))
+
   DEFAULT = 4
 
   def self.get(identifier)

data/lib/head_music/rudiment/rest.rb

@@ -0,0 +1,36 @@
+# A module for music rudiments
+module HeadMusic::Rudiment; end
+
+# A Rest represents a period of silence with a specific rhythmic value.
+# It inherits from RhythmicElement and has a duration but no pitch.
+class HeadMusic::Rudiment::Rest < HeadMusic::Rudiment::RhythmicElement
+  include HeadMusic::Named
+
+  # Make new public for this concrete class
+  public_class_method :new
+
+  def self.get(rhythmic_value)
+    return rhythmic_value if rhythmic_value.is_a?(HeadMusic::Rudiment::Rest)
+
+    rhythmic_value = HeadMusic::Rudiment::RhythmicValue.get(rhythmic_value)
+    return nil unless rhythmic_value
+
+    fetch_or_create(rhythmic_value)
+  end
+
+  def self.fetch_or_create(rhythmic_value)
+    @rests ||= {}
+    hash_key = rhythmic_value.to_s
+    @rests[hash_key] ||= new(rhythmic_value)
+  end
+
+  def name
+    "#{rhythmic_value} rest"
+  end
+
+  def sounded?
+    false
+  end
+
+  private_class_method :fetch_or_create
+end

data/lib/head_music/rudiment/rhythmic_element.rb

@@ -0,0 +1,53 @@
+# A module for music rudiments
+module HeadMusic::Rudiment; end
+
+# Abstract base class for rhythmic elements that have a rhythmic value.
+# This includes notes (pitched), rests (silence), and unpitched notes (percussion).
+class HeadMusic::Rudiment::RhythmicElement < HeadMusic::Rudiment::Base
+  include Comparable
+
+  LetterName = HeadMusic::Rudiment::LetterName
+  Alteration = HeadMusic::Rudiment::Alteration
+  Register = HeadMusic::Rudiment::Register
+  RhythmicValue = HeadMusic::Rudiment::RhythmicValue
+
+  attr_reader :rhythmic_value
+
+  delegate :unit, :dots, :tied_value, :ticks, to: :rhythmic_value
+
+  # Make new private to prevent direct instantiation of abstract class
+  private_class_method :new
+
+  def initialize(rhythmic_value)
+    @rhythmic_value = rhythmic_value
+  end
+
+  # Create a new instance with a different rhythmic value
+  def with_rhythmic_value(new_rhythmic_value)
+    self.class.get(new_rhythmic_value)
+  end
+
+  def ==(other)
+    return false unless other.is_a?(self.class)
+    rhythmic_value == other.rhythmic_value
+  end
+
+  def <=>(other)
+    return nil unless other.is_a?(HeadMusic::Rudiment::RhythmicElement)
+    rhythmic_value <=> other.rhythmic_value
+  end
+
+  def to_s
+    name
+  end
+
+  # Abstract method - must be implemented by subclasses
+  def name
+    raise NotImplementedError, "Subclasses must implement the name method"
+  end
+
+  # Abstract method - must be implemented by subclasses
+  def sounded?
+    raise NotImplementedError, "Subclasses must implement the sounded? method"
+  end
+end

data/lib/head_music/rudiment/rhythmic_unit/parser.rb

@@ -0,0 +1,86 @@
+class HeadMusic::Rudiment::RhythmicUnit::Parser
+  attr_reader :rhythmic_unit, :identifier
+
+  RHYTHMIC_UNITS_DATA = HeadMusic::Rudiment::RhythmicUnit::RHYTHMIC_UNITS_DATA
+
+  TEMPO_SHORTHAND_PATTERN = RHYTHMIC_UNITS_DATA.map { |unit| unit["tempo_shorthand"] }.compact.uniq.sort_by { |s| -s.length }.join("|")
+
+  def self.parse(identifier)
+    return nil if identifier.nil? || identifier.to_s.strip.empty?
+    new(identifier).parsed_name
+  end
+
+  def initialize(identifier)
+    @identifier = identifier.to_s.strip
+    parse
+  end
+
+  def parse
+    @unit_data = from_american_name || from_british_name || from_tempo_shorthand || from_duration
+    @rhythmic_unit = @unit_data ? HeadMusic::Rudiment::RhythmicUnit.get_by_name(@unit_data["american_name"]) : nil
+  end
+
+  def parsed_name
+    # Return the name format that was used in input
+    return nil unless @unit_data
+
+    # Check which type matched
+    if from_british_name == @unit_data && @unit_data["british_name"]
+      @unit_data["british_name"]
+    else
+      @unit_data["american_name"]
+    end
+  end
+
+  def american_name
+    # Always return the American name if a unit was found
+    @unit_data&.fetch("american_name", nil)
+  end
+
+  def normalized_identifier
+    @normalized_identifier ||= identifier.downcase.strip.gsub(/[^a-z0-9]/, "_").gsub(/_+/, "_").gsub(/^_|_$/, "")
+  end
+
+  def from_american_name
+    RHYTHMIC_UNITS_DATA.find do |unit|
+      normalize_name(unit["american_name"]) == normalized_identifier
+    end
+  end
+
+  def from_british_name
+    RHYTHMIC_UNITS_DATA.find do |unit|
+      normalize_name(unit["british_name"]) == normalized_identifier
+    end
+  end
+
+  def from_tempo_shorthand
+    # Handle shorthand with dots (e.g., "q." should match "q")
+    clean_identifier = identifier.downcase.strip.gsub(/\.*$/, "")
+    RHYTHMIC_UNITS_DATA.find do |unit|
+      unit["tempo_shorthand"] && unit["tempo_shorthand"].downcase == clean_identifier
+    end
+  end
+
+  def from_duration
+    RHYTHMIC_UNITS_DATA.find do |unit|
+      # Match decimal duration (e.g., "0.25")
+      return unit if unit["duration"].to_s == identifier.strip
+
+      # Match fraction notation (e.g., "1/4" = 0.25)
+      if identifier.match?(%r{^\d+/\d+$})
+        numerator, denominator = identifier.split("/").map(&:to_f)
+        calculated_duration = numerator / denominator
+        return unit if (calculated_duration - unit["duration"]).abs < 0.0001
+      end
+
+      false
+    end
+  end
+
+  private
+
+  def normalize_name(name)
+    return nil if name.nil?
+    name.to_s.downcase.strip.gsub(/[^a-z0-9]/, "_").gsub(/_+/, "_").gsub(/^_|_$/, "")
+  end
+end

data/lib/head_music/rudiment/rhythmic_unit.rb

@@ -2,21 +2,25 @@
 module HeadMusic::Rudiment; end
 
 # A rhythmic unit is a rudiment of duration consisting of doublings and divisions of a whole note.
-class HeadMusic::Rudiment::RhythmicUnit
+class HeadMusic::Rudiment::RhythmicUnit < HeadMusic::Rudiment::Base
   include HeadMusic::Named
   include Comparable
 
-  # Note values longer than a whole note
+  RHYTHMIC_UNITS_DATA = YAML.load_file(File.expand_path("rhythmic_units.yml", __dir__)).freeze
+
   AMERICAN_MULTIPLES_NAMES = [
     "whole", "double whole", "longa", "maxima"
   ].freeze
 
-  # Note values from whole note down to very short subdivisions
   AMERICAN_DIVISIONS_NAMES = [
     "whole", "half", "quarter", "eighth", "sixteenth", "thirty-second",
     "sixty-fourth", "hundred twenty-eighth", "two hundred fifty-sixth"
   ].freeze
 
+  AMERICAN_DURATIONS = (AMERICAN_MULTIPLES_NAMES + AMERICAN_DIVISIONS_NAMES).freeze
+
+  PATTERN = /#{Regexp.union(AMERICAN_DURATIONS)}/i
+
   # British terminology for note values longer than a whole note
   BRITISH_MULTIPLES_NAMES = %w[semibreve breve longa maxima].freeze
 
@@ -48,7 +52,11 @@ class HeadMusic::Rudiment::RhythmicUnit
   attr_reader :numerator, :denominator
 
   def self.get(name)
-    get_by_name(name)
+    # Use the parser to handle tempo shorthand and other formats
+    parsed_name = HeadMusic::Rudiment::RhythmicUnit::Parser.parse(name)
+    return nil unless parsed_name
+
+    get_by_name(parsed_name)
   end
 
   def self.all
@@ -83,7 +91,7 @@ class HeadMusic::Rudiment::RhythmicUnit
   end
 
   def ticks
-    HeadMusic::Rudiment::Rhythm::PPQN * 4 * relative_value
+    (HeadMusic::Rudiment::Rhythm::PPQN * 4 * relative_value).to_i
   end
 
   def notehead

data/lib/head_music/rudiment/rhythmic_units.yml

@@ -0,0 +1,80 @@
+- american_name: maxima
+  british_name: maxima
+  duration: 8.0
+  stem: false
+  flags: 0
+  notehead: maxima
+- american_name: longa
+  british_name: longa
+  duration: 4.0
+  stem: false
+  flags: 0
+  notehead: longa
+- american_name: double whole
+  british_name: breve
+  duration: 2.0
+  stem: false
+  flags: 0
+  notehead: breve
+- american_name: whole
+  british_name: semibreve
+  duration: 1.0
+  stem: false
+  flags: 0
+  notehead: open
+  tempo_shorthand: w
+- american_name: half
+  british_name: minim
+  duration: 0.5
+  stem: true
+  flags: 0
+  notehead: open
+  tempo_shorthand: h
+- american_name: quarter
+  british_name: crotchet
+  duration: 0.25
+  stem: true
+  flags: 0
+  notehead: closed
+  tempo_shorthand: q
+- american_name: eighth
+  british_name: quaver
+  duration: 0.125
+  stem: true
+  flags: 1
+  notehead: closed
+  tempo_shorthand: e
+- american_name: sixteenth
+  british_name: semiquaver
+  duration: 0.0625
+  stem: true
+  flags: 2
+  notehead: closed
+  tempo_shorthand: s
+- american_name: thirty-second
+  british_name: demisemiquaver
+  duration: 0.03125
+  stem: true
+  flags: 3
+  notehead: closed
+  tempo_shorthand: t
+- american_name: sixty-fourth
+  british_name: hemidemisemiquaver
+  duration: 0.015625
+  stem: true
+  flags: 4
+  notehead: closed
+  tempo_shorthand: x
+- american_name: hundred twenty-eighth
+  british_name: semihemidemisemiquaver
+  duration: 0.0078125
+  stem: true
+  flags: 5
+  notehead: closed
+  tempo_shorthand: o
+- american_name: two hundred fifty-sixth
+  british_name: demisemihemidemisemiquaver
+  duration: 0.00390625
+  stem: true
+  flags: 6
+  notehead: closed