turbine-graph 0.1.0

data/lib/turbine/pipeline/sender.rb

@@ -0,0 +1,51 @@
+module Turbine
+  module Pipeline
+    # A segment which transforms its input by sending a +message+ to each
+    # input and returning the result.
+    #
+    #   ( Pump.new([1, 2]) | Sender.new(:to_s) ).to_a
+    #   # => ['1', '2']
+    #
+    # Each item coming from the source segment must have a public method with
+    # the same name as the +message+.
+    #
+    # Some methods in Turbine return an Array, Collection, or Enumerator as a
+    # sort of "result set" -- such as Node#in, Node#descendants, etc. In these
+    # cases, each element in the result set is yielded separately before
+    # continuing with the next input. See Expander for more details.
+    class Sender < Expander
+      attr_reader :message, :args
+
+      # Public: Creates a new Sender segment.
+      #
+      # message - The message (method name) to be sent to each value in the
+      #           pipeline.
+      # args    - Optional arguments to be sent with the message.
+      #
+      # Returns a Sender.
+      def initialize(message, *args)
+        @message = message
+        @args    = args
+
+        super()
+      end
+
+      # Public: Describes the segments through which each input will pass.
+      #
+      # Returns a string.
+      def to_s
+        "#{ source_to_s } | #{ message.to_s }" \
+          "(#{ args.map(&:inspect).join(', ') })"
+      end
+
+      #######
+      private
+      #######
+
+      def input
+        super.public_send(@message, *args)
+      end
+
+    end # Sender
+  end # Pipeline
+end # Turbine

data/lib/turbine/pipeline/split.rb

@@ -0,0 +1,132 @@
+module Turbine
+  module Pipeline
+    # Splits the upstream source into multiple pipelines which are evaluated
+    # in turn on the source, with the combined results being emitted.
+    #
+    # For example
+    #
+    #   pump  = Pump.new([node1, node2, node3])
+    #   split = Split.new(->(x) { x.get(:age) },
+    #                     ->(x) { x.get(:gender) })
+    #
+    #   (pump | split).to_a # => [ 18, :male, 27, :female, 25, :male ]
+    #
+    # You may supply as many separate branches as you wish.
+    class Split < Expander
+      Branch = Struct.new(:pump, :pipe)
+
+      # Public: Creates a new Split segment.
+      #
+      # branches - One or more procs; each proc is given a new pipeline DSL so
+      #            that you may transform / filter the inputs before the
+      #            results are merged back into the output.
+      #
+      # Returns a new Split.
+      def initialize(*branches)
+        if branches.none?
+          raise ArgumentError, 'Split requires at least one proc'
+        end
+
+        super()
+
+        # Each DSL is evaluated once, and +handle_result+ changes the source
+        # for each value being processed. This is more efficient than creating
+        # and evaluating a new DSL for every input.
+        @branches = branches.map do |branch|
+          dsl  = Pipeline.dsl([])
+          pump = dsl.source
+
+          Branch.new(pump, branch.call(dsl))
+        end
+
+        # JRuby doesn't support calling +next+ on enum.cycle.with_index.
+        @branches_cycle = @branches.zip((0...@branches.length).to_a).cycle
+      end
+
+      # Public: Returns the trace containing the most recently emitted values
+      # for all source segments. The trace for the current branch pipeline is
+      # merged into the trace.
+      #
+      # See Segment#trace.
+      #
+      # Returns an array.
+      def trace
+        super { |trace| trace.push(*@previous_trace) }
+      end
+
+      # Public: Enables or disables tracing on the segment. Passes the boolean
+      # through to the internal branch pipelines also, so that their traces
+      # may be combined with the output.
+      #
+      # Returns the tracing setting.
+      def tracing=(use_tracing)
+        super
+
+        @branches.each do |branch|
+          branch.pipe.source.tracing = use_tracing
+        end
+      end
+
+      #######
+      private
+      #######
+
+      # Internal: Returns the next value to be processed by the pipeline.
+      #
+      # Calling +input+ will fetch the input from the upstream segment,
+      # process it on the first branch and return the value. The next call
+      # will process the same input on the second branch, and so on util the
+      # value has been passed through each branch. Only then do we fetch a new
+      # input and start over.
+      #
+      # Returns an object.
+      def input
+        branch, iteration = @branches_cycle.next
+
+        # We've been through each branch for the current source, time to fetch
+        # the next one?
+        if iteration.zero?
+          @branch_source = Array(super).to_enum
+        end
+
+        branch.pump.source = @branch_source
+        branch.pipe.source.rewind
+
+        values = branch.pipe.to_a
+
+        @previous_trace = branch.pipe.source.trace.drop(1) if @tracing
+
+        values.any? ? values : input
+      end
+    end # Split
+
+    # A special case of split which emits the input value, and the results
+    # of a the given branches.
+    #
+    # For example
+    #
+    #   # Get your friends and their friends, and emit both as a single list.
+    #   nodes.out(:friend).also(->(node) { node.out(:friend) })
+    #
+    class Also < Split
+      # Creates a new Also segment.
+      #
+      # branches - A single branch whose results will be emitted along with
+      #            the input value.
+      #
+      # For example
+      #
+      #   nodes.also(->(n) { n.out(:spouse) }, ->(n) { n.out(:child) })
+      #
+      # If you only need to supply a single branch, you can pass it as a block
+      # instead of a proc wrapped in an array.
+      #
+      #   nodes.also { |n| n.out(:spouse) }
+      #
+      # Returns a new Also.
+      def initialize(*branches, &block)
+        super(*[->(node) { node }, *branches, block].compact)
+      end
+    end # Also
+  end # Pipeline
+end # Turbine

