mtk 0.0.3.3 → 0.4

data/lib/mtk/lang/mtk_grammar.citrus

@@ -133,25 +133,35 @@ grammar MTK_Grammar
   end
 
   rule pitch_class
-    ( [A-Ga-g] [#b]*2 ) {
+    ( diatonic_pitch_class accidental? ) {
       MTK::Core::PitchClass[to_s]
     }
   end
 
+  rule diatonic_pitch_class
+    ( [A-G] ) {
+      MTK::Core::PitchClass[to_s]
+    }
+  end
+
+  rule accidental
+    ('#'1*2 | 'b'1*2)
+  end
+
   rule interval
-    ( [Pp] [1458] | ('maj'|'min'|[Mm]) [2367] | 'TT' | 'tt' ) {
+    ( 'P' [1458] | [Mm] [2367] | 'a' [1-7] | 'd' [2-8] | 'TT' ) {
       MTK::Core::Interval.from_s(to_s)
     }
   end
 
   rule intensity
-    ( ('p'1*3 | 'mp' | 'mf' | 'o' | 'f'2*3) ('+'|'-')? ) {
+    ( ('p'1*3 | 'mp' | 'mf' | 'f'1*3) ('+'|'-')? ) {
       MTK::Core::Intensity.from_s(to_s)
     }
   end
 
   rule duration
-    ( rest:'-'? multiplier:number? [whqisrx] ('.'|'t')* ) {
+    ( rest:'-'? multiplier:number? [whqesrx] ('.'|'t')* ) {
       MTK::Core::Duration.from_s(to_s)
     }
   end

data/lib/mtk/lang/parser.rb

@@ -12,15 +12,20 @@ Citrus.load File.join(File.dirname(__FILE__),'mtk_grammar')
 module MTK
   module Lang
 
-    # Parser for the {file:lib/mtk/lang/mtk_grammar.citrus MTK grammar}
+    # Parser for the {file:lib/mtk/lang/mtk_grammar.citrus MTK syntax}
     class Parser
 
-      def self.parse(syntax, root=:root, dump=false)
+      # Parse the given MTK syntax according to the {file:lib/mtk/lang/mtk_grammar.citrus grammar rules}
+      # @return [Sequencers::LegatoSequencer] by default
+      # @return [Core,Patterns,Sequencers] a core object, pattern or sequencer when an optional grammar rule
+      #                                   is given. Depends on the rule.
+      # @raise [Citrus::ParseError] for invalid syntax
+      def self.parse(syntax, grammar_rule=:root, dump=false)
         syntax = syntax.to_s.strip
         return nil if syntax.empty?
-        matcher = ::MTK_Grammar.parse(syntax, :root => root)
-        puts matcher.dump if dump
-        matcher.value
+        match = ::MTK_Grammar.parse(syntax, root: grammar_rule)
+        puts match.dump if dump
+        match.value
       end
 
     end

data/lib/mtk/lang/pitch_classes.rb

@@ -1,29 +1,57 @@
 module MTK
   module Lang
 
-    # Defines a constant for each {PitchClass} in the Western chromatic scale.
+    # Defines a constant for each {Core::PitchClass} in the Western chromatic scale.
+    #
+    # Because '#' is not a valid identifier character in Ruby. All chromatic pitch classes are defined as
+    # the flat of a diatonic pitch class, for example Eb is a constant because D# is not a valid Ruby constant name.
+    #
+    # To help automate the documentation, the constants are listed under "Instance Attribute Summary" on this page.
+    #
+    # @see Core::PitchClass
+    #
     module PitchClasses
 
-      # The values of all constants defined in this module
-      PITCH_CLASSES = MTK::Core::PitchClass::PITCH_CLASSES
+      # @private
+      # @!macro [attach] define_pitch_class
+      #   PitchClass $1 $3
+      #   @!attribute [r]
+      #   @return [MTK::Core::PitchClass] PitchClass $1 (value $2)
+      def self.define_pitch_class name, value, more_info=nil
+        const_set name, MTK::Core::PitchClass.from_name(name)
+      end
+
+      define_pitch_class 'C', 0
+
+      define_pitch_class 'Db', 1, '(also known as C#)'
+
+      define_pitch_class 'D', 2
+
+      define_pitch_class 'Eb', 3, '(also known as D#)'
+
+      define_pitch_class 'E', 4
+
+      define_pitch_class 'F', 5
+
+      define_pitch_class 'Gb', 6, '(also known as F#)'
+
+      define_pitch_class 'G', 7
+
+      define_pitch_class 'Ab', 8, '(also known as G#)'
+
+      define_pitch_class 'A', 9
+
+      define_pitch_class 'Bb', 10, '(also known as A#)'
+
+      define_pitch_class 'B', 11
+
+      # All constants defined in this module
+      PITCH_CLASSES = [C, Db, D, Eb, E, F, Gb, G, Ab, A, Bb, B].freeze
 
       # The names of all constants defined in this module
+      # @see MTK::Core::PitchClass::NAMES
       PITCH_CLASS_NAMES = MTK::Core::PitchClass::NAMES
 
-      PITCH_CLASSES.each { |pc| const_set pc.name, pc }
-
-      # Lookup the value of an pitch class constant by name.
-      # @example lookup value of 'C'
-      #         MTK::Core::PitchClasses['C']
-      # @see Groups::PitchClass.[]
-      def self.[](name)
-        begin
-          const_get name
-        rescue
-          nil
-        end
-      end
-
     end
   end
 end

data/lib/mtk/lang/pitches.rb

@@ -2,51 +2,188 @@ module MTK
   module Lang
 
     # Defines a constants for each {Core::Pitch} in the standard MIDI range using scientific pitch notation.
+    # The constants range from C-1 (MIDI value 0) to G9 (MIDI value)
     #
-    # See http://en.wikipedia.org/wiki/Scientific_pitch_notation
+    # Because the character '#' cannot be used in the name of a constant,
+    # the "black key" pitches are all named as flats with 'b' (for example, Gb3 or Db4).
+    # And because the character '-' (minus) cannot be used in the name of a constant,
+    # the low pitches use '_' (underscore) in place of '-' (minus) (for example C_1).
     #
-    # @note Because the character '#' cannot be used in the name of a constant,
-    #     the "black key" pitches are all named as flats with 'b' (for example, Gb3 or Cb4)
-    # @note Because the character '-' (minus) cannot be used in the name of a constant,
-    #     the low pitches use '_' (underscore) in place of '-' (minus) (for example C_1).
-    module Pitches
+    # To help automate the documentation, the constants are listed under "Instance Attribute Summary" on this page.
+    #
+    # @see Core::Pitch
+    # @see Events::Note
+    # @see http://en.wikipedia.org/wiki/Scientific_pitch_notation
+  module Pitches
+
+      # @private
+      # @!macro [attach] define_pitch
+      #   Pitch $1 (MIDI pitch $2)
+      #   @!attribute [r]
+      #   @return [MTK::Core::Pitch] Pitch $1 (value $2)
+      def self.define_pitch name, value
+        pitch = MTK::Core::Pitch.from_i(value)
+        const_set name, pitch
+        PITCHES << pitch
+        PITCH_NAMES << name
+      end
 
       # The values of all constants defined in this module
+      # @note This is populated dynamically so the documentation does not reflect the actual value
       PITCHES = []
 
       # The names of all constants defined in this module
+      # @note This is populated dynamically so the documentation does not reflect the actual value
       PITCH_NAMES = []
 
-      128.times do |note_number|
-        pitch = MTK::Core::Pitch.from_i( note_number )
-        PITCHES << pitch
-
-        octave_str = pitch.octave.to_s.sub(/-/,'_') # '_1' for -1
-        name = "#{pitch.pitch_class}#{octave_str}"
-        PITCH_NAMES << name
-
-        # TODO? also define lower case pseudo constants for consistency with the grammar?
-
-        const_set name, pitch
-      end
+      define_pitch 'C_1', 0
+      define_pitch 'Db_1', 1
+      define_pitch 'D_1', 2
+      define_pitch 'Eb_1', 3
+      define_pitch 'E_1', 4
+      define_pitch 'F_1', 5
+      define_pitch 'Gb_1', 6
+      define_pitch 'G_1', 7
+      define_pitch 'Ab_1', 8
+      define_pitch 'A_1', 9
+      define_pitch 'Bb_1', 10
+      define_pitch 'B_1', 11
+      define_pitch 'C0', 12
+      define_pitch 'Db0', 13
+      define_pitch 'D0', 14
+      define_pitch 'Eb0', 15
+      define_pitch 'E0', 16
+      define_pitch 'F0', 17
+      define_pitch 'Gb0', 18
+      define_pitch 'G0', 19
+      define_pitch 'Ab0', 20
+      define_pitch 'A0', 21
+      define_pitch 'Bb0', 22
+      define_pitch 'B0', 23
+      define_pitch 'C1', 24
+      define_pitch 'Db1', 25
+      define_pitch 'D1', 26
+      define_pitch 'Eb1', 27
+      define_pitch 'E1', 28
+      define_pitch 'F1', 29
+      define_pitch 'Gb1', 30
+      define_pitch 'G1', 31
+      define_pitch 'Ab1', 32
+      define_pitch 'A1', 33
+      define_pitch 'Bb1', 34
+      define_pitch 'B1', 35
+      define_pitch 'C2', 36
+      define_pitch 'Db2', 37
+      define_pitch 'D2', 38
+      define_pitch 'Eb2', 39
+      define_pitch 'E2', 40
+      define_pitch 'F2', 41
+      define_pitch 'Gb2', 42
+      define_pitch 'G2', 43
+      define_pitch 'Ab2', 44
+      define_pitch 'A2', 45
+      define_pitch 'Bb2', 46
+      define_pitch 'B2', 47
+      define_pitch 'C3', 48
+      define_pitch 'Db3', 49
+      define_pitch 'D3', 50
+      define_pitch 'Eb3', 51
+      define_pitch 'E3', 52
+      define_pitch 'F3', 53
+      define_pitch 'Gb3', 54
+      define_pitch 'G3', 55
+      define_pitch 'Ab3', 56
+      define_pitch 'A3', 57
+      define_pitch 'Bb3', 58
+      define_pitch 'B3', 59
+      define_pitch 'C4', 60
+      define_pitch 'Db4', 61
+      define_pitch 'D4', 62
+      define_pitch 'Eb4', 63
+      define_pitch 'E4', 64
+      define_pitch 'F4', 65
+      define_pitch 'Gb4', 66
+      define_pitch 'G4', 67
+      define_pitch 'Ab4', 68
+      define_pitch 'A4', 69
+      define_pitch 'Bb4', 70
+      define_pitch 'B4', 71
+      define_pitch 'C5', 72
+      define_pitch 'Db5', 73
+      define_pitch 'D5', 74
+      define_pitch 'Eb5', 75
+      define_pitch 'E5', 76
+      define_pitch 'F5', 77
+      define_pitch 'Gb5', 78
+      define_pitch 'G5', 79
+      define_pitch 'Ab5', 80
+      define_pitch 'A5', 81
+      define_pitch 'Bb5', 82
+      define_pitch 'B5', 83
+      define_pitch 'C6', 84
+      define_pitch 'Db6', 85
+      define_pitch 'D6', 86
+      define_pitch 'Eb6', 87
+      define_pitch 'E6', 88
+      define_pitch 'F6', 89
+      define_pitch 'Gb6', 90
+      define_pitch 'G6', 91
+      define_pitch 'Ab6', 92
+      define_pitch 'A6', 93
+      define_pitch 'Bb6', 94
+      define_pitch 'B6', 95
+      define_pitch 'C7', 96
+      define_pitch 'Db7', 97
+      define_pitch 'D7', 98
+      define_pitch 'Eb7', 99
+      define_pitch 'E7', 100
+      define_pitch 'F7', 101
+      define_pitch 'Gb7', 102
+      define_pitch 'G7', 103
+      define_pitch 'Ab7', 104
+      define_pitch 'A7', 105
+      define_pitch 'Bb7', 106
+      define_pitch 'B7', 107
+      define_pitch 'C8', 108
+      define_pitch 'Db8', 109
+      define_pitch 'D8', 110
+      define_pitch 'Eb8', 111
+      define_pitch 'E8', 112
+      define_pitch 'F8', 113
+      define_pitch 'Gb8', 114
+      define_pitch 'G8', 115
+      define_pitch 'Ab8', 116
+      define_pitch 'A8', 117
+      define_pitch 'Bb8', 118
+      define_pitch 'B8', 119
+      define_pitch 'C9', 120
+      define_pitch 'Db9', 121
+      define_pitch 'D9', 122
+      define_pitch 'Eb9', 123
+      define_pitch 'E9', 124
+      define_pitch 'F9', 125
+      define_pitch 'Gb9', 126
+      define_pitch 'G9', 127
 
       PITCHES.freeze
       PITCH_NAMES.freeze
 
-      # Lookup the value of an pitch constant by name.
-      # @example lookup value of 'C3'
-      #         MTK::Core::Pitches['C3']
-      # @see Core::Pitch.from_s
-      # @note Unlike {Core::Pitch.from_s} this method will accept either '_' (underscore) or '-' (minus) and treat it like '-' (minus)
-      # @note Unlike {Core::Pitch.from_s} this method only accepts the accidental 'b'
-      def self.[](name)
-        begin
-          const_get name.sub('-','_')
-        rescue
-          nil
-        end
-      end
-
     end
   end
 end
+
+
+
+=begin
+
+Script for generating the define_pitch statements in this file.
+Run in the irb console after requiring 'mtk'
+
+128.times do |value|
+  pitch = MTK::Core::Pitch.from_i(value)
+  octave_str = pitch.octave.to_s.sub(/-/,'_') # '_1' for -1
+  name = "#{pitch.pitch_class}#{octave_str}"
+  puts "      define_pitch '#{name}', #{value}"
+end
+
+=end

data/lib/mtk/lang/tutorial.rb

@@ -0,0 +1,279 @@
+# encoding: UTF-8
+
+require 'mtk/io/midi_output'
+require 'mtk/lang/tutorial_lesson'
+
+module MTK
+  module Lang
+
+    # @private
+    class Tutorial
+
+      def initialize
+        @current_lesson_index = 0
+
+        @lessons = [
+              ###################### 79 character width for description #####################
+          {
+            title: 'Pitch Classes (diatonic)',
+            description: "
+              The diatonic pitch classes are the 7 white keys on a piano in a given octave.
+              They can be used to play, for example, the C major or A natural minor scales.
+
+              To play a diatonic pitch class, enter #{'one'.bold.underline} of the following letters
+              (must be upper-case):
+
+              C D E F G A B
+              ",
+            validation: :diatonic_pitch_class,
+          },
+          {
+            title: 'Pitch Classes (chromatic)',
+            description: "
+              The chromatic pitch classes are the 12 white or black keys on a piano in a
+              given octave. They form the basis of all 'western' music theory.
+
+              To play a chromatic pitch class, enter any of the 7 diatonic pitch classes
+              immediately followed by 0, 1, or 2 flats (b) or sharps (#). Each flat (b)
+              lowers the pitch by a half step and each sharp (#) raises by a half step.
+
+              Here are some examples, try entering #{'one'.bold.underline} of the following:
+
+              C# Bb A## Ebb F
+              ",
+            validation: :pitch_class,
+          },
+          {
+            title: 'Pitches',
+            description: "
+              To play a pitch, enter a (chromatic) pitch class immediately following by an
+              octave number.
+
+              There is no universal standard numbering scheme for octaves in music.
+              This library uses \"scientific pitch notation\", which defines
+              C4 as \"Middle C\" and A4 as the standard tuning pitch A440.
+
+              In this library, C-1 is the lowest note available and G9 is the highest,
+              corresponding to MIDI pitch values 0 and 127. If you try to play a pitch
+              outside this range, it will be mapped to the closest available pitch.
+
+              Here are some examples, try entering #{'one'.bold.underline} of the following:
+
+              G3 Eb4 F#5 B-1 C##9 Dbb6
+              ",
+            validation: :pitch,
+          },
+          {
+            title: 'Sequences',
+            description: "
+              To play a sequence of pitches or pitch classes, enter them with spaces in
+              between. Pitches and pitch classes may be interchanged in a given sequence.
+              Any pitch class will output a pitch closest to the previous pitch (starting
+              from C4 at the beginning of the sequence).
+
+              Here is an example (Note, unlike previous lessons, enter the #{'entire line'.bold.underline}):
+
+              C5 C G5 G A A G
+              ",
+            validation: :bare_sequence,
+          },
+          {
+            title: 'Repetition',
+            description: "
+              To repeat a note, suffix a pitch or pitch class with *N, where N is the
+              number of repetitions. You can also wrap a subsequence of notes with
+              parentheses and repeat them. Here is an example sequence with repetition:
+
+              C*3 D (E D)*2 C
+
+              You can also nest repetitions (optional whitespace added for readability):
+
+              ( C5 (E G)*2 )*2
+              ",
+            validation: /\*/,
+          },
+
+        ].map{|lesson_options| TutorialLesson.new(lesson_options) }
+      end
+
+
+      def run(output)
+        puts SEPARATOR
+        puts
+        puts "Welcome to the MTK syntax tutorial!".bold.yellow
+        puts
+        puts "MTK is the Music Tool Kit for Ruby, which includes a custom syntax for"
+        puts "generating musical patterns. This tutorial has a variety of lessons to teach"
+        puts "you the syntax. It assumes basic familiarity with music theory."
+        puts
+        puts "Make sure your speakers are on and the volume is turned up."
+        puts
+        puts "This is a work in progress. Check back in future versions for more lessons."
+        puts
+        puts "#{'NOTE:'.bold} MTK syntax is case-sensitive. Upper vs lower-case matters."
+        puts
+
+        output = ensure_output(output)
+        loop{ select_lesson.run(output) }
+
+      rescue SystemExit, Interrupt
+        puts
+        puts
+        puts "Goodbye!"
+        puts
+      end
+
+
+      # table of contents
+      def toc
+        @lessons.map.with_index do |lesson,index|
+          "#{'> '.bold.yellow if @current_lesson_index == index}#{index+1}: #{lesson}"
+        end.join("\n")
+      end
+
+
+      def select_lesson
+        puts
+        puts SEPARATOR
+        puts
+        puts "Lessons".bold.yellow
+        puts
+
+        all_done = @current_lesson_index >= @lessons.length
+        lesson = nil
+        while lesson == nil
+          puts toc
+          puts
+          if all_done
+            puts "You've completed the last lesson!"
+            puts "To explore more, try running #{$0} with the --eval option."
+            puts
+          end
+          puts "Press Ctrl+C to exit at any time.".bold
+          puts
+          print "Select a lesson number, or press enter to ".blue
+          if all_done
+            puts "exit:".blue
+          else
+            puts "go to the next one ".blue + "(indicated by " + '>'.bold.yellow + "):"
+          end
+
+          input = gets.strip
+          lesson_index = case input
+            when /^\d+$/
+              input.to_i - 1
+            when ''
+              if all_done then raise SystemExit.new else @current_lesson_index end
+            else
+              nil
+          end
+
+          lesson = @lessons[lesson_index] if lesson_index and lesson_index >= 0
+
+          puts "Invalid lesson number: #{input}\n\n" if lesson.nil?
+        end
+
+        @current_lesson_index = lesson_index + 1
+        lesson
+      end
+
+
+      #####################################################
+      private
+
+      def ensure_output(output)
+        unless output
+          puts SEPARATOR
+          puts
+          puts "Select an output".bold.yellow
+          puts
+          puts "You need to select a MIDI output device before you can hear sound."
+          puts
+
+          require 'rbconfig'
+          case RbConfig::CONFIG['host_os'].downcase
+            when /darwin/
+              puts "You appear to be on OS X."
+              puts "You can use the \"Apple DLS Synthesizer\" to hear sound with no extra setup."
+              puts "It's recommended you use this unless you have a good reason to do otherwise."
+            when /win/
+              puts "You appear to be on Windows"
+              puts "You can use the \"Microsoft Synthesizer\" to hear sound with no extra setup."
+              puts "It's recommended you use this unless you have a good reason to do otherwise."
+          end
+
+          until output
+            puts
+            puts "Available MIDI outputs:".bold.yellow
+            MTK::IO::MIDIOutput.devices.each.with_index do |device,index|
+              name = device.name
+              name += " (#{device.id})" if device.respond_to? :id
+              puts "#{index+1}: #{name}"
+            end
+
+            puts "Select an output number:".blue
+
+            input = STDIN.gets.strip
+            if input =~ /^\d+$/
+              number = input.to_i
+              if number > 0
+                device = MTK::IO::MIDIOutput.devices[number-1]
+                output = MTK::IO::MIDIOutput.open(device) if device
+              end
+            end
+
+            puts "Invalid selection.".red unless device
+          end
+
+          puts
+          puts "OK! Using output '#{output.name}'".bold.green
+          puts "#{'NOTE:'.bold} You can skip the output selection step in the future by running "
+          puts "#{$0} with the --output option."
+          puts "Press enter to continue".blue
+          gets
+        end
+        output
+      end
+
+    end
+  end
+end
+
+
+####################################################################################################
+# Patch String to support terminal colors
+
+# @private
+class String
+  {
+    bold: 1,
+    underline: 4,
+    red: 31,
+    green: 32,
+    yellow: 33,
+    blue: 36 # really this cyan but the standard blue is too dark IMO
+  }.each do |effect,code|
+    if $tutorial_color
+      define_method effect do
+        "\e[#{code}m#{self}\e[0m"
+      end
+    else
+      define_method effect do
+        self
+      end
+    end
+  end
+
+end
+
+
+####################################################################################################
+# And now that we've got some colors we can define colored constants
+module MTK
+  module Lang
+    # @private
+    class Tutorial
+      SEPARATOR = "===============================================================================".bold.yellow
+    end
+  end
+end