head_music 12.6.0 → 14.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: db91f6ff65b081bb369f3d2a85e2bc6e6cd092bb0018c2c416bf36bcfc4d4e9d
-  data.tar.gz: 266914dfbc382dc27591ea37302b57571b8693f2e0e4bd5189d2fffdff2a7c00
+  metadata.gz: ed605ba621e60e4222568efe6071c86daace2bbf21c6c577b7ccfda1fb67f769
+  data.tar.gz: b4a0f23c074d7d5bca6eb849a4e01ba099631c87d7cef89e3fd130c294a20803
 SHA512:
-  metadata.gz: d53ea28ee01b301ae1070a94fe8929d00b649c7d581976183d20e0bbfd080ccf4c08003719f2280001fb7d6ed00cfe1a5a634bd69b046d5859db56dfab6c6bb5
-  data.tar.gz: 9cd2929bddff0033d3caa84832e97a77a920cfc61e4e2d55d4d0be338f1ef7904beaad73748f6d6cc4ef93aea5a3b06292e16b285d0b61d5ad78b4ba2818932b
+  metadata.gz: 888d95ec1fab0517520899150d8caf794f7ec4edc7fa19e19d370d761d4541287712d207beb4b6f6772e0da62615258607c8ce5dbfb93d9311d5e32c692bbbc8
+  data.tar.gz: 759c97ee1504589dfbd6f91c2ac2bad6aa685ce70cf413ffc76eea2bdd4864fc6598b56d742d5e34d5f3ac528f88548830ca502ef7f866d034b0a349c5cf7e8f

data/CHANGELOG.md

@@ -7,6 +7,31 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [14.0.0] - 2026-07-05
+
+### Added
+
+- `HeadMusic::Style::Guidelines::Contoured` — configurable guideline judging a melody against a chosen contour (`Contoured.with(:arch)` and five other keys: `ascending`, `descending`, `valley`, `wave`, `static`). Predicates are trend-based rather than strictly monotonic; a wrong contour receives a single mark spanning the melody. Unknown contour keys raise `ArgumentError` at guide-definition time.
+- Six contour guides subclassing `Guides::DiatonicMelody`, each appending the configured `Contoured` guideline to the inherited ruleset: `ArchContourMelody`, `AscendingContourMelody`, `DescendingContourMelody`, `StaticContourMelody`, `ValleyContourMelody`, `WaveContourMelody`
+- Contour judgments deliberately complement `ConsonantClimax`: an arch requires only an interior climax pitch level, leaving climax uniqueness and consonance to the existing guideline
+
+## [13.0.0] - 2026-07-05
+
+### Added
+
+- `HeadMusic::Notation::NotationStyle` — named notation traditions (`british_brass_band`, `german`, `italian`, `concert_pitch`) resolved as sparse overlays on a `default` style, backed by `notation_styles.yml`, with `.get`/`.default` factories and `#notation_for`
+- `HeadMusic::Notation::InstrumentNotation` — the resolved notation value object (clef, sounding transposition, staves, and recorded register/clef alternatives) with value equality
+- `Instrument#notation(style:)` — notate an instrument through a chosen notation style, defaulting to `default`
+
+### Changed
+
+- Notation concerns (clef, sounding transposition, staff structure) now live in `NotationStyle` instead of on the instrument. `Instrument`'s notation methods (`default_staves`, `default_clefs`, `sounding_transposition`, etc.) delegate to the default style and resolve to the same values as before.
+- `Instrument#staff_schemes` now returns only the instrument's default scheme; named schemes (brass-band, German/Italian bass clarinet, and register/clef alternatives) have moved into notation styles.
+
+### Removed
+
+- `staff_schemes` data from `instruments.yml` and the internal `staff_schemes` plumbing on `Instrument`. Per-instrument notation conventions are now expressed as notation styles. (Breaking change — hence the major version bump.)
+
 ## [12.6.0] - 2026-07-03
 
 ### Added

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    head_music (12.6.0)
+    head_music (14.0.0)
       activesupport (>= 7.0, < 10)
       humanize (~> 2.0)
       i18n (~> 1.8)