data/lib/turbine/pipeline/trace.rb

@@ -0,0 +1,55 @@
+module Turbine
+  module Pipeline
+    # Trace alters the pipeline such that instead of returning a single
+    # "reduced" value each time the pipeline is run, an array is returned with
+    # each element containing the result of each segment.
+    #
+    # See DSL#trace for more information.
+    class Trace < Segment
+      # Public: Sets the segment which serves as the source for the Trace.
+      # Enables tracing on the source, and all of the parent sources.
+      #
+      # Returns the source.
+      def source=(upstream)
+        upstream.tracing = true
+        super
+      end
+
+      # Public: Runs the pipeline once, returning the full trace which was
+      # traversed in order to retrieve the value.
+      #
+      # Returns an object.
+      def next
+        @source.next
+        @source.trace
+      end
+
+      # When included into a segment, sets it so that the value emitted by the
+      # segment is not included in traces. Useful for filters which would
+      # otherwise result in a duplicate value in the trace.
+      module Transparent
+        # Public: Trace each transformation made to an input value.
+        #
+        # See Segment#trace.
+        #
+        # Returns an array.
+        def trace
+          @source.trace
+        end
+      end # Transparent
+
+      # When included into a segment, raises an error if the user tries to
+      # enable tracing.
+      module Untraceable
+        # Public: Enable or disable tracing on the segment. Raises a
+        # NotTraceableError when called with a truthy value.
+        #
+        # Returns the tracing setting.
+        def tracing=(use_tracing)
+          raise NotTraceableError.new(self) if use_tracing
+          super
+        end
+      end # Untraceable
+    end # Trace
+  end # Pipeline
+end # Turbine

data/lib/turbine/pipeline/transform.rb

@@ -0,0 +1,49 @@
+module Turbine
+  module Pipeline
+    # A segment which transforms the input into something else. For example,
+    # a simple transform might receive an integer and output it's square root.
+    #
+    #   Transform.new { |x| Math.sqrt(x) }
+    #
+    class Transform < Segment
+      # Public: Creates a new Transform element.
+      #
+      # You may opt to use the Transform class directly, passing a block when
+      # initializing which is used to transform each value into something
+      # else. Alternatively, provide no block and use a subclass with a custom
+      # +transform+ method.
+      #
+      # Without a filter block, all elements are emitted.
+      #
+      # block - An optional block used to transform each value passing through
+      #         the pipeline into something else.
+      #
+      # Returns a transform.
+      def initialize(&block)
+        @transform = (block || method(:transform))
+        super()
+      end
+
+      #######
+      private
+      #######
+
+      # Internal: Handles each value from the pipeline, using the +transform+
+      # block or method to convert it into something else.
+      #
+      # value - The value being processed.
+      #
+      # Returns nothing.
+      def handle_value(value)
+        super(@transform.call(value))
+      end
+
+      # Internal: The default transform.
+      #
+      # Returns the +value+ untouched.
+      def transform(value)
+        value
+      end
+    end # Transform
+  end # Pipeline
+end # Turbine

