turbine-graph 0.1.0

data/examples/family.rb

@@ -0,0 +1,125 @@
+require 'turbine'
+
+module Turbine
+
+  # This example is taken from a TV show called 'Modern Family' with complex
+  # family relations, in other words: ideal to test a complex graph structure.
+  #
+  # http://en.wikipedia.org/wiki/List_of_Modern_Family_characters
+  def self.family_stub
+    graph    = Turbine::Graph.new
+
+    phil     = graph.add(Turbine::Node.new(:phil,     gender: :male))
+    claire   = graph.add(Turbine::Node.new(:claire,   gender: :female))
+    haley    = graph.add(Turbine::Node.new(:haley,    gender: :female))
+    alex     = graph.add(Turbine::Node.new(:alex,     gender: :female))
+    luke     = graph.add(Turbine::Node.new(:luke,     gender: :male))
+
+    jay      = graph.add(Turbine::Node.new(:jay,      gender: :male))
+    gloria   = graph.add(Turbine::Node.new(:gloria,   gender: :female))
+    manny    = graph.add(Turbine::Node.new(:manny,    gender: :male))
+    unnamed  = graph.add(Turbine::Node.new(:unnamed))
+
+    mitchell = graph.add(Turbine::Node.new(:mitchell, gender: :male))
+    cameron  = graph.add(Turbine::Node.new(:cameron,  gender: :male))
+    lily     = graph.add(Turbine::Node.new(:lily,     gender: :female))
+
+    dede     = graph.add(Turbine::Node.new(:dede,     gender: :female))
+    javier   = graph.add(Turbine::Node.new(:javier,   gender: :male))
+
+    frank    = graph.add(Turbine::Node.new(:frank,    gender: :male))
+    sarah    = graph.add(Turbine::Node.new(:sarah,    gender: :female))
+
+    # Dunphy -----------------------------------------------------------------
+
+    # Phil
+    phil.connect_to(claire,  :spouse)
+    phil.connect_to(haley,   :child)
+    phil.connect_to(alex,    :child)
+    phil.connect_to(luke,    :child)
+
+    # Claire
+    claire.connect_to(phil,  :spouse)
+    claire.connect_to(haley, :child)
+    claire.connect_to(alex,  :child)
+    claire.connect_to(luke,  :child)
+
+    # Pritchett --------------------------------------------------------------
+
+    # Jay
+    jay.connect_to(gloria,     :spouse)
+    jay.connect_to(claire,     :child)
+    jay.connect_to(mitchell,   :child)
+    jay.connect_to(unnamed,    :child)
+    jay.connect_to(dede,       :divorced)
+
+    # Gloria
+    gloria.connect_to(jay,     :spouse)
+    gloria.connect_to(manny,   :child)
+    gloria.connect_to(unnamed, :child)
+    gloria.connect_to(javier,  :divorced)
+
+    # Tucker-Pritchett -------------------------------------------------------
+
+    mitchell.connect_to(cameron, :spouse)
+    mitchell.connect_to(lily,    :child)
+
+    cameron.connect_to(mitchell, :spouse)
+    cameron.connect_to(lily,     :child)
+
+    # Others -----------------------------------------------------------------
+
+    dede.connect_to(claire,   :child)
+    dede.connect_to(mitchell, :child)
+
+    javier.connect_to(manny, :child)
+
+    frank.connect_to(phil,   :child)
+    frank.connect_to(sarah,  :spouse)
+
+    sarah.connect_to(phil,   :child)
+    sarah.connect_to(frank,  :spouse)
+
+    graph
+  end
+end
+
+# Find out that Manny is Jay's step-child with:
+#
+#   jay = Turbine.stub.node(:jay)
+#   jay.out(:spouse).out(:child) - jay.out(:child)
+#
+#   # => #<Turbine::Collection {#<Turbine::Node key=:manny>}>
+#
+# ... or that Alex has two siblings:
+#
+#   alex = Turbine.stub.node(:alex)
+#   alex.in(:child).out(:child) - [alex]
+#
+# ... or that Jay and Gloria have a single "common" child:
+#
+#   graph = Turbine.stub
+#   jay, gloria = graph.node(:jay), graph.node(:gloria)
+#
+#   jay.out(:child) & gloria.out(:child)
+#
+#   # => #<Turbine::Collection {#<Turbine::Node key=:unnamed>}>
+#
+# ... or who are Luke's uncles and aunts:
+#
+#   graph = Turbine.stub
+#   luke  = graph.node(:luke)
+#
+#   parents      = luke.in(:child)
+#   grandparents = parents.in(:child)
+#
+#   # Remove Claire, Luke's mother:
+#   uncles_and_aunts = grandparents.out(:child) - parents
+#
+#   # And add the uncle and aunt spouses for the full list.
+#   uncles_and_aunts + uncles_and_aunts.out(:spouse)
+#
+#   # => #<Turbine::Collection {
+#          #<Turbine::Node key=:mitchell>,
+#          #<Turbine::Node key=:unnamed>,
+#          #<Turbine::Node key=:cameron>}>

