xi-lang 0.1.4 → 0.1.5

data/lib/xi/pattern.rb

@@ -1,172 +1,501 @@
-require 'forwardable'
-require 'xi/event'
 require 'xi/pattern/transforms'
 require 'xi/pattern/generators'
 
 module Xi
+  # A Pattern is a lazy, infinite enumeration of values in time.
+  #
+  # An event represents a value that occurs in a specific moment in time.  It
+  # is a value together with its onset (start position) in terms of cycles, and
+  # its duration.  It is usually represented by a tuple of (value, start,
+  # duration, iteration).  This tuple indicates when a value occurs in time
+  # (start), its duration, and on which iteration of the pattern happens.
+  #
+  # P is an alias of Pattern, so you can build them using P instead.  Note that
+  # if the pattern was built from an array, the string representation can be
+  # used to build the same pattern again (almost the same ignoring whitespace
+  # between constructor arguments).
+  #
+  #   P[1,2,3]   #=> P[1, 2, 3]
+  #
   class Pattern
-    include Enumerable
+    extend  Generators
     include Transforms
-    include Generators
-    extend  Forwardable
 
-    attr_reader :source, :event_duration, :metadata, :total_duration
+    # Array or Proc that produces values or events
+    attr_reader :source
 
-    alias_method :dur, :event_duration
+    # Event delta in terms of cycles (default: 1)
+    attr_reader :delta
 
-    def_delegators :@source, :size
+    # Hash that contains metadata related to pattern usage
+    attr_reader :metadata
 
-    # Creates a new Pattern given either a +source+ or a block
-    # that yields values
+    # Size of pattern
+    attr_reader :size
+
+    # Duration of pattern
+    attr_reader :duration
+
+    # Creates a new Pattern given either a +source+ or a +block+ that yields
+    # events.
+    #
+    # If a block is given, +yielder+ parameter must yield +value+ and +start+
+    # (optional) for each event.
+    #
+    # @example Pattern from an Array
+    #   Pattern.new(['a', 'b', 'c']).take(5)
+    #   # => [['a', 0, 1, 0],
+    #   #     ['b', 1, 1, 0],
+    #   #     ['c', 2, 1, 0],
+    #   #     ['a', 3, 1, 1],    # starts cycling...
+    #   #     ['b', 4, 1, 1]]
+    #
+    # @example Pattern from a block that yields only values.
+    #   Pattern.new { |y| y << rand(100) }.take(5)
+    #   # => [[52, 0, 1, 0],
+    #   #     [8,  1, 1, 0],
+    #   #     [83, 2, 1, 0],
+    #   #     [25, 3, 1, 0],
+    #   #     [3,  4, 1, 0]]
     #
-    # @param source [#each]
-    # @param size [Fixnum] number of elements (default: nil)
-    # @param dur [Hash]
+    # @param source [Array]
+    # @param size [Fixnum] number of events per iteration
+    # @param delta [Numeric, Array<Numeric>, Pattern<Numeric>] event delta
+    # @param metadata [Hash]
+    # @yield [yielder, delta] yielder and event delta
+    # @yieldreturn [value, start, duration]
+    # @return [Pattern]
     #
-    def initialize(source=nil, size: nil, **metadata)
-      if source.nil? && !block_given?
+    def initialize(source=nil, size: nil, delta: nil, **metadata, &block)
+      if source.nil? && block.nil?
         fail ArgumentError, 'must provide source or block'
       end
 
-      size ||= source.size if source.respond_to?(:size)
+      if delta && delta.respond_to?(:size) && !(delta.size < Float::INFINITY)
+        fail ArgumentError, 'delta cannot be infinite'
+      end
+
+      # If delta is an array of 1 or 0 values, flatten array
+      delta = delta.first if delta.is_a?(Array) && delta.size <= 1
 
-      @source = if block_given?
-        Enumerator.new(size) { |y| yield y }
+      # Block takes precedence as source, even though +source+ can be used to
+      # infer attributes
+      @source = block || source
+
+      # Infer attributes from +source+ if it is a pattern
+      if source.is_a?(Pattern)
+        @delta = source.delta
+        @size = source.size
+        @metadata = source.metadata
       else