data/lib/turbine/pipeline/traversal.rb

@@ -0,0 +1,34 @@
+module Turbine
+  module Pipeline
+    class Traverse < Expander
+      include Trace::Untraceable
+
+      # Public: Creates a new Traverse segment. Uses one of the traversal
+      # classes to emit every descendant of the input node.
+      #
+      # direction - The direction in which to traverse edges. :in or :out.
+      # label     - An optional label by which to restrict the edges
+      #             traversed.
+      # klass     - The traversal strategy. Defaults to BreadthFirst.
+      #
+      # Returns a new Traverse.
+      def initialize(direction, label = nil, klass = nil)
+        @direction = direction
+        @label     = label
+        @klass   ||= Traversal::BreadthFirst
+      end
+
+      #######
+      private
+      #######
+
+      # Public: Passes each value into a traversal class, emitting every
+      # adjacent node.
+      #
+      # Returns the traversed objects.
+      def input
+        @klass.new(super, @direction, [@label]).to_enum
+      end
+    end # Traverse
+  end # Pipeline
+end # Turbine

data/lib/turbine/pipeline/unique.rb

@@ -0,0 +1,47 @@
+module Turbine
+  module Pipeline
+    # A Pipeline segment which only emits values which it hasn't emitted
+    # previously.
+    #
+    # In order to determine if a value is a duplicate, Unique needs to keep a
+    # reference to each input it sees. For large result sets, you may prefer
+    # to sacrifice performance for reduced space complexity by passing a
+    # block; this used to reduce each input to a simpler value for storage and
+    # comparison:
+    #
+    #   pipeline.uniq { |value| value.hash }
+    #
+    # See also: Array#uniq.
+    class Unique < Filter
+
+      # Public: Creates a new Unique segment.
+      #
+      # block - An optional block which is used to "reduce" each value for
+      #         comparison with previously seen value.
+      #
+      # Returns a Unique.
+      def initialize(&block)
+        @seen = Set.new
+
+        super do |value|
+          key  = block ? block.call(value) : value
+          seen = @seen.include?(key)
+
+          @seen.add(key)
+
+          not seen
+        end
+      end
+
+      # Public: Rewinds the segment so that iteration can happen from the
+      # first input again.
+      #
+      # Returns nothing.
+      def rewind
+        @seen.clear
+        super
+      end
+
+    end # Unique
+  end # Pipeline
+end # Turbine

data/lib/turbine/properties.rb

@@ -0,0 +1,48 @@
+module Turbine
+  module Properties
+
+    # Public: Returns the properties associated with the model.
+    #
+    # Returns a hash containing the properties. This is the original
+    # properties hash, not a duplicate.
+    def properties
+      @properties ||= Hash.new
+    end
+
+    # Public: Mass-assigns properties to the model.
+    #
+    # new_props - A hash containing zero or more properties. The internal
+    #             properties hash is set to whatever parameters you provide; a
+    #             duplicate is not made before assignment. You may provide
+    #             +nil+ to remove all properties.
+    #
+    # Returns the properties.
+    def properties=(new_props)
+      unless new_props.is_a?(Hash) || new_props.nil?
+        raise InvalidPropertiesError.new(self, new_props)
+      end
+
+      @properties = new_props
+    end
+
+    # Public: Sets a single property on the model.
+    #
+    # key   - The property name.
+    # value - The value to be set.
+    #
+    # Returns the value.
+    def set(key, value)
+      properties[key] = value
+    end
+
+    # Public: Returns a single property on the model.
+    #
+    # key - The property to be retrieved.
+    #
+    # Returns the value or nil if the property does not exist.
+    def get(key)
+      properties[key]
+    end
+
+  end # Properties
+end # Turbine

data/lib/turbine/traversal/base.rb

