head_music 0.17.0 → 0.18.0

data/lib/head_music/quality.rb

@@ -1,3 +1,6 @@
+# frozen_string_literal: true
+
+# A quality is a categorization of an interval.
 class HeadMusic::Quality
   SHORTHAND = {
     perfect: 'P',
@@ -7,7 +10,7 @@ class HeadMusic::Quality
     augmented: 'A',
     doubly_diminished: 'dd',
     doubly_augmented: 'AA',
-  }
+  }.freeze
   NAMES = SHORTHAND.keys
 
   PERFECT_INTERVAL_MODIFICATION = {
@@ -15,16 +18,16 @@ class HeadMusic::Quality
     -1 => :diminished,
     0 => :perfect,
     1 => :augmented,
-    2 => :doubly_augmented
-  }
+    2 => :doubly_augmented,
+  }.freeze
 
   MAJOR_INTERVAL_MODIFICATION = {
     -2 => :diminished,
     -1 => :minor,
     0 => :major,
     1 => :augmented,
-    2 => :doubly_augmented
-  }
+    2 => :doubly_augmented,
+  }.freeze
 
   def self.get(identifier)
     @qualities ||= {}
@@ -48,7 +51,7 @@ class HeadMusic::Quality
   end
 
   def ==(other)
-    self.to_s == other.to_s
+    to_s == other.to_s
   end
 
   def shorthand

data/lib/head_music/rhythm.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module HeadMusic::Rhythm
   PPQN = PULSES_PER_QUARTER_NOTE = 960
 end

data/lib/head_music/rhythmic_unit.rb

@@ -1,11 +1,20 @@
+# frozen_string_literal: true
+
+# A rhythmic unit is a rudiment of duration consisting of doublings and divisions of a whole note.
 class HeadMusic::RhythmicUnit
   include HeadMusic::NamedRudiment
 
-  MULTIPLES = ['whole', 'double whole', 'longa', 'maxima']
-  FRACTIONS = ['whole', 'half', 'quarter', 'eighth', 'sixteenth', 'thirty-second', 'sixty-fourth', 'hundred twenty-eighth', 'two hundred fifty-sixth']
+  MULTIPLES = ['whole', 'double whole', 'longa', 'maxima'].freeze
+  FRACTIONS = [
+    'whole', 'half', 'quarter', 'eighth', 'sixteenth', 'thirty-second',
+    'sixty-fourth', 'hundred twenty-eighth', 'two hundred fifty-sixth',
+  ].freeze
 
-  BRITISH_MULTIPLE_NAMES = %w[semibreve breve longa maxima]
-  BRITISH_DIVISION_NAMES = %w[semibreve minim crotchet quaver semiquaver demisemiquaver hemidemisemiquaver semihemidemisemiquaver demisemihemidemisemiquaver]
+  BRITISH_MULTIPLE_NAMES = %w[semibreve breve longa maxima].freeze
+  BRITISH_DIVISION_NAMES = %w[
+    semibreve minim crotchet quaver semiquaver demisemiquaver
+    hemidemisemiquaver semihemidemisemiquaver demisemihemidemisemiquaver
+  ].freeze
 
   def self.for_denominator_value(denominator)
     get(FRACTIONS[Math.log2(denominator).to_i])
@@ -32,32 +41,25 @@ class HeadMusic::RhythmicUnit
   end
 
   def notehead
-    case relative_value
-    when 8
-      :maxima
-    when 4
-      :longa
-    when 2
-      :breve
-    when 0.5, 1
-      :open
-    else
-      :closed
-    end
+    return :maxima if relative_value == 8
+    return :longa if relative_value == 4
+    return :breve if relative_value == 2
+    return :open if [0.5, 1].include? relative_value
+    :closed
   end
 
   def flags
     FRACTIONS.include?(name) ? [FRACTIONS.index(name) - 2, 0].max : 0
   end
 
-  def has_stem?
+  def stemmed?
     relative_value < 1
   end
 
   def british_name
-    if MULTIPLES.include?(name)
+    if multiple?
       BRITISH_MULTIPLE_NAMES[MULTIPLES.index(name)]