-        source
+        @delta = 1
+        @size = (source.respond_to?(:size) ? source.size : nil) ||
+          Float::INFINITY
+        @metadata = {}
       end
 
-      @event_duration = metadata.delete(:dur) || metadata.delete(:event_duration)
-      @event_duration ||= source.event_duration if source.respond_to?(:event_duration)
-      @event_duration ||= 1
+      # Flatten source if it is a pattern
+      @source = @source.source if @source.is_a?(Pattern)
 
-      @metadata = source.respond_to?(:metadata) ? source.metadata : {}
+      # Override or merge custom attributes if they were specified
+      @size = size if size
+      @delta = delta if delta
       @metadata.merge!(metadata)
 
-      @is_infinite = @source.size.nil? || @source.size == Float::INFINITY
+      # Flatten delta values to an array, if it is an enumerable or pattern
+      @delta = @delta.to_a if @delta.respond_to?(:to_a)
 
-      if @is_infinite
-        @total_duration = if @event_duration.respond_to?(:each)
-          @event_duration.each.first
-        else
-          @event_duration
-        end
-      else
-        last_ev = each_event.take(@source.size).last
-        @total_duration = last_ev ? last_ev.start + last_ev.duration : 0
-      end
+      # Set duration based on delta values
+      @duration = delta_values.reduce(:+) || 0
+    end
+
+    # Create a new Pattern given an array of +args+
+    #
+    # @see Pattern#initialize
+    #
+    # @param args [Array]
+    # @param kwargs [Hash]
+    # @return [Pattern]
+    #
+    def self.[](*args, **kwargs)
+      new(args, **kwargs)
     end
 
-    def self.[](*args, **metadata)
-      new(args, **metadata)
+    # Returns a new Pattern with the same +source+, but with +delta+ overriden
+    # and +metadata+ merged.
+    #
+    # @param delta [Array<Numeric>, Pattern<Numeric>, Numeric]
+    # @param metadata [Hash]
+    # @return [Pattern]
+    #
+    def p(*delta, **metadata)
+      delta = delta.compact.empty? ? @delta : delta
+      Pattern.new(@source, delta: delta, size: @size, **@metadata.merge(metadata))
     end
 
+    # Returns true if pattern is infinite
+    #
+    # A Pattern is infinite if it was created from a Proc or another infinite
+    # pattern, and size was not specified.
+    #
+    # @return [Boolean]
+    # @see #finite?
+    #
     def infinite?
-      @is_infinite
+      @size == Float::INFINITY
     end
 
+    # Returns true if pattern is finite
+    #
+    # A pattern is finite if it has a finite size.
+    #
+    # @return [Boolean]
+    # @see #infinite?
+    #
     def finite?
       !infinite?
     end
 
-    def ==(o)
-      self.class == o.class &&
-        source == o.source &&
-        event_duration == o.event_duration &&
-        metadata == o.metadata
+    # Calls the given block once for each event, passing its value, start
+    # position, duration and iteration as parameters.
+    #
+    # +cycle+ can be any number, even if there is no event that starts exactly
+    # at that moment.  It will start from the next event.
+    #
+    # If no block is given, an enumerator is returned instead.
+    #
+    # Enumeration loops forever, and starts yielding events based on pattern's
+    # delta and from the +cycle+ position, which is by default 0.
+    #
+    # @example block yields value, start, duration and iteration
+    #   Pattern.new([1, 2], delta: 0.25).each_event.take(4)
+    #   # => [[1, 0.0,  0.25, 0],
+    #   #     [2, 0.25, 0.25, 0],
+    #   #     [1, 0.5,  0.25, 1],
+    #   #     [2, 0.75, 0.25, 1]]
+    #
+    # @example +cycle+ is used to start iterating from that moment in time
+    #   Pattern.new([:a, :b, :c], delta: 1/2).each_event(42).take(4)
+    #   # => [[:a, (42/1), (1/2), 28],
+    #   #     [:b, (85/2), (1/2), 28],
+    #   #     [:c, (43/1), (1/2), 28],
+    #   #     [:a, (87/2), (1/2), 29]]
+    #
+    # @example +cycle+ can also be a fractional number
+    #   Pattern.new([:a, :b, :c]).each_event(0.97).take(3)
+    #   # => [[:b, 1, 1, 0],
+    #   #     [:c, 2, 1, 0],
+    #   #     [:a, 3, 1, 1]]
+    #
+    # @param cycle [Numeric]
+    # @yield [v, s, d, i] value, start, duration and iteration
+    # @return [Enumerator]
+    #
+    def each_event(cycle=0)
+      return enum_for(__method__, cycle) unless block_given?
+      EventEnumerator.new(self, cycle).each { |v, s, d, i| yield v, s, d, i }
     end
 
