mtk 0.0.1 → 0.0.2

data/lib/mtk/pitch_class_set.rb

@@ -1,35 +1,39 @@
 module MTK
 
-  # A Set of PitchClasses, for 12-tone set-theory pitch analysis and manipulations
+  # An ordered Set of PitchClasses, for 12-tone set-theory pitch analysis and manipulations
   #
   class PitchClassSet
 
-    include Mappable
+    include Helper::Collection
+    include Transform::Mappable
+    include Transform::Transposable
+    include Transform::Invertible
+    include Transform::SetTheoryOperations
 
     attr_reader :pitch_classes
-    
-    def initialize(pitch_classes)
-      @pitch_classes = pitch_classes.to_a.uniq.sort.freeze
+
+    def self.random_row
+      new(PitchClasses::PITCH_CLASSES.shuffle)
     end
 
-    def self.from_a enumerable
-      new enumerable
+    def self.all
+      @all ||= new(PitchClasses::PITCH_CLASSES)
     end
 
-    def to_a
-      Array.new(@pitch_classes)
+    def initialize(pitch_classes)
+      @pitch_classes = pitch_classes.to_a.uniq.freeze
     end
 
-    def each &block
-      @pitch_classes.each &block
+    def elements
+      @pitch_classes
     end
 
-    def size
-      @pitch_classes.size
+    def self.from_a enumerable
+      new enumerable
     end
 
     def normal_order
-      ordering = Array.new(@pitch_classes)
+      ordering = Array.new(@pitch_classes.sort)
       min_span, start_index_for_normal_order = nil, nil
 
       # check every rotation for the minimal span:
@@ -86,6 +90,22 @@ module MTK
       end
     end
 
+    # Compare for equality, ignoring order
+    # @param other [#pitch_classes, #to_a, #sort, Array]
+    def =~ other
+      if other.is_a? Array and other.frozen?
+        @pitch_classes.sort == other
+      elsif other.respond_to? :pitch_classes
+        @pitch_classes.sort == other.pitch_classes.sort
+      elsif other.respond_to? :to_a
+        @pitch_classes.sort == other.to_a.sort
+      elsif other.respond_to? :sort
+        @pitch_classes.sort == other.sort
+      else
+        @pitch_classes.sort == other
+      end
+    end
+
     def to_s
       @pitch_classes.join(' ')
     end
@@ -103,4 +123,16 @@ module MTK
     end
 
   end
+
+  # Construct a {PitchClassSet} from any supported type
+  def PitchClassSet(*anything)
+    anything = anything.first if anything.size == 1
+    case anything
+      when Array then PitchClassSet.new(anything.map{|elem| PitchClass(elem) })
+      when PitchClassSet then anything
+      else PitchClassSet.new([PitchClass(anything)])
+    end
+  end
+  module_function :PitchClassSet
+
 end

data/lib/mtk/pitch_set.rb

@@ -4,7 +4,10 @@ module MTK
   #
   class PitchSet
 
-    include Mappable
+    include Helper::Collection
+    include Transform::Mappable
+    include Transform::Transposable
+    include Transform::Invertible
 
     attr_reader :pitches
 
@@ -12,16 +15,12 @@ module MTK
       @pitches = pitches.to_a.uniq.sort.freeze
     end
 
-    def self.from_a enumerable
-      new enumerable
+    def elements
+      @pitches
     end
 
-    def to_a
-      Array.new(@pitches)
-    end
-
-    def each &block
-      @pitches.each &block
+    def self.from_a enumerable
+      new enumerable
     end
 
     def to_pitch_class_set
@@ -32,18 +31,7 @@ module MTK
       @pitch_classes ||= @pitches.map{|p| p.pitch_class }.uniq
     end
 
-    def + semitones
-      each_pitch_apply :+, semitones
-    end
-
-    def - semitones
-      each_pitch_apply :-, semitones
-    end
-
-    def invert(center_pitch=@pitches.first)
-      each_pitch_apply :invert, center_pitch
-    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)
@@ -61,12 +49,8 @@ module MTK
       self.class.new pitch_set
     end
 
-    def include? pitch
-      @pitches.include? pitch
-    end
-
     def nearest(pitch_class)
-      self + @pitches.first.pitch_class.distance_to(pitch_class)
+      self.transpose @pitches.first.pitch_class.distance_to(pitch_class)
     end
 
     # @param other [#pitches, #to_a, Array]
