mtk 0.0.2 → 0.0.3

data/lib/mtk.rb

@@ -1,70 +1,82 @@
-##############################################
 # Description of modules for documentation:
 
 # The top level module for this library
 module MTK
 
+  # Constants for modeling frequency, intensity, and duration.
+  module Constants
+  end
+
   # Internal helper classes used to avoid duplicating code in this library.
-  module Helper
+  module Helpers
   end
 
-  # Classes that emit elements one at a time. Used by {Sequencer}s to construct {Timeline}s.
-  #
-  # The core interface for Pattern classes is {Pattern::Enumerator#next} and {Pattern::Enumerator#rewind}.
-  module Pattern
+  # Musical events, such as {Events::Note}s and {Events::Parameter} changes, that are arranged in time via a {Timeline}.
+  module Events
   end
 
-  # Classes that assemble {Pattern}s into {Timeline}s.
-  module Sequencer
+  # Classes that emit elements one at a time. Used by {MTK::Sequencers::Sequencer}s to construct {Timeline}s.
+  module Patterns
+  end
+
+  # Classes that assemble {Patterns::Pattern}s into {Timeline}s.
+  module Sequencers
   end
 
   # Optional classes for the "MTK language", which let's you compose music via MTK without writing any Ruby code
   module Lang
   end
 
-  # Optional classes for MIDI input and output.
+  # Optional classes for MIDI input and {Output}.
   module MIDI
   end
 
 end
 
-require 'mtk/helper/collection'
-require 'mtk/helper/pseudo_constants'
-
-require 'mtk/transform/mappable'
-require 'mtk/transform/transposable'
-require 'mtk/transform/invertible'
-require 'mtk/transform/set_theory_operations'
-
 require 'mtk/pitch_class'
-require 'mtk/pitch_class_set'
 require 'mtk/pitch'
-require 'mtk/pitch_set'
+require 'mtk/duration'
+require 'mtk/intensity'
 
-require 'mtk/event'
-require 'mtk/note'
-require 'mtk/timeline'
+require 'mtk/interval'
 
-require 'mtk/_constants/pitch_classes'
-require 'mtk/_constants/pitches'
-require 'mtk/_constants/intervals'
-require 'mtk/_constants/intensities'
-require 'mtk/_constants/durations'
+require 'mtk/variable'
 
-require 'mtk/pattern/enumerator'
-require 'mtk/pattern/abstract_pattern'
-require 'mtk/pattern/sequence'
-require 'mtk/pattern/cycle'
-require 'mtk/pattern/choice'
-require 'mtk/pattern/function'
-require 'mtk/pattern/lines'
-require 'mtk/pattern/palindrome'
+require 'mtk/helpers/collection'
+require 'mtk/helpers/pitch_collection'
+require 'mtk/helpers/pseudo_constants'
+require 'mtk/helpers/convert'
 
-require 'mtk/helper/event_builder'
-require 'mtk/sequencer/abstract_sequencer'
-require 'mtk/sequencer/step_sequencer'
-require 'mtk/sequencer/rhythmic_sequencer'
+require 'mtk/pitch_class_set'
+require 'mtk/melody'
+require 'mtk/chord'
 
-require 'mtk/_numeric_extensions'
+require 'mtk/events/event'
+require 'mtk/events/note'
+require 'mtk/events/parameter'
 
+require 'mtk/timeline'
 
+require 'mtk/constants/pitch_classes'
+require 'mtk/constants/pitches'
+require 'mtk/constants/intervals'
+require 'mtk/constants/intensities'
+require 'mtk/constants/durations'
+
+require 'mtk/patterns/pattern'
+require 'mtk/patterns/sequence'
+require 'mtk/patterns/cycle'
+require 'mtk/patterns/choice'
+require 'mtk/patterns/function'
+require 'mtk/patterns/lines'
+require 'mtk/patterns/palindrome'
+require 'mtk/patterns/chain'
+require 'mtk/patterns/for_each'
+
+require 'mtk/sequencers/event_builder'
+require 'mtk/sequencers/sequencer'
+require 'mtk/sequencers/step_sequencer'
+require 'mtk/sequencers/rhythmic_sequencer'
+require 'mtk/sequencers/legato_sequencer'
+
+require 'mtk/lang/parser'

data/lib/mtk/chord.rb

