jumoku 0.1.1

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) Jean-Denis Vauguet <jd@vauguet.fr>
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,112 @@
+![Texte alternatif](http://img547.imageshack.us/img547/2932/logoJumoku.png "Jumoku logo")
+
+**Build and manipulate tree structures in Ruby.**
+
+## Synopsis
+
+Jumoku provides you with tree structures and related tools to perform manipulation and computation the easy way. Trees are a subset of graphs, which are used in a whole slew of computer science and mathematical problems: network modelization, datasets storage, scientific computation, load balancing, games and AI designs, … Trees are frequently used to mimic hierarchal structures such as filesystems, or modelize decisionnal patterns, for instance.
+
+Jumoku is built upon [Graphy](http://github.com/bruce/graphy "Graphy on Github"), a ruby-powered Graph Theory library, and aims at being a fully-fledged, pithy solution for tree-like structures managment. See below for additionnal information about graphs, trees, arborescences, why they're different and how to make good use of them.
+
+## A few words about *trees*
+
+A Tree is a graph subject to three basic constraints: nodes are all connected, they must not form any loop, and the branches binding nodes have no preferential direction. A tree is not compelled to have a root node and leaves as you may think *prima facie*. Trees with such features are called arborescences and Jumoku has support for them, too.
+
+Jumoku (*currently under early development stage*) provides you with the following structures:
+
+* RawTree: a tree-graph with only basic features
+* **Tree**: a tree-graph with extended features built upon RawTree. That's what you'd want to use as a basic tree structure
+* AVLTree (*not yet*)
+* RedBlackTree (*not yet*)
+* **Arborescence** (*not yet*): the structure everybody thinks of when asked about "trees", with a root, internal nodes and leaves
+
+You can also extend those structures with hybrid behaviors (not Graph Theory compliant but may be useful):
+
+* Directed (*not yet*): relax the *undirected* constraint
+* Loopy (*not yet*): relax the *acyclic* constraint
+* Atomic (*not yet*): relax the *connected* constraint
+
+## Basic usage
+
+To create an instance of a tree, you may use either inheritance or mixins.
+
+### Inheritance or direct initialization
+
+``` ruby
+class MyTree < Jumoku::Tree; end
+tree = MyTree.new
+
+# or even simpler:
+tree = Jumoku::Tree.new
+```
+
+### Mixing-in a "builder" module
+
+``` ruby
+class MyTree
+  include Jumoku::RawTreeBuilder
+end
+tree = MyTree.new
+```
+
+Actually the RawTree class is nothing but the mixin code snippet above.
+
+### What you get
+
+`tree` is now a Tree object, shipping with some default options:
+
+* it is a valid tree *per se* (an undirected, acyclic, connected graph)
+* Jumoku API's methods will ensure it remains so
+* it has no constraint on its branching number (the number of branches per node)
+
+## Install, first steps and bootstraping
+
+In order to play with Jumoku, you must:
+
+``` bash
+gem install jumoku
+```
+
+Now you can play in IRB:
+
+``` bash
+$ irb
+ruby-1.9.1-p378 > require 'Jumoku'
+=> true
+ruby-1.9.1-p378 > include Jumoku # so you won't have to prefix everything with "Jumoku::"
+=> Object
+ruby-1.9.1-p378 > t = Tree.new
+=> #<Jumoku::Tree:0x000000020d5ac8 @vertex_dict={}, @vertex_labels={}, @edge_labels={}, @allow_loops=false, @parallel_edges=false, @edgelist_class=Set> 
+ruby-1.9.1-p378 > t.methods
+=> # lot of stuff hopefully :)
+```
+
+A good way to get you started is by [reading the doc online](http://rdoc.info/projects/chikamichi/Jumoku "Jumoku on rdoc.info"). You can locally generate the doc with any of the following commands (you'll need to have the `yard` gem installed):
+
+``` bash
+rake yard
+yardoc
+```
+
+Be sure to take a look at the tests in `spec/` as well, as they document the public API extensively.
+
+## What about graphs?
+
+Trees are just simple graphs, with specific constraints on edges (branches) and vertices (nodes). In graph theory, a tree is defined as a graph which is undirected, acyclic and connected. A forest is a disjoint union of trees. Let's review those constraints:
+
+* undirected: the branches of a tree have no direction;
+* acyclic: a cycle is defined as a path such that the starting node and the ending node are the same. Such paths are forbidden in a tree;
+* connected: a tree is such that pair of distinct nodes can be connected through some path (not a cycle).
+
+This is restrictive, but not *that* restrictive. Instinctively, a tree structure would rather be described as an arborescence, with a root and some leaves. That's what you would use to use to modelize nested directories, for instance. Such a structure has additional constraints, and it makes sense to derive it from the more generalist tree*-as-in-graph-theory* structure, under the name "arborescence".
+
+Therefore, it is easy to implement those structures using graphs. Fortunately, several ruby graph libraries exist (and even a ruby binding for the igraph C backend, but that'd be a burden to use). Jumoku makes use of the most up-to-date project among those available, [Graphy](http://github.com/bruce/graphy "Graphy on Github").
+
+## License
+
+See the LICENSE file.
+
+## Contributing
+
+Fork, hack, request!
+

data/Rakefile

@@ -0,0 +1,25 @@
+# encoding: UTF-8
+require 'rubygems'
+begin
+  require 'bundler/setup'
+rescue LoadError
+  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+end
+
+require 'rake'
+require 'rake/rdoctask'
+
+require 'rspec/core'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec
+
+Rake::RDocTask.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'Logg'
+  rdoc.options << '--line-numbers' << '--inline-source'
+  rdoc.rdoc_files.include('README.rdoc')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/lib/jumoku.rb

@@ -0,0 +1,21 @@
+$:.unshift File.dirname(__FILE__) unless
+  $:.include?(File.dirname(__FILE__)) || $:.include?(File.expand_path(File.dirname(__FILE__)))
+
+require 'pathname'
+require 'pp'
+require 'active_support'
+require 'facets'
+require 'graphy'
+
+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'
+
+  require 'jumoku/support/support'
+  require 'jumoku/ext/ext'
+end

data/lib/jumoku/builders/raw_tree.rb

@@ -0,0 +1,243 @@
+module Jumoku
+  # This module provides the basic routines needed to implement the specialized builders:
+  # {TreeBuilder}, {BinaryTreeBuilder}, … each of them streamlining {RawTreeBuilder}'s
+  # behavior. Those implementations are under the control of the {TreeAPI}.
+  #
+  # A {RawTree} sticks to the standard definition of trees in Graph Theory: undirected,
+  # connected, acyclic graphs. Using Graphy::UndirectedGraphBuilder as its backend,
+  # {RawTreeBuilder} ensures the two remaining constraints are satisfied (connected and
+  # acyclic). {RawTreeBuilder RawTree} offers limited functionalities, therefore the main
+  # tree structure you'll likely to use is its extended version, {TreeBuilder Tree}. A
+  # {Tree} share the same behavior but is a fully-fledged object with user-friendly public
+  # methods built upon {RawTree}'s internals.
+  #
+  # Note that a node can be any Object. There is no "node type", therefore arguments which
+  # are expected to be nodes are simply labelled as "`node`". A nice object type to us as
+  # a node would be an OpenStruct or an
+  # [OpenObject](http://facets.rubyforge.org/apidoc/api/more/classes/OpenObject.html)
+  # (from the Facets library), as it turns nodes into versatile handlers.
+  #
+  # This builder defines a few methods not required by the API so as to maintain consistency
+  # in the DSL.
+  module RawTreeBuilder
+    include Graphy::UndirectedGraphBuilder
+
+    # 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 [RawTree]
+    def initialize(*params)
+      class << self
+        self
+      end.module_eval do
+        # Ensure the builder abides by its API requirements.
+        include Jumoku::TreeAPI
+      end
+      super(*params) # Delegates to Graphy.
+    end
+
+    # Ensure trees are seen as undirected graphs.
+    #
+    # @return [Boolean] false
+    def directed?
+      return false
+    end
+    # FIXME: should be able to reach Graphy's method ?!
+
+    # Adds the node to the tree.
+    #
+    # For convenience, you may pass a branch as the parameter,
+    # which one node already exists in the tree and the other is
+    # to be added.
+    #
+    # @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 [RawTree] self
+    def add_node! u, v = nil
+      if nodes.empty?
+        add_vertex! u
+      elsif u.is_a? Jumoku::Branch
+        add_branch! u
+      elsif not v.nil?
+        add_branch! u, v
+      else
+        # Ensure the connected constraint.
+        raise RawTreeError, "In order to add a node to the tree, you must specify another node to attach to."
+      end
+    end
+
+    # Adds a new branch to the tree.
+    #
+    # As a tree is an undirected structure, the order of the parameters is of
+    # no importance, that is: `add_branch!(u,v) == add_branch!(v,u)`.
+    #
+    # @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 [RawTree] self
+    def add_branch! u, v = nil, l = nil
+      if has_node? u and has_node? v
+        unless has_branch? u, v
+          # Ensure the acyclic constraint.
+          raise RawTreeError, "Can't form a cycle within a tree."
+        end
+      end
+
+      # TODO: DRY this up.
+      if u.is_a? Jumoku::Branch
+        v = u.target
+        u = u.source
+      end
+
+      if has_node? u or has_node? v or nodes.empty?
+        add_edge! u, v, l
+      else
+        # Ensure the connected constraint.
+        raise RawTreeError, "Can't add a dead branch to a tree."
+      end
+    end
+
+    # Removes a node from the tree.
+    #
+    # You cannot remove non terminal nodes as it would break the
+    # connectivity constraint of the tree.
+    #
+    # I may add an option which would allow to force removal
+    # of internal nodes and return two new trees from this
+    # destructive operation.
+    #
+    # @param [node] u
+    # @return [RawTree] self
+    def remove_node!(u, force = false)
+      if terminal? u or force
+        remove_vertex! u
+      else
+        # Ensure the connected constraint.
+        raise RawTreeError, "Can't remove a non terminal node in a tree"
+      end
+    end
+
+    # Removes a branch from the tree.
+    #
+    # You cannot remove non terminal branches as it would break
+    # the connectivity constraint of the tree.
+    #
+    # I may add an option which would allow to force removal
+    # of internal nodes and return two new trees from this
+    # destructive operation.
+    #
+    # @overload remove_branch!(i, j)
+    #   @param [node] i
+    #   @param [node] j
+    # @overload remove_branch!(b)
+    #   @param [Branch] b
+    # @return [RawTree] self
+    def remove_branch! u, v = nil
+      if u.is_a? Jumoku::Branch
+        v = u.target
+        u = u.source
+      end
+
+      if has_node? u and has_node? v
+        if terminal? u and terminal? v
+          remove_edge! u, v
+          # empty the tree if u and v are the last two nodes, for they're
+          # not connected anymore
+          if [u, v].all? { |node| nodes.include? node } and nodes.size == 2
+            remove_node! u, true
+            remove_node! v, true
+          end
+        elsif terminal? u and not terminal? v
+          remove_node! u
+        elsif terminal? v and not terminal? u
+          remove_node! v
+        else
+          raise RawTreeError, "Can't remove a non terminal branch in a tree."
+        end
+      else
+        raise RawTreeError, "Can't remove a branch which does not exist."
+      end
+    end
+    # TODO: add an option to force nodes deletion upon branch deletion
+    # (:and_nodes => true) ; called by a wrapping method
+    # remove_branch_and_nodes, alias break_branch
+    # (and their ! roomates).
+
+    # The nodes of the tree in a 1D array.
+    #
+    # @return [Array(node)]
+    def nodes
+      vertices
+    end
+
+    # The terminal nodes of the tree in a 1D array.
+    #
+    # @return [Array(node)] only terminal nodes (empty array if no terminal nodes,
+    #   but should never happen in a tree).
+    def terminal_nodes
+      nodes.inject([]) do |t_nodes, node|
+        t_nodes << node if terminal?(node)
+        t_nodes # must return t_nodes explicitily because
+                # (rubydoc Enumerable#inject) "at each step, memo is set to the value returned by the block"
+                # (sets t_nodes to nil otherwise).
+      end
+    end
+    alias boundaries terminal_nodes
+
+    # The branches of the tree in a 1D array.
+    #
+    # @return [Array(Branch)]
+    def branches
+      edges
+    end
+
+    # Aliasing.
+    alias has_node? has_vertex?
+    alias has_branch? has_edge?
+
+    # Tree helpers.
+
+    # Checks whether the tree is *really* a valid tree, that is if the
+    # following conditions are fulfilled:
+    #
+    # * undirected
+    # * acyclic
+    # * connected
+    #
+    # @return [Boolean]
+    def valid?
+      acyclic? and connected? and not directed?
+    end
+
+    # Is the node a terminal node?
+    #
+    # @return [Boolean]
+    def terminal? u
+      if has_node? u
+        # root is always terminal, otherwise check whether degree is unitary
+        nodes == [u] ? true : (degree(u) == 1)
+      else
+        raise RawTreeNodeError, "Not a node of this tree."
+      end
+    end
+    alias has_terminal_node? terminal?
+
+    # Is the tree empty?
+    #
+    # @return [Boolean]
+    def empty?
+      nodes.empty?
+    end
+  end
+end

data/lib/jumoku/builders/tree.rb

@@ -0,0 +1,336 @@
+module Jumoku
+  # This builder extends the cheap implementation {RawTreeBuilder}, which
+  # purpose is to implement the {TreeAPI}. {TreeBuilder} provides extended
+  # functionalities and acts as the main tree structure you may use, either
+  # by mixing-in this module or by inheritance of the associated {Tree} class.
+  #
+  #     tree = Tree.new
+  #
+  #     # or
+  #
+  #     class MyTree < Tree
+  #       # your stuff
+  #     end
+  #     tree = MyTree.new
+  #
+  #     # or
+  #
+  #     class MyTree
+  #       include TreeBuilder
+  #       # your stuff
+  #     end
+  #     tree = MyTree.new
+  module TreeBuilder
+    include RawTreeBuilder
+
+    def initialize(*params)
+      super(*params)
+    end
+
+    # 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)
+      x = self.class.new(self)
+      x.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)
+      x = self.class.new(self)
+      x.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)
+      x = self.class.new(self)
+      x.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)
+      x = self.class.new(self)
+      x.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)
+      x = self.class.new(self)
+      x.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.
+    #
+    #     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)
+      x = self.class.new(self)
+      x.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)
+      x = self.class.new(self)
+      x.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)
+      x = self.class.new(self)
+      x.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)
+      x = self.class.new(self)
+      x.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 Graphy.
+
+    # 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
+      all = true
+
+      # Branch objects are really Edge objects within Graphy, 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| # Graphy::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
+      all = true
+
+      # Branch objects are really Edge objects within Graphy, therefore
+      # cannot rely on #eql? to compare those structures and must drop
+      # down to the attributes.
+      branches.each do |e| # Graphy::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/classes/tree_classes.rb