data/lib/turbine.rb

@@ -0,0 +1,29 @@
+require 'tsort'
+require 'set'
+require 'forwardable'
+
+# On with the library...
+require 'turbine/properties'
+require 'turbine/algorithms/tarjan'
+require 'turbine/algorithms/filtered_tarjan'
+require 'turbine/edge'
+require 'turbine/errors'
+require 'turbine/graph'
+require 'turbine/pipeline/dsl'
+require 'turbine/pipeline/segment'
+require 'turbine/pipeline/trace'
+require 'turbine/pipeline/expander'
+require 'turbine/pipeline/filter'
+require 'turbine/pipeline/journal'
+require 'turbine/pipeline/journal_filter'
+require 'turbine/pipeline/pump'
+require 'turbine/pipeline/transform'
+require 'turbine/pipeline/traversal'
+require 'turbine/pipeline/sender'
+require 'turbine/pipeline/split'
+require 'turbine/pipeline/unique'
+require 'turbine/traversal/base'
+require 'turbine/traversal/breadth_first'
+require 'turbine/traversal/depth_first'
+require 'turbine/node'
+require 'turbine/version'

data/lib/turbine/algorithms/filtered_tarjan.rb

@@ -0,0 +1,33 @@
+module Turbine
+  module Algorithms
+    # Internal: A wrapper around the Ruby stdlib implementation of Tarjan's
+    # strongly connected components and topological sort algorithms. Restricts
+    # the sort to only those edges which match the filter.
+    class FilteredTarjan < Tarjan
+
+      # Public: Creates a FilteredTarjan instance. If you simply wish to
+      # filter by the edge label, the standard Tarjan class will do this with
+      # better performance.
+      #
+      # graph   - A Turbine graph whose nodes are to be sorted.
+      # &filter - Block which sleects the edges used to perform the sort.
+      #
+      # Returns a FilteredTarjan.
+      def initialize(graph, &filter)
+        super(graph, nil)
+        @filter = filter
+      end
+
+      #######
+      private
+      #######
+
+      # Internal: Used by TSort to iterate through each +out+ node.
+      #
+      # Returns nothing.
+      def tsort_each_child(node)
+        node.out_edges.select(&@filter).each { |edge| yield edge.to }
+      end
+    end # FilteredTarjan
+  end # Algorithms
+end # Turbine

data/lib/turbine/algorithms/tarjan.rb

@@ -0,0 +1,50 @@
+module Turbine
+  module Algorithms
+    # Internal: A wrapper around the Ruby stdlib implementation of Tarjan's
+    # strongly connected components and topological sort algorithms.
+    class Tarjan
+      include TSort
+
+      # Public: Creates a new Tarjan instance used for topologically sorting
+      # graphs.
+      #
+      # graph - A Turbine graph whose nodes are to be sorted.
+      # label - An optional label which will be used when traversing from a
+      #         node to its +out+ nodes.
+      #
+      # For example
+      #
+      #   Turbine::Algorithms::Tarjan.new(graph).tsort
+      #   # => [ [ #<Node key=one>, #<Node key=two>, #<Node key=three> ],
+      #          [ #<Node key=five> ],
+      #          [ #<Node key=six>, #<Node key=seven> ] ]
+      #
+      #   Turbine::Algorithms::Tarjan.new(graph, :spouse).tsort
+      #   # => [ ... ]
+      #
+      # Returns a Tarjan.
+      def initialize(graph, label = nil)
+        @nodes = graph.nodes
+        @label = label
+      end
+
+      #######
+      private
+      #######
+
+      # Internal: Used by TSort to iterate through each node in the graph.
+      #
+      # Returns nothing.
+      def tsort_each_node
+        @nodes.each { |node| yield node }
+      end
+
+      # Internal: Used by TSort to iterate through each +out+ node.
+      #
+      # Returns nothing.
+      def tsort_each_child(node)
+        node.nodes(:out, @label).each { |out| yield out }
+      end
+    end # Tarjan
+  end # Algorithms
+end # Turbine

data/lib/turbine/edge.rb

