mtk 0.0.3.2 → 0.0.3.3

data/lib/mtk/core/duration.rb

@@ -0,0 +1,213 @@
+module MTK
+  module Core
+
+    # A measure of time in musical beats.
+    # May be negative to indicate a rest, which uses the absolute value for the effective duration.
+    class Duration
+
+      include Comparable
+
+      # The names of the base durations. See {MTK::Lang::Durations} for more info.
+      NAMES = %w[w h q i s r x].freeze
+
+      VALUES_BY_NAME = {
+        'w' => 4,
+        'h' => 2,
+        'q' => 1,
+        'i' => Rational(1,2),
+        's' => Rational(1,4),
+        'r' => Rational(1,8),
+        'x' => Rational(1,16)
+      }
+
+      @flyweight = {}
+
+      # The number of beats, typically represented as a Rational
+      attr_reader :value
+
+      def initialize( length_in_beats )
+        @value = length_in_beats
+      end
+
+      # Return a duration, only constructing a new instance when not already in the flyweight cache
+      def self.[](length_in_beats)
+        if length_in_beats.is_a? Fixnum
+          value = length_in_beats
+        else
+          value = Rational(length_in_beats)
+        end
+        @flyweight[value] ||= new(value)
+      end
+
+      class << self
+        alias :from_f :[]
+        alias :from_i :[]
+      end
+
+      # Lookup a duration by name.
+      # This method supports appending any combination of '.' and 't' for more fine-grained values.
+      # each '.' multiplies by 3/2, and each 't' multiplies by 2/3.
+      # You may use the prefix '-' to negate the duration (which turns it into a rest of the same length).
+      # You may also prefix (after the '-' if present) the base duration name with an integer, float, or rational number
+      # to multiply the base duration value. Rationals are in the form "#!{numerator_integer}/#!{denominator_integer}".
+      # @example lookup value of 'q.', which is 1.5 times a quarter note (1.5 beats):
+      #          MTK::Core::Duration.from_s('q.')
+      # @example lookup the value of 3/4w, which three-quarters of a whole note (3 beats):
+      #          MTK::Core::Duration.from_s('3/4w')
+      def self.from_s(s)
+        if s =~ /^(-)?(\d+([\.\/]\d+)?)?([whqisrx])((\.|t)*)$/i
+          name = $4.downcase
+          modifier = $5.downcase
+          modifier << $1 if $1 # negation
+          multiplier = $2
+        else
+          raise ArgumentError.new("Invalid Duration string '#{s}'")
+        end
+
+        value = VALUES_BY_NAME[name]
+        modifier.each_char do |mod|
+          case mod
+            when '-' then value *= -1
+            when '.' then value *= Rational(3,2)
+            when 't' then value *= Rational(2,3)
+          end
+        end
+
+        if multiplier
+          case multiplier
+            when /\./
+              value *= multiplier.to_f
+            when /\//
+              numerator, denominator = multiplier.split('/')
+              value *= Rational(numerator.to_i, denominator.to_i)
+            else
+              value *= multiplier.to_i
+          end
+        end
+
+        self[value]
+      end
+
+      class << self
+        alias :from_name :from_s
+      end
+
+      # The magnitude (absolute value) of the duration.
+      # This is the actual duration for rests.
+      # @see #rest?
+      def length
+        @value < 0 ? -@value : @value
+      end
+
+      # Durations with negative values are rests.
+      # @see #length
+      # @see #-@
+      def rest?
+        @value < 0
+      end
+
+      # The number of beats as a floating point number
+      def to_f
+        @value.to_f
+      end
+
+      # The numerical value for the nearest whole number of beats
+      def to_i
+        @value.round
+      end
+
+      def to_s
+        value = @value.to_s
+        value = sprintf '%.2f', @value if value.length > 6 # threshold is 6 for no particular reason...
+        "#{value} #{@value.abs > 1 || @value==0 ? 'beats' : 'beat'}"
+      end
+
+      def inspect
+        "#<#{self.class}:#{object_id} @value=#{@value}>"
+      end
+
+      def ==( other )
+        if other.is_a? MTK::Core::Duration
+          other.value == @value
+        else
+          other == @value
+        end
+      end
+
+      def <=> other
+        if other.respond_to? :value
+          @value <=> other.value
+        else
+          @value <=> other
+        end
+      end
+
+      # Add this duration to another.
+      # @return a new Duration that has a value of the sum of the arguments.
+      def + duration
+        if duration.is_a? MTK::Core::Duration
+          MTK::Core::Duration[@value + duration.value]
+        else
+          MTK::Core::Duration[@value + duration]
+        end
+      end
+
+      # Subtract another duration from this one.
+      # @return a new Duration that has a value of the difference of the arguments.
+      def - duration
+        if duration.is_a? MTK::Core::Duration
+          MTK::Core::Duration[@value - duration.value]
+        else
+          MTK::Core::Duration[@value - duration]
+        end
+      end
+
+      # Multiply this duration with another.
+      # @return a new Duration that has a value of the product of the arguments.
+      def * duration
+        if duration.is_a? MTK::Core::Duration
+          MTK::Core::Duration[@value * duration.value]
+        else
+          MTK::Core::Duration[@value * duration]
+        end
+      end
+
+      # Divide this duration with another.
+      # @return a new Duration that has a value of the division of the arguments.
+      def / duration
+        if duration.is_a? MTK::Core::Duration
+          MTK::Core::Duration[to_f / duration.value]
+        else
+          MTK::Core::Duration[to_f / duration]
+        end
+      end
+
+      # Negate the duration value.
+      # Turns normal durations into rests and vice versa.
+      # @return a new Duration that has a negated value.
+      # @see #rest?
+      def -@
+        MTK::Core::Duration[@value * -1]
+      end
+
+      # Allow basic math operations with Numeric objects.
+      def coerce(other)
+        return MTK::Core::Duration[other], self
+      end
+
+    end
+  end
+
+  # Construct a {Duration} from any supported type
+  def Duration(*anything)
+    anything = anything.first if anything.length == 1
+    case anything
+      when Numeric then MTK::Core::Duration[anything]
+      when String, Symbol then MTK::Core::Duration.from_s(anything)
+      when Duration then anything
+      else raise "Duration doesn't understand #{anything.class}"
+    end
+  end
+  module_function :Duration
+
+end