@@ -0,0 +1,7 @@
+module Jumoku
+  # A generic {RawTreeBuilder RawTree} class you can inherit from.
+  class RawTree; include RawTreeBuilder; end
+
+  # The main tree class to use. Fully-fledged tree structure with user-friendly public API.
+  class Tree;    include TreeBuilder;    end
+end

data/lib/jumoku/ext/ext.rb

@@ -0,0 +1,50 @@
+class Array
+  # Takes a flat array of nodes pairs and yield
+  # them to the block.
+  def each_nodes_pair
+    raise if self.size % 2 != 0
+    each_by(2) { |pair| yield pair }
+  end
+
+  # Fetches the positions of Branch items in an array,
+  # and expands them in place as nodes pairs.
+  #
+  #     expand_branches!(1,2, Branch.new(2, 3), 3,4, 4,5)
+  #     # => 1,2, 2,3, 3,4, 4,5
+  #
+  # @param [*nodes, *Branch] *a a flat list of nodes pairs and branches
+  # @return [*nodes] a flat list of nodes pairs
+  def expand_branches!
+    branches_positions = self.dup.map_send(:"is_a?", Jumoku::Branch).map_with_index { |e,i| i if e == true }.compact
+    # obviously positions will gain an offset of 1 for each expanded branch,
+    # so let's correct this right away
+    branches_positions = branches_positions.map_with_index { |e,i| e += i }
+    branches_positions.each do |pos|
+      branch = self.delete_at pos
+      self.insert pos,   branch.source
+      self.insert pos+1, branch.target
+    end
+    return self
+  end
+
+  def create_pairs
+    self.map_with_index { |e,i| ((pairs ||= []) << e).concat(self.values_at(i+1)) }[0..-2]
+  end
+
+  # Creates nodes pairs from a flat array specifying unique nodes.
+  #
+  #     b = [1, 2, 3, "foo", :bar, Array.new]
+  #     b.create_nodes_pairs
+  #     => [1, 2, 2, 3, 3, "foo", "foo", :bar, :bar, []]
+  #
+  # @return [Array(nodes)]
+  def create_nodes_pairs_list
+    self.create_pairs.flatten(1)
+  end
+
+  def create_branches_list
+    branches = []
+    self.expand_branches!.each_by(2) { |pair| branches << Jumoku::Branch.new(pair[0], pair[1]) }
+    branches
+  end
+end