-    elsif FRACTIONS.include?(name)
+    elsif fraction?
       BRITISH_DIVISION_NAMES[FRACTIONS.index(name)]
     elsif BRITISH_MULTIPLE_NAMES.include?(name) || BRITISH_DIVISION_NAMES.include?(name)
       name
@@ -68,6 +70,14 @@ class HeadMusic::RhythmicUnit
 
   private
 
+  def multiple?
+    MULTIPLES.include?(name)
+  end
+
+  def fraction?
+    FRACTIONS.include?(name)
+  end
+
   def numerator_exponent
     MULTIPLES.index(name) || BRITISH_MULTIPLE_NAMES.index(name) || 0
   end

data/lib/head_music/rhythmic_value.rb

@@ -1,3 +1,6 @@
+# frozen_string_literal: true
+
+# A rhythmic value is a duration composed of a rhythmic unit, any number of dots, and a tied value.
 class HeadMusic::RhythmicValue
   attr_reader :unit, :dots, :tied_value
 
@@ -25,8 +28,8 @@ class HeadMusic::RhythmicValue
   end
 
   def self.dots_from_words(identifier)
-    return 0 unless identifier =~ /dotted/
-    modifier, _ = identifier.split(/_*dotted_*/)
+    return 0 unless identifier.match?(/dotted/)
+    modifier, = identifier.split(/_*dotted_*/)
     case modifier
     when /tripl\w/
       3

data/lib/head_music/scale.rb