data/lib/mtk/core/intensity.rb

@@ -0,0 +1,158 @@
+module MTK
+  module Core
+
+    # A measure of intensity, using an underlying value in the range 0.0-1.0
+    class Intensity
+
+      include Comparable
+
+      # The names of the base intensities. See {}MTK::Lang::Intensities} for more info.
+      NAMES = %w[ppp pp p mp mf o ff fff].freeze
+
+      VALUES_BY_NAME = {
+        'ppp' => 0.125,
+        'pp' => 0.25,
+        'p' => 0.375,
+        'mp' => 0.5,
+        'mf' => 0.625,
+        'o' => 0.75,
+        'ff' => 0.875,
+        'fff' => 1.0
+      }
+
+      @flyweight = {}
+
+      # The number of beats, typically representation as a Rational
+      attr_reader :value
+
+      def initialize(value)
+        @value = value
+      end
+
+      # Return an Intensity, only constructing a new instance when not already in the flyweight cache
+      def self.[](value)
+        value = value.to_f
+        @flyweight[value] ||= new(value)
+      end
+
+      class << self
+        alias :from_f :[]
+        alias :from_i :[]
+      end
+
+      # Lookup an intensity by name.
+      # This method supports appending '-' or '+' for more fine-grained values.
+      def self.from_s(s)
+        return self[1.0] if s == 'fff+' # special case because "fff" is already the maximum
+
+        name = nil
+        modifier = nil
+        if s =~ /^(\w+)([+-])?$/
+          name = $1
+          modifier = $2
+        end
+
+        value = VALUES_BY_NAME[name]
+        raise ArgumentError.new("Invalid Intensity string '#{s}'") unless value
+
+        value += 1.0/24 if modifier == '+'
+        value -= 1.0/24 if modifier == '-'
+
+        self[value]
+      end
+
+      class << self
+        alias :from_name :from_s
+      end
+
+      # The number of beats as a floating point number
+      def to_f
+        @value.to_f
+      end
+
+      # The numerical value for the nearest whole number of beats
+      def to_i
+        @value.round
+      end
+
+      def to_midi
+        (to_f * 127).round
+      end
+
+      def to_percent
+        (@value * 100).round
+      end
+
+      def to_s
+        "#{to_percent}% intensity"
+      end
+
+      def inspect
+        "#<#{self.class}:#{object_id} @value=#{@value}>"
+      end
+
+      def ==( other )
+        other.is_a? MTK::Core::Intensity and other.value == @value
+      end
+
+      def <=> other
+        if other.respond_to? :value
+          @value <=> other.value
+        else
+          @value <=> other
+        end
+
+      end
+
+      def + intensity
+        if intensity.is_a? MTK::Core::Intensity
+          MTK::Core::Intensity[@value + intensity.value]
+        else
+          MTK::Core::Intensity[@value + intensity]
+        end
+      end
+
+      def -intensity
+        if intensity.is_a? MTK::Core::Intensity
+          MTK::Core::Intensity[@value - intensity.value]
+        else
+          MTK::Core::Intensity[@value - intensity]
+        end
+      end
+
+      def * intensity
+        if intensity.is_a? MTK::Core::Intensity
+          MTK::Core::Intensity[@value * intensity.value]
+        else
+          MTK::Core::Intensity[@value * intensity]
+        end
+      end
+
+      def / intensity
+        if intensity.is_a? MTK::Core::Intensity
+          MTK::Core::Intensity[to_f / intensity.value]
+        else
+          MTK::Core::Intensity[to_f / intensity]
+        end
+      end
+
+      def coerce(other)
+        return MTK::Core::Intensity[other], self
+      end
+
+    end
+  end
+
+  # Construct a {Duration} from any supported type
+  def Intensity(*anything)
+    anything = anything.first if anything.length == 1
+    case anything
+      when Numeric then MTK::Core::Intensity[anything]
+      when String, Symbol then MTK::Core::Intensity.from_s(anything)
+      when Intensity then anything
+      else raise "Intensity doesn't understand #{anything.class}"
+    end
+  end
+  module_function :Intensity
+
+end