-    def p(dur=nil, **metadata)
-      Pattern.new(@source, dur: dur || @event_duration,
-                  size: size, **@metadata.merge(metadata))
-    end
+    # Calls the given block passing the delta of each value in pattern
+    #
+    # This method is used internally by {#each_event} to calculate when each
+    # event in pattern occurs in time.  If no block is given, an Enumerator is
+    # returned instead.
+    #
+    # @param index [Numeric]
+    # @yield [d] duration
+    # @return [Enumerator]
+    #
+    def each_delta(index=0)
+      return enum_for(__method__, index) unless block_given?
 
-    def each_event
-      return enum_for(__method__) unless block_given?
+      delta = @delta
 
-      dur_enum = each_event_duration
-      pos = 0
+      if delta.is_a?(Array)
+        size = delta.size
+        return if size == 0
 
-      @source.each do |value|
-        if value.is_a?(Pattern)
-          value.each do |v|
-            dur = dur_enum.next
-            yield Event.new(v, pos, dur)
-            pos += dur
-          end
-        elsif value.is_a?(Event)
-          yield value
-          pos += value.duration
-        else
-          dur = dur_enum.next
-          yield Event.new(value, pos, dur)
-          pos += dur
+        start = index.floor
+        i = start % size
+        loop do
+          yield delta[i]
+          i = (i + 1) % size
+          start += 1
         end
+      elsif delta.is_a?(Pattern)
+        delta.each_event(index) { |v, _| yield v }
+      else
+        loop { yield delta }
       end
     end
 
+    # Calls the given block once for each value in source
+    #
+    # @example
+    #   Pattern.new([1, 2, 3]).each.to_a
+    #   # => [1, 2, 3]
+    #
+    # @return [Enumerator]
+    # @yield [Object] value
+    #
     def each
       return enum_for(__method__) unless block_given?
-      each_event { |e| yield e.value }
+
+      each_event { |v, _, _, i|
+        break if i > 0
+        yield v
+      }
     end
 
-    def each_event_duration
+    # Same as {#each} but in reverse order
+    #
+    # @example
+    #   Pattern.new([1, 2, 3]).reverse_each.to_a
+    #   # => [3, 2, 1]
+    #
+    # @return [Enumerator]
+    # @yield [Object] value
+    #
+    def reverse_each
       return enum_for(__method__) unless block_given?
-      if @event_duration.respond_to?(:each)
-        loop { @event_duration.each { |v| yield v } }
-      else
-        loop { yield @event_duration }
+      each.to_a.reverse.each { |v| yield v }
+    end
+
+    # Returns an array of values from a single iteration of pattern
+    #
+    # @return [Array] values
+    # @see #to_events
+    #
+    def to_a
+      fail StandardError, 'pattern is infinite' if infinite?
+      each.to_a
+    end
+
+    # Returns an array of events (i.e. a tuple [value, start, duration,
+    # iteration]) from the first iteration.
+    #
+    # Only applies to finite patterns.
+    #
+    # @return [Array] events
+    # @see #to_a
+    #
+    def to_events
+      fail StandardError, 'pattern is infinite' if infinite?
+      each_event.take(size)
+    end
+
+    # Returns a new Pattern with the results of running +block+ once for every
+    # value in +self+
+    #
+    # If no block is given, an Enumerator is returned.
+    #
+    # @yield [v, s, d, i] value, start, duration and iteration
+    # @yieldreturn [v, s, d] value, start (optional) and duration (optional)
+    # @return [Pattern]
+    #
+    def map
+      return enum_for(__method__) unless block_given?
+
+      Pattern.new(self) do |y, d|
+        each_event do |v, s, ed, i|
+          y << yield(v, s, ed, i)
+        end
       end
     end
