head_music 8.3.0 → 9.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ec01f26a90e391dbe250ca2587586ceb9bc062a8eba06d97f52767eaf08bb2f0
-  data.tar.gz: b2253758a487b28f9e02ae6479da2586da39ff45337bca0a24f9634988ff9eb4
+  metadata.gz: 012ce64dd4174cbeec42f1d4825e9fd10af79ed8f4b83a3beedbc14a9aea34fa
+  data.tar.gz: a31dbb0b6b3d732bd41e1dbfe6a042a8395db05832d58848ec4d53e5ae4a4524
 SHA512:
-  metadata.gz: 6633eb9a47b72f81a44225d475d60b67924136809d469ba2a45ffe39ea6c1356ffbecd79e64f931c15146dd00980a9ff220c2b5c95deb955e5b3cf0eec7fef67
-  data.tar.gz: 5628ee5c9f0a442560f502d071f155e0d93771b3081572e9a98a86a154f387b0c9431662b051fd58bb9189b71906b5e7c9c29dbeddebd278f1d4a23d97416634
+  metadata.gz: a98367425dcfb4899b24ef2e7986a7fbc594202c960b553ab35d3cecd5ee0b5ecb10f65e1e458fe2d1797b70eded378fd319b2cbfc7b9a5a2e393773ce75f06b
+  data.tar.gz: d3baf95b28de6c2df0e3d14250ed9c335cb3793d598eb7cf1c417dd40b6463bb57ddcda19be309a1045e835809ad3b9ad45dc0fd21797563319069da35db76bc

data/CHANGELOG.md

@@ -7,6 +7,59 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [9.0.0] - 2025-10-24
+
+### Added
+- Added `HeadMusic::Rudiment::Pitch::Parser` for strict pitch parsing
+- Added `HeadMusic::Rudiment::RhythmicValue::Parser` for rhythmic value parsing
+- Both parsers provide standardized `.parse()` class method API
+
+### Changed
+- `Pitch.from_name` now uses `Pitch::Parser` internally
+- `RhythmicValue.get` now uses `RhythmicValue::Parser` internally
+- `Note.get` now parses "pitch rhythmic_value" strings inline without Parse module
+
+### Removed
+- **BREAKING**: Removed `HeadMusic::Parse::Pitch` class
+- **BREAKING**: Removed `HeadMusic::Parse::RhythmicValue` class
+- **BREAKING**: Removed `HeadMusic::Parse::RhythmicElement` class
+- **BREAKING**: Removed entire `HeadMusic::Parse` module
+
+### Migration Guide
+
+If you were using the removed Parse classes, migrate as follows:
+
+```ruby
+# Before (v8.x)
+parser = HeadMusic::Parse::Pitch.new("C#4")
+pitch = parser.pitch
+
+# After (v9.x)
+pitch = HeadMusic::Rudiment::Pitch.get("C#4")
+# or for strict parsing:
+pitch = HeadMusic::Rudiment::Pitch::Parser.parse("C#4")
+```
+
+```ruby
+# Before (v8.x)
+parser = HeadMusic::Parse::RhythmicValue.new("dotted quarter")
+value = parser.rhythmic_value
+
+# After (v9.x)
+value = HeadMusic::Rudiment::RhythmicValue.get("dotted quarter")
+# or for strict parsing:
+value = HeadMusic::Rudiment::RhythmicValue::Parser.parse("dotted quarter")
+```
+
+```ruby
+# Before (v8.x)
+parser = HeadMusic::Parse::RhythmicElement.new("F#4 dotted-quarter")
+note = parser.note
+
+# After (v9.x)
+note = HeadMusic::Rudiment::Note.get("F#4 dotted-quarter")
+```
+
 ## [8.2.1] - 2025-06-21
 
 ### Added

data/CLAUDE.md

@@ -41,14 +41,26 @@ bundle exec rake doc
 bundle exec rake doc_stats
 ```
 
-### Linting and Formatting
+### Git Etiquette
 
-The project uses Standard Ruby for style enforcement. Always run linting before committing:
+Do not make a commit unless I ask you to.
+
+When composing git commit messages, follow best-practices. However, do not mention yourself (claude) or list yourself as a co-author.
+
+This project uses a rebase flow and `main` as the mainline branch.
+
+### Code Style, Linting, and Formatting
+
+The project uses Standard Ruby for style enforcement. Always run linting after editing and before committing.
 
 ```bash
-bundle exec rubocop
+bundle exec rubocop -a
 ```
 
+Always strip trailing whitespace from all lines being added or edited. Always include a blank line at the end of each file.
+
+Do not use an assignment inside a condition.
+
 ### Testing
 
 Tests are written in RSpec and located in the `/spec` directory, mirroring the `/lib` structure. The project requires 90% code coverage minimum.
@@ -60,25 +72,25 @@ Tests are written in RSpec and located in the `/spec` directory, mirroring the `
 The codebase follows a domain-driven design with clear module boundaries:
 
 1. **HeadMusic::Rudiment** - Core music theory elements