@@ -84,12 +68,17 @@ module MTK
       @pitches.inspect
     end
 
-    #######################################
-    protected
+  end
 
-    def each_pitch_apply(method_name, *args, &block)
-      self.class.new @pitches.map{|pitch| pitch.send(method_name, *args, &block) }
+  # Construct a {PitchSet} from any supported type
+  def PitchSet(*anything)
+    anything = anything.first if anything.size == 1
+    case anything
+      when Array then PitchSet.new(anything.map{|elem| Pitch(elem) })
+      when PitchSet then anything
+      else PitchSet.new([Pitch(anything)])
     end
-
   end
+  module_function :PitchSet
+
 end

data/lib/mtk/sequencer/abstract_sequencer.rb

@@ -0,0 +1,85 @@
+module MTK
+  module Sequencer
+
+    # A Sequencer produces {Timeline}s from a collection of {Pattern}s.
+    #
+    # @abstract Subclass and override {#advance} to implement a Sequencer.
+    #
+    class AbstractSequencer
+
+      # The maximum number of [time,event_list] entries that will be generated for the {Timeline}.
+      # nil means no maximum (be careful of infinite loops!)
+      attr_accessor :max_steps
+
+      # The maximum time (key) that will be generated for the {Timeline}.
+      # nil means no maximum (be careful of infinite loops!)
+      attr_accessor :max_time
+
+      # Used by {#to_timeline} to builds event lists from the results of #{Pattern::Enumerator#next} for the {Pattern}s in this Sequencer.
+      attr_reader :event_builder
+
+      # The current time offset for the sequencer. Used for the {Timeline} times.
+      attr_reader :time
+
+      # The current sequencer step index (the number of times-1 that {#next} has been called), or -1 if the sequencer has not yet started.
+      attr_reader :step
+
+      def initialize(patterns, options={})
+        @patterns = patterns
+        @max_steps = options[:max_steps]
+        @max_time = options[:max_time]
+
+        event_builder_class = options.fetch :event_builder, Helper::EventBuilder
+        @event_builder = event_builder_class.new(patterns, options)
+        rewind
+      end
+
+
+      # Produce a {Timeline} from the {Pattern}s in this Sequencer.
+      def to_timeline
+        rewind
+        timeline = Timeline.new
+        loop do
+          events = self.next
+          timeline[@time] = events if events
+        end
+        timeline
+      end
+
+
+      # Advanced the step index and time, and return the next list of events built from the sequencer patterns.
+      # @note this is called automatically by {#to_timeline},
+      #    so you can ignore this method unless you want to hack on sequencers at a lower level.
+      def next
+        if @step >= 0
+          advance!
+          raise StopIteration if @max_time and @time > @max_time
+        end
+        @step += 1
+        raise StopIteration if @max_steps and @step >= @max_steps
+        @event_builder.next
+      end
+
+
+      # Reset the sequencer and all its patterns.
+      # @note this is called automatically at the beginning of {#to_timeline},
+      #    so you can ignore this method unless you want to hack on sequencers at a lower level.
+      def rewind
+        @time = 0
+        @step = -1
+        event_builder.rewind
+      end
+
+
+      ########################
+      protected
+
+      # Advance @time to the next time for the {Timeline} being produced by {#to_timeline}
+      def advance!
+        @time += 1 # default behavior simply advances one beat at a time
+      end
+
+    end
+
+  end
+end

data/lib/mtk/sequencer/rhythmic_sequencer.rb

@@ -0,0 +1,29 @@
+module MTK
+  module Sequencer
+
+    # A Sequencer which uses a :rhythm type {Pattern} to determine the delta times between entries in the {Timeline}.
+    class RhythmicSequencer < AbstractSequencer
+
+      def initialize(patterns, options={})
+        patterns = patterns.clone
+        patterns.each_with_index do |pattern, index|
+          if pattern.type == :rhythm
+            @rhythm = pattern
+            patterns.delete_at index # so we don't enumerate the rhythm values in EventBuilder
+          end
+        end
+        super(patterns, options)
+      end
+
+     ########################
+      protected
+
+      # (see AbstractSequencer#advance!)
+      def advance!
+        @time += @rhythm.next
+      end
+
+    end
+
+  end
+end

data/lib/mtk/sequencer/step_sequencer.rb

