jumoku 0.1.2 → 0.1.3

data/Gemfile

@@ -1,4 +1,4 @@
 source "http://rubygems.org"
 
 gemspec
-gem 'graphy', :path => 'vendor/git/graphy'
+gem 'plexus', :path => 'vendor/git/plexus'

data/README.md

@@ -6,7 +6,7 @@
 
 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.
+Jumoku is built upon [Plexus](http://github.com/chikamichi/plexus "Plexus 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*
 
@@ -49,15 +49,15 @@ end
 tree = MyTree.new
 ```
 
-Actually the RawTree class is nothing but the mixin code snippet above.
+The RawTree class is actually implemented this way.
 
 ### 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)
+* Jumoku API's methods will ensure it remains so as you manipulate it
+* it has no constraint on the number of branches per node (its branching number)
 
 ## Install, first steps and bootstraping
 
@@ -71,17 +71,17 @@ Now you can play in IRB:
 
 ``` bash
 $ irb
-ruby-1.9.1-p378 > require 'Jumoku'
+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> 
+=> #<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):
+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
@@ -94,17 +94,17 @@ Be sure to take a look at the tests in `spec/` as well, as they document the pub
 
 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;
+* undirected: the branches of a tree have no direction and you can flow either from root toward leaves or reversily;
 * 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).