@@ -1,10 +1,11 @@
+# frozen_string_literal: true
+
+# A scale contains ordered pitches starting at a tonal center.
 class HeadMusic::Scale
   SCALE_REGEX = /^[A-G][#b]?\s+\w+$/
 
   def self.get(root_pitch, scale_type = nil)
-    if root_pitch.is_a?(String) && scale_type =~ SCALE_REGEX
-      root_pitch, scale_type = root_pitch.split(/\s+/)
-    end
+    root_pitch, scale_type = root_pitch.split(/\s+/) if root_pitch.is_a?(String) && scale_type =~ SCALE_REGEX
     root_pitch = HeadMusic::Pitch.get(root_pitch)
     scale_type = HeadMusic::ScaleType.get(scale_type || :major)
     @scales ||= {}
@@ -13,6 +14,8 @@ class HeadMusic::Scale
     @scales[hash_key] ||= new(root_pitch, scale_type)
   end
 
+  delegate :letter_name_cycle, to: :root_pitch
+
   attr_reader :root_pitch, :scale_type
 
   def initialize(root_pitch, scale_type)
@@ -26,30 +29,6 @@ class HeadMusic::Scale
     @pitches[direction][octaves] ||= determine_scale_pitches(direction, octaves)
   end
 
-  def determine_scale_pitches(direction, octaves)
-    semitones_from_root = 0
-    [root_pitch].tap do |pitches|
-      [:ascending, :descending].each do |single_direction|
-        if [single_direction, :both].include?(direction)
-          (1..octaves).each do
-            direction_intervals(single_direction).each_with_index do |semitones, i|
-              semitones_from_root += semitones * direction_sign(single_direction)
-              pitches << pitch_for_step(i+1, semitones_from_root, single_direction)
-            end
-          end
-        end
-      end
-    end
-  end
-
-  def direction_sign(direction)
-    direction == :descending ? -1 : 1
-  end
-
-  def direction_intervals(direction)
-    scale_type.send("#{direction}_intervals")
-  end
-
   def spellings(direction: :ascending, octaves: 1)
     pitches(direction: direction, octaves: octaves).map(&:spelling).map(&:to_s)
   end
@@ -58,10 +37,6 @@ class HeadMusic::Scale
     pitches(direction: direction, octaves: octaves).map(&:name)
   end
 
-  def letter_name_cycle
-    @letter_name_cycle ||= root_pitch.letter_name_cycle
-  end
-
   def root_pitch_number
     @root_pitch_number ||= root_pitch.number
   end
@@ -72,26 +47,41 @@ class HeadMusic::Scale
 
   private
 
+  def determine_scale_pitches(direction, octaves)
+    semitones_from_root = 0
+    pitches = [root_pitch]
+    %i[ascending descending].each do |single_direction|
+      next unless [single_direction, :both].include?(direction)
+      (1..octaves).each do
+        pitches += octave_scale_pitches(single_direction, semitones_from_root)
+        semitones_from_root += 12 * direction_sign(single_direction)
+      end
+    end
+    pitches
+  end
+
+  def octave_scale_pitches(direction, semitones_from_root)
+    direction_intervals(direction).map.with_index do |semitones, i|
+      semitones_from_root += semitones * direction_sign(direction)
+      pitch_for_step(i + 1, semitones_from_root, direction)
+    end
+  end
+
+  def direction_sign(direction)
+    direction == :descending ? -1 : 1
+  end
+
+  def direction_intervals(direction)
+    scale_type.send("#{direction}_intervals")
+  end
+
   def parent_scale_pitches
     HeadMusic::Scale.get(root_pitch, scale_type.parent_name).pitches if scale_type.parent
   end
 
   def parent_scale_pitch_for(semitones_from_root)
-    parent_scale_pitches.detect { |parent_scale_pitch|
+    parent_scale_pitches.detect do |parent_scale_pitch|
       parent_scale_pitch.pitch_class == (root_pitch + semitones_from_root).to_i % 12
-    }
-  end
-
-  def letter_for_step(step, semitones_from_root, direction)
-    pitch_class_number = (root_pitch.pitch_class.to_i + semitones_from_root) % 12
-    if scale_type.intervals.length == 7
-      direction == :ascending ? letter_name_cycle[step % 7] : letter_name_cycle[-step % 7]
-    elsif scale_type.intervals.length < 7 && parent_scale_pitches
-      parent_scale_pitch_for(semitones_from_root).letter_name
-    elsif root_pitch.flat?
-      HeadMusic::PitchClass::FLAT_SPELLINGS[pitch_class_number]
-    else
-      HeadMusic::PitchClass::SHARP_SPELLINGS[pitch_class_number]
     end
   end
 
@@ -100,4 +90,34 @@ class HeadMusic::Scale
     letter_name = letter_for_step(step, semitones_from_root, direction)
     HeadMusic::Pitch.from_number_and_letter(pitch_number, letter_name)
   end
+
+  def letter_for_step(step, semitones_from_root, direction)
+    diatonic_letter_for_step(direction, step) ||
+      child_scale_letter_for_step(semitones_from_root) ||
+      flat_letter_for_step(semitones_from_root) ||
+      sharp_letter_for_step(semitones_from_root)
+  end
+
+  def diatonic_letter_for_step(direction, step)
+    return unless scale_type.diatonic?
+    direction == :ascending ? letter_name_cycle[step % 7] : letter_name_cycle[-step % 7]
+  end
+
+  def child_scale_letter_for_step(semitones_from_root)
+    return unless scale_type.parent
+    parent_scale_pitch_for(semitones_from_root).letter_name
+  end
+
+  def flat_letter_for_step(semitones_from_root)
+    return unless root_pitch.flat?
+    HeadMusic::PitchClass::FLAT_SPELLINGS[pitch_class_number(semitones_from_root)]
+  end
+
+  def sharp_letter_for_step(semitones_from_root)
+    HeadMusic::PitchClass::SHARP_SPELLINGS[pitch_class_number(semitones_from_root)]
+  end
+
+  def pitch_class_number(semitones_from_root)
+    (root_pitch.pitch_class.to_i + semitones_from_root) % 12
+  end
 end

data/lib/head_music/scale_degree.rb

@@ -1,7 +1,11 @@
+# frozen_string_literal: true
+
+# A scale degree is a number indicating the ordinality of the spelling in the key signature.
+# TODO: Rewrite to accept a tonal_center and a scale type.
 class HeadMusic::ScaleDegree
   include Comparable
 
-  NAME_FOR_DIATONIC_DEGREE = [nil, 'tonic', 'supertonic', 'mediant', 'subdominant', 'dominant', 'submediant']
+  NAME_FOR_DIATONIC_DEGREE = [nil, 'tonic', 'supertonic', 'mediant', 'subdominant', 'dominant', 'submediant'].freeze
 
   attr_reader :key_signature, :spelling
   delegate :scale, to: :key_signature
@@ -17,8 +21,8 @@ class HeadMusic::ScaleDegree
   end
 
   def sign
-    sign_semitones = spelling.sign && spelling.sign.semitones || 0
-    usual_sign_semitones = scale_degree_usual_spelling.sign && scale_degree_usual_spelling.sign.semitones || 0
+    sign_semitones = spelling.sign&.semitones || 0
+    usual_sign_semitones = scale_degree_usual_spelling.sign&.semitones || 0
     delta = sign_semitones - usual_sign_semitones
     HeadMusic::Sign.by(:semitones, delta) if delta != 0
   end
@@ -36,10 +40,9 @@ class HeadMusic::ScaleDegree
   end
 
   def name_for_degree
-    if scale_type.diatonic?
-      NAME_FOR_DIATONIC_DEGREE[degree] ||
+    return unless scale_type.diatonic?
+    NAME_FOR_DIATONIC_DEGREE[degree] ||
       (scale_type.intervals.last == 1 || sign == '#' ? 'leading tone' : 'subtonic')
-    end
   end
 
   private

data/lib/head_music/scale_type.rb

@@ -1,10 +1,12 @@
+# frozen_string_literal: true
+
+# A ScaleType represents a particular scale pattern, such as major, lydian, or minor pentatonic.
 class HeadMusic::ScaleType
   H = 1 # whole step
   W = 2 # half step
-  WH = W + H # augmented second
 
   # Modal
-  I = [W, W, H, W, W, W, H]
+  I = [W, W, H, W, W, W, H].freeze
   II = I.rotate
   III = I.rotate(2)
   IV = I.rotate(3)
@@ -13,47 +15,73 @@ class HeadMusic::ScaleType
   VII = I.rotate(6)
 
   # Tonal
-  HARMONIC_MINOR = [W, H, W, W, H, WH, H]
-  MELODIC_MINOR_ASCENDING = [W, H, W, W, W, W, H]
+  HARMONIC_MINOR = [W, H, W, W, H, 3, H].freeze
+  MELODIC_MINOR_ASCENDING = [W, H, W, W, W, W, H].freeze
 
   MODE_NAMES = {
-    i: [:ionian, :major],
+    i: %i[ionian major],
     ii: [:dorian],
     iii: [:phrygian],
     iv: [:lydian],
     v: [:mixolydian],
-    vi: [:aeolian, :minor, :natural_minor],
+    vi: %i[aeolian minor natural_minor],
     vii: [:locrian],
-  }
-  SCALE_TYPES = {}
-  MODE_NAMES.each do |roman_numeral, aliases|
-    intervals = { ascending: const_get(roman_numeral.upcase) }
-    SCALE_TYPES[roman_numeral] = intervals
-    aliases.each do |name|
-      SCALE_TYPES[name.to_sym] = intervals
+  }.freeze
+
+  CHROMATIC = [H, H, H, H, H, H, H, H, H, H, H, H].freeze
+
+  MINOR_PENTATONIC = [3, 2, 2, 3, 2].freeze
+
+  def self._modes
+    {}.tap do |modes|
+      MODE_NAMES.each do |roman_numeral, aliases|
+        intervals = { ascending: const_get(roman_numeral.upcase) }
+        modes[roman_numeral] = intervals
+        aliases.each { |name| modes[name] = intervals }
+      end
     end
   end
