mtk 0.0.2 → 0.0.3

data/lib/mtk/{pattern → patterns}/lines.rb

@@ -1,15 +1,17 @@
 module MTK
-  module Pattern
+  module Patterns
 
     # A piecewise linear function (see {http://en.wikipedia.org/wiki/File:PiecewiseLinear.png}) defined in terms
     # of [value, steps_to_reach_value] pairs.
     #
     # The "steps_to_reach_value" for the first element is ignored and may be omitted, since it takes 0 steps to start.
-    class Lines < AbstractPattern
+    class Lines < Pattern
 
-      # Reset the sequence to the beginning
-      def rewind
-        @index = -1
+      ###################
+      protected
+
+      # (see Pattern#rewind_or_cycle)
+      def rewind_or_cycle(is_cycling=false)
         @steps = -1
         @step_count = -1
         @prev = nil
@@ -17,13 +19,8 @@ module MTK
         super
       end
 
-      ###################
-      protected
-
-      # (see AbstractPattern#advance!)
-      def advance!
-        super
-
+      # (see Pattern#advance)
+      def advance
         while @step_count >= @steps
           @step_count = 0
 
@@ -42,15 +39,12 @@ module MTK
         end
 
         @step_count += 1
-      end
 
-      # (see AbstractPattern#current)
-      def current
         if @prev and @next
           # linear interpolation
-          @prev + (@next - @prev)*@step_count/@steps
+          @current = @prev + (@next - @prev)*@step_count/@steps
         else
-          @next
+          @current = @next
         end
       end
 

data/lib/mtk/{pattern → patterns}/palindrome.rb

@@ -1,15 +1,10 @@
 module MTK
-  module Pattern
+  module Patterns
 
     # An endless enumerator that outputs an element one at a time from a list of elements,
     # looping back to the beginning when elements run out.
     class Palindrome < Cycle
 
-      def rewind
-        @direction = 1
-        super
-      end
-
       # true if the first/last element are repeated when the ends are reached, else false
       def repeat_ends?
         @repeat_ends ||= @options.fetch :repeat_ends, false
@@ -18,8 +13,14 @@ module MTK
       ##############
       protected
 
-      # (see AbstractPattern#advance!)
-      def advance!
+      # (see Pattern#rewind_or_cycle)
+      def rewind_or_cycle(is_cycling=false)
+        @direction = 1
+        super
+      end
+
+      # (see Pattern#advance)
+      def advance
         raise StopIteration if @elements.nil? or @elements.empty? # prevent infinite loops
 
         @index += @direction
@@ -34,6 +35,8 @@ module MTK
           @index = 0
           @index += 1 unless repeat_ends? or @elements.length == 1
         end
+
+        @current = @elements[@index]
       end
 
     end

data/lib/mtk/patterns/pattern.rb

@@ -0,0 +1,171 @@
+module MTK
+  module Patterns
+
+    # A pattern of elements that can be emitted one element at a time via calls to {#next}.
+    #
+    # Patterns can be reset to the beginning via {#rewind}.
+    #
+    # @abstract Subclass and override {#advance} and {#current} to implement a Pattern.
+    #
+    class Pattern
+      include MTK::Helpers::Collection
+
+      # The elements in the pattern
+      attr_reader :elements
+
+      attr_reader :options
+
+      # The number of elements emitted since the last {#rewind}
+      attr_reader :element_count
+
+      # The minimum number of elements this Pattern will emit before a StopIteration exception
+      # This overrides any conflicting max_cycles setting.
+      attr_reader :min_elements
+
+      # The maximum number of elements this Pattern will emit before a StopIteration exception
+      # A nil value means infinite elements.
+      # @note {max_cycles} may cause this Pattern to end before max_elements are emitted.
+      #       If this is undesirable then use min_elements to override max_cycles.
+      attr_reader :max_elements
+
+      # The number of cycles emitted (1 cycle == all elements emitted) since the last {#rewind}
+      attr_reader :cycle_count
+
+      # The maximum number of cycles this Pattern will emit before a StopIteration exception.
+      # A nil value means inifinite cycles.
+      attr_reader :max_cycles
+
+      # @param elements [Enumerable] the list of elements in the pattern
+      # @param options [Hash] the pattern options
+      # @option options [Fixnum] :max_elements the {#max_elements} (default is nil, which means unlimited)
+      # @option options [Fixnum] :max_cycles the {#max_cycles} (default is 1)
+      def initialize(elements, options={})
+        elements = elements.to_a if elements.is_a? Enumerable
+        @elements = elements
+        @options = options
+        @min_elements = options[:min_elements]
+        @max_elements = options[:max_elements]
+        @max_cycles = options.fetch(:max_cycles, 1)
+        rewind
+      end
+
+      # Construct a pattern from an Array.
+      # @param (see #initialize)
+      # @option (see #initialize)
+      # @see #initialize
+      def self.from_a(elements, options={})
+        new(elements, options)
+      end
+
+      # Reset the pattern to the beginning
+      def rewind
+        rewind_or_cycle
+        self
+      end
+
+      # Emit the next element in the pattern
+      # @raise StopIteration when the pattern has emitted all values, or has hit the {#max_elements} limit.
+      def next
+        raise StopIteration if empty?
+
+        if @current.is_a? Pattern
+          begin
+            return emit(@current.next)
+          rescue StopIteration
+            raise if max_elements_exceeded?
+            # else fall through and continue with normal behavior
+          end
+        end
+
+        begin
+          advance
+        rescue StopIteration
+          rewind_or_cycle(true)
+          return self.next
+        end
+
+        if @current.kind_of? Pattern
+          @current.rewind # ensure nested patterns start from the beginning each time they are encountered
+          return self.next
+        end
+
+        emit(@current)
+      end
+
+
+      def min_elements_unmet?
+        @min_elements and @element_count < @min_elements
+      end
+
+      def max_elements_exceeded?
+        @max_elements and @element_count >= @max_elements
+      end
+
+      def max_cycles_exceeded?
+        @max_cycles and @cycle_count >= @max_cycles
+      end
+
+      def empty?
+        @elements.nil? or @elements.empty?
+      end
+
+      ##################
+      protected
+
+      # Reset the pattern to the beginning
+      # @param is_cycling [Boolean] true when #next is performing a cycle back to the beginning of the Pattern. false for a normal #rewind
+      def rewind_or_cycle(is_cycling=false)
+        @current = nil
+        @index = -1
+
+        # and rewind child patterns
+        @elements.each{|element| element.rewind if element.is_a? Pattern }
+
+        if is_cycling
+          @cycle_count += 1
+          raise StopIteration if max_cycles_exceeded? and not min_elements_unmet?
+        else
+          @element_count = 0
+          @cycle_count = 0
+        end
+      end
+
+      # Update internal state (index, etc) and set @current to the next element.
+      def advance
+        @current = elements[0]
+      end
+
+
+      ##################
+      private
+
+      def emit element
+        raise StopIteration if (max_elements_exceeded? or max_cycles_exceeded?) and not min_elements_unmet?
+        @element_count += 1
+        element
+      end
+
+      def self.inherited(subclass)
+        # Define a convenience method like MTK::Patterns.Sequence()
+        # that can handle varargs or a single array argument, plus any Hash options
+        classname = subclass.name.sub /.*::/, '' # Strip off module prefixes
+        MTK::Patterns.define_singleton_method classname do |*args|
+          options  = (args[-1].is_a? Hash) ? args.pop : {}
+          args = args[0] if args.length == 1 and args[0].is_a? Array
+          subclass.new(args,options)
+        end
+
+        %w(Pitch PitchClass Intensity Duration Interval Rhythm).each do |type|
+          MTK::Patterns.define_singleton_method "#{type}#{classname}" do |*args|
+            options  = (args[-1].is_a? Hash) ? args.pop : {}
+            args = args[0] if args.length == 1 and args[0].is_a? Array
+            constructor_for_type = (type == 'Rhythm') ? 'Duration' : type
+            args = args.map{|arg| (arg.nil? or arg.is_a? Proc) ? arg : MTK.send(constructor_for_type, arg) } # coerce to the given type (or Duration for rhythm type)
+            subclass.new(args,options)
+          end
+        end
+      end
+    end
+
+  end
+end