@@ -0,0 +1,26 @@
+module MTK
+  module Sequencer
+
+    # A Sequencer which has a constant {#step_size} time between {Timeline} entries.
+    class StepSequencer < AbstractSequencer
+
+      # The time between entries in the {Timeline}.
+      attr_accessor :step_size
+
+      def initialize(patterns, options={})
+        super
+        @step_size = options.fetch :step_size, 1
+      end
+
+     ########################
+      protected
+
+      # (see AbstractSequencer#advance!)
+      def advance!
+        @time += @step_size
+      end
+
+    end
+
+  end
+end

data/lib/mtk/timeline.rb

@@ -1,12 +1,14 @@
 module MTK
 
+  # A collection of timed events. The core data structure used to interface with input and output.
+  #
   # Maps sorted times to lists of events.
   #
-  # Enumerable as |time,event| pairs.
+  # Enumerable as [time,event_list] pairs.
   #
   class Timeline
 
-    include Mappable
+    include Transform::Mappable
 
     def initialize()
       @timeline = {}
@@ -90,37 +92,32 @@ module MTK
     end
 
     def each
-      times.each do |time|
-        events = @timeline[time]
-        events.each do |event|
-          yield time,event
-        end
-      end
-    end
-
-    def each_time
-      times.each do |time|
-        events = @timeline[time]
-        yield time,events
+      # this is similar to @timeline.each, but by iterating over #times, we yield the events in chronological order
+      for time in times
+        yield time,@timeline[time]
       end
     end
 
     def map! &block
+      # we use the enumerable_map that aliased by the Mappable module,
+      # because Mappable#map will create an extra timeline instance, which is unnecessary in this case
       mapped = enumerable_map &block
       clear
       merge mapped
     end
 
+    # Map every individual event, without regard for the time at which is occurs
     def map_events
       mapped_timeline = Timeline.new
-      each_time do |time,events|
+      for time,events in self
         mapped_timeline[time] = events.map{|event| yield event }
       end
       mapped_timeline
     end
 
+    # Map every individual event in place, without regard for the time at which is occurs
     def map_events!
-      each_time do |time,events|
+      for time,events in self
         self[time] = events.map{|event| yield event }
       end
     end
@@ -135,18 +132,68 @@ module MTK
     
     def flatten
       flattened = Timeline.new
-      for time,event in self
-        if event.is_a? Timeline
-          for subtime, subevent in event.flatten
-            flattened.add(time+subtime, subevent)
+      for time,events in self
+        for event in events
+          if event.is_a? Timeline
+            for subtime,subevent in event.flatten
+              flattened.add(time+subtime, subevent)
+            end
+          else
+            flattened.add(time,event)
           end
-        else
-          flattened.add(time,event)
         end
       end
       flattened
     end
 
+    # @return a new Timeline where all times have been quantized to multiples of the given interval
+    # @example timeline.quantize(0.5)  # quantize to eight notes (assuming the beat is a quarter note)
+    # @see quantize!
+    def quantize interval
+      map{|time,events| [self.class.quantize_time(time,interval), events] }
+    end
+
+    def quantize! interval
+      map!{|time,events| [self.class.quantize_time(time,interval), events] }
+    end
+
+    # shifts all times by the given amount
+    # @see #shift!
+    # @see #shift_to
+    def shift time_delta
+      map{|time,events| [time+time_delta, events] }
+    end
+
+    # shifts all times in place by the given amount
+    # @see #shift
+    # @see #shift_to!
+    def shift! time_delta
+      map!{|time,events| [time+time_delta, events] }
+    end
+
+    # shifts the times so that the start of the timeline is at the given time
+    # @see #shift_to!
+    # @see #shift
+    def shift_to absolute_time
+      start = times.first
+      if start
+        shift absolute_time - start
+      else
+        clone
+      end
+    end
+
+    # shifts the times in place so that the start of the timeline is at the given time
+    # @see #shift_to
+    # @see #shift!
+    def shift_to! absolute_time
+      start = times.first
+      if start
+        shift! absolute_time - start
+      end
+      self
+    end
+
     def to_s
       times.map{|t| "#{t} => #{@timeline[t].join ', '}" }.join "\n"
     end
@@ -155,6 +202,12 @@ module MTK
       @timeline.inspect
     end
 