@@ -9,27 +9,27 @@ PATH
 GEM
   remote: https://rubygems.org/
   specs:
-    activesupport (7.2.2.1)
+    activesupport (8.1.3)
       base64
-      benchmark (>= 0.3)
       bigdecimal
       concurrent-ruby (~> 1.0, >= 1.3.1)
       connection_pool (>= 2.2.5)
       drb
       i18n (>= 1.6, < 2)
+      json
       logger (>= 1.4.2)
       minitest (>= 5.1)
       securerandom (>= 0.3)
       tzinfo (~> 2.0, >= 2.0.5)
-    addressable (2.8.7)
-      public_suffix (>= 2.0.2, < 7.0)
+      uri (>= 0.13.1)
+    addressable (2.9.0)
+      public_suffix (>= 2.0.2, < 8.0)
     ast (2.4.3)
     axiom-types (0.1.1)
       descendants_tracker (~> 0.0.4)
       ice_nine (~> 0.11.0)
       thread_safe (~> 0.3, >= 0.3.1)
     base64 (0.3.0)
-    benchmark (0.4.1)
     bigdecimal (3.2.2)
     bundler-audit (0.9.2)
       bundler (>= 1.2.0, < 3)
@@ -38,7 +38,7 @@ GEM
       logger (~> 1.5)
     coercible (1.0.0)
       descendants_tracker (~> 0.0.1)
-    concurrent-ruby (1.3.5)
+    concurrent-ruby (1.3.7)
     connection_pool (2.5.3)
     descendants_tracker (0.0.4)
       thread_safe (~> 0.3, >= 0.3.1)
@@ -201,11 +201,12 @@ GEM
     unicode-display_width (3.1.4)
       unicode-emoji (~> 4.0, >= 4.0.4)
     unicode-emoji (4.0.4)
+    uri (1.1.1)
     virtus (2.0.0)
       axiom-types (~> 0.1)
       coercible (~> 1.0)
       descendants_tracker (~> 0.0, >= 0.0.3)
-    yard (0.9.37)
+    yard (0.9.44)
     zeitwerk (2.7.3)
 
 PLATFORMS

data/lib/head_music/content/bar.rb

@@ -3,17 +3,72 @@ module HeadMusic::Content; end
 
 # Representation of a bar in a composition
 # Encapsulates meter and key signature changes
+# and repeat structure (repeat barlines and volta brackets) as content semantics
 class HeadMusic::Content::Bar
-  attr_reader :composition
+  attr_reader :composition, :ends_repeat_after_num_plays, :plays_on_passes
   attr_accessor :key_signature, :meter
+  attr_writer :starts_repeat
 
   def initialize(composition, key_signature: nil, meter: nil)
     @composition = composition
     @key_signature = HeadMusic::Rudiment::KeySignature.get(key_signature) if key_signature
     @meter = HeadMusic::Rudiment::Meter.get(meter) if meter
+    @starts_repeat = false
+    @ends_repeat_after_num_plays = nil
+    @plays_on_passes = nil
+  end
+
+  def starts_repeat?
+    @starts_repeat
+  end
+
+  def ends_repeat_after_num_plays=(value)
+    unless valid_ends_repeat_after_num_plays?(value)
+      raise ArgumentError, "ends_repeat_after_num_plays must be nil or an integer of at least 2"
+    end
+    @ends_repeat_after_num_plays = value
+  end
+
+  def ends_repeat?
+    !ends_repeat_after_num_plays.nil?
+  end
+
+  def plays_on_passes=(value)
+    unless valid_plays_on_passes?(value)
+      raise ArgumentError, "plays_on_passes must be nil or a non-empty array of unique positive integers"
+    end
+    @plays_on_passes = value
+  end
+
+  def plays_on_pass?(pass_number)
+    plays_on_passes.nil? || plays_on_passes.include?(pass_number)
   end
 
   def to_s