data/lib/mtk/core/interval.rb

@@ -0,0 +1,157 @@
+module MTK
+  module Core
+
+    # A measure of intensity, using an underlying value in the range 0.0-1.0
+    class Interval
+
+      include Comparable
+
+      # The preferred names of all pre-defined intervals
+      NAMES = %w[P1 m2 M2 m3 M3 P4 TT P5 m6 M6 m7 M7 P8].freeze
+
+      # All valid names of pre-defined intervals, indexed by their value.
+      NAMES_BY_VALUE =
+        [ #   names      # value # description
+          %w( P1 p1 ),   #   0   #  unison
+          %w( m2 min2 ), #   1   #  minor second
+          %w( M2 maj2 ), #   2   #  major second
+          %w( m3 min3 ), #   3   #  minor third
+          %w( M3 maj3 ), #   4   #  major third
+          %w( P4 p4 ),   #   5   #  perfect fourth
+          %w( TT tt ),   #   6   #  tritone (AKA augmented fourth, diminished fifth)
+          %w( P5 p5 ),   #   7   #  perfect fifth
+          %w( m6 min6 ), #   8   #  minor sixth
+          %w( M6 maj6 ), #   9   #  major sixth
+          %w( m7 min7 ), #  10   #  minor seventh
+          %w( M7 maj7 ),  #  11   #  major seventh
+          %w( P8 p8 )    #  12   #  octave
+        ].freeze
+
+      # A mapping from intervals names to their value
+      VALUES_BY_NAME = Hash[ # a map from a list of name,value pairs
+          NAMES_BY_VALUE.map.with_index do |names,value|
+            names.map{|name| [name,value] }
+          end.flatten(1)
+      ].freeze
+
+      # All valid interval names
+      ALL_NAMES = NAMES_BY_VALUE.flatten.freeze
+
+
+      @flyweight = {}
+
+      # The number of semitones represented by this interval
+      attr_reader :value
+
+      def initialize(value)
+        @value = value
+      end
+
+      # Return an {Interval}, only constructing a new instance when not already in the flyweight cache
+      def self.[](value)
+        value = value.to_f unless value.is_a? Fixnum
+        @flyweight[value] ||= new(value)
+      end
+
+      class << self
+        alias :from_f :[]
+        alias :from_i :[]
+      end
+
+      # Lookup an interval duration by name.
+      def self.from_s(s)
+        value = VALUES_BY_NAME[s.to_s]
+        raise ArgumentError.new("Invalid Interval string '#{s}'") unless value
+        self[value]
+      end
+
+      class << self
+        alias :from_name :from_s
+      end
+
+      # The number of semitones as a floating point number
+      def to_f
+        @value.to_f
+      end
+
+      # The numerical value for the nearest whole number of semitones in this interval
+      def to_i
+        @value.round
+      end
+
+      def to_s
+        @value.to_s
+      end
+
+      def inspect
+        "#{self.class}<#{to_s} semitones>"
+      end
+
+      def ==( other )
+        other.is_a? MTK::Core::Interval and other.value == @value
+      end
+
+      def <=> other
+        if other.respond_to? :value
+          @value <=> other.value
+        else
+          @value <=> other
+        end
+      end
+
+      def + interval
+        if interval.is_a? MTK::Core::Interval
+          MTK::Core::Interval[@value + interval.value]
+        else
+          MTK::Core::Interval[@value + interval]
+        end
+      end
+
+      def -interval
+        if interval.is_a? MTK::Core::Interval
+          MTK::Core::Interval[@value - interval.value]
+        else
+          MTK::Core::Interval[@value - interval]
+        end
+      end
+
+      def * interval
+        if interval.is_a? MTK::Core::Interval
+          MTK::Core::Interval[@value * interval.value]
+        else
+          MTK::Core::Interval[@value * interval]
+        end
+      end
+
+      def / interval
+        if interval.is_a? MTK::Core::Interval
+          MTK::Core::Interval[to_f / interval.value]
+        else
+          MTK::Core::Interval[to_f / interval]
+        end
+      end
+
+      def -@
+        MTK::Core::Interval[@value * -1]
+      end
+
+      def coerce(other)
+        return MTK::Core::Interval[other], self
+      end
+
+    end
+  end
+
+  # Construct a {Duration} from any supported type
+  def Interval(*anything)
+    anything = anything.first if anything.length == 1
+    case anything
+      when Numeric then MTK::Core::Interval[anything]
+      when String, Symbol then MTK::Core::Interval.from_s(anything)
+      when Interval then anything
+      else raise "Interval doesn't understand #{anything.class}"
+    end
+  end
+  module_function :Interval
+
+end

