turbine-graph 0.1.0

data/lib/turbine/node.rb

@@ -0,0 +1,246 @@
+module Turbine
+  # In graph theory, a node is the fundamental unit of which graphs are
+  # formed: a directed graph consists of a set of nodes and a set of edges.
+  class Node
+    include Properties
+
+    # Public: Returns the unique key which identifies the node.
+    attr_reader :key
+
+    # Creates a new Node.
+    #
+    # key        - A unique identifier for the node. The uniqueness of the key
+    #              is not checked upon initializing, but instead when the node
+    #              is added to the graph (Graph#add).
+    # properties - Optional key/value properties to be associated with the
+    #              node.
+    #
+    # Returns the node.
+    def initialize(key, properties = nil)
+      @key        = key
+      @in_edges   = Set.new
+      @out_edges  = Set.new
+
+      self.properties = properties
+    end
+
+    # Public: Returns nodes which have an outgoing edge to this node.
+    #
+    # label - An optional label by which to filter the in edges, before
+    #         fetching the matched nodes.
+    #
+    # Returns an array of Node instances.
+    def in(label = nil)
+      Pipeline.dsl(self).in(label)
+    end
+
+    # Public: Returns verticies to which this node has outgoing edges.
+    #
+    # label - An optional label by which to filter the out edges, before
+    #         fetching the matched nodes.
+    #
+    # Returns an array of Node instances.
+    def out(label = nil)
+      Pipeline.dsl(self).out(label)
+    end
+
+    # Public: Returns this node's incoming edges.
+    #
+    # label - An optional label; only edges with this label will be returned.
+    #         Passing nil will return all in edges.
+    #
+    # Raises an InvalidEdgeFilterError if you supply both a +label+ and
+    # +block+ for filtering the edges.
+    #
+    # Returns an array of Edges.
+    def in_edges(label = nil)
+      Pipeline.dsl(self).in_edges(label)
+    end
+
+    # Public: Returns this node's outgoing edges.
+    #
+    # label - An optional label; only edges with this label will be returned.
+    #         Passing nil will return all out edges.
+    #
+    # Raises an InvalidEdgeFilterError if you supply both a +label+ and
+    # +block+ for filtering the edges.
+    #
+    # Returns an array of Edges.
+    def out_edges(label = nil)
+      Pipeline.dsl(self).out_edges(label)
+    end
+
+    # Public: Returns an enumerator containing all nodes which are outward
+    # nodes, and all of their outward nodes.
+    #
+    # Uses a BreadthFirst traversal so that immediately adjacent nodes are
+    # visited before more distant nodes.
+    #
+    # Returns an Enumerator containing Nodes.
+    def descendants(label = nil)
+      Pipeline.dsl(self).traverse(:out, label)
+    end
+
+    # Public: Returns an enumerator containing all nodes which are inward
+    # nodes, and all of their inward nodes.
+    #
+    # Uses a BreadthFirst traversal so that immediately adjacent nodes are
+    # visited before more distant nodes.
+    #
+    # Returns an Enumerator containing Nodes.
+    def ancestors(label = nil)
+      Pipeline.dsl(self).traverse(:in, label)
+    end
+
+    # Internal: Low-level method which retrieves all of the edges in a given
+    # +direction+, in an array.
+    #
+    # Returns an array of edges.
+    def edges(direction, label = nil)
+      select_edges(direction == :in ? @in_edges : @out_edges, label)
+    end
+
+    # Internal: Low-level method which retrieves all of the nodes in a given
+    # +direction+, in an array.
+    #
+    # Returns an array of nodes.
+    def nodes(direction, label = nil)
+      edges(direction, label).map(&(direction == :in ? :from : :to))
+    end
+
+    # Public: Returns a human-readable version of the node.
+    def inspect
+      "#<#{ self.class.name } key=#{ @key.inspect }>"
+    end
+
+    alias_method :to_s, :inspect
+
+    # Public: Connects this node to another.
+    #
+    # target     - The node to which you want to connect. The +target+ node
+    #              will be the "from" end of the edge.
+    # label      - An optional label describing the relationship between the
+    #              two nodes.
+    # properties - Optional key/value properties to be associated with the
+    #              edge.
+    #
+    # Example:
+    #
+    #   phil = Turbine::Node.new(:phil)
+    #   luke = Turbine::Node.new(:luke)
+    #
+    #   phil.connect_to(luke, :child)
+    #
+    # Returns the Edge which was created.
+    #
+    # Raises a Turbine::DuplicateEdgeError if the Edge already existed.
+    def connect_to(target, label = nil, properties = nil)
+      Edge.new(self, target, label, properties).tap do |edge|
+        self.connect_via(edge)
+        target.connect_via(edge)
+      end
+    end
+
+    # Public: Disconnects this node from the +target+. Assumes that the
+    # receiver is the +from+ node.
+    #
+    # target - The node from which the receiver is to be disconnected.
+    # label  - An optional label; only the edge with this label will be
+    #          removed, with other edges kept intact. No label will remove all
+    #          outward edges between the receiver and the target.
+    #
+    # Raises NoSuchEdge if the two nodes are not connected.
+    #
+    # Returns nothing.
+    def disconnect_from(target, label = nil)
+      edges(:out, label).select { |edge| edge.to == target }.each do |edge|
+        disconnect_via(edge)
+        target.disconnect_via(edge)
+      end
+
+      nil
+    end
+
+    # Internal: Given an Edge, establishes the connection for this node.
+    #
+    # Please note that you need to call +connect_via+ on both the "from" and
+    # "to" nodes. Unless you need to create the connection using a subclass of
+    # Edge, you will likey prefer using the simpler +connect_to+.
+    #
+    # Example:
+    #
+    #   phil  = Turbine::Node.new(:phil)
+    #   haley = Turbine::Node.new(:haley)
+    #
+    #   edge  = Turbine::Edge.new(phil, haley, :child)
+    #
+    #   # Adds an link from "phil" to "haley".
+    #   phil.connect_via(edge)
+    #   haley.connect_via(edge)
+    #
+    # Raises a Turbine::CannotConnectError if this node is not the +from+ or
+    # +to+ node specified by the edge.
+    #
+    # Returns the given edge.
+    def connect_via(edge)
+      connect_endpoint(@in_edges, edge)  if edge.to   == self
+      connect_endpoint(@out_edges, edge) if edge.from == self
+
+      edge
+    end
+
+    # Internal: Given an edge, removes the connection for this node.
+    #
+    # Please note that you need to call +disconnect_via+ on both the "from"
+    # and "to" nodes.
+    #
+    # Example:
+    #
+    #   haley = Turbine::Node.new(:haley)
+    #   dylan = Turbine::Node.new(:dylan)
+    #
+    #   edge  = haley.connect_to(dylan, :boyfriend)
+    #
+    #   haley.disconnect_via(edge)
+    #   dylan.disconnect_via(edge)
+    #
+    # Returns nothing.
+    def disconnect_via(edge)
+      @in_edges.delete(edge)
+      @out_edges.delete(edge)
+
+      nil
+    end
+
+    #######
+    private
+    #######
+
+    # Internal: Given an edge, and a Node's in_edges or out_edges, adds the
+    # edge only if there is not a similar edge already present.
+    #
+    # collection - The collection to which the edge is to be added.
+    # edge       - The edge.
+    #
+    # Returns nothing.
+    def connect_endpoint(collection, edge)
+      if collection.any? { |o| ! edge.equal?(o) && edge.similar?(o) }
+        raise DuplicateEdgeError.new(self, edge)
+      end
+
+      collection.add(edge)
+    end
+
+    # Internal: Given an array of edges, and an optional label label, selects
+    # the edges from the given set.
+    #
+    # edges - The array of edges to be filtered.
+    # label - The label of the edges to be emitted.
+    #
+    # Returns an array of edges.
+    def select_edges(edges, label)
+      label.nil? ? edges : edges.select { |edge| edge.label == label }
+    end
+
+  end # Node
+end # Turbine