-  SCALE_TYPES[:harmonic_minor] = { ascending: HARMONIC_MINOR }
-  SCALE_TYPES[:melodic_minor] = { ascending: MELODIC_MINOR_ASCENDING, descending: VI.reverse }
 
-  CHROMATIC = [H, H, H, H, H, H, H, H, H, H, H, H]
-  SCALE_TYPES[:chromatic] = { ascending: CHROMATIC }
+  def self._minor_scales
+    {
+      harmonic_minor: { ascending: HARMONIC_MINOR },
+      melodic_minor: { ascending: MELODIC_MINOR_ASCENDING, descending: VI.reverse },
+    }
+  end
 
-  MINOR_PENTATONIC = [3, 2, 2, 3, 2]
-  SCALE_TYPES[:minor_pentatonic] = { ascending: MINOR_PENTATONIC, parent_name: :minor }
-  SCALE_TYPES[:major_pentatonic] = { ascending: MINOR_PENTATONIC.rotate, parent_name: :major }
-  SCALE_TYPES[:egyptian_pentatonic] = { ascending: MINOR_PENTATONIC.rotate(2), parent_name: :minor }
-  SCALE_TYPES[:blues_minor_pentatonic] = { ascending: MINOR_PENTATONIC.rotate(3), parent_name: :minor }
-  SCALE_TYPES[:blues_major_pentatonic] = { ascending: MINOR_PENTATONIC.rotate(4), parent_name: :major }
+  def self._chromatic_scales
+    { chromatic: { ascending: CHROMATIC } }
+  end
 