-   - Pitch, Note, Scale, Key, Interval, Chord
-   - Factory methods: `.get()` for most rudiments
+  - Pitch, Note, Scale, Key, Interval, Chord
+  - Factory methods: `.get()` for most rudiments
 
 2. **HeadMusic::Analysis** - Musical analysis tools
-   - Intervals, Chords, Motion analysis
-   - Harmonic and melodic analysis
+  - Intervals, Chords, Motion analysis
+  - Harmonic and melodic analysis
 
 3. **HeadMusic::Content** - Musical composition representation
-   - Composition, Voice, Note, Rest
-   - Rhythmic values and time signatures
+  - Composition, Voice, Note, Rest
+  - Rhythmic values and time signatures
 
 4. **HeadMusic::Instruments** - Instrument definitions
-   - Instrument families and properties
-   - Pitch ranges and transposition
+  - Instrument families and properties
+  - Pitch ranges and transposition
 
 5. **HeadMusic::Style** - Composition rules and guidelines
-   - Counterpoint rules
-   - Voice leading guidelines
-   - Style analysis
+  - Counterpoint rules
+  - Voice leading guidelines
+  - Style analysis
 
 ### Key Design Patterns
 
@@ -115,6 +127,7 @@ The gem supports multiple languages through the HeadMusic::Named mixin:
 - Follow Standard Ruby style guide
 - Use YARD documentation format for public methods
 - Prefer delegation over inheritance
+- Always run `bundle exec rubocop -a` after editing ruby code
 
 ## Common Development Tasks
 
@@ -131,4 +144,8 @@ The gem supports multiple languages through the HeadMusic::Named mixin:
 1. Check for dependent classes that might be affected
 2. Run tests for the specific module: `bundle exec rspec spec/head_music/[module_name]`
 3. Update documentation with YARD comments
-4. Ensure translations are updated if names change
+4. Ensure translations are updated if names change
+
+## Music theory and concepts
+
+Please refer to MUSIC_THEORY.md for music theory domain knowledge.

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    head_music (8.3.0)
+    head_music (9.0.0)
       activesupport (~> 7.0)
       humanize (~> 2.0)
       i18n (~> 1.8)

data/MUSIC_THEORY.md

@@ -0,0 +1,120 @@
+# Music Theory
+Domain-specific knowledge for this project.
+
+## Rudiments
+
+The rudiments of music theory are built up piece-by-piece.
+
+letter name
+  - C, D, E, F, G, A, B, …
+  - equivalent to:
+   - do, re, mi, fa, sol, la, si/ti, …
+
+alteration
+  - sharp, flat, double sharp, double flat
+  - optional
+  - none is same as 'natural'
+  - found in key signatures
+  - found in bars as accidentals
+
+spelling
+  - letter name + alteration
+  - example: "E♭"
+
+register
+  - an integer typically between 0 and 8
+  - represents the octaves of an 88-key piano
+  - scientific pitch notation
+    - middle C is C4
+    - increments between B and C
+      - a half step below C4 is B3.
+
+pitch
+  - spelling + register
+  - example: "E♭3"
+
+rhythmic unit
+  - duration
+  - expressed in fractions (or multiples) of a standard whole note
+    - whole, half, quarter, eighth, sixteenth, …
+    - breve, …
+
+rhythmic value (duration)
+  - a rhythmic unit plus optional augmentation dots
+  - augmentation dots extend the duration of the rhythmic unit
+    - one dot extends the rhythmic value 50%
+    - two dots extend the rhythmic value 75%
+    - two dots extend the rhythmic value 87.5%
+
+rest
+  - a rhythmic value that passes in silence
+
+note
+  - pitch + rhythmic value
+  - example: "E♭3 dotted quarter"
+
+unpitched note
+  - an unpitched percussion note, such as a drum hit
+  - a sounded rhythmic value without a specific pitch
+
+tied duration
+  - combines multiple rhythmic values into one longer note
+  - ties allow rhythmic values to be combined across barlines or strong beats
+
+articulation
+  - a category of expressions that modify how one or more notes are performed.
+  - level of connection
+    - staccatissimo - the most staccato, even shorted and more clipped
+    - staccato – detatched (shortened to lease space between adjacent notes)
+    - tenuto - held of the full value
+    - legato - smoothly connected
+  - emphasis
+    - accent - play with emphasis or a stronger attack
+    - marcato - markedly emphasized
+  - instrument specific
+    - bowings
+    - breath mark
+    - roll mark
+
+## Instrument Families
+
+There are several ways that people talk about families and other categorizations of instruments. For example, the "string family" or "woodwind family", but also more specifically, the word family is applied more specifically (e.g. the "oboe family").
+
+### Text Conversation with Brian Head (May 7, 2023)
+
+Brian Head, brother and faculty at USC Thornton School of Music
+https://music.usc.edu/brian-head/
+
+Robert Head:
+	Hey, Brian. You have a sec for a music question? I’m trying to come up with different terms for the way “family” is used. “Woodwind family” vs. “Oboe family”.
+
+Brian Head:
+	Those are good, I’d say.  In what context?
+
+Robert Head:
+	In my software project, I’m trying to define those relationships. One is a section of the orchestra and the other is species of instrument. But usually people, in my experience, just say “family”.
+	Is there some more precise terminology or adjective that can disambiguate those two terms?
+
+Brian Head:
+	Hmmm. Already “family” is informal. Blatter distinguishes between “choir” and “family” as in the  trumpet family” within the “brass choir”.
+
+Robert Head:
+	Ah, yes! I do like that.
+	But does it apply to percussion?
+	“Section” is another candidate, but that gets used for string parts as well.
+
+Brian Head:
+	Strings and percussion probably don’t think of themselves as a choir, but if you’re mainly looking for a taxonomically consistent word, that’s the feat I can think of at the moment.
+	Section is a good word, too, which easily flows between smaller and larger meanings.
+
+Robert Head:
+	Obviously, the four “families” is a garbage way to classify all instruments and it really is more applicable to the orchestral context, so maybe “orchestra family” or “orchestra section”.
+
+Brian Head:
+	I’d say that “family” is best used at the instrument level, as in “saxophone family”. Choir or section are better for larger collections. Still, both of those words connote membership in an orchestra. Or large ensemble.  “Woodwinds” or “percussion” describe the class of instruments themselves.
+
+Robert Head:
+	Cool
+
+Action Item: Call them orchestra_section
+DONE