data/lib/turbine/pipeline/README.mdown

@@ -0,0 +1,31 @@
+# Pipeline
+
+Pipeline classes, appended to one another, provide a way to take a
+source and lazily transform and filter that source. It is also more
+efficient than the current `in` and `out` implementations in that
+chaining multiple expressions together can be done without the need for
+temporary collections between each chained method, and each source is
+traversed only once.
+
+This provides support for interesting traversal expressions:
+
+```Ruby
+# Get and "name" the child's parents:
+luke.in(:child).as('parents').
+  # Get Grandparents:
+  in(:child).
+  # Get Grandparents' children (which includes Luke's parents):
+  out(:child).uniq.
+  # Remove Luke's parents, leaving the Uncles and Aunts:
+  except('parents').
+  # Add the Uncles' and Aunts' spouses:
+  also { |node| node.out(:spouse) }
+```
+
+Pipeline is inspired by Dave Thomas' 2008 articles on using Fiber to
+create pipelines in Ruby<sup>[1][pipelines-one] & [2][pipelines-two]</sup>,
+and the Java ["Pipes" library][pipes-library].
+
+[pipelines-one]: http://pragdave.blogs.pragprog.com/pragdave/2007/12/pipelines-using.html
+[pipelines-two]: http://pragdave.blogs.pragprog.com/pragdave/2008/01/pipelines-using.html
+[pipes-library]: https://github.com/tinkerpop/pipes/wiki