-  # exotic scales
-  SCALE_TYPES[:octatonic] = { ascending: [W, H, W, H, W, H, W, H] }
-  SCALE_TYPES[:whole_tone] = { ascending: [W, W, W, W, W, W] }
+  def self._pentatonic_scales
+    {
+      minor_pentatonic: { ascending: MINOR_PENTATONIC, parent_name: :minor },
+      major_pentatonic: { ascending: MINOR_PENTATONIC.rotate, parent_name: :major },
+      egyptian_pentatonic: { ascending: MINOR_PENTATONIC.rotate(2), parent_name: :minor },
+      blues_minor_pentatonic: { ascending: MINOR_PENTATONIC.rotate(3), parent_name: :minor },
+      blues_major_pentatonic: { ascending: MINOR_PENTATONIC.rotate(4), parent_name: :major },
+    }
+  end
+
+  def self._exotic_scales
+    {
+      octatonic: { ascending: [W, H, W, H, W, H, W, H] },
+      whole_tone: { ascending: [W, W, W, W, W, W] },
+    }
+  end
+
+  SCALE_TYPES = {}.tap do |scales|
+    scales.merge!(_modes)
+    scales.merge!(_minor_scales)
+    scales.merge!(_chromatic_scales)
+    scales.merge!(_pentatonic_scales)
+    scales.merge!(_exotic_scales)
+  end.freeze
 
   class << self
-    SCALE_TYPES.keys.each do |name|
+    SCALE_TYPES.each_key do |name|
       define_method(name) do
-        self.get(name)
+        get(name)
       end
     end
   end
@@ -70,7 +98,7 @@ class HeadMusic::ScaleType
   end
 
   attr_reader :name, :ascending_intervals, :descending_intervals, :parent_name
-  alias_method :intervals, :ascending_intervals
+  alias intervals ascending_intervals
 
   delegate :to_s, to: :name
 
@@ -82,7 +110,7 @@ class HeadMusic::ScaleType
   end
 
   def ==(other)
-    self.state == other.state
+    state == other.state
   end
 
   def state
@@ -96,4 +124,16 @@ class HeadMusic::ScaleType
   def diatonic?
     intervals.length == 7
   end
+
+  def whole_tone?
+    intervals.length == 6 && intervals.uniq == [2]
+  end
+
+  def pentatonic?
+    intervals.length == 5
+  end
+
+  def chromatic?
+    intervals.length == 12
+  end
 end

data/lib/head_music/sign.rb

@@ -1,15 +1,18 @@
+# frozen_string_literal: true
+
+# A Sign is a symbol that modifies pitch, such as a sharp, flat, or natural.
 class HeadMusic::Sign
   include Comparable
 
-  attr_reader :identifier, :name, :ascii, :unicode, :html_entity, :cents
+  attr_reader :identifier, :ascii, :unicode, :html_entity, :cents
 
   def self.all
     @all ||= [
-      new(identifier: :sharp, name: 'sharp', ascii: '#', unicode: '♯', html_entity: '♯', cents: 100),
-      new(identifier: :flat, name: 'flat', ascii: 'b', unicode: "♭", html_entity: '♭', cents: -100),
-      new(identifier: :natural, name: 'natural', ascii: '', unicode: '♮', html_entity: '♮', cents: 0),
-      new(identifier: :double_sharp, name: 'double sharp', ascii: '##', unicode: '𝄪', html_entity: '𝄪', cents: 200),
-      new(identifier: :double_flat, name: 'double flat', ascii: 'bb', unicode: '𝄫', html_entity: '𝄫', cents: -200),
+      new(identifier: :sharp, ascii: '#', unicode: '♯', html_entity: '♯', cents: 100),
+      new(identifier: :flat, ascii: 'b', unicode: '♭', html_entity: '♭', cents: -100),
+      new(identifier: :natural, ascii: '', unicode: '♮', html_entity: '♮', cents: 0),
+      new(identifier: :double_sharp, ascii: '##', unicode: '𝄪', html_entity: '𝄪', cents: 200),
+      new(identifier: :double_flat, ascii: 'bb', unicode: '𝄫', html_entity: '𝄫', cents: -200),
     ]
   end
 
