outro_rails 0.1.0

data/lib/outro_rails/theory/transposer.rb

@@ -0,0 +1,248 @@
+# frozen_string_literal: true
+
+module OutroRails
+  module Theory
+    # Transposes freeform chord-chart text between chord symbols and
+    # Nashville numbers, or between keys. Tokens that don't parse as a
+    # known chord (or number) pass through untouched, so lyrics and other
+    # notation survive:
+    #
+    #   Transposer.transpose_chords("C Am7 F G7", from: "C", to: "Eb")
+    #   # => "Eb Cm7 Ab Bb7"
+    #   Transposer.chords_to_nashville("C Am7 F G7", key: "C")
+    #   # => "1 6m7 4 57"
+    #   Transposer.nashville_to_chords("1 6m7 4 5", key: "G")
+    #   # => "G Em7 C D"
+    module Transposer
+      # A note name with its accidental, shared with NoteName so the two
+      # can't drift.
+      NOTE_PATTERN = NoteName::NAME_PATTERN
+
+      # A whole chord symbol: root, everything up to a slash as the
+      # quality/extension suffix, then an optional slash bass.
+      CHORD_PATTERN = %r{
+        \A
+        (?<root>#{NOTE_PATTERN})
+        (?<suffix>[^/]*)
+        (?:/(?<bass>#{NOTE_PATTERN}))?
+        \z
+      }x
+
+      # Chart punctuation that can wrap a chord: "|C|", "(Am)", "F,".
+      WRAPPER_PATTERN = %r{
+        \A
+        (?<open>[(\[|]*)
+        (?<core>.*?)
+        (?<close>[)\]|,.;:!?]*)
+        \z
+      }mx
+
+      # Every quality/extension suffix the vocabulary can symbolize.
+      KNOWN_SUFFIXES = ChordVocabulary::SYMBOLS.values
+                                               .flat_map(&:values)
+                                               .uniq
+                                               .freeze
+
+      # Alteration and added-tone tails that may trail a suffix (C7b9,
+      # Cadd9), longest first so add11 wins over shorter alternatives.
+      tails = (
+        ChordVocabulary::ALTERATIONS.keys +
+        ChordVocabulary::ADDED_TONE_INTERVALS.keys
+      ).map(&:to_s)
+        .sort_by { |tail| -tail.length }
+        .map { |tail| Regexp.escape(tail) }
+        .join("|")
+
+      TAIL_PATTERN = /(?:#{tails})\z/
+
+      module_function
+
+      # Chord symbols respelled into a new key; each root (and slash bass)
+      # keeps its relationship to the key, so G major's F# lands on Bb
+      # major's A.
+      def transpose_chords(text, from:, to:)
+        from = Key.parse(from)
+        to = Key.parse(to)
+
+        transform(text) do |core|
+          chord = parse_chord(core)
+          next nil unless chord
+
+          root = from.transpose_note(chord[:root], to: to)
+          bass = chord[:bass] && from.transpose_note(chord[:bass], to: to)
+
+          "#{root}#{chord[:suffix]}#{"/#{bass}" if bass}"
+        end
+      end
+
+      # Chord symbols => Nashville numbers relative to `key`; the quality
+      # suffix carries over verbatim (Am7 in C => 6m7, Bb in C => b7).
+      def chords_to_nashville(text, key:)
+        key = Key.parse(key)
+
+        transform(text) do |core|
+          chord = parse_chord(core)
+          next nil unless chord
+
+          number = nashville_root(key, chord[:root])
+          next nil unless number
+
+          if chord[:bass]
+            bass = nashville_root(key, chord[:bass])
+            next nil unless bass
+          end
+
+          "#{number}#{chord[:suffix]}#{"/#{bass}" if bass}"
+        end
+      end
+
+      # Nashville numbers (or roman numerals) => chord symbols in `key`,
+      # via Key#nashville. Slash basses are degrees too: "1/3" in C => C/E.
+      def nashville_to_chords(text, key:)
+        key = Key.parse(key)
+
+        transform(text) do |core|
+          number, bass = core.split("/", 2)
+
+          begin
+            symbol = key.nashville(number).fetch(:symbol)
+
+            if bass
+              parsed = NashvilleNumber.parse(bass)
+              note = key.note_for_degree(
+                parsed.degree,
+                parsed.accidental_offset
+              )
+              symbol = "#{symbol}/#{note}"
+            end
+
+            symbol
+          rescue ArgumentError, KeyError
+            nil
+          end
+        end
+      end
+
+      # Every distinct chord symbol recognized in freeform chart text, in
+      # the order each first appears; lyrics and anything else pass
+      # unrecognized ("Amazing Grace, how sweet the C sound" only yields
+      # "C"). Used to find which chords a chart references, e.g. to look
+      # up their diagrams:
+      #
+      #   Transposer.scan_chords("C  Am7  F  G7")  # => ["C", "Am7", "F"]
+      def scan_chords(text)
+        symbols = []
+
+        transform(text) do |core|
+          chord = parse_chord(core)
+          next nil unless chord
+
+          symbol =
+            "#{chord[:root]}#{chord[:suffix]}" \
+            "#{"/#{chord[:bass]}" if chord[:bass]}"
+          symbols << symbol unless symbols.include?(symbol)
+          nil # never replace - this only scans, it doesn't rewrite.
+        end
+
+        symbols
+      end
+
+      # Splits a chord symbol into its base symbol and slash bass:
+      #
+      #   Transposer.split_bass("G/B")  # => ["G", "B"]
+      #   Transposer.split_bass("Am7")  # => ["Am7", nil]
+      #
+      # Unrecognized input comes back unchanged with a nil bass, so
+      # callers can feed it anything scan_chords produced.
+      def split_bass(symbol)
+        chord = parse_chord(symbol.to_s)
+        return [ symbol.to_s, nil ] unless chord
+
+        [ "#{chord[:root]}#{chord[:suffix]}", chord[:bass] ]
+      end
+
+      # Wraps every recognized chord token in `text` with whatever the
+      # block returns, given the symbol as it should be displayed -
+      # lyrics and punctuation pass through untouched. Pass `from`/`to` to
+      # transpose the wrapped symbol at the same time; omitted (or equal)
+      # leaves chords spelled as written. Used to render a chart body with
+      # its chords highlighted, optionally previewed in another key,
+      # without mutating anything in storage:
+      #
+      #   Transposer.annotate_chords(body, from: "C", to: "D")
+      #     { |symbol| "<mark>#{symbol}</mark>" }
+      def annotate_chords(text, from: nil, to: nil)
+        from_key = from && Key.parse(from)
+        to_key = to && Key.parse(to)
+
+        transform(text) do |core|
+          chord = parse_chord(core)
+          next nil unless chord
+
+          root = chord[:root]
+          bass = chord[:bass]
+
+          if from_key && to_key
+            root = from_key.transpose_note(root, to: to_key)
+            bass = bass && from_key.transpose_note(bass, to: to_key)
+          end
+
+          yield("#{root}#{chord[:suffix]}#{"/#{bass}" if bass}")
+        end
+      end
+
+      # Walks whitespace-separated tokens, unwrapping chart punctuation,
+      # and replaces each token the block converts (block returns nil to
+      # leave a token untouched). Whitespace is preserved exactly.
+      def transform(text)
+        text.to_s.split(/(\s+)/).map do |token|
+          next token if token.empty? || token.match?(/\A\s+\z/)
+
+          match = token.match(WRAPPER_PATTERN)
+          replacement = match[:core].empty? ? nil : yield(match[:core])
+
+          replacement ? "#{match[:open]}#{replacement}#{match[:close]}" : token
+        end.join
+      end
+
+      # { root:, suffix:, bass: } when the token is a known chord symbol,
+      # nil otherwise ("Amazing" has a note-shaped start but no known
+      # suffix, so it stays lyrics).
+      def parse_chord(core)
+        match = core.match(CHORD_PATTERN)
+        return nil unless match && known_suffix?(match[:suffix])
+
+        { root: match[:root], suffix: match[:suffix], bass: match[:bass] }
+      end
+
+      # Whether a suffix names a chord the vocabulary knows: alteration and
+      # added-tone tails are peeled off the end (C7b9b13 => C7) and what
+      # remains must be a symbolizable suffix. "" counts - a bare root is
+      # a major triad.
+      def known_suffix?(suffix)
+        core = suffix.dup
+        core = core.sub(TAIL_PATTERN, "") while core.match?(TAIL_PATTERN)
+
+        KNOWN_SUFFIXES.include?(core)
+      end
+
+      # Accidental + degree for a note in a key ("b7", "4"), or nil when
+      # the spelling is too remote to write as a Nashville accidental.
+      def nashville_root(key, note)
+        degree, offset = key.degree_of(note)
+        return nil if offset.abs > 1
+
+        NashvilleNumber.format(degree: degree,
+                               quality: :major,
+                               accidental_offset: offset)
+      end
+
+      # Internal helpers - the public surface is the conversions, plus
+      # scan_chords/annotate_chords, above.
+      private_class_method :transform,
+                           :parse_chord,
+                           :known_suffix?,
+                           :nashville_root
+    end
+  end
+end

data/lib/outro_rails/theory.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require "outro_rails/theory/interval"
+require "outro_rails/theory/note_name"
+require "outro_rails/theory/pitch"
+require "outro_rails/theory/chord_vocabulary"
+require "outro_rails/theory/scale"
+require "outro_rails/theory/key"
+require "outro_rails/theory/nashville_number"
+require "outro_rails/theory/transposer"
+
+module OutroRails
+  module Theory
+  end
+end

data/lib/outro_rails/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module OutroRails
+  VERSION = "0.1.0"
+end

data/lib/outro_rails.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require "outro_rails/version"
+require "outro_rails/engine"
+
+require "outro_rails/theory"
+require "outro_rails/instruments"
+
+require "outro_rails/chord_chart_attribute"
+
+module OutroRails
+  mattr_accessor :chord_chart_voicing_authorization,
+    default: ->(chord_chart:, controller:) { true }
+
+  def self.chord_chart_voicing_authorized?(chord_chart:, controller:)
+    !!chord_chart_voicing_authorization.call(chord_chart: chord_chart,
+                                             controller:  controller)
+  end
+end

data/lib/tasks/outro_rails_tasks.rake

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+namespace :outro_rails do
+  desc "Seed the Outro chord library (idempotent - safe to re-run)"
+  task seed: :environment do
+    OutroRails::Engine.load_seed
+  end
+
+  namespace :chords do
+    require "fileutils"
+    require "outro_rails/theory"
+    require "outro_rails/generators/chord_seed_generator"
+
+    seed_dir = File.expand_path("../../db/seeds/chords", __dir__)
+
+    write_seed = lambda do |root|
+      FileUtils.mkdir_p(seed_dir)
+
+      path = File.join(seed_dir, "#{root.path_slug}.yml")
+      yaml = OutroRails::ChordSeedGenerator.new(root_name: root).to_yaml
+      File.write(path, yaml)
+
+      puts "wrote #{path} (#{yaml.scan(/^- symbol/).size} chords)"
+    end
+
+    desc "Generate chord seed YAML for all canonical roots into db/seeds/chords"
+    task :generate_seed_yml do
+      OutroRails::Theory::NoteName::CANONICAL_ROOTS.each do |name|
+        write_seed.call(OutroRails::Theory::NoteName.parse(name))
+      end
+    end
+  end
+
+  namespace :chord_voicings do
+    require "fileutils"
+    require "yaml"
+    require "outro_rails/generators/voicing_stub_generator"
+    require "outro_rails/generators/guitar_voicing_generator"
+
+    chords_dir = File.expand_path("../../db/seeds/chords", __dir__)
+    voicings_dir = File.expand_path("../../db/seeds/chord_voicings", __dir__)
+
+    # Guitar voicings are generated from the CAGED shape library when the chord
+    # has shapes defined; Piano voicings are created by rotating inversions.
+    # Everything else is stubbed for manual entry.
+    #
+    # Pass FORCE=1 to overwrite existing files.
+    desc "Create voicing seed YAML for every chord in db/seeds/chords."
+    task :stub_seed_yml do
+      force = ENV["FORCE"] == "1"
+      FileUtils.mkdir_p(voicings_dir)
+      generated = 0
+      stubbed = 0
+      skipped = 0
+      filenames = {}
+
+      Dir.glob(File.join(chords_dir, "*.yml")).sort.each do |file|
+        YAML.load_file(file).each do |chord|
+          stubber = OutroRails::VoicingStubGenerator.new(chord)
+          guitar = OutroRails::GuitarVoicingGenerator.new(chord)
+
+          OutroRails::VoicingStubGenerator::INSTRUMENTS.each do |instrument|
+            relative_path = stubber.relative_path(instrument)
+
+            claimed_by = filenames[relative_path]
+            if claimed_by && claimed_by != stubber.symbol
+              raise "Filename collision: #{claimed_by} and #{stubber.symbol}" \
+                    "both slug to #{relative_path}"
+            end
+
+            filenames[relative_path] = stubber.symbol
+            path = File.join(voicings_dir, relative_path)
+            FileUtils.mkdir_p(File.dirname(path))
+
+            if File.exist?(path) && !force
+              skipped += 1
+            elsif instrument == :guitar && guitar.supported?
+              File.write(path, guitar.to_yaml)
+              generated += 1
+            else
+              File.write(path, stubber.stub_yaml(instrument))
+              stubbed += 1
+            end
+          end
+        end
+      end
+
+      puts "generated #{generated} guitar voicing files, stubbed #{stubbed}, " \
+           "skipped #{skipped} existing (#{voicings_dir})"
+    end
+  end
+end