+    alias_method :collect, :map
+
+    # Returns a Pattern containing all events of +self+ for which +block+ is
+    # true.
+    #
+    # If no block is given, an Enumerator is returned.
+    #
+    # @see Pattern#reject
+    #
+    # @yield [v, s, d, i] value, start, duration and iteration
+    # @yieldreturn [Boolean] whether value is selected
+    # @return [Pattern]
+    #
+    def select
+      return enum_for(__method__) unless block_given?
+
+      Pattern.new(self) do |y, d|
+        each_event do |v, s, ed, i|
+          y << v if yield(v, s, ed, i)
+        end
+      end
+    end
+    alias_method :find_all, :select
+
+    # Returns a Pattern containing all events of +self+ for which +block+
+    # is false.
+    #
+    # If no block is given, an Enumerator is returned.
+    #
+    # @see Pattern#select
+    #
+    # @yield [v, s, d, i] value, start, duration and iteration
+    # @yieldreturn [Boolean] whether event is rejected
+    # @return [Pattern]
+    #
+    def reject
+      return enum_for(__method__) unless block_given?
+
+      select { |v, s, d, i| !yield(v, s, d, i) }
+    end
+
+    # Returns the first +n+ events from the pattern, starting from +cycle+
+    #
+    # @param n [Fixnum]
+    # @param cycle [Numeric]
+    # @return [Array] values
+    #
+    def take(n, cycle=0)
+      each_event(cycle).take(n)
+    end
+
+    # Returns the first +n+ values from +self+, starting from +cycle+.
+    #
+    # Only values are returned, start position and duration are ignored.
+    #
+    # @see #take
+    #
+    def take_values(*args)
+      take(*args).map(&:first)
+    end
+
+    # Returns the first element, or the first +n+ elements, of the pattern.
+    #
+    # If the pattern is empty, the first form returns nil, and the second form
+    # returns an empty array.
+    #
+    # @see #take
+    #
+    # @param n [Fixnum]
+    # @param args same arguments as {#take}
+    # @return [Object, Array]
+    #
+    def first(n=nil, *args)
+      res = take(n || 1, *args)
+      n.nil? ? res.first : res
+    end
 
+    # Returns a string containing a human-readable representation
+    #
+    # When source is not a Proc, this string can be evaluated to construct the
+    # same instance.
+    #
+    # @return [String]
+    #
     def inspect
       ss = if @source.respond_to?(:join)
              @source.map(&:inspect).join(', ')
-           elsif @source.is_a?(Enumerator)
-             "?enum"
+           elsif @source.is_a?(Proc)
+             "?proc"
            else
              @source.inspect
            end
 
       ms = @metadata.reject { |_, v| v.nil? }
-      ms.merge!(dur: dur) if dur != 1
+      ms.merge!(delta: delta) if delta != 1
       ms = ms.map { |k, v| "#{k}: #{v.inspect}" }.join(', ')
 
       "P[#{ss}#{", #{ms}" unless ms.empty?}]"
     end
     alias_method :to_s, :inspect
 
-    def map_events
-      return enum_for(__method__) unless block_given?
-      Pattern.new(self) { |y| each_event { |e| y << yield(e) } }
+    # Returns pattern interation size or length
+    #
+    # This is usually calculated from the least-common multiple between the sum
+    # of delta values and the size of the pattern.  If pattern is infinite,
+    # pattern size is assumed to be 1, so iteration size depends on delta
+    # values.
+    #
+    # @return [Fixnum]
+    #
+    def iteration_size
+      finite? ? delta_size.lcm(@size) : delta_size
     end
-    alias_method :collect_events, :map_events
 