data/lib/jumoku/raw_tree_node.rb

@@ -0,0 +1,27 @@
+module Jumoku
+  module RawTree
+
+    # This module describes a raw tree node.
+    #
+    # You can include it in a class of your own to make it act
+    # as a raw tree node, while customizing behaviors.
+    module Node
+
+      # Creates a new node.
+      #
+      # @param [#to_s, #to_sym] name a valid name, considering the :names_as options
+      #   passed to the raw tree you want to create a node for.
+      # @param [Object] data the data field type to use. Defaults to an empty OpenObject
+      # @param [Array(#to_s)] children an array of children nodes ids
+      #
+      # @return [OpenObject] the node as an OpenObject instance
+      def create name, data = OpenObject.new, children = []
+        @name = name
+        @data = data
+        @children = children
+
+        OpenObject.new(:name => @name, :data => @data, :children => @children)
+      end
+    end
+  end
+end

data/lib/jumoku/support/branch.rb

@@ -0,0 +1,4 @@
+module Jumoku
+  class Branch < Graphy::Edge
+  end
+end

data/lib/jumoku/support/support.rb

@@ -0,0 +1,15 @@
+module Jumoku
+  # Base error class for the library.
+  class JumokuError < StandardError; end
+
+  # Raised in several circumstances when the basic constraints related
+  # to a tree are not fulfilled (undirected, acyclic, connected).
+
+  class RawTreeError < JumokuError; end
+  # Error related to nodes.
+
+  class RawTreeNodeError < RawTreeError; end
+  # Raised if one attempts to add an already existing branch to a tree.
+
+  class BranchAlreadyExistError < JumokuError; end
+end

