turbine-graph 0.1.0

data/lib/turbine/pipeline/expander.rb

@@ -0,0 +1,67 @@
+module Turbine
+  module Pipeline
+    # A Pipeline segment which expands arrays, sets, and enumerators such
+    # that, instead of sending them to the next segment, each member of the
+    # collection is sent separately.
+    #
+    #   pump   = Pump.new(%w( abc def ), %w( hik klm ))
+    #   expand = Expander.new
+    #
+    #   pipeline = pump | expand
+    #
+    #   pipeline.next # => 'abc'
+    #   pipeline.next # => 'def'
+    #   pipeline.next # => 'hij'
+    #   pipeline.next # => 'klm'
+    #
+    # Using Expander on a pipeline has the same effect as calling +flatten(1)+
+    # on an Array.
+    class Expander < Segment
+
+      # Public: Creates a new Expander segment.
+      #
+      # Returns an Expander.
+      def initialize
+        super
+        @buffer = nil
+      end
+
+      # Public: Runs the pipeline once returning the next value.
+      #
+      # If a recent call to +next+ returned an array, set or enumerator, the
+      # next value from that collection will be emitted instead. Only once all
+      # of the values in the buffer have been emitted will the upstream
+      # segment be called again.
+      #
+      # Returns an object.
+      def next
+        if from_buffer = input_from_buffer
+          handle_value(from_buffer)
+        else
+          case value = super
+          when Array, Set, Enumerator
+            # Recurse into arrays, as the input may return multiple results (as
+            # is commonly the case when calling Node#in, Node#descendants, etc).
+            @buffer = value.to_a.compact
+            @buffer.any? ? handle_value(@buffer.shift) : self.next
+          else
+            handle_value(value)
+          end
+        end
+      end
+
+      #######
+      private
+      #######
+
+      # Internal: If there are any buffered values yet to be emitted, returns
+      # the next one; otherwise returns nil.
+      #
+      # Returns an object or nil.
+      def input_from_buffer
+        @buffer && @buffer.any? && @buffer.shift
+      end
+
+    end # Expander
+  end # Pipeline
+end # Turbine

data/lib/turbine/pipeline/filter.rb

@@ -0,0 +1,52 @@
+module Turbine
+  module Pipeline
+    # Emits only those values in the pipeline which satisfy the +filter+.
+    # Filter is to Pipeline as +select+ is to Enumerable.
+    #
+    #   Filter.new { |x| firewall.permitted?(x) }
+    #
+    class Filter < Segment
+      include Trace::Transparent
+
+      # Public: Creates a new Filter segment.
+      #
+      # You may opt to use the Filter class directly, passing a block when
+      # initializing which is used to control which values are emitted.
+      # Alternatively, provide no block and use a subclass with a custom
+      # +filter+ method.
+      #
+      # Without a filter block, all elements are emitted.
+      #
+      # block - An optional block used to select which values are emitted by
+      #         the filter.
+      #
+      # Returns a Filter.
+      def initialize(&block)
+        @filter = (block || method(:filter))
+        super()
+      end
+
+      # Public: Runs the pipeline continuously until a value which matches the
+      # filter is found, then that value is emitted.
+      #
+      # Returns an object.
+      def next
+        # Discard non-matching values.
+        nil until (value = input) && @filter.call(value)
+
+        handle_value(value)
+      end
+
+      #######
+      private
+      #######
+
+      # Internal: The default filter condition.
+      #
+      # Returns true or false.
+      def filter(value)
+        true
+      end
+    end # Filter
+  end # Pipeline
+end # Turbine

data/lib/turbine/pipeline/journal.rb

