jumoku 0.2.3 → 0.2.4

data/README.md

@@ -2,21 +2,22 @@
 
 ## 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 provides you with tree structures and related tools to perform manipulation and computation, the easy way. Trees are frequently used to mimic hierarchal structures such as filesystems, or modelize decisionnal patterns, for instance.
 
 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*
 
-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.
+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. Trees are an important subset of graphs used in a whole slew of computer science and mathematical problems: network modelization, datasets storage, scientific computation, load balancing, games, AI designs, etc. They however are not limited to directed patterns: a tree is not compelled to have a "root" node, nor to have "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
+* RawUndirectedTree: a pure tree-graph with only basic features
+* RawDirectedTree: a tree that's an arborescence, that is, a tree with a flow from its root to its leaf nodes
+* **Tree**: a tree-graph with extended features built upon RawUndirectedTree. That's what you'd want to use as a fully-fledged tree structure
+* **Arborescence**: an arbo-graph with extended features built upon RawDirectedTree. That's what you'd want to use as a fully-fledged arborescence 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):
 
@@ -24,6 +25,10 @@ You can also extend those structures with hybrid behaviors (not Graph Theory com
 * Loopy (*not yet*): relax the *acyclic* constraint
 * Atomic (*not yet*): relax the *connected* constraint
 
+There are also strategies one may enable:
+
+* a simple edge labeling scheme (increasing integer indexes), providing edges and nodes sorting facilities
+
 ## Basic usage
 
 To create an instance of a tree, you may use either inheritance or mixins.
@@ -42,7 +47,7 @@ tree = Jumoku::Tree.new
 
 ``` ruby
 class MyTree
-  include Jumoku::RawTreeBuilder
+  include Jumoku::TreeBuilder
 end
 tree = MyTree.new
 ```
@@ -51,7 +56,7 @@ The RawTree class is actually implemented this way.
 
 ### What you get
 
-`tree` is now a Tree object, shipping with some default options:
+Following the previous code example, `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 as you manipulate it

data/lib/jumoku/builders/arborescence.rb

@@ -8,16 +8,173 @@ module Jumoku
     include RawDirectedTreeBuilder
     include Extended
 
+    def add_branch!(u, v = nil, l = nil)
+      return super(u,v,l) if @_options[:free_flow]
+      return add_branch!(u.source, u.target, l) if u.is_a? _branch_type
+      return super(u,v,l) if nodes.size < 2
+
+      nodes.include?(u) ? super(u,v,l) : super(v,u,l)
+    end
+
+    # Find the root node.
+    #
+    # @return [Node]
+    #
+    def root
+      return nodes.first if nodes.size == 1
+      nodes.find { |node| root?(node) }
+    end
+
+    # Return the list of arcs branched out from the root node.
+    #
+    # @return [Array<Plexus::Arc>]
+    #
+    def root_edges
+      adjacent(root, :type => :edges)
+    end
+
+    # Check whether a node is the root.
+    #
+    # @return [true, false]
+    #
+    def root?(node)
+      in_degree(node) == 0 && out_degree(node) > 0
+    end
+
+    # Return the list of a node's children.
+    #
+    # @param [Node] node
+    # @return [Array<Node>]
+    #
+    def children(parent)
+      adjacent(parent)
+    end
+    alias children_of children
+
+    # Return the parent node of another.
+    #
+    # @param [Node] node
+    # @raise if the node has more than one parent (should never occur!)
+    # @return [Node, nil] nil if the node is root
+    #
+    def parent(node)
+      parent = adjacent(node, :direction => :in)
+      raise JumokuError, "Inconsistent directed tree (more than one parent for the node!)" if parent.size > 1
+      parent.empty? ? nil : parent.first
+    end
+    alias parent_of parent
+
+    # Check whether a node is a parent. If another node is provided as
+    # second parameter, check whether the former node is the parent of the
+    # latter node.
+    #
+    # @overload parent?(node)
+    #   @param [Node] node
+    #   @return [true, false]
+    # @overload parent?(node, maybe_child)
+    #   @param [Node] node
+    #   @param [Node] maybe_child
+    #   @return [true, false]
+    #
+    def parent?(node, maybe_child = nil)
+      if maybe_child.nil?
+        !children(node).empty?
+      else
+        children(node).include? maybe_child
+      end
+    end
+
+    # Return the siblings for a node. Siblings are other node's parent children.
+    #
+    # @param [Node] node
+    # @return [Array<Node>] empty list if the node is root
+    #
+    def siblings(node)
+      return [] if root?(node)
+      siblings = children(parent(node))
+      siblings.delete(node)
+      siblings
+    end
+    alias siblings_of siblings
+
+    # Check whether two nodes are siblings.
+    #
+    # @param [Node] node1
+    # @param [Node] node2
+    # @return [true, false]
+    #
+    def siblings?(node1, node2)
+      siblings(node1).include?(node2)
+    end
+
+    # Return the list of a node's neighbours, that is, children of node's
+    # parent siblings (cousins).
+    #
+    # @param [Node] node
+    # @param [Hash] options
+    # @option options [true, false] :siblings whether to include the node's
+    #   siblings in the list
+    # @return [Array<Node>]
+    #
+    def neighbours(node, options = {:siblings => false})
+      # special case when the node is the root
+      return [] if root?(node)
+
+      # special case when the node is a root's child
+      if root?(parent(node))
+        nghb = children(parent(node))
+        nghb.delete_if { |child| child == node } unless options[:siblings]
+        return nghb.map { |child| [child] }
+      end
+
+      # general case
+      nghb = siblings(parent(node)).map do |sibling|
+        children(sibling)
+      end
+      nghb << siblings(node) if options[:siblings]
+      nghb
+    end
+    alias cousins neighbours
+
+    # Check whether two nodes are neighbours. To include the node's siblings
+    # in the matching candidates, pass the :siblings option to true.
+    #
+    # @param [Node] node1
+    # @param [Node] node2
+    # @param [Hash] options
+    # @option options [true, false] :siblings whether to include the node's
+    #   siblings in the list
+    # @return [true, false]
+    #
+    def neighbours?(node1, node2, options = {:siblings => false})
+      neighbours(node1, options).any? { |set| set.include? node2 }
+    end
+    alias cousins? neighbours?
+
+    # Return the list of leaf nodes.
+    #
+    # @return [Array<Node>]
+    #
     def leaves
       terminal_nodes.delete_if do |node|
         out_degree(node) > 0
       end
     end
 
+    # Check whether a node is a leaf.
+    #
+    # @param [Node]
+    # @return [true, false]
+    #
     def leaf?(node)
       terminal?(node) && out_degree(node) == 0
     end
 
+    # Check whether all nodes from a list are leaves.
+    #
+    # @param [#to_a] nodes
+    # @return [true, false]
+    #
     def leaves?(*nodes)
       nodes.to_a.flatten.all? { |node| leaf?(node) }
     end

data/lib/jumoku/builders/raw_directed_tree.rb

@@ -21,11 +21,11 @@ module Jumoku
     # @return enhanced Plexus::DirectedGraph
     #
     def initialize(*params)
+      super(*params) # Delegates to Plexus.
       args = (params.pop if params.last.is_a? Hash) || {}
+      @_options = args
       strategies = _extract_strategies(args)
 
-      super(*params) # Delegates to Plexus.
-
       class << self; self; end.module_eval do
         strategies.each { |strategy| include strategy }
         alias has_branch? has_arc?

data/lib/jumoku/builders/raw_undirected_tree.rb

@@ -25,7 +25,9 @@ module Jumoku
     # @return enhanced Plexus::UndirectedGraph
     #
     def initialize(*params)
+      super(*params) # Delegates to Plexus.
       args = (params.pop if params.last.is_a? Hash) || {}
+      @_options = args
       strategies = _extract_strategies(args)
 
       super(*params) # Delegates to Plexus.

data/lib/jumoku/builders/shared.rb

@@ -3,6 +3,8 @@ module Jumoku
   # builders: {UndirectedTreeBuilder} and {DirectedTreeBuilder}.
   #
   module Shared
+    STRATEGIES = [:edge_labeling, :node_labeling]
+
     def self.included(base)
       base.class_eval do
         # Late aliasing as it references methods provided by Plexus modules.
@@ -10,6 +12,8 @@ module Jumoku
       end
     end
 
+    attr_accessor :_options
+
     # Adds the node to the tree.
     #
     # For convenience, you may pass a branch as the parameter,
@@ -208,6 +212,7 @@ module Jumoku
     end
 
     def _extract_strategies(options)
+      options = options.dup.select! { |k,v| STRATEGIES.include?(k) } || options.dup
       options.inject([]) do |strategies, (k,v)|
         begin
           strategies << Jumoku.const_get(k.to_s.constantize).const_get(v.to_s.constantize)

data/lib/jumoku/strategies/edge_labeling.rb

@@ -7,7 +7,7 @@ module Jumoku
       #
       # @return [Array]
       #
-      def sort_edges(&block)
+      def sorted_edges(&block)
         return edges.sort_by { |edge| block.call(edge) } if block_given?
         edges
       end

data/lib/jumoku/strategies/edge_labeling/simple.rb

@@ -31,9 +31,18 @@ module Jumoku
       #
       # @return [Array]
       #
-      def sort_edges(&block)
+      def sorted_edges(&block)
         return super(&block) if block_given?
-        edges.sort { |a,b| a.label._weight <=> b.label._weight }
+        _sort_edges(edges)
+      end
+
+      # Sort a set of edges.
+      #
+      # @param [Array]
+      # @return [Array]
+      #
+      def sort_edges(set)
+        _sort_edges(set)
       end
 
       # Only for directed trees.
@@ -70,6 +79,10 @@ module Jumoku
         self.next_simple_edge_label_number += 1
         super
       end
+
+      def _sort_edges(set)
+        set.sort { |a,b| a.label._weight <=> b.label._weight }
+      end
     end
   end
 end

data/lib/jumoku/version.rb

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

data/spec/arborescence_spec.rb

@@ -14,6 +14,147 @@ describe Arborescence do
 
   it_should_behave_like "a tree with extended features"
 
+  context "arcs flow" do
+    it "should by default be forced to match direction of the first arc added" do
+      tree.add_branch! 1, 2, 0
+      tree.add_branch! 2, 3, 1
+      tree.add_branch! 4, 3, 2 # will be reversed actually
+      tree.edges.sort_by { |edge| edge.label }.map { |edge| edge.target }.should == [2, 3, 4]
+    end
+
+    it "should be possible to relax this constraint" do
+      tree = Arborescence.new(:free_flow => true)
+      tree.add_branch! 1, 2, 0
+      tree.add_branch! 2, 3, 1
+      tree.add_branch! 4, 3, 2 # will *not* be reversed
+      tree.edges.sort_by { |edge| edge.label }.map { |edge| edge.target }.should == [2, 3, 3]
+    end
+  end
+
+  context "root helpers" do
+    before :each do
+      tree.add_branches! 1,2, 2,3, 1,4, 4,5, 4,6
+    end
+
+    describe "#root" do
+      it "should return the root node" do
+        tree.root.should == 1
+      end
+    end
+
+    describe "#root_edges" do
+      it "should return the edge(s) branched from the root" do
+        tree.root_edges.size.should == 2
+      end
+    end
+
+    describe "#root?" do
+      it "should report whether a node is the root" do
+        tree.root?(1).should be_true
+        (3..6).all? { |i| !tree.root?(i) }.should be_true
+      end
+    end
+  end
+
+  context "children helpers" do
+    before :each do
+      tree.add_branches! 1,2, 2,3, 1,4, 4,5, 4,6
+    end
+
+    describe "#children" do
+      it "should return the list of children nodes for a node" do
+        tree.children(1).sort.should == [2,4]
+        tree.children_of(4).sort.should == [5,6]
+      end
+    end
+  end
+
+  describe "parent helpers" do
+    before :each do
+      tree.add_branches! 1,2, 2,3, 1,4, 4,5, 4,6
+    end
+
+    describe "#parent" do
+      it "should return the parent of a node" do
+        tree.parent(1).should be_nil
+        tree.parent(2).should == 1
+        tree.parent_of(6).should == 4
+      end
+    end
+
+    describe "parent?" do
+      it "should check whether a node is the parent of another (which may be specified)" do
+        tree.parent?(1).should be_true
+        tree.parent?(6).should be_false
+        tree.parent?(1,2).should be_true
+      end
+    end
+  end
+
+  context "siblings helpers" do
+    before :each do
+      tree.add_branches! 1,2, 2,3, 1,4, 4,5, 4,6, 1,7
+    end
+
+    describe "#siblings" do
+      it "should return the siblings for a node" do
+        tree.siblings(1).should be_empty
+        tree.siblings_of(2).sort.should == [4,7]
+      end
+    end
+
+    describe "#siblings?" do
+      it "should check whether two nodes are siblings" do
+        tree.siblings?(1,2).should be_false
+        tree.siblings?(2,3).should be_false
+        tree.siblings?(2,4).should be_true
+      end
+    end
+
+    describe "#neighbours" do
+      before :each do
+        tree.add_node! 2, 8
+        tree.add_node! 7, 9
+      end
+
+      it "should return the grand-siblings for a node" do
+        tree.neighbours(1).should be_empty
+        tree.neighbours(2).size.should == 2
+        [4,7].each { |node| tree.neighbours(2).should include([node]) }
+        neighbours  = tree.neighbours(8)
+        neighbours.size.should == 2
+        neighbours.should include [5,6]
+        neighbours.should include [9]
+      end
+
+      it "should be able to include siblings as well" do
+        neighbours = tree.neighbours(8, :siblings => true)
+        neighbours.size.should == 3
+        neighbours.should include [3]
+        neighbours.should include [5,6]
+        neighbours.should include [9]
+      end
+    end
+
+    describe "#neighbours?" do
+      before :each do
+        tree.add_node! 2, 8
+        tree.add_node! 7, 9
+      end
+
+      it "should check whether two nodes are neighbours" do
+        tree.neighbours?(1,2).should be_false
+        tree.neighbours?(2,8).should be_false
+        tree.neighbours?(3,8).should be_false
+        tree.neighbours?(5,8).should be_true
+      end
+
+      it "should be possible to include siblings in the match" do
+        tree.neighbours?(3,8, :siblings => true).should be_true
+      end
+    end
+  end
+
   context "leaf nodes inspection" do
     before :each do
       tree.add_branches! 1,2, 2,3, 1,4, 1,5

data/spec/raw_directed_tree_spec.rb

@@ -7,6 +7,7 @@ describe RawDirectedTree do
   let(:branch_type) { subject.send :_branch_type }
 
   it_should_behave_like "a legacy tree"
+
   it "should not allow to add a reverse arc" do
     tree.add_branch! 1, 2
     lambda { tree.add_branch! 2, 1 }.should raise_error ForbiddenCycle

data/spec/strategies/simple_edge_labeling.rb

@@ -25,21 +25,28 @@ describe EdgeLabeling::Simple do
       tree.edges.map { |e| e.label._weight }.sort.should == [1,2,3,5]
     end
 
-    describe "#sort_edges" do
+    describe "#sorted_edges" do
       it "should by default return the list of edges in (increasing) order" do
         tree.add_branches! 1,2, 1,3, 2,4, 1,5, 3,6, 1,7
-        tree.sort_edges.map { |e| e.label._weight }.should == (0..5).to_a
+        tree.sorted_edges.map { |e| e.label._weight }.should == (0..5).to_a
       end
 
       it "should accept a block to sort edges" do
         # for the sake of this specs, one'd actually #reverse the default sorting ;)
         tree.add_branches! 1,2, 1,3, 2,4, 1,5, 3,6, 1,7
-        tree.sort_edges do |edge|
+        tree.sorted_edges do |edge|
           -edge.label._weight
         end.map { |e| e.label._weight }.should == (0..5).to_a.reverse
       end
     end
 
+    describe "#sort_edges" do
+      it "should sort a set of edges using the simple scheme" do
+        tree.add_branches! 1,2, 1,3, 2,4, 1,5, 3,6, 1,7
+        tree.sort_edges(tree.adjacent(1, :type => :edges)).map { |e| e.target }.should == [2,3,5,7]
+      end
+    end
+
     it "should thus allow for local edge and children ordering (directed trees only)" do
       arbo.add_branches! 1,2, 1,3, 2,4, 1,5, 3,6, 1,7
       arbo.sorted_arcs_from(1).map { |e| e.target }.should == [2,3,5,7]

data/spec/tree_spec.rb

@@ -7,8 +7,10 @@ describe Tree do
   let(:branch_type) { subject.send :_branch_type }
 
   it_should_behave_like "a legacy tree"
+
   it "should be a undirected graph" do
     tree.class.ancestors.should include RawUndirectedTreeBuilder
   end
+
   it_should_behave_like "a tree with extended features"
 end

metadata

@@ -2,7 +2,7 @@
 name: jumoku
 version: !ruby/object:Gem::Version 
   prerelease: 
-  version: 0.2.3
+  version: 0.2.4
 platform: ruby
 authors: 
 - Jean-Denis Vauguet <jd@vauguet.fr>
@@ -10,7 +10,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-07-11 00:00:00 +02:00
+date: 2011-07-12 00:00:00 +02:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency