mtk 0.0.1 → 0.0.2

data/lib/mtk/pattern/abstract_pattern.rb

@@ -0,0 +1,132 @@
+module MTK
+  module Pattern
+
+    # 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 AbstractPattern
+      include Helper::Collection
+      include Enumerator
+
+      # The elements in the pattern
+      attr_reader :elements
+
+      attr_reader :options
+
+      # The type of elements in the pattern, such as :pitch, :intensity, or :duration
+      #
+      # This is often needed by {Sequencer} classes to interpret the pattern elements.
+      attr_reader :type
+
+      # The number of elements emitted since the last {#rewind}
+      attr_reader :element_count
+      
+      # The maximum number of elements this Pattern will emit before a StopIteration exception
+      attr_reader :max_elements
+
+      # @param elements [Enumerable, #to_a] the list of elements in the pattern
+      # @param options [Hash] the pattern options
+      # @option options [String] :type the pattern {#type}
+      # @option options [Fixnum] :max_elements the {#max_elements}
+      def initialize(elements, options={})
+        elements = elements.to_a if elements.respond_to? :to_a and not elements.is_a? Proc # Proc check prevents warnings in Ruby 1.8
+        @elements = elements
+        @options = options
+        @type = options[:type]
+        @max_elements = options[:max_elements]
+        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
+        @current = nil
+        @element_count = 0
+        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
+        if @current.is_a? Enumerator
+          begin
+            subpattern_next = @current.next
+            subpattern_has_next = true
+          rescue StopIteration
+            subpattern_has_next = false
+          end
+
+          return emit subpattern_next if subpattern_has_next
+          # else fall through and continue with normal behavior
+        end
+
+        begin
+          advance!
+        rescue StopIteration
+          @current = nil
+          raise
+        end
+
+        @current = current
+        if @current.is_a? Enumerator
+          @current.rewind # start over, in case we already enumerated this element and then did a rewind
+          return self.next
+        end
+
+        emit @current
+      end
+
+
+      ##################
+      protected
+
+      # Update internal state (index, etc) so that {#current} will refer to the next element.
+      # @note Override this method in a subclass to define a custom Pattern.
+      # @raise StopIteration if there are no more elements
+      def advance!
+        raise StopIteration if @elements.nil? or @elements.empty?
+      end
+
+      # The current element in the pattern, which will be returned by {#next} (after a call to {#advance!}).
+      # @note Override this method in a subclass to define a custom Pattern.
+      def current
+        @elements[0]
+      end
+
+
+      ##################
+      private
+
+      def emit element
+        @element_count += 1
+        raise StopIteration if @max_elements and @element_count > @max_elements
+        element
+      end
+    end
+
+    # Build any "TypedPattern" (like PitchCycle or DurationPalindrome) or even just Pattern
+    def method_missing(method, *args, &block)
+      # Assuming we get something like PitchCycle, split into 'Pitch' and 'Cycle'
+      camel_case_words = method.to_s.gsub(/([a-z])([A-Z])/,'\1 \2').split(' ')
+      pattern = MTK::Pattern.const_get camel_case_words.last
+      if camel_case_words.length > 1
+        type = camel_case_words.first.downcase.to_sym
+        pattern.new(args, :type => type)
+      else
+        pattern.new(args)
+      end
+    end
+    module_function :method_missing
+
+  end
+end

data/lib/mtk/pattern/choice.rb

@@ -1,18 +1,34 @@
 module MTK
   module Pattern
 
-    # An element enumerator that randomly choices from a list of elements
-    class Choice
+    # Randomly choose from a list of elements.
+    #
+    # Supports giving different weights to different choices.
+    # Default is to weight all choices equally.
+    #
+    class Choice < AbstractPattern
 
-      # The element choices
-      attr_reader :elements
-
-      def initialize(elements)
-        @elements = elements
+      # @param (see AbstractPattern#initialize)
+      # @option (see AbstractPattern#initialize)
+      # @option options [Array] :weights a list of chances that each corresponding element will be selected (normalized against the total weight)
+      # @example choose the second element twice as often as the first or third:
+      #     MTK::Pattern::Choice.new [:first,:second,:third], :weights => [1,2,1]
+      def initialize(elements, options={})
+        super
+        @weights = options.fetch :weights, Array.new(@elements.length, 1)
+        @total_weight = @weights.inject(:+).to_f
       end
 
-      def next
-        @elements[rand(@elements.length)] if @elements and not @elements.empty?
+      #####################
+      protected
+
+      # (see AbstractPattern#current)
+      def current
+        target = rand * @total_weight
+        @weights.each_with_index do |weight,index|
+          return @elements[index] if target < weight
+          target -= weight
+        end
       end
 
     end

data/lib/mtk/pattern/cycle.rb

@@ -0,0 +1,51 @@
+module MTK
+  module Pattern
+
+    # 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 Cycle < AbstractPattern
+
+      # 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
+      attr_reader :max_cycles
+
+      def initialize(elements, options={})
+        super
+        @max_cycles = options[:max_cycles]
+      end
+
+      # Reset the sequence to the beginning
+      def rewind
+        @index = -1
+        @cycle_count = 0
+        super
+      end
+
+      ###################
+      protected
+
+      # (see AbstractPattern#advance!)
+      def advance!
+        super # base advance!() implementation prevents infinite loops with empty patterns
+        @index += 1
+        if @index >= @elements.length
+          @cycle_count += 1
+          if @max_cycles and @cycle_count >= @max_cycles
+            raise StopIteration
+          end
+          @index = -1
+          advance!
+        end
+      end
+
+      # (see AbstractPattern#current)
+      def current
+        @elements[@index]
+      end
+
+    end
+
+  end
+end

data/lib/mtk/pattern/enumerator.rb

@@ -0,0 +1,26 @@
+module MTK
+  module Pattern
+
+    # The core interface for all Patterns.
+    #
+    # This module doesn't provide any useful default functionality.
+    # It only indicates that a class is compatible with MTK's pattern enumerator interface.
+    #
+    module Enumerator
+
+      # Return the next element in the enumerator
+      # @raise StopIteration when no more elements are available
+      def next
+        raise StopIteration
+      end
+
+      # Reset the enumerator to the beginning
+      # @return self
+      def rewind
+        self
+      end
+
+    end
+
+  end
+end

data/lib/mtk/pattern/function.rb

@@ -0,0 +1,46 @@
+module MTK
+  module Pattern
+
+    # An arbitrary function that dynamically generates elements.
+    #
+    class Function < AbstractPattern
+
+      attr_reader :function
+      
+      def initialize(elements, options={})
+        super
+        @function = @elements
+        # unpack from the varargs Array that may be passed in from the "convenience constructor methods" defined in MTK::Pattern                        \
+        @function = @function.first if @function.is_a? Enumerable
+      end
+      
+      # Reset the sequence to the beginning
+      def rewind
+        @prev = nil
+        @function_call_count = -1
+        super
+      end
+
+      ###################
+      protected
+
+      # (see AbstractPattern#advance!)
+      def advance!
+        raise StopIteration if @elements.nil?
+      end
+
+      # (see AbstractPattern#current)
+      def current
+        @function_call_count += 1
+        @prev = case @function.arity
+          when 0 then @function.call
+          when 1 then @function.call(@prev)
+          when 2 then @function.call(@prev, @function_call_count)
+          else @function.call(@prev, @function_call_count, @element_count)
+        end
+      end
+
+    end
+
+  end
+end

data/lib/mtk/pattern/lines.rb

@@ -0,0 +1,60 @@
+module MTK
+  module Pattern
+
+    # 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
+
+      # Reset the sequence to the beginning
+      def rewind
+        @index = -1
+        @steps = -1
+        @step_count = -1
+        @prev = nil
+        @next = nil
+        super
+      end
+
+      ###################
+      protected
+
+      # (see AbstractPattern#advance!)
+      def advance!
+        super
+
+        while @step_count >= @steps
+          @step_count = 0
+
+          @index += 1
+          raise StopIteration if @index >= @elements.length
+
+          @prev = @next
+          next_elem = @elements[@index]
+          if next_elem.is_a? Array
+            @next = next_elem.first
+            @steps = next_elem.last.to_f
+          else
+            @next = next_elem
+            @steps = 1.0
+          end
+        end
+
+        @step_count += 1
+      end
+
+      # (see AbstractPattern#current)
+      def current
+        if @prev and @next
+          # linear interpolation
+          @prev + (@next - @prev)*@step_count/@steps
+        else
+          @next
+        end
+      end
+
+    end
+
+  end
+end

data/lib/mtk/pattern/palindrome.rb