-    ["Bar", key_signature, meter].compact.join(" ")
+    ["Bar", key_signature, meter, repeat_summary].compact.join(" ")
+  end
+
+  private
+
+  def valid_ends_repeat_after_num_plays?(value)
+    return true if value.nil?
+
+    value.is_a?(Integer) && value >= 2
+  end
+
+  def valid_plays_on_passes?(value)
+    return true if value.nil?
+
+    value.is_a?(Array) && !value.empty? &&
+      value.all? { |pass| pass.is_a?(Integer) && pass.positive? } &&
+      value.uniq.length == value.length
+  end
+
+  def repeat_summary
+    parts = []
+    parts << "|:" if starts_repeat?
+    parts << ":|x#{ends_repeat_after_num_plays}" if ends_repeat?
+    parts << "(passes #{plays_on_passes.join(",")})" if plays_on_passes
+    parts.join(" ") unless parts.empty?
   end
 end

data/lib/head_music/content/comment.rb

@@ -0,0 +1,32 @@
+# A module for musical content
+module HeadMusic::Content; end
+
+# A comment is a free-text annotation, optionally anchored to a position in a composition.
+class HeadMusic::Content::Comment
+  attr_reader :composition, :text, :position
+
+  def initialize(composition, text, position = nil)
+    @composition = composition
+    @text = text
+    ensure_position(position)
+  end
+
+  def to_s
+    text
+  end
+
+  private
+
+  def ensure_position(position)
+    return if position.nil?
+
+    @position = if position.is_a?(HeadMusic::Content::Position)
+      unless position.composition.equal?(composition)
+        raise ArgumentError, "position belongs to a different composition"
+      end
+      position
+    else
+      HeadMusic::Content::Position.new(composition, position)
+    end
+  end
+end

data/lib/head_music/content/composition.rb

@@ -3,11 +3,14 @@ module HeadMusic::Content; end
 
 # A composition is musical content.
 class HeadMusic::Content::Composition
-  attr_reader :name, :key_signature, :meter, :voices
+  attr_reader :name, :key_signature, :meter, :voices, :composer, :origin, :comments
 
-  def initialize(name: nil, key_signature: nil, meter: nil)
+  def initialize(name: nil, key_signature: nil, meter: nil, composer: nil, origin: nil, comments: nil)
     ensure_attributes(name, key_signature, meter)
+    @composer = composer
+    @origin = origin
     @voices = []
+    @comments = Array(comments).map { |text| HeadMusic::Content::Comment.new(self, text) }
   end
 
   def add_voice(role: nil)
@@ -15,6 +18,11 @@ class HeadMusic::Content::Composition
     @voices.last
   end
 
+  def add_comment(text, position = nil)
+    @comments << HeadMusic::Content::Comment.new(self, text, position)
+    @comments.last
+  end
+
   def meter_at(bar_number)
     meter_change = last_meter_change(bar_number)
     meter_change ? meter_change.meter : meter

data/lib/head_music/instruments/instrument.rb

@@ -21,13 +21,12 @@ module HeadMusic::Instruments; end
 #   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
 
   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
+  attr_reader :name_key, :parent_key, :alias_name_keys, :range_categories
 
   class << self
     # Factory method to get an Instrument instance
@@ -110,18 +109,29 @@ class HeadMusic::Instruments::Instrument
     @pitch_designation ||= HeadMusic::Rudiment::Spelling.get(pitch_key_to_designation)
   end
 
-  # Staff schemes (notation concern - kept for backward compatibility)
+  # Notation for this instrument in the given style (defaults to :default).
+  def notation(style: :default)
+    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
-    @staff_schemes ||= build_staff_schemes
+    [default_staff_scheme]
   end
 
   def default_staff_scheme
-    @default_staff_scheme ||=
-      staff_schemes.find(&:default?) || staff_schemes.first
+    @default_staff_scheme ||= HeadMusic::Instruments::StaffScheme.new(
+      key: "default",
+      instrument: self,
+      list: default_notation_staves_data
+    )
   end
 
   def default_staves
-    default_staff_scheme&.staves || []
+    default_staff_scheme.staves
   end
 
   def default_clefs
@@ -254,7 +264,6 @@ class HeadMusic::Instruments::Instrument
     @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
@@ -305,15 +314,10 @@ class HeadMusic::Instruments::Instrument
     end
   end
 
-  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
+  # 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