+* connected: a tree is such that pair of distinct nodes can be connected through some path (but *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".
+This is quite restrictive, but not *that* restrictive. Instinctively, a tree structure would rather be described as an arborescence, that is a collection of nodes with a root node and some leaves (ending nodes), that is with a general direction (top-down). That is what you would use to use to modelize nested directories, for instance. From the mathematical point of view, legacy trees and arborescences have some little differencies (the latter are more constrained). Jumoku provides both structures.
 
-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").
+Several ruby graph libraries exist, some pure-ruby, some as bindings (for instance, the popular igraph C backend). Jumoku makes use of the most up-to-date project among those available, [Plexus](http://github.com/chikamichi/plexus "Plexus on Github"). It's been forked to implement new features required by Jumoku, and is vendorized within this gem.
 
 ## License
 
-See the LICENSE file.
+[MIT License](http://en.wikipedia.org/wiki/MIT_License). See the LICENSE file.
 
 ## Contributing
 

data/lib/jumoku.rb

@@ -1,13 +1,13 @@
 libpath = File.expand_path(File.dirname(__FILE__))
 $:.unshift File.dirname(__FILE__) unless $:.include?(File.dirname(__FILE__)) || $:.include?(libpath)
-$: << libpath + '/../vendor/git/graphy/lib'
+$: << libpath + '/../vendor/git/plexus/lib'
 puts $:.inspect
 
 require 'pathname'
 require 'pp'
 require 'active_support'
 require 'facets'
-require 'graphy'
+require 'plexus'
 
 module Jumoku
   # jumoku internals: graph builders and additionnal behaviors

data/lib/jumoku/builders/raw_tree.rb

@@ -4,7 +4,7 @@ module Jumoku
   # 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,
+  # connected, acyclic graphs. Using Plexus::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
@@ -20,7 +20,7 @@ module Jumoku
   # This builder defines a few methods not required by the API so as to maintain consistency
   # in the DSL.
   module RawTreeBuilder
-    include Graphy::UndirectedGraphBuilder
+    include Plexus::UndirectedGraphBuilder
 
     # This method is called by the specialized implementations
     # upon tree creation.
@@ -39,7 +39,7 @@ module Jumoku
         # Ensure the builder abides by its API requirements.
         include Jumoku::TreeAPI
       end
-      super(*params) # Delegates to Graphy.
+      super(*params) # Delegates to Plexus.
     end
 
     # Ensure trees are seen as undirected graphs.
@@ -48,7 +48,7 @@ module Jumoku
     def directed?
       return false
     end
-    # FIXME: should be able to reach Graphy's method ?!
+    # FIXME: should be able to reach Plexus's method ?!
 
     # Adds the node to the tree.
     #

data/lib/jumoku/builders/tree.rb

@@ -252,7 +252,7 @@ module Jumoku
     end
     alias has_nodes_among? nodes_among?
     alias has_node_among?  nodes_among?
-    # FIXME: these helpers could be backported into Graphy.
+    # FIXME: these helpers could be backported into Plexus.
 
     # Returns true if i or (i,j) is a {Branch branch} of the tree.
     #
@@ -280,11 +280,11 @@ module Jumoku
       list = maybe_branches.create_branches_list
       all = true
 
-      # Branch objects are really Edge objects within Graphy, therefore
+      # 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| # Graphy::Edge structs
+        all = branches.any? do |b| # Plexus::Edge structs
           (b[:source] == e[:source]) and (b[:target] == e[:target])
         end
       end
@@ -305,10 +305,10 @@ module Jumoku
       list = maybe_branches.create_branches_list
       all = true
 
-      # Branch objects are really Edge objects within Graphy, therefore
+      # 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| # Graphy::Edge structs
+      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

data/lib/jumoku/support/branch.rb

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

data/lib/jumoku/tree_api.rb

@@ -4,7 +4,7 @@ module Jumoku
   #
   # 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_node!(n, l = nil) — adds a node to the tree and return the tree; l is an optional label (see Plexus 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.

data/lib/jumoku/version.rb

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

data/spec/raw_tree_spec.rb

@@ -317,7 +317,7 @@ describe "RawTreeBuilder" do
         @tree.add_node! :one
         @tree.add_node! :two, :one
         @tree.branches.size.should == 1
-        @tree.branches.first.class.should == Graphy::Edge # the Jumoku::Branch class is just
+        @tree.branches.first.class.should == Plexus::Edge # the Jumoku::Branch class is just
                                                           # a lazy wrapper of it
         @tree.should be_valid
       end

data/vendor/git/plexus/Gemfile

@@ -0,0 +1,3 @@
+source "http://rubygems.org"
+
+gemspec

data/vendor/git/plexus/Gemfile.lock

@@ -0,0 +1,28 @@
+PATH
+  remote: .
+  specs:
+    plexus (0.5.3)
+      facets
+
+GEM
+  remote: http://rubygems.org/
+  specs:
+    diff-lcs (1.1.2)
+    facets (2.9.1)
+    rspec (2.6.0)
+      rspec-core (~> 2.6.0)
+      rspec-expectations (~> 2.6.0)
+      rspec-mocks (~> 2.6.0)
+    rspec-core (2.6.4)
+    rspec-expectations (2.6.0)
+      diff-lcs (~> 1.1.2)
+    rspec-mocks (2.6.0)
+    yard (0.7.2)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  plexus!
+  rspec
+  yard

data/vendor/git/{graphy → plexus}/LICENSE

@@ -1,10 +1,12 @@
+Copyright (c) 2010 Jean-Denis Vauguet <jd@vauguet.fr>
+
 Copyright (c) 2009 Bruce Williams
 
 Copyright (c) 2007,2006 Shawn Patrick Garbett
 
 Copyright (c) 2002,2004,2005 by Horst Duchene
 
-Copyright (c) 2000,2001  Jeremy Siek, Indiana University (jsiek@osl.iu.edu) 
+Copyright (c) 2000,2001  Jeremy Siek, Indiana University (jsiek@osl.iu.edu)
 
 All rights reserved.
 

data/vendor/git/plexus/README.md

@@ -0,0 +1,208 @@
+# Plexus (was Graphy). A framework for graph theory, graph data structures and associated algorithms.
+
+Graph algorithms currently provided are:
+
+* Topological Sort
+* Strongly Connected Components
+* Transitive Closure
+* Rural Chinese Postman
+* Biconnected
+
+These are based on more general algorithm patterns:
+
+* Breadth First Search
+* Depth First Search
+* A* Search
+* Floyd-Warshall
+* Best First Search
+* Djikstra's Algorithm
+* Lexicographic Search
+
+## A quick Tour
+
+### Arcs
+
+There are two vertices bound classes, `Plexus::Arc` and `Plexus::Edge`. The
+former defines directional edges, the latter undirected edges.
+
+### Vertices
+
+Vertices can be any `Object`.
+
+### Graph Types
+
+There are a number of different graph types, each of which provide
+different features and constraints:
+
+`Plexus::Digraph` and its alias `Plexus::DirectedGraph`:
+
+* Single directed edges (arcs) between vertices
+* Loops are forbidden
+
+`Plexus::DirectedPseudoGraph`:
+
+* Multiple directed edges (arcs) between vertices
+* Loops are forbidden
+
+`Plexus::DirectedMultiGraph`:
+
+* Multiple directed edges (arcs) between vertices
+* Loops on vertices
+
+`Plexus::UndirectedGraph`, `Plexus::UndirectedPseudoGraph`, and
+`Graph::UndirectedMultiGraph` are similar but all edges are undirected.
+
+### Data Structures
+
+In order to modelize data structures, make use of the `Plexus::AdjacencyGraph`
+module which provides a generalized adjacency list and an edge list adaptor.
+
+The `Plexus::Digraph` class is the general purpose "swiss army knife" of graph
+classes, most of the other classes are just modifications to this class.
+It is optimized for efficient access to just the out-edges, fast vertex
+insertion and removal at the cost of extra space overhead, etc.
+
+## Example Usage
+
+Using IRB, first require the library:
+
+``` bash
+require 'rubygems' # only if you are using ruby 1.8.x
+require 'plexus'
+```
+
+If you'd like to include all the classes in the current scope (so you
+don't have to prefix with `Plexus::`), just:
+
+``` bash
+include Plexus
+```
+
+Let's play with the library a bit in IRB:
+
+``` bash
+>> dg = Digraph[1,2, 2,3, 2,4, 4,5, 6,4, 1,6]
+=> Plexus::Digraph[[2, 3], [1, 6], [2, 4], [4, 5], [1, 2], [6, 4]]
+```
+
+A few properties of the graph we just created:
+
+``` bash
+>> dg.directed?
+=> true
+>> dg.vertex?(4)
+=> true
+>> dg.edge?(2,4)
+=> true
+>> dg.edge?(4,2)
+=> false
+>> dg.vertices
+=> [1, 2, 3, 4, 5, 6]
+```
+
+Every object could be a vertex, even the class object `Object`:
+
+``` bash
+>> dg.vertex?(Object)
+=> false
+
+>> UndirectedGraph.new(dg).edges.sort.to_s
+=> "[Plexus::Edge[1,2,nil], Plexus::Edge[2,3,nil], Plexus::Edge[2,4,nil],
+      Plexus::Edge[4,5,nil], Plexus::Edge[1,6,nil], Plexus::Edge[6,4,nil]]"
+```
+
+Add inverse edge `(4-2)` to directed graph:
+
+``` bash
+>> dg.add_edge!(4,2)
+=> Plexus::DirectedGraph[Plexus::Arc[1,2,nil], Plexus::Arc[1,6,nil], Plexus::Arc[2,3,nil],
+                          Plexus::Arc[2,4,nil], Plexus::Arc[4,5,nil], Plexus::Arc[4,2,nil],
+                          Plexus::Arc[6,4,nil]]
+```
+
+`(4-2) == (2-4)` in the undirected graph (4-2 doesn't show up):
+
+``` bash
+    >> UndirectedGraph.new(dg).edges.sort.to_s
+    => "[Plexus::Edge[1,2,nil], Plexus::Edge[2,3,nil], Plexus::Edge[2,4,nil],
+         Plexus::Edge[4,5,nil], Plexus::Edge[1,6,nil], Plexus::Edge[6,4,nil]]"
+```
+
+`(4-2) != (2-4)` in directed graphs (both show up):
+
+``` bash
+>> dg.edges.sort.to_s
+=> "[Plexus::Arc[1,2,nil], Plexus::Arc[1,6,nil], Plexus::Arc[2,3,nil],
+      Plexus::Arc[2,4,nil], Plexus::Arc[4,2,nil], Plexus::Arc[4,5,nil],
+      Plexus::Arc[6,4,nil]]"
+
+>> dg.remove_edge! 4,2
+=> Plexus::DirectedGraph[Plexus::Arc[1,2,nil], Plexus::Arc[1,6,nil], Plexus::Arc[2,3,nil],
+                          Plexus::Arc[2,4,nil], Plexus::Arc[4,5,nil], Plexus::Arc[6,4,nil]]
+```
+
+Topological sorting is realized with an iterator:
+
+``` bash
+>> dg.topsort
+=> [1, 6, 2, 4, 5, 3]
+>> y = 0; dg.topsort { |v| y += v }; y
+=> 21
+```
+
+You can use DOT to visualize the graph:
+
+``` bash
+>> require 'plexus/dot'
+>> dg.write_to_graphic_file('jpg','visualize')
+```
+
+Here's an example showing the module inheritance hierarchy:
+
+``` bash
+>> module_graph = Digraph.new
+>> ObjectSpace.each_object(Module) do |m|
+>>   m.ancestors.each {|a| module_graph.add_edge!(m,a) if m != a}
+>> end
+>> gv = module_graph.vertices.select {|v| v.to_s.match(/Plexus/) }
+>> module_graph.induced_subgraph(gv).write_to_graphic_file('jpg','module_graph')
+```
+
+Look for more in the examples directory.
+
+## History
+
+This library is based on [GRATR][1] by Shawn Garbett (itself a fork of
+Horst Duchene's [RGL][2] library) which is heavily influenced by the [Boost][3]
+Graph Library (BGL).
+
+This fork attempts to modernize and extend the API and tests.
+
+## References
+
+For more information on Graph Theory, you may want to read:
+
+* the [documentation][3] for the Boost Graph Library
+* [the Dictionary of Algorithms and Data Structures][4]
+
+## Credits
+
+See CREDITS.markdown
+
+## TODO
+
+See TODO.markdown
+
+## CHANGELOG
+
+See CHANGELOG.markdown
+
+## License
+
+[MIT License](http://en.wikipedia.org/wiki/MIT_License). See the LICENSE file.
+
+[1]: http://gratr.rubyforge.org
+[2]: http://rgl.rubyforge.org
+[3]: http://www.boost.org/libs/graph/doc
+[4]: http://www.nist.gov/dads/HTML/graph.html
+