@@ -22,7 +25,7 @@ class HeadMusic::Sign
   end
 
   def self.symbol?(candidate)
-    /^(#{matcher})$/.match?(candidate)
+    candidate =~ /^(#{matcher})$/
   end
 
   def self.get(identifier)
@@ -34,14 +37,17 @@ class HeadMusic::Sign
 
   def self.by(key, value)
     all.detect do |sign|
-      if %i[cents semitones].include?(key.to_sym)
-        sign.send(key) == value
-      end
+      sign.send(key) == value if %i[cents semitones].include?(key.to_sym)
     end
   end
 
+  def name
+    identifier.to_s.tr('_', ' ')
+  end
+
   def representions
-    [identifier, identifier.to_s, name, ascii, unicode, html_entity].reject { |representation| representation.to_s.strip == '' }
+    [identifier, identifier.to_s, name, ascii, unicode, html_entity].
+      reject { |representation| representation.to_s.strip == '' }
   end
 
   def semitones
@@ -54,14 +60,13 @@ class HeadMusic::Sign
 
   def <=>(other)
     other = HeadMusic::Sign.get(other)
-    self.cents <=> other.cents
+    cents <=> other.cents
   end
 
   private
 
   def initialize(attributes)
     @identifier = attributes[:identifier]
-    @name = attributes[:name]
     @ascii = attributes[:ascii]
     @unicode = attributes[:unicode]
     @html_entity = attributes[:html_entity]

data/lib/head_music/spelling.rb

@@ -1,3 +1,8 @@
+# frozen_string_literal: true
+
+# Represents the spelling of a pitch, such as C# or Db.
+# Composite of a LetterName and an optional Sign.
+# Does not include the octave. See Pitch for that.
 class HeadMusic::Spelling
   MATCHER = /^\s*([A-G])(#{HeadMusic::Sign.matcher}?)(\-?\d+)?\s*$/i
 
@@ -15,18 +20,17 @@ class HeadMusic::Spelling
     from_name(identifier) || from_number(identifier)
   end
 
-  def self.match(string)
+  def self.matching_string(string)
     string.to_s.match(MATCHER)
   end
 
   def self.from_name(name)
-    if match(name)
-      letter_name, sign_string, _octave = match(name).captures
-      letter_name = HeadMusic::LetterName.get(letter_name)
-      return nil unless letter_name
-      sign = HeadMusic::Sign.get(sign_string)
-      fetch_or_create(letter_name, sign)
-    end
+    return nil unless matching_string(name)
+    letter_name, sign_string, _octave = matching_string(name).captures
+    letter_name = HeadMusic::LetterName.get(letter_name)
+    return nil unless letter_name
+    sign = HeadMusic::Sign.get(sign_string)
+    fetch_or_create(letter_name, sign)
   end
 
   def self.from_number(number)
@@ -73,8 +77,8 @@ class HeadMusic::Spelling
     sign && sign == 'b'
   end
 
-  def ==(value)
-    other = HeadMusic::Spelling.get(value)
+  def ==(other)
+    other = HeadMusic::Spelling.get(other)
     to_s == other.to_s
   end
 

data/lib/head_music/staff.rb

@@ -1,8 +1,11 @@
+# frozen_string_literal: true
+
+# A staff is a set of lines and spaces that provides context for a pitch
 class HeadMusic::Staff
   DEFAULT_LINE_COUNT = 5
 
   attr_reader :default_clef, :line_count, :instrument
-  alias_method :clef, :default_clef
+  alias clef default_clef
 
   def initialize(default_clef, instrument: nil, line_count: nil)
     @default_clef = HeadMusic::Clef.get(default_clef)