@@ -0,0 +1,42 @@
+module MTK
+  module Pattern
+
+    # 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
+      end
+
+      ##############
+      protected
+
+      # (see AbstractPattern#advance!)
+      def advance!
+        raise StopIteration if @elements.nil? or @elements.empty? # prevent infinite loops
+
+        @index += @direction
+
+        if @index >= @elements.length
+          @direction = -1
+          @index = @elements.length - 1
+          @index -= 1 unless repeat_ends? or @elements.length == 1
+
+        elsif @index < 0
+          @direction = 1
+          @index = 0
+          @index += 1 unless repeat_ends? or @elements.length == 1
+        end
+      end
+
+    end
+
+  end
+end

data/lib/mtk/pattern/sequence.rb

@@ -1,64 +1,29 @@
 module MTK
   module Pattern
 
-    # 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 Sequence
+    # A finite list of elements, which can be enumerated one at a time.
+    class Sequence < AbstractPattern
 
-      # The list of elements enumerated by this Sequence
-      attr_reader :elements
-
-      # @param elements [Array] the list of {#elements}
-      # @param default [Object] the default value returned by {#next} in place of nil
-      def initialize(elements)
-        if elements.respond_to? :elements
-          @elements = elements.elements
-        else
-          @elements = elements.to_a
-        end
-        reset
-      end
-
-      # reset the Sequence to its initial state
-      def reset
+      # Reset the sequence to the beginning
+      def rewind
         @index = -1
-        @element = nil
-        @value = nil
+        super
       end
 
-      # The value of the next element in the Sequence.
-      # The sequence goes back to the first element if there are no more elements.
-      #
-      # @return if an element is a Proc, it is called (depending on the arity of the Proc: with either no arguments,
-      #   the last value of #next, or the last value and last element) and its return value is returned.
-      # @return if an element is nil, previous value of #next is returned. If there is no previous value the @default is returned.
-      # @return otherwise the element itself is returned
-      #
-      def next
-        if @elements and not @elements.empty?
-          @index = (@index + 1) % @elements.length
-          element = @elements[@index]
-          value = value_of(element)
-          @element, @value = element, value
-        end
-        @value
-      end
-
-      ####################
+      ###################
       protected
 
-      def value_of element
-        case element
-          when Proc
-            case element.arity
-              when 0 then element.call
-              when 1 then element.call(@value)
-              else element.call(@value, @element)
-            end
-          else element
-        end
+      # (see AbstractPattern#advance!)
+      def advance!
+        super
+        @index += 1
+        raise StopIteration if @index >= @elements.length
       end
 
+      # (see AbstractPattern#current)
+      def current
+        @elements[@index]
+      end
     end
 
   end

data/lib/mtk/pitch.rb

@@ -1,7 +1,6 @@
 module MTK
 
   # A frequency represented by a {PitchClass}, an integer octave, and an offset in semitones.
-  
   class Pitch
 
     include Comparable
@@ -15,28 +14,49 @@ module MTK
 
     @flyweight = {}
 
+    # Return a pitch with no offset, only constructing a new instance when not already in the flyweight cache
     def self.[](pitch_class, octave)
+      pitch_class = MTK.PitchClass(pitch_class)
       @flyweight[[pitch_class,octave]] ||= new(pitch_class, octave)
     end
-    
+
+    # Lookup a pitch by name, which consists of any {PitchClass::VALID_NAMES} and an octave number.
+    # The name may also be optionally suffixed by +/-###cents (where ### is any number).
+    # @example get the Pitch for middle C :
+    #         Pitch.from_s('C4')
+    # @example get the Pitch for middle C + 50 cents:
+    #         Pitch.from_s('C4+50cents')
     def self.from_s( s )
-      # TODO: update to handle offset
+      s = s.to_s
       s = s[0..0].upcase + s[1..-1].downcase # normalize name
