jumoku 0.1.3 → 0.2.0

data/README.md

@@ -1,5 +1,3 @@
-![Texte alternatif](http://img547.imageshack.us/img547/2932/logoJumoku.png "Jumoku logo")
-
 **Build and manipulate tree structures in Ruby.**
 
 ## Synopsis

data/lib/jumoku.rb

@@ -1,7 +1,6 @@
 libpath = File.expand_path(File.dirname(__FILE__))
 $:.unshift File.dirname(__FILE__) unless $:.include?(File.dirname(__FILE__)) || $:.include?(libpath)
 $: << libpath + '/../vendor/git/plexus/lib'
-puts $:.inspect
 
 require 'pathname'
 require 'pp'
@@ -9,15 +8,44 @@ require 'active_support'
 require 'facets'
 require 'plexus'
 
+# Jumoku provides you with several modules and classes to build and manipulate
+# tree graphs. Two basic implementations are available: undirected trees
+# ({RawUndirectedTree}) and directed trees ({RawDirectedTree}).
+#
+# {Tree} is derived from the undirected flavour and sticks to the mathematical
+# tree definition. {Arborescence} is derived from the directed flavour and is
+# likely to be used as the basis to modelize hierarchy structures, such as a
+# family tree, a file browser…
+#
+# Note that a node can be any Object. There is no "node type", therefore
+# arguments which re expected to be nodes are simply labelled as "`node`"
+# within this documentation. A nice object type to use as a node may be an
+# OpenStruct or an [OpenObject](http://facets.rubyforge.org/apidoc/api/more/classes/OpenObject.html)
+# (from the Facets library), both turning nodes into versatile handlers.
+#
 module Jumoku
-  # jumoku internals: graph builders and additionnal behaviors
-  autoload :TreeAPI,        'jumoku/tree_api'
-  autoload :RawTreeBuilder, 'jumoku/builders/raw_tree'
-  autoload :TreeBuilder,    'jumoku/builders/tree'
-  autoload :RawTree,        'jumoku/classes/tree_classes'
-  autoload :Tree,           'jumoku/classes/tree_classes'
-  autoload :Branch,         'jumoku/support/branch'
+  # API, core implementations
+  autoload :TreeAPI,                  'jumoku/tree_api'
+  autoload :Shared,                   'jumoku/builders/shared'
+  autoload :Extended,                 'jumoku/builders/extended'
 
+  # branch types
+  autoload :UndirectedBranch,         'jumoku/support/branch'
+  autoload :DirectedBranch,           'jumoku/support/branch'
+
+  # tree builders
+  autoload :RawUndirectedTreeBuilder, 'jumoku/builders/raw_undirected_tree'
+  autoload :RawDirectedTreeBuilder,   'jumoku/builders/raw_directed_tree'
+  autoload :TreeBuilder,              'jumoku/builders/tree'
+  autoload :ArborescenceBuilder,      'jumoku/builders/arborescence'
+
+  # tree classes
+  autoload :RawDirectedTree,          'jumoku/classes/tree_classes'
+  autoload :RawUndirectedTree,        'jumoku/classes/tree_classes'
+  autoload :Tree,                     'jumoku/classes/tree_classes'
+  autoload :Arborescence,             'jumoku/classes/tree_classes'
+
+  # support
   require 'jumoku/support/support'
   require 'jumoku/ext/ext'
 end

data/lib/jumoku/builders/arborescence.rb

@@ -0,0 +1,11 @@
+module Jumoku
+  # This builder extends {RawDirectedTreeBuilder} implementation.
+  #
+  # It provides a directed tree which acts as a hierarchical structure, known
+  # as an arborescence.
+  #
+  module ArborescenceBuilder
+    include RawDirectedTreeBuilder
+    include Extended
+  end
+end

data/lib/jumoku/builders/extended.rb

@@ -0,0 +1,327 @@
+module Jumoku
+  # This module provides methods extending the core TreeAPI. Most of those
+  # methods are cloning the receiver tree and perform their operation on the
+  # duplicated object. Some other are helpers adding reflexivity to trees.
+  # There are also a few in-place methods.
+  #
+  module Extended
+    # Non destructive version of {RawTreeBuilder#add_node!} (works on a copy of the tree).
+    #
+    # @overload add_node!(n)
+    #   @param [node] n
+    # @overload add_node!(b)
+    #   @param [Branch] b Branch[node i, node j, label l = nil]; if i (j) already exists, then j (i) must not exist
+    # @return [Tree] a modified copy of `self`
+    # @see RawTreeBuilder#add_node!
+    #
+    def add_node(n, l = nil)
+      _clone.add_node!(n, l)
+    end
+
+    # Non destructive version {RawTreeBuilder#add_branch!} (works on a copy of the tree).
+    #
+    # @overload add_branch!(i, j, l = nil)
+    #   @param [node] i
+    #   @param [node] j
+    #   @param [Label] l
+    # @overload add_branch!(b)
+    #   @param [Branch] b Branch[node i, node j, label l = nil]; if i (j) already exists, then j (i) must not exist
+    # @return [Tree] a modified copy of `self`
+    # @see RawTreeBuilder#add_branch!
+    #
+    def add_branch(i, j = nil, l = nil)
+      _clone.add_branch!(i, j, l)
+    end
+
+    # Non destructive version of {RawTreeBuilder#remove_node!} (works on a copy of the tree).
+    #
+    # @param [node] n
+    # @return [Tree] a modified copy of `self`
+    # @see RawTreeBuilder#remove_node!
+    #
+    def remove_node(n)
+      _clone.remove_node!(n)
+    end
+
+    # Non destructive version {RawTreeBuilder#remove_branch!} (works on a copy of the tree).
+    #
+    # You cannot remove non terminal branches as it would break the connectivity constraint
+    # of the tree.
+    #
+    # @param [node] i
+    # @param [node] j
+    # @return [Tree] a modified copy of `self`
+    # @see RawTreeBuilder#remove_branch!
+    #
+    def remove_branch(i, j = nil, *params)
+      _clone.remove_branch!(i, j)
+    end
+
+    # Adds all specified nodes to the node set.
+    #
+    # The nodes defines implicit branches, that is it is mandatory to provide
+    # an odd number of connected nodes which do not form cycles. You may specify
+    # Branch objects within the list, though.
+    #
+    # Valid usage:
+    #
+    #     tree = Tree.new                # an empty tree
+    #     tree.add_nodes!(1,2, 2,3, 3,4) # tree.nodes => [1, 2, 3, 4]
+    #                                    # branches are (1-2), (2-3), (3-4)
+    #     tree.add_nodes!(1,2, 2,3, Branch.new(3,4), 10,1)
+    #     tree.add_nodes! [1,2, 2,3, 3,4]
+    #
+    # Invalid usages:
+    #
+    #     tree = Tree.new                # an empty tree
+    #     tree.add_nodes!(1, 2, 3)       # even number of nodes
+    #     tree.add_nodes!(1,2, 2,3, 3,1) # cycle
+    #     tree.add_nodes!(1,2, 4,5)      # not connected
+    #
+    # A helper exist to make it easy to add nodes in a suite.
+    # See {TreeBuilder#add_consecutive_nodes! add_consecutive_nodes!}.
+    #
+    # @param [#each] *a an Enumerable nodes set
+    # @return [Tree] `self`
+    #
+    def add_nodes!(*a)
+      a = a.flatten.expand_branches!
+      if a.size == 1                                   # This allows for using << to add the root as well,
+        if empty?                                      # so that you may write:
+          add_node! a.only                             # Tree.new << :root << [:root, 1] << [1,2, 2,3, Branch.new(3,4)]...
+        else
+          raise RawTreeError, "Cannot add a node without a neighbour."
+        end
+      else
+        a.expand_branches!.each_nodes_pair { |pair| add_branch! pair[0], pair[1] }
+      end
+      self
+    end
+    alias << add_nodes!
+
+    # Same as {TreeBuilder#add_nodes! add_nodes!} but works on a copy of the receiver.
+    #
+    # @param [#each] *a an Enumerable nodes set
+    # @return [Tree] a modified copy of `self`
+    #
+    def add_nodes(*a)
+      _clone.add_nodes!(*a)
+    end
+
+    # Allows for adding consecutive nodes, each nodes being connected to their previous and
+    # next neighbours.
+    #
+    # You may pass {Branch branches} within the nodes list.
+    #
+    #     Tree.new.add_consecutive_nodes!(1, 2, 3, :four, Branch.new(:foo, "bar")).branches
+    #     # => (1=2, 2=3, 3=:four, :four=:foo, :foo="bar")
+    #
+    # @param [Array(nodes)] *a flat array of unique nodes
+    # @return [Tree] `self`
+    #
+    def add_consecutive_nodes!(*a)
+      # FIXME: really this may not be as efficient as it could be.
+      # We may get rid of nodes duplication (no expand_branches!)
+      # and add nodes by pair, shifting one node at a time from the list.
+      add_nodes!(a.expand_branches!.create_nodes_pairs_list)
+      self
+    end
+
+    # Same as {TreeBuilder#add_consecutive_nodes! add_consecutive_nodes!} but
+    # works on a copy of the receiver.
+    #
+    # @param [Array(nodes)] *a flat array of unique nodes
+    # @return [Tree] a modified copy of `self`
+    #
+    def add_consecutive_nodes(*a)
+      _clone.add_consecutive_nodes!(*a)
+    end
+
+    # Adds all branches mentionned in the specified Enumerable to the branch set.
+    #
+    # Elements of the Enumerable can be either two-element arrays or instances of
+    # {Branch}.
+    #
+    # @param [#each] *a an Enumerable branches set
+    # @return [Tree] `self`
+    #
+    def add_branches!(*a)
+      a.expand_branches!.each_nodes_pair { |pair| add_branch! pair[0], pair[1] }
+      self
+    end
+
+    # Same as {TreeBuilder#add_branches! add_branches!} but works on a copy of the receiver.
+    #
+    # @param [#each] *a an Enumerable branches set
+    # @return [Tree] a modified copy of `self`
+    #
+    def add_branches(*a)
+      _clone.add_branches!(*a)
+    end
+
+    # Removes all nodes mentionned in the specified Enumerable from the tree.
+    #
+    # The process relies on {RawTreeBuilder#remove_node! remove_node!}.
+    #
+    # @param [#each] *a an Enumerable nodes set
+    # @return [Tree] `self`
+    #
+    def remove_nodes!(*a)
+      a.flatten.each { |v| remove_node! v }
+      self
+    end
+    alias delete_nodes! remove_nodes!
+
+    # Same as {TreeBuilder#remove_nodes! remove_nodes!} but works on a copy of the receiver.
+    #
+    # @param [#each] *a a node Enumerable set
+    # @return [Tree] a modified copy of `self`
+    #
+    def remove_nodes(*a)
+      _clone.remove_nodes!(*a)
+    end
+    alias delete_nodes remove_nodes
+
+    # Removes all branches mentionned in the specified Enumerable from the tree.
+    #
+    # @param [#each] *a an Enumerable branches set
+    # @return [Tree] `self`
+    #
+    def remove_branches!(*a)
+      a.expand_branches!.each_nodes_pair { |pair| remove_branch! pair[0], pair[1] }
+      self
+    end
+    alias delete_branches! remove_branches!
+
+    # Same as {TreeBuilder#remove_branches! remove_branches!} but works on a copy of the receiver.
+    #
+    # @param [#each] *a an Enumerable branches set
+    # @return [Tree] a modified copy of `self`
+    # @see RawTreeBuilder#remove_branch!
+    #
+    def remove_branches(*a)
+      _clone.remove_branches!(*a)
+    end
+    alias delete_branches remove_branches
+
+    # Returns true if the specified node belongs to the tree.
+    #
+    # This is a default implementation that is of O(n) average complexity.
+    # If a subclass uses a hash to store nodes, then this can be
+    # made into an O(1) average complexity operation.
+    #
+    # @param [node] n
+    # @return [Boolean]
+    #
+    def node?(n)
+      nodes.include?(n)
+    end
+    alias has_node? node?
+
+    # Returns true if all specified nodes belong to the tree.
+    #
+    # @param [nodes]
+    # @return [Boolean]
+    #
+    def nodes?(*maybe_nodes)
+      maybe_nodes.all? { |node| nodes.include? node }
+    end
+    alias has_nodes? nodes?
+
+    # Returns true if any of the specified nodes belongs to the tree.
+    #
+    # @param [nodes]
+    # @return [Boolean]
+    #
+    def nodes_among?(*maybe_nodes)
+      maybe_nodes.any? { |node| nodes.include? node }
+    end
+    alias has_nodes_among? nodes_among?
+    alias has_node_among?  nodes_among?
+    # FIXME: these helpers could be backported into Plexus.
+
+    # Returns true if i or (i,j) is a {Branch branch} of the tree.
+    #
+    # @overload branch?(a)
+    #   @param [Branch] a
+    # @overload branch?(i, j)
+    #   @param [node] i
+    #   @param [node] j
+    # @return [Boolean]
+    #
+    def branch?(*args)
+      branches.include?(edge_convert(*args))
+    end
+    alias has_branch? branch?
+
+    # Returns true if the specified branches are a subset of or match exactly the
+    # branches set of the tree (no ordering criterion).
+    #
+    # Labels are not part of the matching constraint: only connected nodes
+    # matter in defining branch equality.
+    #
+    # @param [*Branch, *nodes] *maybe_branches a list of branches, either as Branch
+    #   objects or as nodes pairs
+    # @return [Boolean]
+    #
+    def branches?(*maybe_branches)
+      list = maybe_branches.create_branches_list(_branch_type)
+      all = true
+
+      # Branch objects are really Edge objects within Plexus, therefore
+      # cannot rely on #eql? to compare those structures and must drop
+      # down to the attributes.
+      list.each do |e| # Jumoku::Branch structs
+        all = branches.any? do |b| # Plexus::Edge structs
+          (b[:source] == e[:source]) and (b[:target] == e[:target])
+        end
+      end
+      all
+    end
+    alias has_branches? branches?
+
+    # Returns true if actual branches are included in the specified set of branches
+    # (no ordering criterion).
+    #
+    # Labels are not part of the matching constraint: only connected nodes
+    # matter in defining equality.
+    #
+    # @param [*Branch, *nodes] *maybe_branches a list of branches, either as Branch
+    #   objects or as nodes pairs
+    # @return [Boolean]
+    #
+    def branches_among?(*maybe_branches)
+      list = maybe_branches.create_branches_list(_branch_type)
+      all = true
+
+      # Branch objects are really Edge objects within Plexus, therefore
+      # cannot rely on #eql? to compare those structures and must drop
+      # down to the attributes.
+      branches.each do |e| # Plexus::Edge structs
+        all = list.any? do |b| # Jumoku::Branch structs
+          (b[:source] == e[:source]) and (b[:target] == e[:target])
+        end
+      end
+      all
+    end
+    alias has_branches_among? branches_among?
+
+    # Number of nodes.
+    #
+    # @return [Integer]
+    #
+    def num_nodes
+      nodes.size
+    end
+    alias number_of_nodes num_nodes
+
+    # Number of branches.
+    #
+    # @return [Integer]
+    #
+    def num_branches
+      branches.size
+    end
+    alias number_of_branches num_branches
+  end
+end

data/lib/jumoku/builders/raw_directed_tree.rb

@@ -0,0 +1,33 @@
+module Jumoku
+  # A {RawDirectedTree} relax the undirected constraint of trees as defined in
+  # Graph Theory. They remain connected and acyclic.
+  #
+  # It thus uses Plexus::DirectedGraphBuilder as its backend.
+  #
+  # It offers limited functionalities, therefore the main tree structure you'll likely to
+  # use is its extended version, {Arborescence}.
+  module RawDirectedTreeBuilder
+    include Plexus::DirectedGraphBuilder
+    include Shared
+
+    # This method is called by the specialized implementations upon tree creation.
+    #
+    # Initialization parameters can include:
+    #
+    # * an array of branches to add
+    # * one or several trees to copy (will be merged if multiple)
+    #
+    # @param *params [Hash] the initialization parameters
+    # @return enhanced Plexus::DirectedGraph
+    #
+    def initialize(*params)
+      super(*params) # Delegates to Plexus.
+    end
+
+    private
+
+    def _branch_type
+      DirectedBranch
+    end
+  end
+end

data/lib/jumoku/builders/raw_undirected_tree.rb

@@ -0,0 +1,37 @@
+module Jumoku
+  # A {RawUndirectedTree} sticks to the standard definition of trees in Graph Theory:
+  #  * undirected,
+  #  * connected,
+  #  * acyclic.
+  # It thus uses Plexus::UndirectedGraphBuilder as its backend, which ensure the first
+  # constraint.
+  #
+  # {RawUndirectedTreeBuilder} ensures the two remaining constraints are satisfied.
+  # It offers limited functionalities, therefore the main tree structure you'll likely to
+  # use is its extended version, {TreeBuilder}.
+  #
+  module RawUndirectedTreeBuilder
+    include Plexus::UndirectedGraphBuilder
+    include Shared
+
+    # This method is called by the specialized implementations upon tree creation.
+    #
+    # Initialization parameters can include:
+    #
+    # * an array of branches to add
+    # * one or several trees to copy (will be merged if multiple)
+    #
+    # @param *params [Hash] the initialization parameters
+    # @return enhanced Plexus::UndirectedGraph
+    #
+    def initialize(*params)
+      super(*params) # Delegates to Plexus.
+    end
+
+    private
+
+    def _branch_type
+      UndirectedBranch
+    end
+  end
+end