data/lib/head_music/analysis/diatonic_interval.rb

@@ -57,16 +57,17 @@ class HeadMusic::Analysis::DiatonicInterval
 
   alias_method :to_i, :semitones
 
-  # Override Named module methods to use computed name from naming
+  # Override Named module method to try I18n and fall back to computed name
   def name(locale_code: nil)
     if locale_code
-      # Try to get translation from locale files
-      name_key = naming.name.downcase.gsub(" ", "_").to_sym
-      translation = I18n.translate(name_key, scope: "head_music.diatonic_intervals", locale: locale_code, default: nil)
-      translation || naming.name
-    else
-      naming.name
+      name_key = HeadMusic::Utilities::HashKey.for(naming.name)
+      if I18n.backend.translations[locale_code]
+        locale_data = I18n.backend.translations[locale_code][:head_music] || {}
+        return locale_data[:diatonic_intervals][name_key] if locale_data.dig(:diatonic_intervals, name_key)
+        return locale_data[:chromatic_intervals][name_key] if locale_data.dig(:chromatic_intervals, name_key)
+      end
     end
+    naming.name
   end
 
   def to_s
@@ -111,26 +112,39 @@ class HeadMusic::Analysis::DiatonicInterval
   alias_method :invert, :inversion
 
   def consonance(style = :standard_practice)
-    consonance_for_perfect(style) ||
-      consonance_for_major_and_minor ||
-      HeadMusic::Rudiment::Consonance.get(:dissonant)
+    consonance_analysis(style).consonance
   end
 
   def consonance?(style = :standard_practice)
-    consonance(style).perfect? || consonance(style).imperfect?
+    consonance(style).consonant?
+  end
+
+  def consonant?(style = :standard_practice)
+    consonance_analysis(style).consonant?
   end
-  alias_method :consonant?, :consonance?
 
   def perfect_consonance?(style = :standard_practice)
-    consonance(style).perfect?
+    consonance_analysis(style).perfect_consonance?
   end
 
   def imperfect_consonance?(style = :standard_practice)
-    consonance(style).imperfect?
+    consonance_analysis(style).imperfect_consonance?
   end
 
   def dissonance?(style = :standard_practice)
-    consonance(style).dissonant?
+    consonance_analysis(style).dissonant?
+  end
+
+  def dissonant?(style = :standard_practice)
+    consonance_analysis(style).dissonant?
+  end
+
+  def consonance_analysis(style = :standard_practice)
+    HeadMusic::Analysis::IntervalConsonance.new(self, style)
+  end
+
+  def consonance_classification(style: :standard_practice)
+    consonance_analysis(style).classification
   end
 
   def above(pitch)
@@ -181,16 +195,4 @@ class HeadMusic::Analysis::DiatonicInterval
   def naming
     @naming ||= Naming.new(number: number, semitones: semitones)
   end
