clef 0.1.0 → 1.0.0

data/lib/clef/core/metadata.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Clef
+  module Core
+    module Metadata
+      # @return [Hash]
+      def metadata
+        immutable_metadata(@metadata)
+      end
+
+      # @param value [Hash]
+      def metadata=(value)
+        raise ArgumentError, "metadata must be a Hash" unless value.is_a?(Hash)
+
+        @metadata = value.dup
+      end
+
+      # @param key [Object]
+      # @param value [Object]
+      # @return [self]
+      def set_metadata(key, value)
+        @metadata[key] = value
+        self
+      end
+
+      # @param value [Hash, nil]
+      # @param kwargs [Hash]
+      # @return [self]
+      def update_metadata(value = nil, **kwargs)
+        source = value || {}
+        raise ArgumentError, "metadata must be a Hash" unless source.is_a?(Hash)
+
+        @metadata.merge!(source)
+        @metadata.merge!(kwargs)
+        self
+      end
+
+      private
+
+      def immutable_metadata(value)
+        case value
+        when Hash
+          value.to_h { |key, item| [key, immutable_metadata(item)] }.freeze
+        when Array
+          value.map { |item| immutable_metadata(item) }.freeze
+        else
+          value
+        end
+      end
+    end
+  end
+end

data/lib/clef/core/note.rb

@@ -3,21 +3,29 @@
 module Clef
   module Core
     class Note
+      VALID_ARTICULATIONS = %i[staccato tenuto accent marcato fermata].freeze
+      TIE_STATES = %i[start continue stop].freeze
+
       attr_reader :pitch, :duration
-      attr_accessor :articulations, :tied
+      attr_reader :articulations, :tie_state
+      attr_accessor :slur_start, :slur_end, :beam_start, :beam_end
 
       # @param pitch [Pitch]
       # @param duration [Duration]
       # @param articulations [Array<Symbol>]
-      # @param tied [Boolean]
+      # @param tied [Boolean, Symbol]
       def initialize(pitch, duration, articulations: [], tied: false)
         validate_pitch!(pitch)
         validate_duration!(duration)
 
         @pitch = pitch
         @duration = duration
-        @articulations = Array(articulations).map(&:to_sym)
-        @tied = !!tied
+        self.articulations = articulations
+        @tie_state = normalize_tie_state(tied)
+        @slur_start = false
+        @slur_end = false
+        @beam_start = false
+        @beam_end = false
       end
 
       # @return [Rational]
@@ -25,6 +33,28 @@ module Clef
         duration.length
       end
 
+      # @return [Boolean]
+      def tied
+        !tie_state.nil?
+      end
+
+      # @param value [Boolean, Symbol]
+      def tied=(value)
+        @tie_state = normalize_tie_state(value)
+      end
+
+      # @param values [Array<Symbol>]
+      def articulations=(values)
+        @articulations = normalize_articulations(values).freeze
+      end
+
+      # @param articulation [Symbol]
+      # @return [Note]
+      def add_articulation(articulation)
+        self.articulations = articulations + [articulation]
+        self
+      end
+
       private
 
       def validate_pitch!(pitch)
@@ -38,6 +68,22 @@ module Clef
 
         raise ArgumentError, "duration must be a Clef::Core::Duration"
       end
+
+      def normalize_articulations(values)
+        symbols = Array(values).map(&:to_sym)
+        invalid = symbols - VALID_ARTICULATIONS
+        raise ArgumentError, "unsupported articulations: #{invalid.join(", ")}" unless invalid.empty?
+
+        symbols
+      end
+
+      def normalize_tie_state(value)
+        return nil if value.nil? || value == false
+        return :start if value == true
+        return value if TIE_STATES.include?(value)
+
+        raise ArgumentError, "tied must be true, false, or one of #{TIE_STATES.inspect}"
+      end
     end
   end
 end

data/lib/clef/core/pitch.rb

@@ -37,6 +37,24 @@ module Clef
         10 => [:a, 1],
         11 => [:b, 0]
       }.freeze