@@ -0,0 +1,94 @@
+module Turbine
+  # Edges represent a connection between an +from+ node and an +to+ node.
+  #
+  # Note that simply creating an Edge does not actually establish the
+  # connection between the two nodes. Rather than creating the Edge
+  # instance manually, Node can do this for you with +Node#connect_to+ and
+  # +Node#connect_via+:
+  #
+  #   jay    = Turbine::Node.new(:jay)
+  #   gloria = Turbine::Node.new(:gloria)
+  #
+  #   jay.connect_to(gloria, :spouse)
+  #   gloria.connect_to(jay, :spouse)
+  #
+  # However, if you want to do it manually (perhaps with a subclass of Edge),
+  # you should use +Node#connect_via+:
+  #
+  #   jay    = Turbine::Node.new(:jay)
+  #   gloria = Turbine::Node.new(:gloria)
+  #
+  #   jay_married_to_gloria = Turbine::Edge.new(jay, gloria, :spouse)
+  #   gloria_married_to_jay = Turbine::Edge.new(gloria, jay, :spouse)
+  #
+  #   jay.connect_via(jay_married_to_gloria)
+  #   gloria.connect_via(jay_married_to_gloria)
+  #
+  #   jay.connect_via(gloria_married_to_jay)
+  #   gloria.connect_via(gloria_married_to_jay)
+  #
+  class Edge
+    include Properties
+
+    # Public: The node which the edge leaves; the edge is an +out_edge+ on
+    # this node.
+    attr_reader :from
+
+    # Public: The node to which the edge points; the edge is an +in_edge+ on
+    # this node.
+    attr_reader :to
+
+    # Public: Returns the optional label assigned to the edge.
+    attr_reader :label
+
+    # Attribute aliases.
+    alias_method :parent, :from
+    alias_method :child,  :to
+
+    # Public: Creates a new Edge.
+    #
+    # from_node  - The Node from which the edge originates.
+    # in_node    - The Node to which the edge points.
+    # label      - An optional label for describing the nature of the
+    #              relationship between the two nodes.
+    # properties - Optional key/value properties to be associated with the
+    #              edge.
+    #
+    def initialize(from_node, to_node, label = nil, properties = nil)
+      @from  = from_node
+      @to    = to_node
+      @label = label
+
+      self.properties = properties
+    end
+
+    # Public: Determines if the +other+ edge is similar to this one.
+    #
+    # Two edges are considered similar if have the same +to+ and +from+ nodes,
+    # and their label is identical.
+    #
+    # Returns true or false.
+    def similar?(other)
+      other && other.to == @to && other.from == @from && other.label == @label
+    end
+
+    # Public: Returns a human-readable version of the edge.
+    def inspect
+      "#<#{ self.class.name } #{ to_s }>".sub('>', "\u27A4")
+    end
+
+    # Public: Returns a human-readable version of the edge by showing the from
+    # and to nodes, connected by the label.
+    def to_s
+      "#{ @from.key.inspect } -#{ @label.inspect }-> #{ @to.key.inspect }"
+    end
+
+    # Internal: A low-level method which retrieves the node in a given
+    # direction. Used for compatibility with Pipeline.
+    #
+    # Returns a Node.
+    def nodes(direction, *)
+      direction == :to ? @to : @from
+    end
+  end # Edge
+end # Turbine

data/lib/turbine/errors.rb

@@ -0,0 +1,74 @@
+module Turbine
+  # Error class which serves as a base for all errors which occur in Turbine.
+  TurbineError = Class.new(StandardError)
+
+  # Internal: Creates a new error class which inherits from TurbineError,
+  # whose message is created by evaluating the block you give.
+  #
+  # For example
+  #
+  #   MyError = error_class do |weight, limit|
+  #     "#{ weight } exceeds #{ limit }"
+  #   end
+  #
+  #   raise MyError.new(5000, 2500)
+  #   # => #<Turbine::MyError: 5000 exceeds 2500>
+  #
+  # Returns an exception class.
+  def self.error_class(superclass = TurbineError, &block)
+    Class.new(superclass) do
+      def initialize(*args) ; super(make_message(*args)) ; end
+      define_method(:make_message, &block)
+    end
+  end
+
+  # Added a node to a graph, when one already exists with the same key.
+  DuplicateNodeError = error_class do |key|
+    "Graph already has a node with the key #{ key.inspect }"
+  end
+
+  # Attempted an operation on a Node which does not exist.
+  NoSuchNodeError = error_class do |key|
+    "Graph does not contain a node with the key #{ key.inspect }"
+  end
+
+  # Added an edge between two nodes which was too similar to an existing edge.
+  # See Edge#similar?
+  DuplicateEdgeError = error_class do |node, edge|
+    "Another edge already exists on #{ node.inspect } which is too similar " \
+    "to #{ edge.inspect }"
+  end
+
+  # Attempted to set properties on an object, when the properties were not in
+  # the form of a hash, or were otherwise invalid in some way.
+  InvalidPropertiesError = error_class do |model, properties|
+    "Tried to assign properties #{ properties.inspect } on " \
+    "#{ model.inspect } - it must be a Hash, or subclass of Hash"
+  end
+
+  # Tried to access values from a non-existant Journal segment.
+  NoSuchJournalError = error_class do |name|
+    "No such upstream journal: #{ name.inspect }"
+  end
+
+  # Attempted to get trace information from a pipeline when tracing has not
+  # been enabled.
+  TracingNotEnabledError = error_class do |segment|
+    "You cannot get trace information from the #{ segment.inspect } " \
+    "segment as tracing is not enabled"
+  end
+
+  # Tried to enable tracing on a segment which doesn't support it.
+  NotTraceableError = error_class do |segment|
+    "You cannot enable tracing on pipelines with #{ segment.class.name } " \
+    "segments"
+  end
+
+  # Tried to topologically sort a graph which contains loops.
+  class CyclicError < TurbineError
+    def initialize(orig_exception)
+      set_backtrace(orig_exception.backtrace)
+      super(orig_exception.message)
+    end
+  end
+end # Turbine