-
-  def consonance_for_perfect(style = :standard_practice)
-    HeadMusic::Rudiment::Consonance.get(dissonant_fourth?(style) ? :dissonant : :perfect) if perfect?
-  end
-
-  def consonance_for_major_and_minor
-    HeadMusic::Rudiment::Consonance.get((third_or_compound? || sixth_or_compound?) ? :imperfect : :dissonant) if major? || minor?
-  end
-
-  def dissonant_fourth?(style = :standard_practice)
-    fourth_or_compound? && style == :two_part_harmony
-  end
 end

data/lib/head_music/analysis/interval_consonance.rb

@@ -0,0 +1,51 @@
+# Analysis class that combines an interval with a style tradition to determine consonance
+class HeadMusic::Analysis::IntervalConsonance
+  attr_reader :interval, :style_tradition
+
+  def initialize(interval, style_tradition = HeadMusic::Style::ModernTradition.new)
+    @interval = interval
+    @style_tradition = style_tradition.is_a?(HeadMusic::Style::Tradition) ?
+                       style_tradition :
+                       HeadMusic::Style::Tradition.get(style_tradition)
+  end
+
+  def classification
+    @classification ||= style_tradition.consonance_classification(interval)
+  end
+
+  def consonance
+    @consonance ||= HeadMusic::Rudiment::Consonance.get(classification)
+  end
+
+  def consonant?
+    [HeadMusic::Rudiment::Consonance::PERFECT_CONSONANCE, HeadMusic::Rudiment::Consonance::IMPERFECT_CONSONANCE].include?(classification)
+  end
+
+  def dissonant?
+    [HeadMusic::Rudiment::Consonance::MILD_DISSONANCE, HeadMusic::Rudiment::Consonance::HARSH_DISSONANCE, HeadMusic::Rudiment::Consonance::DISSONANCE].include?(classification)
+  end
+
+  def contextual?
+    classification == HeadMusic::Rudiment::Consonance::CONTEXTUAL
+  end
+
+  def perfect_consonance?
+    classification == HeadMusic::Rudiment::Consonance::PERFECT_CONSONANCE
+  end
+
+  def imperfect_consonance?
+    classification == HeadMusic::Rudiment::Consonance::IMPERFECT_CONSONANCE
+  end
+
+  def mild_dissonance?
+    classification == HeadMusic::Rudiment::Consonance::MILD_DISSONANCE
+  end
+
+  def harsh_dissonance?
+    classification == HeadMusic::Rudiment::Consonance::HARSH_DISSONANCE
+  end
+
+  def dissonance?
+    classification == HeadMusic::Rudiment::Consonance::DISSONANCE
+  end
+end

data/lib/head_music/content/note.rb

@@ -11,7 +11,7 @@ class HeadMusic::Content::Note
 
   def initialize(pitch, rhythmic_value, voice = nil, position = nil)
     @pitch = HeadMusic::Rudiment::Pitch.get(pitch)
-    @rhythmic_value = HeadMusic::Content::RhythmicValue.get(rhythmic_value)
+    @rhythmic_value = HeadMusic::Rudiment::RhythmicValue.get(rhythmic_value)
     @voice = voice || HeadMusic::Content::Voice.new
     @position = position || HeadMusic::Content::Position.new(@voice.composition, "1:1")
   end

data/lib/head_music/content/placement.rb

@@ -55,7 +55,7 @@ class HeadMusic::Content::Placement
   def ensure_attributes(voice, position, rhythmic_value, pitch)
     @voice = voice
     ensure_position(position)
-    @rhythmic_value = HeadMusic::Content::RhythmicValue.get(rhythmic_value)
+    @rhythmic_value = HeadMusic::Rudiment::RhythmicValue.get(rhythmic_value)
     @pitch = HeadMusic::Rudiment::Pitch.get(pitch)
   end
 

data/lib/head_music/content/position.rb

@@ -53,7 +53,7 @@ class HeadMusic::Content::Position
   end
 
   def +(other)
-    other = HeadMusic::Content::RhythmicValue.new(other) if [HeadMusic::Rudiment::RhythmicUnit, Symbol, String].include?(other.class)
+    other = HeadMusic::Rudiment::RhythmicValue.new(other) if [HeadMusic::Rudiment::RhythmicUnit, Symbol, String].include?(other.class)
     self.class.new(composition, bar_number, count, tick + other.ticks)
   end
 

data/lib/head_music/content/staff.rb

@@ -8,7 +8,7 @@ class HeadMusic::Content::Staff
   attr_reader :default_clef, :line_count, :instrument
 
   def initialize(default_clef_key, instrument: nil, line_count: nil)
-    @instrument = HeadMusic::Instruments::Instrument.get(instrument) if instrument
+    @instrument = HeadMusic::Instruments::InstrumentType.get(instrument) if instrument
     begin
       @default_clef = HeadMusic::Rudiment::Clef.get(default_clef_key)
     rescue KeyError, NoMethodError