@@ -0,0 +1,55 @@
+module MTK
+
+  # A sorted collection of distinct {Pitch}es.
+  #
+  # The "vertical" (simultaneous) pitch collection.
+  #
+  # @see Melody
+  # @see PitchClassSet
+  #
+  class Chord < Melody
+
+    # @param pitches [#to_a] the collection of pitches
+    # @note duplicate pitches will be removed. See #{Melody} if you want to maintain duplicates.
+    # @see MTK#Chord
+    #
+    def initialize(pitches)
+      pitches = pitches.to_a.clone
+      pitches.uniq!
+      pitches.sort!
+      @pitches = pitches.freeze
+    end
+
+    # Generate a chord inversion (positive numbers move the lowest notes up an octave, negative moves the highest notes down)
+    def inversion(number)
+      number = number.to_i
+      pitch_set = Array.new(@pitches.uniq.sort)
+      if number > 0
+        number.times do |count|
+          index = count % pitch_set.length
+          pitch_set[index] += 12
+        end
+      else
+        number.abs.times do |count|
+          index = -(count + 1) % pitch_set.length # count from -1 downward to go backwards through the list starting at the end
+          pitch_set[index] -= 12
+        end
+      end
+      self.class.new pitch_set.sort
+    end
+
+    # Transpose the chord so that it's lowest pitch is the given pitch class.
+    def nearest(pitch_class)
+      self.transpose @pitches.first.pitch_class.distance_to(pitch_class)
+    end
+  end
+
+  # Construct an ordered {Melody} with no duplicates.
+  # @see #Chord
+  # @see #Melody
+  def Chord(*anything)
+    Chord.new Helpers::Convert.to_pitches(*anything)
+  end
+  module_function :Chord
+
+end

data/lib/mtk/constants/durations.rb

@@ -0,0 +1,57 @@
+require 'rational'
+
+module MTK
+  module Constants
+
+    # Defines duration constants using abbreviations for standard rhythm values ('w' for whole note, 'h' for half note, etc).
+    #
+    # In order to avoid conflict with pitch class 'e', the constant for eighth note is 'i'
+    #
+    # These can be thought of like constants, but they
+    # use lower-case names and therefore define them as "pseudo constant" methods.
+    # The methods are available either through the module (MTK::Durations::e) or via mixin (include MTK::Durations; q)
+    #
+    # These values assume the quarter note is one beat (1.0), so they work best with 4/4 and other */4 time signatures.
+    #
+    # @note Including this module defines a bunch of single-character variables, which may shadow existing variable names.
+    #       Just be mindful of what is defined in this module when including it.
+    #
+    # @see Note
+    module Durations
+      extend Helpers::PseudoConstants
+
+      # NOTE: the yard doc macros here only fill in [$2] with the actual value when generating docs under Ruby 1.9+
+
+      # whole note
+      # @macro [attach] durations.define_constant
+      #   @attribute [r]
+      #   @return [$2] number of beats for $1
+      define_constant 'w', MTK::Duration[4]
+
+      # half note
+      define_constant 'h', MTK::Duration[2]
+
+      # quarter note
+      define_constant 'q', MTK::Duration[1]
+
+      # eight note
+      define_constant 'i', MTK::Duration[Rational(1,2)]
+
+      # sixteenth note
+      define_constant 's', MTK::Duration[Rational(1,4)]
+
+      # thirty-second note
+      define_constant 'r', MTK::Duration[Rational(1,8)]
+
+      # sixty-fourth note
+      define_constant 'x', MTK::Duration[Rational(1,16)]
+
+      # The values of all "psuedo constants" defined in this module
+      DURATIONS = [w, h, q, i, s, r, x].freeze
+
+      # The names of all "psuedo constants" defined in this module
+      DURATION_NAMES = MTK::Duration::NAMES
+
+    end
+  end
+end

data/lib/mtk/constants/intensities.rb

@@ -0,0 +1,61 @@
+module MTK
+  module Constants
+
+    # Defines intensity constants using standard dynamic symbols.
+    #
+    # These can be thought of like constants, but in order to distinguish 'f' (forte) from the {PitchClass} 'F'
+    # it was necessary to use lower-case names and therefore define them as "pseudo constant" methods.
+    # The methods are available either through the module (MTK::Intensities::f) or via mixin (include MTK::Intensities;  f)
+    #
+    # These values are intensities in the range 0.125 - 1.0 (in increments of 1/8), so they can be easily scaled (unlike MIDI velocities).
+    #
+    # It is also possible to retrieve values in increments of 1/24 by using the '+' and '-' suffix when looking
+    # up values via the {.[]} method.
+    #
+    # @note Including this module shadows Ruby's built-in p() method.
+    #   If you include this module, you can access the built-in p() method via Kernel.p()
+    #
+    # @see Note
+    module Intensities
+      extend Helpers::PseudoConstants
+
+      # NOTE: the yard doc macros here only fill in [$2] with the actual value when generating docs under Ruby 1.9+
+
+      # pianississimo
+      # @macro [attach] intensities.define_constant
+      #   @attribute [r]
+      #   @return [$2] intensity value for $1
+      define_constant 'ppp', MTK::Intensity[0.125]
+
+      # pianissimo
+      define_constant 'pp', MTK::Intensity[0.25]
+
+      # piano
+      # @note Including this module shadows Ruby's built-in p() method.
+      #   If you include this module, you can access the built-in p() method via Kernel.p()
+      define_constant 'p', MTK::Intensity[0.375]
+
+      # mezzo-piano
+      define_constant 'mp', MTK::Intensity[0.5]
+
+      # mezzo-forte
+      define_constant 'mf', MTK::Intensity[0.625]
+
+      # forte
+      define_constant 'o', MTK::Intensity[0.75]
+
+      # fortissimo
+      define_constant 'ff', MTK::Intensity[0.875]
+
+      # fortississimo
+      define_constant 'fff', MTK::Intensity[1.0]
+
+      # The values of all "psuedo constants" defined in this module
+      INTENSITIES = [ppp, pp, p, mp, mf, o, ff, fff].freeze
+
+      # The names of all "psuedo constants" defined in this module
+      INTENSITY_NAMES = MTK::Intensity::NAMES
+
+    end
+  end
+end