@@ -0,0 +1,130 @@
+module Turbine
+  module Pipeline
+    # Journal segments keep track of all of the values emitted by the source
+    # segment so that they can be used later in the pipeline.
+    class Journal < Segment
+      include Trace::Transparent
+
+      # The name used to refer to the segments values later in the pipeline.
+      attr_reader :name
+
+      # Public: Creates a new Journal segment.
+      #
+      # name - A name which is associated with the values remembered by the
+      #        segment. This is required so that the values can be referred to
+      #        in later segments.
+      #
+      # Returns a Journal instance.
+      def initialize(name)
+        super()
+
+        @name = name
+        forget!
+      end
+
+      # Public: The values stored by the segment; contains the results of
+      # running the upstream segments on all the inputs.
+      #
+      # Returns an array.
+      def values
+        @values ||= @source.to_a
+      end
+
+      # Public: Run the pipeline once, returning the next value. Forces
+      # complete evalulation of the values emitted by the upstream segments.
+      #
+      # See Segment#next.
+      #
+      # Returns the next value.
+      def next
+        values
+
+        if @index >= values.length - 1
+          # We test length-1 because the index is always one position *lower*
+          # than the actual position at this stage; it is incremented later
+          # when calling +input+.
+          raise StopIteration
+        else
+          super
+        end
+      end
+
+      # Public: Rewinds the segment so that iteration can happen from the
+      # first in put again.
+      #
+      # Returns nothing.
+      def rewind
+        forget!
+        super
+      end
+
+      # Public: Checks if the given +value+ is stored in the Journal. Faster
+      # than +values.include?+.
+      #
+      # value - The value to look for.
+      #
+      # Returns true or false.
+      def include?(value)
+        @lookup ||= Set.new(values)
+        @lookup.include?(value)
+      end
+
+      alias_method :member?, :include?
+
+      # Public: Describes the segments through which each input will pass.
+      #
+      # Return a string.
+      def to_s
+        "#{ source_to_s } | as(#{ @name.inspect })"
+      end
+
+      #######
+      private
+      #######
+
+      # Internal: Resets the Journal so that previously computed values are
+      # forgotten.
+      #
+      # Returns nothing.
+      def forget!
+        @values = nil
+        @lookup = nil
+        @index  = -1
+      end
+
+      # Internal: Retrieves the next value emitted by the upstream segment.
+      #
+      # Returns an object.
+      def input
+        @values[@index += 1]
+      end
+
+      # A collection of methods providing segment classes with the means to
+      # easily access values stored in an upstream Journal.
+      module Read
+        # Public: Retrieves the values stored in the upstream journal whose
+        # name is +name+.
+        #
+        # name - The name of the upstream journal.
+        #
+        # Raises a NoSuchJournalError if the given +name+ does not match a
+        # journal in the pipeline.
+        #
+        # Returns an array of values.
+        def journal(name)
+          upstream = source
+
+          while upstream.kind_of?(Segment)
+            if upstream.is_a?(Journal) && upstream.name == name
+              return upstream
+            end
+
+            upstream = upstream.source
+          end
+
+          raise NoSuchJournalError.new(name)
+        end
+      end # Read
+    end # Journal
+  end # Pipeline
+end # Turbine

data/lib/turbine/pipeline/journal_filter.rb

@@ -0,0 +1,71 @@
+module Turbine
+  module Pipeline
+    # A filter which uses an upstream Journal as a basis for determining which
+    # values should be emitted.
+    class JournalFilter < Filter
+      include Journal::Read
+
+      # Public: Creates a new JournalFilter.
+      #
+      # mode - The filter mode to be used. :only will cause the filter to emit
+      #        only values which were seen in the journal, while :except will
+      #        emit only those which were *not* seen.
+      # name - The name of the Journal whose values will be used.
+      #
+      # Returns a JournalFilter.
+      def initialize(mode, name)
+        unless mode == :only || mode == :except
+          raise ArgumentError, 'JournalFilter mode must be :only or :except'
+        end
+
+        @mode = mode
+        @journal_name = name
+
+        super(&method(:"filter_#{ mode }"))
+      end
+
+      # Public: Sets the previous segment in the pipeline.
+      #
+      # Raises NoSuchJournalError if the Journal required by the filter is not
+      # present in the source pipeline.
+      #
+      # Returns the source.
+      def source=(source)
+        super
+        @journal = journal(@journal_name)
+      end
+
+      # Public: Describes the segments through which each input will pass.
+      #
+      # Return a string.
+      def to_s
+        "#{ source_to_s } | #{ @mode }(#{ @journal_name.inspect })"
+      end
+
+      #######
+      private
+      #######
+
+      # Internal: Filter mode which emits only the values which were seen in
+      # the journal.
+      #
+      # value - The value emitted by the source.
+      #
+      # Returns true or false.
+      def filter_only(value)
+        @journal.include?(value)
+      end
+
+      # Internal: Filter mode which emits only the values which were not seen
+      # in the journal.
+      #
+      # value - The value emitted by the source.
+      #
+      # Returns true or false.
+      def filter_except(value)
+        not filter_only(value)
+      end
+
+    end # Only
+  end # Pipeline
+end # Turbine

data/lib/turbine/pipeline/pump.rb

@@ -0,0 +1,19 @@
+module Turbine
+  module Pipeline
+    # A pipeline segment which acts as the source for the pipeline. Values
+    # from the pump are "piped" through each segment in the pipeline.
+    class Pump < Segment
+      # Public: Creates a new pump upon whose elements the pipeline will act.
+      #
+      # source - The elements in the source which will pass through the
+      #          pipeline. Anything which responds to #each is acceptable,
+      #          including arrays, Turbine collections, and enumerators.
+      #
+      # Returns a Pump.
+      def initialize(source)
+        @source = source.to_enum
+        super()
+      end
+    end # Pump
+  end # Pipeline
+end # Turbine

data/lib/turbine/pipeline/segment.rb