-      if s =~ /^([A-G](#|##|b|bb)?)(-?\d+)$/
+      if s =~ /^([A-G](#|##|b|bb)?)(-?\d+)(\+(\d+(\.\d+)?)cents)?$/
         pitch_class = PitchClass.from_s($1)
         if pitch_class
           octave = $3.to_i
-          new( pitch_class, octave )
+          offset_in_cents = $5.to_f
+          if offset_in_cents.nil? or offset_in_cents.zero?
+            self[pitch_class, octave]
+          else
+            new( pitch_class, octave, offset_in_cents/100.0 )
+          end
         end
       end
     end
+
+    class << self
+      alias :from_name :from_s
+    end
     
     # Convert a Numeric semitones value into a Pitch
     def self.from_f( f )
       i, offset = f.floor, f%1  # split into int and fractional part
       pitch_class = PitchClass.from_i(i)
       octave = i/12 - 1
-      new( pitch_class, octave, offset )      
+      if offset == 0
+        self[pitch_class, octave]
+      else
+        new( pitch_class, octave, offset )
+      end
     end
 
     def self.from_hash(hash)
@@ -86,6 +106,7 @@ module MTK
     def + interval_in_semitones
      self.class.from_f( @value + interval_in_semitones.to_f )
     end
+    alias transpose +
 
     def - interval_in_semitones
       self.class.from_f( @value - interval_in_semitones.to_f )
@@ -109,4 +130,22 @@ module MTK
 
   end
 
+  # Construct a {Pitch} from any supported type
+  def Pitch(*anything)
+    anything = anything.first if anything.length == 1
+    case anything
+      when Numeric then Pitch.from_f(anything)
+      when String, Symbol then Pitch.from_s(anything)
+      when Pitch then anything
+      when Array
+        if anything.length == 2
+          Pitch[*anything]
+        else
+          Pitch.new(*anything)
+        end
+      else raise "Pitch doesn't understand #{anything.class}"
+    end
+  end
+  module_function :Pitch
+
 end

data/lib/mtk/pitch_class.rb

@@ -6,9 +6,9 @@ module MTK
 
   class PitchClass
 
-    NAMES = ['C', 'Db', 'D', 'Eb', 'E', 'F', 'Gb', 'G', 'Ab', 'A', 'Bb', 'B']
+    NAMES = ['C', 'Db', 'D', 'Eb', 'E', 'F', 'Gb', 'G', 'Ab', 'A', 'Bb', 'B'].freeze
 
-    VALID_NAMES = [
+    VALID_NAMES_BY_VALUE = [
         ['B#', 'C', 'Dbb'],
         ['B##', 'C#', 'Db'],
         ['C##', 'D', 'Ebb'],
@@ -21,55 +21,40 @@ module MTK
         ['G##', 'A', 'Bbb'],
         ['A#', 'Bb', 'Cbb'],
         ['A##', 'B', 'Cb']
-    ]
+    ].freeze
 
-    attr_reader :name
+    VALID_NAMES = VALID_NAMES_BY_VALUE.flatten.freeze
 
-    ##########################################        
-    private
+    attr_reader :name
 
     def initialize(name, int_value)
       @name, @int_value = name, int_value
     end
-
     private_class_method :new
 
     @flyweight = {}
 
-    def self.get(name, int_value)
-      @flyweight[name] ||= new(name, int_value)
-    end
-
-    private_class_method :get
-
-    ##########################################    
-    public
-
-    def self.from_s(s)
-      s = s.to_s
-      s = s[0..0].upcase + s[1..-1].downcase # normalize the name      
-      VALID_NAMES.each_with_index do |names, index|
-        return get(s, index) if names.include? s
+    # 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
       end
       nil
     end
 
     class << self
-      alias from_name from_s # alias self.from_name to self.from_s
+      alias :from_s :[]
+      alias :from_name :[]
     end
 
     def self.from_i(value)
-      value = value.to_i % 12
-      name = NAMES[value]
-      get(name, value)
-    end
-
-    def self.[](name_or_value)
-      if name_or_value.kind_of? Numeric
-        from_i(name_or_value)
-      else
-        from_s(name_or_value)
-      end
+      name = NAMES[value.to_i % 12]
+      self[name]
     end
 
     def == other
@@ -88,14 +73,19 @@ module MTK
       @int_value
     end
 
-    def +(interval)
+    def + interval
       self.class.from_i(to_i + interval.to_i)
     end
+    alias transpose +
 
-    def -(interval)
+    def - interval
       self.class.from_i(to_i - interval.to_i)
     end
 
+    def invert(center_pitch_class)
+      self + 2*(center_pitch_class.to_i - to_i)
+    end
+
     # the smallest interval in semitones that needs to be added to this PitchClass to reach the given PitchClass
     def distance_to(pitch_class)
       delta = (pitch_class.to_i - to_i) % 12
@@ -110,4 +100,15 @@ module MTK
 
   end
 
+  # Construct a {PitchClass} from any supported type
+  def PitchClass(anything)
+    case anything
+      when Numeric then PitchClass.from_i(anything)
+      when String, Symbol then PitchClass.from_s(anything)
+      when PitchClass then anything
+      else raise "PitchClass doesn't understand #{anything.class}"
+    end
+  end
+  module_function :PitchClass
+
 end