+    def self.quantize_time time, interval
+      upper = interval * (time.to_f/interval).ceil
+      lower = upper - interval
+      (time - lower) < (upper - time) ? lower : upper
+    end
+
   end
 
 end

data/lib/mtk/transform/invertible.rb

@@ -0,0 +1,15 @@
+module MTK::Transform
+
+  # {Mappable} class whose elements can handle the :invert message
+  # @note Classes including this module should include either MTK::Collection or provide a #first method
+  module Invertible
+
+    # Invert all elements around the given inversion point
+    # @param inversion_point [Numeric] the value around which all elements will be inverted (defaults to the first element in the collection)
+    def invert(inversion_point=first)
+      map{|elem| elem.invert(inversion_point) }
+    end
+
+  end
+
+end

data/lib/mtk/{util → transform}/mappable.rb

@@ -1,14 +1,18 @@
-module MTK
+module MTK::Transform
 
   # Similar to Enumerable, but relies on the including Class's from_a method to
-  # provide an implementation of #map which returns an object of the same type
+  # provide an implementation of #map which returns an object of the same type.
   module Mappable
     include Enumerable
 
+    # the original Enumerable#map implementation, which returns an Array
     alias enumerable_map map
+
+    # the overriden #map implementation, which returns an object of the same type
     def map &block
       self.class.from_a(enumerable_map &block)
     end
 
   end
+
 end

data/lib/mtk/transform/set_theory_operations.rb

@@ -0,0 +1,34 @@
+module MTK::Transform
+
+  # {Helper::Collection} that supports set theory operations
+  module SetTheoryOperations
+
+    # the collection of elements present in both sets
+    def intersection(other)
+      self.class.from_a(to_a & other.to_a)
+    end
+
+    # the collection of all elements present in either set
+    def union(other)
+      self.class.from_a(to_a | other.to_a)
+    end
+
+    # the collection of elements from this set with any elements from the other set removed
+    def difference(other)
+      self.class.from_a(to_a - other.to_a)
+    end
+
+    # the collection of elements that are members of exactly one of the sets
+    def symmetric_difference(other)
+      union(other).difference( intersection(other) )
+    end
+
+    # the collection of elements that are not members of this set
+    # @note this method requires that the including class define the class method .all(), which returns the collection of all possible elements
+    def complement
+      self.class.all.difference(self)
+    end
+
+  end
+
+end

data/lib/mtk/transform/transposable.rb

@@ -0,0 +1,14 @@
+module MTK::Transform
+
+  # {Mappable} class whose elements can handle the :transpose message
+  module Transposable
+
+    # Transpose all elements upward by the given interval
+    # @param interval_in_semitones [Numeric] an interval in semitones
+    def transpose interval_in_semitones
+      map{|elem| elem + interval_in_semitones }
+    end
+
+  end
+
+end

data/lib/mtk.rb

@@ -1,4 +1,41 @@
-require 'mtk/util/mappable'
+##############################################
+# Description of modules for documentation:
+
+# The top level module for this library
+module MTK
+
+  # Internal helper classes used to avoid duplicating code in this library.
+  module Helper
+  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
+  end
+
+  # Classes that assemble {Pattern}s into {Timeline}s.
+  module Sequencer
+  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.
+  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'
@@ -6,31 +43,28 @@ require 'mtk/pitch_set'
 
 require 'mtk/event'
 require 'mtk/note'
-require 'mtk/chord'
 require 'mtk/timeline'
 
-require 'mtk/constants/pseudo_constants'
-require 'mtk/constants/pitch_classes'
-require 'mtk/constants/pitches'
-require 'mtk/constants/intervals'
-require 'mtk/constants/dynamics'
+require 'mtk/_constants/pitch_classes'
+require 'mtk/_constants/pitches'
+require 'mtk/_constants/intervals'
+require 'mtk/_constants/intensities'
+require 'mtk/_constants/durations'
 
-require 'mtk/numeric_extensions'
+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/helper/event_builder'
+require 'mtk/sequencer/abstract_sequencer'
+require 'mtk/sequencer/step_sequencer'
+require 'mtk/sequencer/rhythmic_sequencer'
 
-##############################################
-# Description of modules for documentation:
+require 'mtk/_numeric_extensions'
 
-# The top level module for this library
-module MTK
-
-  # Classes for MIDI input and output
-  module MIDI
-  end
-
-  # Classes that enumerate elements
-  module Pattern
-  end
-
-end