@@ -0,0 +1,133 @@
+module Turbine
+  module Traversal
+    # Provides the means for traversing through the graph.
+    #
+    # Traversal classes do not themselves provide the methods commonly used
+    # for iterating through collections (each, map, etc), but act as a
+    # generator for the values in an Enumerator.
+    #
+    #   enumerator = DepthFirst.new(node, :in).to_enum
+    #   # => #<Enumerator: Node, Node, ...>
+    #
+    #   enumerator.each { |node| ... }
+    #   enumerator.map  { |node| ... }
+    #   # etc ...
+    #
+    # The Base class should not be used directly, but instead you should use
+    # DepthFirst or BreadthFirst which define strategies for the order in
+    # which items are traversed.
+    #
+    # Each unique item is traversed a maximum of once (loops are not
+    # repeatedly followed).
+    #
+    # Traversals are normally used to iterate through nodes, however you may
+    # also use them to traverse edges by providing a +fetcher+ argument which
+    # tells the traversal how to reach the next set of adjacent items:
+    #
+    #   DepthFirst.new(node, :in_edges, [], :out).to_enum
+    #   # => #<Enumerator: Edge, Edge, ...>
+    #
+    # As an end-user, you should rarely have to instantiate a traversal class
+    # yourself; Node#ancestors and Node#descendants provide a more convenient
+    # short-cut.
+    class Base
+      # Creates a new graph traversal.
+      #
+      # start   - The node from which to start traversing.
+      # method  - The method to be used to fetch the adjacent nodes (typically
+      #           +in+ or +out+).
+      # args    - Additional arguments to be used when calling +method+.
+      # fetcher - An optional method name to be called on each adjacent item
+      #           in order to fetch *its* adjacent items. Useful if traversing
+      #           edges instead of nodes.
+      #
+      # Returns a new traversal.
+      def initialize(start, method, args = nil, fetcher = nil)
+        @start   = start
+        @method  = method
+        @args    = args
+        @fetcher = fetcher
+      end
+
+      # Public: A human-readable version of the traversal.
+      #
+      # Returns a string.
+      def inspect
+        "#<#{ self.class.name } start=#{ @start.inspect } " \
+          "method=#{ @method.inspect }" \
+          "#{ @fetcher ? " fetcher=#{ @fetcher.inspect }" : '' }>"
+      end
+
+      # Public: The next node in the traversal.
+      #
+      # Raises a StopIteration if all reachable nodes have been visited.
+      #
+      # For example
+      #
+      #   traversal.next # => #<Turbine::Node key=:one>
+      #   traversal.next # => #<Turbine::Node key=:two>
+      #   traversal.next # => ! StopIteration
+      #
+      # Returns a Node.
+      def next
+        @fiber.resume
+      end
+
+      # Public: The traversal as an enumerator. This is the main way to
+      # traverse since the enumerator implements +each+, +map+, +with_index+,
+      # etc.
+      #
+      # Returns an Enumerator.
+      def to_enum
+        Enumerator.new do |control|
+          rewind
+          loop { control.yield(self.next) }
+        end
+      end
+
+      #######
+      private
+      #######
+
+      # Internal: Given a +node+ iterates through each of it's adjacent nodes
+      # using the +method+ and +args+ supplied when initializing the
+      # DepthFirst instance.
+      #
+      # When the node itself has matching adjacent nodes, those will also be
+      # visited. If there are loops within the graph, they will not be
+      # followed; each node is visited no more than once.
+      #
+      # node  - The node from which to traverse.
+      # block - A block executed for each matching node.
+      #
+      # Returns nothing.
+      def visit(node, &block)
+        raise NotImplementedError, 'Define visit in a subclass'
+      end
+
+      # Internal: Fetches the next iteration item. If the traversal was
+      # initialized with a +fetcher+, this is called on the item, otherwise
+      # the item is returned untouched.
+      #
+      # Useful when traversing edges instead of nodes.
+      #
+      # Returns an object.
+      def fetch(adjacent)
+        @fetcher ? adjacent.public_send(@fetcher) : adjacent
+      end
+
+      # Internal: Resets the traversal to restart from the beginning.
+      #
+      # Returns nothing.
+      def rewind
+        @seen = { @start => true }
+
+        @fiber = Fiber.new do
+          visit(@start) { |*args| Fiber.yield(*args) }
+          raise StopIteration
+        end
+      end
+
+    end # Base
+  end # Traversal
+end # Turbine