@@ -0,0 +1,175 @@
+module Turbine
+  module Pipeline
+    # Represents a single stage in a pipeline. A pipeline may contain many
+    # segments, each of which transform or filter the elements which pass
+    # through it.
+    class Segment
+      include Enumerable
+
+      # The previous segment in the pipeline.
+      attr_accessor :source
+
+      # Public: Creates a new Segment. Segment itself is of little value in
+      # your pipelines as it will simply emit every value it is given. Instead
+      # you should look to Pump, Transform, and Filter.
+      #
+      # Returns a Segment.
+      def initialize
+        @tracing = false
+      end
+
+      # Public: Appends +other+ segment to be given the values emitted by this
+      # segment. Instead of a Segment instance, a block can be given instead
+      # which is used as a Transform.
+      #
+      # other - The segment or transform block to be run after this segment.
+      #
+      # For example, transforming three numbers using a Transform segment:
+      #
+      #   Pump.new([10, 20, 30]).append(Transform.new { |x| Math.sqrt(x) })
+      #
+      # Or using a lambda:
+      #
+      #   Pump.new([10, 20, 30]).append(->(x) { x ** 10 })
+      #
+      # Or using Dave Thomas' pipes syntax:
+      #
+      #   pump       = Pump.new((100..10000).to_a)
+      #   divide     = Transform.new { |x| x / 100 }
+      #   the_answer = Filter.new { |x| x == 42 }
+      #
+      #   (pump | divide | the_answer).next # => 42
+      #
+      # Returns the +other+ segment.
+      def append(other)
+        if other.respond_to?(:call)
+          other = Transform.new(&other)
+        end
+
+        other.source = self
+        other
+      end
+
+      alias_method :|, :append
+
+      # Public: Runs the pipeline once, returning the next value. Repeatedly
+      # calling this will yield each value in turn. Once all values have been
+      # emitted a StopIteration is raised (mimicking the behaviour of
+      # Enumerator).
+      #
+      # Returns an object.
+      def next
+        handle_value(input)
+      end
+
+      # Public: Iterates through each value in the pipeline.
+      #
+      # Returns nothing.
+      def each
+        rewind
+        loop { yield self.next }
+      end
+
+      # Public: Rewinds the segment so that iteration can happen from the
+      # first input again.
+      #
+      # Returns nothing.
+      def rewind
+        @source.rewind
+        @previous = nil
+      end
+
+      # Public: Enables tracing on the segment and it's source. This tells the
+      # segment to keep track of the most recently emitted value for use in a
+      # subsequent Trace segment.
+      #
+      # Returns the tracing setting.
+      def tracing=(use_tracing)
+        @tracing = use_tracing
+
+        if @source && @source.respond_to?(:tracing=)
+          @source.tracing = use_tracing
+        end
+      end
+
+      # Public: Returns the trace containing the most recently emitted values
+      # for all the source segments, appending this segment's value to the end
+      # of the array.
+      #
+      # For example
+      #
+      #   segment.next && segment.trace
+      #   # => [[ #<Node key=:jay>, #<Node key=:claire>, #<Node key=:haley> ]]
+      #
+      #   segment.next && segment.trace
+      #   # => [[ #<Node key=:jay>, #<Node key=:claire>, #<Node key=:alex> ]]
+      #
+      # Tracing must be enabled (normally by appending a Trace segment to the
+      # pipeline) otherwise a TracingNotEnabledError is raised.
+      #
+      # Subclasses may call +super+ with a block; the sole argument given to
+      # the block will be trace from the source segments.
+      #
+      # Returns an array.
+      def trace
+        unless @tracing
+          raise TracingNotEnabledError.new(self)
+        end
+
+        trace = @source.respond_to?(:trace) ? @source.trace.dup : []
+        block_given? ? yield(trace) : trace.push(@previous)
+      end
+
+      # Public: Describes the segments through which each input will pass.
+      #
+      # For example:
+      #
+      #   pipeline.to_s
+      #   # => "Pump | Sender(out) | Filter"
+      #
+      # Returns a string.
+      def to_s
+        name = self.class.name
+
+        # Nicked from ActiveSupport since it's faster than gsub, and more
+        # memory-efficient than split.
+        name = (index = name.rindex('::')) ? name[(index + 2)..-1] : name
+
+        source_string = source_to_s
+        source_string.nil? ? name : "#{ source_string } | #{ name }"
+      end
+
+      # Public: A human-readable version of the segment for debugging.
+      #
+      # Returns a String.
+      def inspect
+        to_s
+      end
+
+      #######
+      private
+      #######
+
+      def input
+        nil until (value = source.next)
+        value
+      end
+
+      def output(value)
+        if @tracing
+          @previous = value
+        end
+
+        value
+      end
+
+      def handle_value(value)
+        output(value)
+      end
+
+      def source_to_s
+        @source.is_a?(Segment) ? @source.to_s : nil
+      end
+    end # Segment
+  end # Pipeline
+end # Turbine