data/lib/mtk/patterns/sequence.rb

@@ -0,0 +1,20 @@
+module MTK
+  module Patterns
+
+    # A finite list of elements, which can be enumerated one at a time.
+    class Sequence < Pattern
+
+      ###################
+      protected
+
+      # (see Pattern#advance)
+      def advance
+        @index += 1
+        raise StopIteration if @index >= @elements.length
+        @current = @elements[@index]
+      end
+
+    end
+
+  end
+end

data/lib/mtk/pitch.rb

@@ -26,8 +26,8 @@ module MTK
     #         Pitch.from_s('C4')
     # @example get the Pitch for middle C + 50 cents:
     #         Pitch.from_s('C4+50cents')
-    def self.from_s( s )
-      s = s.to_s
+    def self.from_s( name )
+      s = name.to_s
       s = s[0..0].upcase + s[1..-1].downcase # normalize name
       if s =~ /^([A-G](#|##|b|bb)?)(-?\d+)(\+(\d+(\.\d+)?)cents)?$/
         pitch_class = PitchClass.from_s($1)
@@ -35,12 +35,13 @@ module MTK
           octave = $3.to_i
           offset_in_cents = $5.to_f
           if offset_in_cents.nil? or offset_in_cents.zero?
-            self[pitch_class, octave]
+            return self[pitch_class, octave]
           else
-            new( pitch_class, octave, offset_in_cents/100.0 )
+            return new( pitch_class, octave, offset_in_cents/100.0 )
           end
         end
       end
+      raise ArgumentError.new("Invalid pitch name: #{name.inspect}")
     end
 
     class << self
@@ -91,7 +92,7 @@ module MTK
     end
 
     def inspect
-      "#{@pitch_class}#{@octave}" + (@offset.zero? ? '' : "+#{offset_in_cents}cents")
+      "#<#{self.class}:#{object_id} @value=#{@value}>"
     end
 
     def ==( other )
@@ -143,7 +144,7 @@ module MTK
         else
           Pitch.new(*anything)
         end
-      else raise "Pitch doesn't understand #{anything.class}"
+      else raise ArgumentError.new("Pitch doesn't understand #{anything.class}")
     end
   end
   module_function :Pitch

data/lib/mtk/pitch_class.rb

@@ -1,94 +1,171 @@
 module MTK
 
-  # A class of pitches under octave equivalence.
+  # A set of all pitches that are an integer number of octaves apart.
+  # A {Pitch} has the same PitchClass as the pitches one or more octaves away.
+  # @see https://en.wikipedia.org/wiki/Pitch_class
   #
-  # A {Pitch} has the same PitchClass as the {Pitches} one or more octaves away.
-
   class PitchClass
 
-    NAMES = ['C', 'Db', 'D', 'Eb', 'E', 'F', 'Gb', 'G', 'Ab', 'A', 'Bb', 'B'].freeze
-
-    VALID_NAMES_BY_VALUE = [
-        ['B#', 'C', 'Dbb'],
-        ['B##', 'C#', 'Db'],
-        ['C##', 'D', 'Ebb'],
-        ['D#', 'Eb', 'Fbb'],
-        ['D##', 'E', 'Fb'],
-        ['E#', 'F', 'Gbb'],
-        ['E##', 'F#', 'Gb'],
-        ['F##', 'G', 'Abb'],
-        ['G#', 'Ab'],
-        ['G##', 'A', 'Bbb'],
-        ['A#', 'Bb', 'Cbb'],
-        ['A##', 'B', 'Cb']
+    # The normalized names of the 12 pitch classes in the chromatic scale.
+    # The index of each {#name} is the pitch class's numeric {#value}.
+    NAMES = %w( C Db D Eb E F Gb G Ab A Bb B ).freeze
+
+    # All enharmonic names of the 12 pitch classes, including sharps, flats, double-sharps, and double-flats,
+    # organized such that each index contains the allowed names of the pitch class with a {#value} equal to that index.
+    # @see VALID_NAMES
+    VALID_NAMES_BY_VALUE =
+    [ # (valid names ), # value # normalized name
+      %w( B#  C  Dbb ), #   0   #   C
+      %w( B## C# Db  ), #   1   #   Db
+      %w( C## D  Ebb ), #   2   #   D
+      %w( D#  Eb Fbb ), #   3   #   Eb
+      %w( D## E  Fb  ), #   4   #   E
+      %w( E#  F  Gbb ), #   5   #   F
+      %w( E## F# Gb  ), #   6   #   Gb
+      %w( F## G  Abb ), #   7   #   G
+      %w( G#     Ab  ), #   8   #   Ab
+      %w( G## A  Bbb ), #   9   #   A
+      %w( A#  Bb Cbb ), #  10   #   Bb
+      %w( A## B  Cb  )  #  11   #   B
     ].freeze
 
+    # All valid enharmonic pitch class names in a flat list.
+    # @see VALID_NAMES_BY_VALUE
     VALID_NAMES = VALID_NAMES_BY_VALUE.flatten.freeze
 
+    # A mapping from valid names to the value of the pitch class with that name
+    VALUES_BY_NAME = Hash[ # a map from a list of name,value pairs
+      VALID_NAMES_BY_VALUE.map.with_index do |valid_names,value|
+        valid_names.map{|name| [name,value] }
+      end.flatten(1)
+    ].freeze
+
+
+    # The name of this pitch class.
+    # One of the {NAMES} defined by this class.
     attr_reader :name
 
-    def initialize(name, int_value)
-      @name, @int_value = name, int_value
+    # The value of this pitch class.
+    # An integer from 0..11 that indexes this pitch class in {PITCH_CLASSES} and the {#name} in {NAMES}.
+    attr_reader :value
+
+
+    private  ######
+    # Even though new is a private_class_method, YARD gets confused so we temporarily go private
+
+    def initialize(name, value)
+      @name, @value = name, value
     end
     private_class_method :new
 
     @flyweight = {}
 
-    # Lookup a PitchClass by name.
-    # @param name [String, #to_s] one of the values in {VALID_NAMES}
-    def self.[](name)
-      name = name.to_s
-      name = name[0..0].upcase + name[1..-1].downcase # normalize the name
-      VALID_NAMES_BY_VALUE.each_with_index do |names, value|
-        if names.include? name
-          return @flyweight[name] ||= new(name, value)
-        end
+    public   ######
+
+
+    # Lookup a PitchClass by name or value.
+    # @param name_or_value [String,Symbol,Numeric] one of {VALID_NAMES} or 0..12
+    # @return the PitchClass representing the argument
+    # @raise ArgumentError for arguments that cannot be converted to a PitchClass
+    def self.[] name_or_value
+      @flyweight[name_or_value] ||= case name_or_value
+        when String,Symbol then from_name(name_or_value)
+        when Numeric       then from_value(name_or_value.round)
+        else raise ArgumentError.new("PitchClass.[] doesn't understand #{name_or_value.class}")
       end
-      nil
+    end
+
+    # Lookup a PitchClass by name.
+    # @param name [String,#to_s] one of {VALID_NAMES} (case-insensitive)
+    def self.from_name(name)
+      @flyweight[name] ||= (
+        valid_name = name.to_s.capitalize
+        value = VALUES_BY_NAME[valid_name] or raise ArgumentError.new("Invalid PitchClass name: #{name}")
+        new(valid_name,value)
+      )
+    end
+
+    class << self
+      alias from_s from_name
+    end
+
+    # All 12 pitch classes in the chromatic scale.
+    # The index of each pitch class is the pitch class's numeric {#value}.
+    PITCH_CLASSES = NAMES.map{|name| from_name name }.freeze
+
+    # return the pitch class with the given integer value mod 12
+    # @param value [Integer,#to_i]
+    def self.from_value(value)
+      PITCH_CLASSES[value.to_i % 12]
     end
 
     class << self
-      alias :from_s :[]
-      alias :from_name :[]
+      alias from_i from_value
     end
 
-    def self.from_i(value)
-      name = NAMES[value.to_i % 12]
-      self[name]
+    # return the pitch class with the given float rounded to the nearest integer, mod 12
+    # @param value [Float,#to_f]
+    def self.from_f(value)
+      from_i value.to_f.round
     end
 
+    # Compare 2 pitch classes for equal values.
+    # @param other [PitchClass]
+    # @return true if this pitch class's value is equal to the other pitch class's value
     def == other
-      other.is_a? PitchClass and other.to_i == @int_value
+      other.is_a? PitchClass and other.value == @value
     end
 
+    # Compare a pitch class with another pitch class or integer value
+    # @param other [PitchClass,#to_i]
+    # @return -1, 0, or +1 depending on whether this pitch class's value is less than, equal to, or greater than the other object's integer value
+    # @see http://ruby-doc.org/core-1.9.3/Comparable.html
     def <=> other
-      @int_value <=> other.to_i
+      @value <=> other.to_i
     end
 
+    # This pitch class's normalized {#name}.
+    # @see NAMES
     def to_s
-      @name
+      @name.to_s
     end
 
+    # This pitch class's integer {#value}
     def to_i
-      @int_value
+      @value.to_i
+    end
+
+    # This pitch class's {#value} as a floating point number
+    def to_f
+      @value.to_f
     end
 
+    # Transpose this pitch class by adding it's value to the value given (mod 12)
+    # @param interval [PitchClass,Float,#to_f]
     def + interval
-      self.class.from_i(to_i + interval.to_i)
+      new_value = (value + interval.to_f).round
+      self.class.from_value new_value
     end
     alias transpose +
 
+    # Transpose this pitch class by subtracing the given value from this value (mod 12)
+    # @param interval [PitchClass,Float,#to_f]
     def - interval
-      self.class.from_i(to_i - interval.to_i)
+      new_value = (value - interval.to_f).round
+      self.class.from_value new_value
     end
 
-    def invert(center_pitch_class)
-      self + 2*(center_pitch_class.to_i - to_i)
+    # Inverts (mirrors) the pitch class around the given center
+    # @param center [PitchClass,Pitch,Float,#to_f] the value to "mirror" this pitch class around
+    def invert(center)
+      delta = (2*(center.to_f - value)).round
+      self + delta
     end
 
     # the smallest interval in semitones that needs to be added to this PitchClass to reach the given PitchClass
+    # @param pitch_class [PitchClass,#value]
     def distance_to(pitch_class)
-      delta = (pitch_class.to_i - to_i) % 12
+      delta = (pitch_class.value - value) % 12
       if delta > 6
         delta -= 12
       elsif delta == 6 and to_i >= 6
@@ -101,12 +178,13 @@ module MTK
   end
 
   # Construct a {PitchClass} from any supported type
+  # @param anything [PitchClass,String,Symbol,Numeric]
   def PitchClass(anything)
     case anything
-      when Numeric then PitchClass.from_i(anything)
+      when Numeric then PitchClass.from_f(anything)
       when String, Symbol then PitchClass.from_s(anything)
       when PitchClass then anything
-      else raise "PitchClass doesn't understand #{anything.class}"
+      else raise ArgumentError.new("PitchClass doesn't understand #{anything.class}")
     end
   end
   module_function :PitchClass