-    def select_events
-      return enum_for(__method__) unless block_given?
-      Pattern.new(self) { |y| each_event { |e| y << e if yield(e) } }
+    # @private
+    def ==(o)
+      self.class == o.class &&
+        delta == o.delta &&
+        size == o.size &&
+        duration == o.duration &&
+        metadata == o.metadata &&
+        (finite? && to_a == o.to_a)
     end
-    alias_method :find_all_events, :select_events
 
-    def reject_events
-      return enum_for(__method__) unless block_given?
-      Pattern.new(self) { |y| each_event { |e| y << e unless yield(e) } }
-    end
+    private
 
-    def to_events
-      each_event.to_a
+    class EventEnumerator
+      def initialize(pattern, cycle)
+        @cycle = cycle
+
+        @source = pattern.source
+        @size = pattern.size
+        @iter_size = pattern.iteration_size
+
+        @iter = pattern.duration > 0 ? (cycle / pattern.duration).floor : 0
+        @delta_enum = pattern.each_delta(@iter * @iter_size)
+        @start = @iter * pattern.duration
+        @prev_ev = nil
+        @i = 0
+      end
+
+      def each(&block)
+        return enum_for(__method__, @cycle) unless block_given?
+
+        return if @size == 0
+
+        if @source.respond_to?(:call)
+          loop do
+            yielder = ::Enumerator::Yielder.new do |value|
+              each_block(value, &block)
+            end
+            @source.call(yielder, @delta_enum.peek)
+          end
+        elsif @source.respond_to?(:each_event)
+          @source.each_event(@start) do |value, _|
+            each_block(value, &block)
+          end
+        elsif @source.respond_to?(:[])
+          loop do
+            each_block(@source[@i % @size], &block)
+          end
+        else
+          fail StandardError, 'invalid source'
+        end
+      end
+
+      private
+
+      def each_block(value)
+        delta = @delta_enum.peek
+
+        if @start >= @cycle
+          if @prev_ev
+            yield @prev_ev if @start > @cycle
+            @prev_ev = nil
+          end
+          yield value, @start, delta, @iter
+        else
+          @prev_ev = [value, @start, delta, @iter]
+        end
+
+        @iter += 1 if @i + 1 == @iter_size
+        @i = (@i + 1) % @iter_size
+        @start += delta
+        @delta_enum.next
+      end
     end
 
-    def peek(limit=10)
-      values = take(limit + 1)
-      puts "There are more than #{limit} values..." if values.size > limit
-      values.take(limit)
+    def delta_values
+      each_delta.take(iteration_size)
     end
 
-    def peek_events(limit=10)
-      events = each_event.take(limit + 1)
-      puts "There are more than #{limit} events..." if events.size > limit
-      events.take(limit)
+    def delta_size
+      @delta.respond_to?(:each) && @delta.respond_to?(:size) ? @delta.size : 1
     end
   end
 end

data/lib/xi/step_sequencer.rb

@@ -0,0 +1,40 @@
+class Xi::StepSequencer
+  attr_reader :string, :values
+
+  def initialize(string, *values)
+    @string = string
+    @values = values
+  end
+
+  def p(*args, **metadata)
+    build_pattern(**metadata)
+  end
+
+  def inspect
+    "s(#{@string.inspect}" \
+      "#{", #{@values.map(&:inspect).join(', ')}" unless @values.empty?})"
+  end
+
+  private
+
+  def build_pattern(**metadata)
+    val_keys = values_per_key
+
+    values_per_bar = @string.split('|').map { |bar|
+      vs = bar.split(/\s*/).reject(&:empty?)
+      vs.map { |k| val_keys[k] }
+    }.reject(&:empty?)
+
+    delta = values_per_bar.map { |vs| [1 / vs.size] * vs.size }.flatten
+
+    Pattern.new(values_per_bar.flatten, delta: delta, **metadata)
+  end
+
+  def values_per_key
+    keys.map.with_index { |k, i| [k, k == '.' ? nil : @values[i]] }.to_h
+  end
+
+  def keys
+    @string.scan(/\w/).uniq
+  end
+end