data/lib/turbine/pipeline/dsl.rb

@@ -0,0 +1,275 @@
+module Turbine
+  module Pipeline
+    # Public: Starts a new Pipeline chain using the given +source+ as the
+    # source.
+    #
+    # source - An object, or array of objects, which will be iterated through
+    #          the pipeline.
+    #
+    # Returns a DSL.
+    def self.dsl(source)
+      DSL.new(Pump.new(Array(source)))
+    end
+
+    # Provides the chaining DSL used throughout Turbine, such as when calling
+    # Node#in, Node#descendants, etc.
+    class DSL
+      extend  Forwardable
+      include Enumerable
+
+      def_delegators :@source, :to_a, :each, :to_s
+
+      # The final segment in the pipeline.
+      attr_reader :source
+
+      # Public: Creates a new DSL instance.
+      #
+      # source - A Segment which acts as the head of the pipeline. Normally
+      #          an instance of Pump.
+      #
+      # Returns a DSL.
+      def initialize(source)
+        @source = source
+      end
+
+      # Public: Queries each input for its +key+ property. Expects the input
+      # to include Turbine::Properties.
+      #
+      # key - The property key to be queried.
+      #
+      # For example
+      #
+      #   pipe.get(:age) # => [11, 15, 18, 44, 46]
+      #
+      # Returns a new DSL.
+      def get(key)
+        append(Sender.new(:get, key))
+      end
+
+      # Public: Retrieves the in_edges from the input nodes.
+      #
+      # label - An optional label; only edges with a matching label will be
+      #         emitted by the pipeline.
+      #
+      # Returns a DSL.
+      def in_edges(label = nil)
+        append(Sender.new(:edges, :in, label))
+      end
+
+      # Public: Retrieves the out_edges from the input nodes.
+      #
+      # label - An optional label; only edges with a matching label will be
+      #         emitted by the pipeline.
+      #
+      # Returns a new DSL.
+      def out_edges(label = nil)
+        append(Sender.new(:edges, :out, label))
+      end
+
+      # Public: Retrieves the inbound nodes on the input node or edge.
+      #
+      # label - An optional label; only edges connected to the node via an
+      #         edge with this label will be emitted by the pipeline.
+      #
+      # Returns a new DSL.
+      def in(label = nil)
+        append(Sender.new(:nodes, :in, label))
+      end
+
+      # Public: Retrieves the outbound nodes on the input node or edge.
+      #
+      # label - An optional label; only edges connected to the node via an
+      #         edge with this label will be emitted by the pipeline.
+      #
+      # Returns a new DSL.
+      def out(label = nil)
+        append(Sender.new(:nodes, :out, label))
+      end
+
+      # Public: Using the breadth-first traversal strategy, fetches all of a
+      # node's adjacent nodes, and their adjacent nodes, and so on, in a given
+      # +direction+
+      #
+      # direction - In which direction from the current node do you wat to
+      #             traverse? :in or :out?
+      # label     - An optional label which is used to restrict the edges
+      #             traversed to those with the label.
+      #
+      # For example
+      #
+      #   # Fetches all nodes via outgoing edges.
+      #   dsl.traverse(:out).to_a
+      #
+      #   # Gets all out nodes via edges which have the :child label.
+      #   dsl.traverse(:out, :child)
+      #
+      # Returns a new DSL.
+      def traverse(direction, label = nil)
+        append(Traverse.new(direction, label))
+      end
+
+      # Public: Given a block, emits input elements for which the block
+      # evaluates to true.
+      #
+      # block - A block used to determine which element are emitted.
+      #
+      # Returns a new DSL.
+      def select(&block)
+        append(Filter.new(&block))
+      end
+
+      # Public: Given a block, emits input elements for which the block
+      # evaluates to false.
+      #
+      # block - A block used to determine which elements are emitted.
+      #
+      # Returns a new DSL.
+      def reject(&block)
+        append(Filter.new { |value| ! block.call(value) })
+      end
+
+      # Public: Given a block, transforms each input value to the result of
+      # running the block with the input.
+      #
+      # block - A block used to transform each input value.
+      #
+      # Returns a new DSL.
+      def map(&block)
+        append(Transform.new(&block))
+      end
+
+      # Public: Splits the pipeline into separate branches, computes the
+      # values from each branch in turn, then combines the results.
+      #
+      # branches - One or more blocks which will be given the DSL.
+      #
+      # For example
+      #
+      #    nodes.split(->(x) { x.get(:gender) },
+      #                ->(x) { x.in_edges.length },
+      #                ->(x) { x.out_edges.length }).to_a
+      #    # => [ :male, 2, 3, :female, 1, 6, :female, 2, 2, ... ]
+      #
+      # Returns a new DSL.
+      def split(*branches)
+        append(Split.new(*branches))
+      end
+
+      # Public: Like +split+, but also yields the input value before running
+      # each branch.
+      #
+      # branches - One or more blocks which will be given the DSL.
+      #
+      # For example
+      #
+      #   # Yields each node, and their outwards nodes connected with a
+      #   # :spouse edge.
+      #   nodes.also(->(node) { node.out(:spouse) })
+      #
+      # If you only want to supply a single branch, you can pass a block
+      # instead.
+      #
+      #   nodes.also { |node| node.out(:child) }
+      #
+      # Returns a new DSL.
+      def also(*branches, &block)
+        append(Also.new(*branches, &block))
+      end
+
+      # Public: Captures all of the values emitted by the previous segment so
+      # that a later segment (e.g. "only" or "except") can use them.
+      #
+      # name - A name assigned to the captured values.
+      #
+      # Returns a new DSL.
+      def as(name)
+        append(Journal.new(name))
+      end
+
+      # Public: Creates a filter so that only values which were present in a
+      # named journal (created using "as") are emitted.
+      #
+      # journal_name - The name of the "as" journal.
+      #
+      # For example
+      #
+      #   # Did your grandparents "friend" your parents?
+      #   node.in(:child).as(:parents).in(:child).out(:friend).only(:parents)
+      #
+      # Returns a new DSL.
+      def only(journal_name)
+        append(JournalFilter.new(:only, journal_name))
+      end
+
+      # Public: Creates a filter so that only values which were not present in
+      # a named journal (created using "as") are emitted.
+      #
+      # name - The name of the "as" journal.
+      #
+      #   # Who are your uncles and aunts?
+      #   node.in(:child).as(:parents).in(:child).out(:child).except(:parents)
+      #
+      # Returns a new DSL.
+      def except(journal_name)
+        append(JournalFilter.new(:except, journal_name))
+      end
+
+      # Public: Mutates the pipeline so that instead of returning a single
+      # value, it returns an array where each element is the result returned
+      # by each segment in the pipeline.
+      #
+      # Does not work correctly with pipelines where +descendants+ or
+      # +ancestors+ is used before +trace+.
+      #
+      # For example
+      #
+      #   jay.out(:child).out(:child).trace.to_a
+      #   # => [ [ #<Node key=:jay>, #<Node key=:claire>, #<Node key=:haley> ],
+      #   #      [ #<Node key=:jay>, #<Node key=:claire>, #<Node key=:alex> ],
+      #   #      ... ]
+      #
+      # This can be especially useful if you explicitly include edges in your
+      # pipeline:
+      #
+      #   jay.out_edges(:child).in.out_edges(:child).in.trace.next
+      #   # => [ [ #<Node key=:jay>,
+      #   #        #<Edge :jay -:child-> :claire>,
+      #   #        #<Node key=:claire>,
+      #   #        #<Edge :claire -:child-> :haley>,
+      #   #        #<Node key=:haley> ],
+      #   #      ... ]
+      #
+      # Returns a new DSL.
+      def trace
+        DSL.new(@source.append(Trace.new))
+      end
+
+      # Public: Filters each value so that only unique elements are emitted.
+      #
+      # block - An optional block used when determining if the value is
+      #         unique. See Pipeline::Unique#initialize.
+      #
+      # Returns a new DSL.
+      def uniq(&block)
+        append(Unique.new(&block))
+      end
+
+      # Public: Creates a new DSL by appending the given +downstream+ segment
+      # to the current source.
+      #
+      # downstream - The segment to be added in the new DSL.
+      #
+      # Returns a new DSL.
+      def append(downstream)
+        DSL.new(@source.append(downstream))
+      end
+
+      # Public: A human-readable version of the DSL.
+      #
+      # Return a String.
+      def inspect
+        "#<#{ self.class.inspect } {#{ to_s }}>"
+      end
+    end # DSL
+  end # Pipeline
+end # Turbine