data/lib/jumoku/tree_api.rb

@@ -0,0 +1,27 @@
+module Jumoku
+  # This module defines the minimum set of functions required to make a tree that can
+  # use the algorithms defined by this library.
+  #
+  # Each implementation module must implement the following routines:
+  #
+  # * add_node!(n, l = nil) — adds a node to the tree and return the tree; l is an optional label (see Graphy library).
+  # * add_branch!(i, j = nil, l = nil) — adds a branch to the tree and return the tree. i can be a {Branch}, or (i,j) a node pair; l is an optional label.
+  # * remove_node!(n) — removes a node from the tree and return the tree.
+  # * remove_branch!(i, j = nil) — removes an edge from the graph and return the tree. i can be a {Branch}, or (i,j) a node pair.
+  # * nodes — returns an array of all nodes.
+  # * terminal_nodes — returns an array of all terminal nodes.
+  # * branches — returns an array of all branches.
+  module TreeAPI
+
+    # @raise if the API is not completely implemented
+    def self.included(klass)
+      @api_methods ||= [:add_node!, :add_branch!, :remove_node!, :remove_branch!, :nodes, :terminal_nodes, :branches]
+      ruby_18 { @api_methods.each { |m| m.to_s } }
+
+      @api_methods.each do |meth|
+        raise "Must implement #{meth}" unless klass.instance_methods.include?(meth)
+      end
+    end
+
+  end
+end