data/lib/turbine/graph.rb

@@ -0,0 +1,113 @@
+module Turbine
+  # Contains nodes and edges.
+  class Graph
+
+    # Public: Creates a new graph.
+    def initialize
+      @nodes = {}
+    end
+
+    # Public: Adds the +node+ to the graph.
+    #
+    # node - The node to be added.
+    #
+    # Raises a DuplicateNodeError if the graph already contains a node with
+    # the same key.
+    #
+    # Returns the node.
+    def add(node)
+      if @nodes.key?(node.key)
+        raise DuplicateNodeError.new(node.key)
+      end
+
+      @nodes[node.key] = node
+    end
+
+    # Public: Removes the +node+ from the graph and disconnects any nodes
+    # which have edges to the +node+.
+    #
+    # node - The node to be deleted.
+    #
+    # Raises a NoSuchNodeError if the graph does not contain the given +node+.
+    #
+    # Returns the node.
+    def delete(node)
+      unless @nodes.key?(node.key)
+        raise NoSuchNodeError.new(node.key)
+      end
+
+      (node.edges(:out) + node.edges(:in)).each do |edge|
+        edge.from.disconnect_via(edge)
+        edge.to.disconnect_via(edge)
+      end
+
+      @nodes.delete(node.key)
+    end
+
+    # Public: Retrieves the node whose key is +key+.
+    #
+    # key - The key of the desired node.
+    #
+    # Returns the node, or nil if no such node is known.
+    def node(key)
+      @nodes[key]
+    end
+
+    # Public: All of the nodes in an array.
+    #
+    # Generally speaking, the nodes will be returned in the same order as
+    # they were added to the graph, however this may very depending on your
+    # Ruby implementation.
+    #
+    # Returns an array of nodes.
+    def nodes
+      @nodes.values
+    end
+
+    # Public: Topologically sorts the nodes in the graph so that nodes with
+    # no in edges appear at the beginning of the array, and those deeper
+    # within the graph are at the end.
+    #
+    # label - An optional label used to limit the edges used when traversing
+    #         from one node to its outward nodes.
+    #
+    # Raises CyclicError if the graph contains loops.
+    #
+    # Returns an array.
+    def tsort(label = nil)
+      Algorithms::Tarjan.new(self, label).tsort
+    rescue TSort::Cyclic => exception
+      raise CyclicError.new(exception)
+    end
+
+    # Public: Uses Tarjan's strongly-connected components algorithm to detect
+    # nodes which are interrelated.
+    #
+    # label - An optional label used to limit the edges used when traversing
+    #         from one node to its outward nodes.
+    #
+    # For example
+    #
+    #   graph.strongly_connected_components
+    #   # => [ [ #<Node key=one> ],
+    #          [ #<Node key=two>, #<Node key=three>, #<Node key=four> ],
+    #          [ #<Node key=five>, #<Node key=six ] ]
+    #
+    # Returns an array.
+    def strongly_connected_components(label = nil)
+      Algorithms::Tarjan.new(self, label).strongly_connected_components
+    end
+
+    # Public: A human-readable version of the graph.
+    #
+    # Returns a string.
+    def inspect
+      edge_count = @nodes.values.each_with_object(Set.new) do |node, edges|
+        edges.merge(node.edges(:out))
+      end.length
+
+      "#<#{self.class} (#{ @nodes.length } nodes, #{ edge_count } edges)>"
+    end
+
+  end # Graph
+end # Turbine