data/lib/mtk/core/pitch.rb

@@ -0,0 +1,154 @@
+module MTK
+  module Core
+
+    # A frequency represented by a {PitchClass}, an integer octave, and an offset in semitones.
+    class Pitch
+
+      include Comparable
+
+      attr_reader :pitch_class, :octave, :offset
+
+      def initialize( pitch_class, octave, offset=0 )
+        @pitch_class, @octave, @offset = pitch_class, octave, offset
+        @value = @pitch_class.to_i + 12*(@octave+1) + @offset
+      end
+
+      @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( 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)
+          if pitch_class
+            octave = $3.to_i
+            offset_in_cents = $5.to_f
+            if offset_in_cents.nil? or offset_in_cents.zero?
+              return self[pitch_class, octave]
+            else
+              return new( pitch_class, octave, offset_in_cents/100.0 )
+            end
+          end
+        end
+        raise ArgumentError.new("Invalid pitch name: #{name.inspect}")
+      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
+        if offset == 0
+          self[pitch_class, octave]
+        else
+          new( pitch_class, octave, offset )
+        end
+      end
+
+      def self.from_h(hash)
+        new hash[:pitch_class], hash[:octave], hash.fetch(:offset,0)
+      end
+
+      # Convert a Numeric semitones value into a Pitch
+      def self.from_i( i )
+        from_f( i )
+      end
+
+      # The numerical value of this pitch
+      def to_f
+        @value
+      end
+
+      # The numerical value for the nearest semitone
+      def to_i
+        @value.round
+      end
+
+      def offset_in_cents
+        @offset * 100
+      end
+
+      def to_h
+        {:pitch_class => @pitch_class, :octave => @octave, :offset => @offset}
+      end
+
+      def to_s
+        "#{@pitch_class}#{@octave}" + (@offset.zero? ? '' : "+#{offset_in_cents.round}cents")
+      end
+
+      def inspect
+        "#<#{self.class}:#{object_id} @value=#{@value}>"
+      end
+
+      def ==( other )
+        other.respond_to? :pitch_class and other.respond_to? :octave and other.respond_to? :offset and
+        other.pitch_class == @pitch_class and other.octave == @octave and other.offset == @offset
+      end
+
+      def <=> other
+        @value <=> other.to_f
+      end
+
+      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 )
+      end
+
+      def invert(center_pitch)
+        self + 2*(center_pitch.to_f - to_f)
+      end
+
+      def nearest(pitch_class)
+        self + self.pitch_class.distance_to(pitch_class)
+      end
+
+      def coerce(other)
+        return self.class.from_f(other.to_f), self
+      end
+
+      def clone_with(hash)
+        self.class.from_h(to_h.merge hash)
+      end
+
+    end
+  end
+
+  # Construct a {Pitch} from any supported type
+  def Pitch(*anything)
+    anything = anything.first if anything.length == 1
+    case anything
+      when Numeric then MTK::Core::Pitch.from_f(anything)
+      when String, Symbol then MTK::Core::Pitch.from_s(anything)
+      when MTK::Core::Pitch then anything
+      when Array
+        if anything.length == 2
+          MTK::Core::Pitch[*anything]
+        else
+          MTK::Core::Pitch.new(*anything)
+        end
+      else raise ArgumentError.new("Pitch doesn't understand #{anything.class}")
+    end
+  end
+  module_function :Pitch
+
+end