data/lib/jumoku/version.rb

@@ -0,0 +1,6 @@
+module Jumoku
+  MAJOR = 0
+  MINOR = 1
+  PATCH = 1
+  VERSION = [MAJOR, MINOR, PATCH].join('.')
+end

metadata

@@ -0,0 +1,111 @@
+--- !ruby/object:Gem::Specification 
+name: jumoku
+version: !ruby/object:Gem::Version 
+  prerelease: 
+  version: 0.1.1
+platform: ruby
+authors: 
+- Jean-Denis Vauguet <jd@vauguet.fr>
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2011-07-06 00:00:00 +02:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: activesupport
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+  type: :runtime
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: facets
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+  type: :runtime
+  version_requirements: *id002
+- !ruby/object:Gem::Dependency 
+  name: rspec
+  prerelease: false
+  requirement: &id003 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+  type: :development
+  version_requirements: *id003
+- !ruby/object:Gem::Dependency 
+  name: yard
+  prerelease: false
+  requirement: &id004 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+  type: :development
+  version_requirements: *id004
+description: Jumoku provides you with tree behaviors to mixin and tree classes to inherit from. Raw tree, common binary trees, custom trees...
+email: jd@vauguet.fr
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- lib/jumoku.rb
+- lib/jumoku/tree_api.rb
+- lib/jumoku/ext/ext.rb
+- lib/jumoku/builders/raw_tree.rb
+- lib/jumoku/builders/tree.rb
+- lib/jumoku/raw_tree_node.rb
+- lib/jumoku/classes/tree_classes.rb
+- lib/jumoku/support/support.rb
+- lib/jumoku/support/branch.rb
+- lib/jumoku/version.rb
+- LICENSE
+- Rakefile
+- README.md
+has_rdoc: true
+homepage: http://github.com/chikamichi/jumoku
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.6.1
+signing_key: 
+specification_version: 3
+summary: A fully fledged tree library for Ruby.
+test_files: []
+