+      MIDI_CLASS_TO_FLAT_PITCH = {
+        0 => [:c, 0],
+        1 => [:d, -1],
+        2 => [:d, 0],
+        3 => [:e, -1],
+        4 => [:e, 0],
+        5 => [:f, 0],
+        6 => [:g, -1],
+        7 => [:g, 0],
+        8 => [:a, -1],
+        9 => [:a, 0],
+        10 => [:b, -1],
+        11 => [:b, 0]
+      }.freeze
+      SCIENTIFIC_PITCH_REGEX = /\A([A-Ga-g])([#b]{0,2})(-?\d+)\z/
+      LILYPOND_PITCH_REGEX = /\A([a-g])(eses|isis|es|is)?([',]*)\z/
+      TRANSPOSE_PREFERENCES = %i[sharp flat].freeze
+      MIDI_RANGE = (0..127)
 
       attr_reader :note_name, :octave, :alteration
 
@@ -56,7 +74,10 @@ module Clef
 
       # @return [Integer]
       def to_midi
-        semitones + 12
+        midi = semitones + 12
+        raise RangeError, "MIDI pitch out of range: #{midi}" unless MIDI_RANGE.cover?(midi)
+
+        midi
       end
 
       # @return [Integer]
@@ -71,11 +92,18 @@ module Clef
       end
 
       # @param semitones_or_interval [Integer, #semitones]
+      # @param prefer [Symbol, nil]
+      # @param key_signature [KeySignature, nil]
       # @return [Pitch]
-      def transpose(semitones_or_interval)
+      def transpose(semitones_or_interval, prefer: nil, key_signature: nil)
+        spelling = transpose_preference(prefer, key_signature)
+
         target_midi = to_midi + normalize_semitones(semitones_or_interval)
+        raise RangeError, "MIDI pitch out of range: #{target_midi}" unless MIDI_RANGE.cover?(target_midi)
+
         octave = (target_midi / 12) - 1
-        note_name, alteration = MIDI_CLASS_TO_PITCH.fetch(target_midi % 12)
+        pitch_map = (spelling == :flat) ? MIDI_CLASS_TO_FLAT_PITCH : MIDI_CLASS_TO_PITCH
+        note_name, alteration = pitch_map.fetch(target_midi % 12)
         self.class.new(note_name, octave, alteration: alteration)
       end
 
@@ -103,7 +131,7 @@ module Clef
       def self.parse(str)
         raise ArgumentError, "pitch string must be a String" unless str.is_a?(String)
 
-        match = /\A([a-g])(eses|isis|es|is)?([',]*)\z/.match(str)
+        match = LILYPOND_PITCH_REGEX.match(str)
         raise ArgumentError, "invalid lilypond pitch: #{str}" unless match
 
         note_name = match[1].to_sym
@@ -112,6 +140,30 @@ module Clef
         new(note_name, octave, alteration: SUFFIX_ALTERATION.fetch(suffix))
       end
 
+      # @param str [String]
+      # @return [Pitch]
+      def self.parse_scientific(str)
+        raise ArgumentError, "pitch string must be a String" unless str.is_a?(String)
+
+        match = SCIENTIFIC_PITCH_REGEX.match(str)
+        raise ArgumentError, "invalid scientific pitch: #{str}" unless match
+
+        note_name = match[1].downcase.to_sym
+        alteration = {"" => 0, "#" => 1, "##" => 2, "b" => -1, "bb" => -2}.fetch(match[2])
+        new(note_name, match[3].to_i, alteration: alteration)
+      end
+
+      # @param value [String, Symbol, Pitch]
+      # @return [Pitch]
+      def self.parse_any(value)
+        return value if value.is_a?(self)
+        return parse(value.to_s.downcase) if value.is_a?(Symbol)
+
+        parse_scientific(value)
+      rescue ArgumentError
+        parse(value.to_s.downcase)
+      end
+
       private
 
       def octave_marks
@@ -146,6 +198,23 @@ module Clef
 
         raise ArgumentError, "alteration must be between -2 and 2"
       end
+
+      def validate_transpose_preference!(prefer)
+        return if TRANSPOSE_PREFERENCES.include?(prefer)
+
+        raise ArgumentError, "transpose prefer must be :sharp or :flat"
+      end
+
+      def transpose_preference(prefer, key_signature)
+        if prefer
+          validate_transpose_preference!(prefer)
+          return prefer
+        end
+        return :sharp unless key_signature
+        return key_signature.preferred_transpose_spelling if key_signature.is_a?(KeySignature)
+
+        raise ArgumentError, "key_signature must be a Clef::Core::KeySignature"
+      end
     end
   end
 end

data/lib/clef/core/rest.rb

@@ -3,18 +3,26 @@
 module Clef
   module Core
     class Rest
-      attr_reader :duration
+      KINDS = %i[visible invisible spacer multi_measure].freeze
+
+      attr_reader :duration, :kind, :measures
 
       # @param duration [Duration]
-      def initialize(duration)
+      # @param kind [Symbol]
+      # @param measures [Integer]
+      def initialize(duration, kind: :visible, measures: 1)
         raise ArgumentError, "duration must be a Clef::Core::Duration" unless duration.is_a?(Duration)
+        raise ArgumentError, "unsupported rest kind" unless KINDS.include?(kind)
+        raise ArgumentError, "measures must be positive" unless measures.is_a?(Integer) && measures.positive?
 
         @duration = duration
+        @kind = kind
+        @measures = measures
       end
 
       # @return [Rational]
       def length
-        duration.length
+        duration.length * measures
       end
     end
   end

data/lib/clef/core/score.rb

@@ -3,34 +3,45 @@
 module Clef
   module Core
     class Score
-      attr_reader :staff_groups, :metadata
-      attr_accessor :title, :composer, :tempo
+      include Metadata
+
+      attr_accessor :title, :composer, :tempo, :plugins
 
       # @param metadata [Hash]
       def initialize(metadata: {})
         @staff_groups = []
-        @metadata = metadata
+        self.metadata = metadata
       end
 
       # @param staff_group [StaffGroup]
       # @return [Score]
       def add_staff_group(staff_group)
         raise ArgumentError, "staff_group must be a Clef::Core::StaffGroup" unless staff_group.is_a?(StaffGroup)
+        duplicate = staff_group.staves.find { |staff| staves.any? { |existing| existing.id == staff.id } }
+        raise ArgumentError, "duplicate staff id: #{duplicate.id}" if duplicate
 
-        staff_groups << staff_group
+        @staff_groups << staff_group
         self
       end
 
       # @param staff [Staff]
       # @return [Score]
       def add_staff(staff)
+        raise ArgumentError, "staff must be a Clef::Core::Staff" unless staff.is_a?(Staff)
+        raise ArgumentError, "duplicate staff id: #{staff.id}" if staves.any? { |existing| existing.id == staff.id }
+
         default_group.add_staff(staff)
         self
       end
 
       # @return [Array<Staff>]
       def staves
-        staff_groups.flat_map(&:staves)
+        @staff_groups.flat_map(&:staves).freeze
+      end
+
+      # @return [Array<StaffGroup>]
+      def staff_groups
+        @staff_groups.dup.freeze
       end
 
       # @param path [String]
@@ -45,16 +56,144 @@ module Clef
         ::Clef::Compiler.new(self, **options).compile_to_svg(path)
       end
 
+      # @param path [String, #write]
+      # @param options [Hash]
+      def to_midi(path, **options)
+        ::Clef::Midi::Exporter.new(self, **options).export(path)
+      end
+
       # @param path [String]
-      def to_midi(path, **_options)
-        ::Clef::Midi::Exporter.new(self).export(path)
+      # @param options [Hash]
+      def to_format(path, **options)
+        case File.extname(path.to_s).downcase
+        when ".pdf" then to_pdf(path, **options)
+        when ".svg" then to_svg(path, **options)
+        when ".mid", ".midi" then to_midi(path, **options)
+        else
+          raise ArgumentError, "unsupported output format for #{path.inspect}"
+        end
+      end
+
+      # @param strict [Boolean]
+      # @return [ValidationResult]
+      def validate(strict: false)
+        result = ValidationResult.new(validation_issues)
+        raise Clef::Error, result.errors.map(&:message).join(", ") if strict && !result.ok?
+
+        result
+      end
+
+      # @return [Array<ValidationIssue>]
+      def validation_warnings
+        validate.warnings
       end
 
       private
 
+      def validation_issues
+        staff_issues + measure_issues + lyric_issues + pitch_issues
+      end
+
+      def staff_issues
+        staves.map(&:id).tally.filter_map do |id, count|
+          next unless count > 1
+
+          ValidationIssue.new(severity: :error, message: "duplicate staff id: #{id}", path: [:score, :staves, id])
+        end
+      end
+
+      def measure_issues
+        staves.flat_map do |staff|
+          staff.measures.flat_map do |measure|
+            overflow_issues(staff, measure) + underfull_issues(staff, measure)
+          end
+        end
+      end
+
+      def overflow_issues(staff, measure)
+        measure.overflowing_voice_ids.map do |voice_id|
+          ValidationIssue.new(
+            severity: :error,
+            message: "measure #{measure.number} voice #{voice_id} exceeds time signature length",
+            path: [:staff, staff.id, :measure, measure.number, :voice, voice_id]
+          )
+        end
+      end
+
+      def underfull_issues(staff, measure)
+        measure.underfull_voice_ids.map do |voice_id|
+          ValidationIssue.new(
+            severity: :warning,
+            message: "measure #{measure.number} voice #{voice_id} is shorter than time signature length",
+            path: [:staff, staff.id, :measure, measure.number, :voice, voice_id]
+          )
+        end
+      end
+
+      def lyric_issues
+        staves.flat_map do |staff|
+          Array(staff.metadata[:lyrics]).flat_map do |lyric|
+            note_count = staff.measures.sum do |measure|
+              lyric_notes(Array(measure.voices[lyric.voice_id]&.elements)).length
+            end
+            next [] if lyric.note_slot_count == note_count
+
+            [
+              ValidationIssue.new(
+                severity: :warning,
+                message: "lyrics for voice #{lyric.voice_id} have #{lyric.note_slot_count} syllables for #{note_count} notes",
+                path: [:staff, staff.id, :lyrics, lyric.voice_id]
+              )
+            ]
+          end
+        end
+      end
+
+      def lyric_notes(elements)
+        elements.flat_map do |element|
+          case element
+          when Note, Chord then [element]
+          when Tuplet then lyric_notes(element.elements)
+          else []
+          end
+        end
+      end
+
+      def pitch_issues
+        staves.flat_map do |staff|
+          staff.measures.flat_map do |measure|
+            measure.voices.flat_map do |voice_id, voice|
+              voice.elements.flat_map { |element| invalid_pitch_issues(element, staff.id, measure.number, voice_id) }
+            end
+          end
+        end
+      end
+
+      def invalid_pitch_issues(element, staff_id, measure_number, voice_id)
+        pitches_for(element).filter_map do |pitch|
+          pitch.to_midi
+          nil
+        rescue RangeError => e
+          ValidationIssue.new(
+            severity: :error,
+            message: e.message,
+            path: [:staff, staff_id, :measure, measure_number, :voice, voice_id]
+          )
+        end
+      end
+
+      def pitches_for(element)
+        case element
+        when Note then [element.pitch]
+        when Chord then element.pitches
+        when Tuplet then element.elements.flat_map { |child| pitches_for(child) }
+        else []
+        end
+      end
+
       def default_group
-        staff_groups.first || add_staff_group(StaffGroup.new)
-        staff_groups.first
+        @staff_groups.first || add_staff_group(StaffGroup.new)
+        @staff_groups.first
       end
     end
   end

data/lib/clef/core/staff.rb

@@ -3,9 +3,10 @@
 module Clef
   module Core
     class Staff
-      attr_reader :id, :name, :clef, :measures
+      include Metadata
+
+      attr_reader :id, :name, :clef
       attr_accessor :key_signature, :time_signature
-      attr_accessor :metadata
 
       # @param id [Symbol]
       # @param name [String, nil]
@@ -25,10 +26,19 @@ module Clef
       # @return [Staff]
       def add_measure(measure)
         raise ArgumentError, "measure must be a Clef::Core::Measure" unless measure.is_a?(Measure)
+        raise ArgumentError, "duplicate measure number: #{measure.number}" if @measures.any? { |item| item.number == measure.number }
+        if @measures.any? && measure.number < @measures.last.number
+          raise ArgumentError, "measure numbers must be added in ascending order"
+        end
 
-        measures << measure
+        @measures << measure
         self
       end
+
+      # @return [Array<Measure>]
+      def measures
+        @measures.dup.freeze
+      end
     end
   end
 end

data/lib/clef/core/staff_group.rb

@@ -5,7 +5,7 @@ module Clef
     class StaffGroup
       BRACKETS = %i[bracket brace none].freeze
 
-      attr_reader :staves, :bracket_type
+      attr_reader :bracket_type
 
       # @param staves [Array<Staff>]
       # @param bracket_type [Symbol]
@@ -21,10 +21,16 @@ module Clef
       # @return [StaffGroup]
       def add_staff(staff)
         raise ArgumentError, "staff must be a Clef::Core::Staff" unless staff.is_a?(Staff)
+        raise ArgumentError, "duplicate staff id: #{staff.id}" if @staves.any? { |item| item.id == staff.id }
 
-        staves << staff
+        @staves << staff
         self
       end
+
+      # @return [Array<Staff>]
+      def staves
+        @staves.dup.freeze
+      end
     end
   end
 end

data/lib/clef/core/tempo.rb

@@ -14,6 +14,11 @@ module Clef
         @beat_unit = beat_unit
         @bpm = bpm
       end
+
+      # @return [Rational]
+      def length
+        Rational(0, 1)
+      end
     end
   end
 end

data/lib/clef/core/tuplet.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Clef
+  module Core
+    class Tuplet
+      ELEMENT_TYPES = [Note, Rest, Chord, self].freeze
+
+      attr_reader :actual, :normal, :elements
+
+      # @param actual [Integer]
+      # @param normal [Integer]
+      # @param elements [Array<Note, Rest, Chord, Tuplet>]
+      def initialize(actual, normal, elements)
+        raise ArgumentError, "tuplet values must be positive" unless actual.is_a?(Integer) && actual.positive? &&
+          normal.is_a?(Integer) && normal.positive?
+
+        @actual = actual
+        @normal = normal
+        @elements = Array(elements)
+        validate_elements!
+        @elements.freeze
+      end
+
+      # @return [Rational]
+      def length
+        raw_length * ratio
+      end
+
+      # @return [Rational]
+      def ratio
+        Rational(normal, actual)
+      end
+
+      private
+
+      def raw_length
+        elements.reduce(Rational(0, 1)) { |memo, element| memo + element.length }
+      end
+
+      def validate_elements!
+        raise ArgumentError, "tuplet must contain at least one element" if elements.empty?
+        return if elements.all? { |element| ELEMENT_TYPES.any? { |type| element.is_a?(type) } }
+
+        raise ArgumentError, "tuplet elements must be musical elements"
+      end
+    end
+  end
+end

data/lib/clef/core/validation.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Clef
+  module Core
+    ValidationIssue = Struct.new(:severity, :message, :path, keyword_init: true) do
+      def warning?
+        severity == :warning
+      end
+
+      def error?
+        severity == :error
+      end
+    end
+
+    class ValidationResult
+      attr_reader :issues
+
+      # @param issues [Array<ValidationIssue>]
+      def initialize(issues = [])
+        @issues = issues
+      end
+
+      # @return [Boolean]
+      def ok?
+        errors.empty?
+      end
+
+      # @return [Array<ValidationIssue>]
+      def errors
+        issues.select(&:error?)
+      end
+
+      # @return [Array<ValidationIssue>]
+      def warnings
+        issues.select(&:warning?)
+      end
+    end
+  end
+end

data/lib/clef/core/voice.rb

@@ -3,7 +3,9 @@
 module Clef
   module Core
     class Voice
-      attr_reader :id, :elements
+      ELEMENT_TYPES = [Note, Rest, Chord, Tuplet, Tempo].freeze
+
+      attr_reader :id
 
       # @param id [Symbol]
       def initialize(id: :default)
@@ -11,18 +13,32 @@ module Clef
         @elements = []
       end
 
-      # @param element [#length]
+      # @param element [Note, Rest, Chord, Tuplet]
       # @return [Voice]
       def add(element)
-        raise ArgumentError, "element must respond to #length" unless element.respond_to?(:length)
+        raise ArgumentError, "element must be a musical element" unless musical_element?(element)
 
-        elements << element
+        @elements << element
         self
       end
 
+      # @return [Array<Note, Rest, Chord, Tuplet, Tempo>]
+      def elements
+        @elements.dup.freeze
+      end
+
       # @return [Rational]
       def total_length
-        elements.reduce(Rational(0, 1)) { |memo, element| memo + element.length }
+        @elements.reduce(Rational(0, 1)) { |memo, element| memo + element.length }
+      end
+
+      private
+
+      def musical_element?(element)
+        return true if ELEMENT_TYPES.any? { |type| element.is_a?(type) }
+        return true if defined?(::Clef::Notation::Dynamic) && element.is_a?(::Clef::Notation::Dynamic)
+
+        false
       end
     end
   end