data/lib/mtk/constants/intervals.rb

@@ -0,0 +1,73 @@
+module MTK
+  module Constants
+
+    # Defines a constant for intervals up to an octave using diatonic naming conventions (see http://en.wikipedia.org/wiki/Interval_(music)#Main_intervals)
+    #
+    # Naming conventions
+    #   P#: perfect interval
+    #   M#: major interval
+    #   m#: minor interval
+    #   TT: tritone (AKA augmented 4th or diminished 5th)
+    #
+    # These can be thought of like constants, but in order to succinctly distinguish 'm2' (minor) from 'M2' (major),
+    # it was necessary to use lower-case names for some of the values and therefore define them as "pseudo constant" methods.
+    # The methods are available either through the module (MTK::Intervals::m2) or via mixin (include MTK::Intervals; m2)
+    module Intervals
+      extend Helpers::PseudoConstants
+
+      # NOTE: the yard doc macros here only fill in [$2] with the actual value when generating docs under Ruby 1.9+
+
+      # perfect unison
+      # @macro [attach] interval.define_constant
+      #   @attribute [r]
+      #   @return [$2] number of semitones in the interval $1
+      define_constant 'P1', MTK::Interval[0]
+
+      # minor second
+      # @macro [attach] interval.define_constant
+      #   @attribute [r]
+      #   @return [$2] number of semitones in the interval $1
+      define_constant 'm2', MTK::Interval[1]
+
+      # major second
+      define_constant 'M2', MTK::Interval[2]
+
+      # minor third
+      define_constant 'm3', MTK::Interval[3]
+
+      # major third
+      define_constant 'M3', MTK::Interval[4]
+
+      # pefect fourth
+      define_constant 'P4', MTK::Interval[5]
+
+      # tritone (AKA augmented fourth or diminished fifth)
+      define_constant 'TT', MTK::Interval[6]
+
+      # perfect fifth
+      define_constant 'P5', MTK::Interval[7]
+
+      # minor sixth
+      define_constant 'm6', MTK::Interval[8]
+
+      # major sixth
+      define_constant 'M6', MTK::Interval[9]
+
+      # minor seventh
+      define_constant 'm7', MTK::Interval[10]
+
+      # major seventh
+      define_constant 'M7', MTK::Interval[11]
+
+      # pefect octave
+      define_constant 'P8', MTK::Interval[12]
+
+      # The values of all "psuedo constants" defined in this module
+      INTERVALS = [P1, m2, M2, m3, M3, P4, TT, P5, m6, M6, m7, M7, P8].freeze
+
+      # The names of all "psuedo constants" defined in this module
+      INTERVAL_NAMES = MTK::Interval::NAMES
+
+    end
+  end
+end

data/lib/mtk/constants/pitch_classes.rb

@@ -0,0 +1,29 @@
+module MTK
+  module Constants
+
+    # Defines a constant for each {PitchClass} in the Western chromatic scale.
+    module PitchClasses
+
+      # The values of all constants defined in this module
+      PITCH_CLASSES = MTK::PitchClass::PITCH_CLASSES
+
+      # The names of all constants defined in this module
+      PITCH_CLASS_NAMES = MTK::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::PitchClasses['C']
+      # @see PitchClass.[]
+      def self.[](name)
+        begin
+          const_get name
+        rescue
+          nil
+        end
+      end
+
+    end
+  end
+end

data/lib/mtk/constants/pitches.rb

@@ -0,0 +1,52 @@
+module MTK
+  module Constants
+
+    # Defines a constants for each {Pitch} in the standard MIDI range using scientific pitch notation.
+    #
+    # See http://en.wikipedia.org/wiki/Scientific_pitch_notation
+    #
+    # @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
+
+      # The values of all constants defined in this module
+      PITCHES = []
+
+      # The names of all constants defined in this module
+      PITCH_NAMES = []
+
+      128.times do |note_number|
+        pitch = 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
+
+      PITCHES.freeze
+      PITCH_NAMES.freeze
+
+      # Lookup the value of an pitch constant by name.
+      # @example lookup value of 'C3'
+      #         MTK::Pitches['C3']
+      # @see Pitch.from_s
+      # @note Unlike {Pitch.from_s} this method will accept either '_' (underscore) or '-' (minus) and treat it like '-' (minus)
+      # @note Unlike {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