jumoku 0.1.1 → 0.1.2

data/Gemfile

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

data/lib/jumoku.rb

@@ -1,5 +1,7 @@
-$:.unshift File.dirname(__FILE__) unless
-  $:.include?(File.dirname(__FILE__)) || $:.include?(File.expand_path(File.dirname(__FILE__)))
+libpath = File.expand_path(File.dirname(__FILE__))
+$:.unshift File.dirname(__FILE__) unless $:.include?(File.dirname(__FILE__)) || $:.include?(libpath)
+$: << libpath + '/../vendor/git/graphy/lib'
+puts $:.inspect
 
 require 'pathname'
 require 'pp'

data/lib/jumoku/version.rb

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

data/spec/raw_tree_spec.rb

@@ -0,0 +1,353 @@
+require File.join(File.dirname(__FILE__), 'spec_helper')
+
+# The RawTree builder implements TreeAPI and ensures the tree
+# is a valid tree as far as Graph Theory is concerned:
+# a tree is an undirected, connected, acyclic graph.
+#
+# Note: these tests may make use of the "root"/"children" terminology.
+# Be aware this has got *no* structural meaning as a tree is, by
+# definition, undirected. Those terms are used only to simplify
+# nodes creation within the tests, so I recall who branched who.
+# For tests about rooted tree, see arborescence_spec.rb
+describe "RawTreeBuilder" do
+  before :each do
+    #class MyTree
+      #include RawTreeBuilder
+    #end
+
+    @tree = RawTree.new
+  end
+
+  describe "#new" do
+    it "should create a valid tree graph" do
+      @tree.should_not be_directed
+      @tree.should be_acyclic
+      @tree.should be_connected
+      # aka @tree.should be_valid, 'll use that from now own
+
+      @tree.nodes.should be_empty
+    end
+  end
+
+  # Testing TreeAPI implementation.
+
+  describe "#add_node!" do
+    describe "an empty tree" do
+      it "should grow up as a valid tree when adding its first node" do
+        @tree.nodes.size.should == 0
+
+        @tree.add_node! "root"
+        @tree.nodes.size.should == 1
+        @tree.nodes.should == ["root"]
+      end
+    end
+
+    describe "a tree with only one node" do
+      before :each do
+        @tree.add_node! "root" # remember, this has no meaning
+      end
+
+      it "should raise an error when trying to add a new (disconnected) node" do
+        lambda { @tree.add_node! "child1" }.should raise_error
+      end
+
+      it "should grow up as a valid tree when adding new (connected) nodes" do
+        lambda { @tree.add_node! "child1", "root" }.should_not raise_error
+
+        @tree.add_node! "child2", "root"
+        @tree.add_node! "grand-child1", "child2"
+        @tree.add_node! Jumoku::Branch.new("grand-child2", "child2")
+
+        @tree.nodes.size.should == 5
+
+        the_nodes = ["root", "child1", "child2", "grand-child1", "grand-child2"]
+        @tree.nodes.should == the_nodes
+        @tree.topsort.should_not == the_nodes
+
+        @tree.add_node! "grand-grand-child1", "grand-child1"
+        @tree.add_node! "child3", "root"
+        @tree.add_node! "grand-child3", "child3"
+        @tree.add_node! "grand-grand-grand-child", "grand-grand-child1"
+        @tree.should_not be_directed
+        @tree.should be_acyclic
+        @tree.should be_connected
+      end
+
+      it "should raise an error when trying to form a cycle" do
+        @tree.add_node! "child1", "root"
+        @tree.add_node! "child2", "root"
+        @tree.add_node! "grand-child", "child1"
+
+        lambda { @tree.add_node! "grand-child", "child2" }.should raise_error RawTreeError
+
+        @tree.add_node! "grand-grand-child", "grand-child"
+        lambda { @tree.add_node! "grand-grand-child", "child1" }.should raise_error RawTreeError
+        lambda { @tree.add_node! "grand-grand-child", "child2" }.should raise_error RawTreeError
+      end
+    end
+  end
+
+  describe "#add_branch!" do
+    describe "an empty tree" do
+      it "should allow for the creation of its first two nodes as a branch" do
+        lambda { @tree.add_branch! :first, :branch }.should_not raise_error
+        @tree.nodes.should == [:first, :branch]
+        @tree.should be_valid
+      end
+    end
+
+    describe "a tree that's not empty" do
+      before :each do
+        @tree.add_node! 1
+      end
+
+      it "should not allow for disconnected branch creation" do
+        lambda { @tree.add_branch! 10, 11 }.should raise_error RawTreeError
+      end
+
+      it "should grow up as a valid tree when populated with (connected) branches" do
+        @tree.nodes.size.should == 1
+
+        @tree.add_branch! 1, 2
+        @tree.nodes.should_not be_empty
+        @tree.nodes.size.should == 2
+        @tree.nodes.should == [1, 2]
+
+        @tree.add_branch! 2, 3
+        @tree.nodes.size.should == 3
+        @tree.nodes.should == [1, 2, 3]
+
+        @tree.add_branch! 3, 4
+        @tree.add_branch! 2, 5
+        lambda { @tree.add_branch! 5, 5 }.should raise_error RawTreeError # cycle (loop)
+        @tree.add_branch! 4, 3
+        @tree.add_branch! 5, 6
+        @tree.nodes.size.should == 6
+        @tree.nodes.should == [1, 2, 3, 4, 5, 6]
+        @tree.should be_valid
+      end
+    end
+  end
+
+  describe "#remove_node!" do
+    describe "an empty tree" do
+      it "should not allow to remove a node since there's none" do
+        lambda { @tree.remove_node! "vapornode" }.should raise_error RawTreeError
+      end
+    end
+
+    describe "a tree that's a single node" do
+      before :each do
+        @tree.add_node! :last
+      end
+
+      it "should allow for last node deletion" do
+        lambda { @tree.remove_node! :last }.should_not raise_error
+        @tree.nodes.should be_empty
+        @tree.should be_valid
+      end
+    end
+
+    describe "a tree that is one sole branch (two nodes)" do
+      before :each do
+        @tree1 = RawTree.new
+        @tree1.add_node! 1
+        @tree1.add_node! 2, 1
+        @tree2 = RawTree.new
+        @tree2.add_node! 1
+        @tree2.add_node! 2, 1
+      end
+
+      it "should allow to remove both nodes in any order" do
+        @tree1.remove_node! 1
+        @tree1.should be_valid
+        @tree1.nodes.should == [2]
+        @tree1.should be_valid
+
+        @tree2.remove_node! 2
+        @tree2.should be_valid
+        @tree2.nodes.should == [1]
+        @tree2.should be_valid
+      end
+    end
+
+    describe "a tree with more than two nodes" do
+      before :each do
+        # TODO: DRY this snippet
+        # i stands for internal, t for terminal
+        @tree.add_branch! :i1, :i2
+        @tree.add_branch! :i2, :i3
+        @tree.add_branch! :i3, :i4
+        @tree.add_branch! :i3, :i5
+        @tree.add_branch! :i4, :t6
+        @tree.add_branch! :i5, :t7
+        @tree.add_branch! :i1, :t8
+      end
+
+      it "should allow deletion of its terminal nodes but not of its internal nodes" do
+        @tree.nodes.size.should == 8
+        lambda { @tree.remove_node! :t8 }.should_not raise_error
+        @tree.nodes.size.should == 7
+        @tree.nodes.should_not include :t8
+        lambda { @tree.remove_node! :i3 }.should raise_error RawTreeError
+        @tree.should be_valid
+      end
+
+      it "should remain a valid tree after any terminal node was removed" do
+        @tree.remove_node! :t6
+        @tree.has_branch?(:i4, :t6).should_not be_true
+        @tree.should be_valid
+      end
+    end
+  end
+
+  describe "#remove_branch!" do
+    describe "an empty tree" do
+      it "should not allow for branch deletion" do
+        lambda { @tree.remove_branch! :null, :none }.should raise_error RawTreeError
+      end
+    end
+
+    describe "an tree that is only one node" do
+      before :each do
+        @tree.add_node! 1
+      end
+
+      it "should not allow for branch deletion" do
+        lambda { @tree.remove_branch! 1, :none }.should raise_error RawTreeError
+      end
+    end
+
+    describe "a tree with more than two nodes" do
+      before :each do
+        # TODO: DRY this snippet
+        # i stands for internal, t for terminal
+        @tree.add_branch! :i1, :i2
+        @tree.add_branch! :i2, :i3
+        @tree.add_branch! :i3, :i4
+        @tree.add_branch! :i3, :i5
+        @tree.add_branch! :i4, :t6
+        @tree.add_branch! :i5, :t7
+        @tree.add_branch! :i1, :t8
+      end
+
+      it "should allow for terminal branch deletion (triggers terminal node deletion)" do
+        @tree.nodes.size.should == 8
+        lambda { @tree.remove_branch! :i1, :i2 }.should raise_error RawTreeError
+        @tree.nodes.size.should == 8
+        lambda { @tree.remove_branch! :i1, :t8 }.should_not raise_error RawTreeError
+        @tree.nodes.should_not include :t8
+        @tree.has_branch?(:i1, :t8).should be_false
+        @tree.should be_valid
+
+        @tree.remove_branch! Branch.new(:i5, :t7)
+        @tree.has_branch?(:i5, :t7).should be_false
+        @tree.should be_valid
+      end
+    end
+  end
+
+  describe "#nodes" do
+    describe "an empty tree" do
+      it "should not have any node" do
+        @tree.nodes.should be_empty
+      end
+    end
+
+    describe "a tree with some node" do
+      it "should be aware of its node(s)" do
+        @tree.add_node! :solo
+        @tree.nodes.should == [:solo]
+
+        @tree.add_branch! 2, :solo
+        @tree.add_branch! 2, 3
+        @tree.nodes.should == [:solo, 2, 3]
+        @tree.should be_valid
+      end
+    end
+  end
+
+  describe "#terminal_nodes" do
+    describe "an empty tree" do
+      it "should have no terminal nodes" do
+        @tree.terminal_nodes.should be_empty
+      end
+    end
+
+    describe "a tree that's a single node" do
+      it "should have one terminal node" do
+        @tree.add_node! 1
+        @tree.terminal_nodes.should == [1]
+      end
+    end
+
+    describe "a populated tree" do
+      before :each do
+        @tree.add_node! 1
+        @tree.add_node! 2, 1
+        @tree.add_node! 3, 2
+      end
+
+      it "should have a least two terminal nodes" do
+        @tree.terminal_nodes.size.should >= 2
+
+        @tree.add_node! 4, 3
+        @tree.add_node! 5, 3
+        @tree.terminal_nodes.should == [1, 4, 5]
+      end
+    end
+  end
+
+  describe "#branches" do
+    describe "an empty tree" do
+      it "should not have any branch" do
+        @tree.branches.should be_empty
+      end
+    end
+
+    describe "a tree that's one node" do
+      it "should not have any branch" do
+        @tree.add_node! :solo
+        @tree.branches.should be_empty
+      end
+    end
+
+    describe "a tree that's one branch (two nodes)" do
+      it "should have one branch only (undirected)" 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
+                                                          # a lazy wrapper of it
+        @tree.should be_valid
+      end
+    end
+
+    describe "a tree with n nodes" do
+      before :each do
+        # TODO: DRY this as random_tree(n = 10)
+        @n = rand(50) # number of nodes
+        @tree.add_node! @n
+        @old_node = @n
+
+        (@n - 1).times do
+          begin
+            @new_node = rand(100)
+            @tree.add_node!(@new_node, @old_node)
+          rescue RawTreeError
+            retry # cycle detected!
+          end
+          @old_node = @new_node
+        end
+      end
+
+      it "should have n - 1 branches" do
+        @tree.nodes.size.should == @n
+        @tree.branches.size.should == @n - 1
+        @tree.should be_valid
+      end
+    end
+  end
+
+  # TODO: add a final test which sums it up
+end

data/spec/spec.opts

@@ -0,0 +1,4 @@
+--color
+--format progress
+--loadby mtime
+--reverse

data/spec/spec_helper.rb

@@ -0,0 +1,14 @@
+require File.expand_path("../../lib/jumoku.rb",  __FILE__)
+
+require 'jumoku'
+include Jumoku
+
+RSpec.configure do |config|
+  # Remove this line if you don't want RSpec's should and should_not
+  # methods or matchers
+  require 'rspec/expectations'
+  config.include RSpec::Matchers
+
+  # == Mock Framework
+  config.mock_with :rspec
+end

data/spec/tree_spec.rb

@@ -0,0 +1,553 @@
+require File.join(File.dirname(__FILE__), 'spec_helper')
+
+# The Tree builder extends the core functionalities provided
+# by RawTreeBuilder.
+#
+# Note: these tests may make use of the "root"/"children" terminology.
+# Be aware this has got *no* structural meaning as a tree is, by
+# definition, undirected. Those terms are used only to simplify
+# nodes creation within the tests, so I recall who branched who.
+# For tests about rooted tree, see arborescence_spec.rb
+describe "TreeBuilder" do
+  before :each do
+    class MyTree
+      include TreeBuilder
+    end
+
+    @tree = MyTree.new
+  end
+
+  describe "#new" do
+    it "should create a valid tree graph" do
+      @tree.should be_valid
+      @tree.nodes.should be_empty
+    end
+  end
+
+  ## Core API is tested in raw_tree_spec.rb.
+  ## The following tests focus on TreeBuilder additional methods.
+
+  describe "#add_node" do
+    describe "an empty tree" do
+      it "should create a new, valid tree with a single node when its first node is added" do
+        @tree.add_node 1
+        @tree.should be_empty
+
+        new_tree = @tree.add_node 1
+        new_tree.nodes.should == [1]
+        new_tree.should be_valid
+      end
+    end
+
+    describe "a populated tree" do
+      before :each do
+        @tree.add_branch! 1, 2
+        @tree.add_branch! 2, 3
+        @tree.add_branch! 3, 4
+      end
+
+      it "should create a new, extended, valid tree when an additionnal node is added" do
+        @tree.add_node 5, 4
+        @tree.add_node 3, 6
+        @tree.nodes.size.should == 4
+
+        new_tree = @tree.add_node 5, 4
+        new_tree.nodes.size.should == @tree.nodes.size + 1
+        new_tree.nodes.should == [1, 2, 3, 4, 5]
+        new_tree.should be_valid
+      end
+    end
+  end
+
+  describe "#add_branch" do
+    describe "an empty tree" do
+      it "should create a new, valid tree with only two nodes when a branch is added" do
+        new_tree = @tree.add_branch :one, :two
+        @tree.should be_empty
+        @tree.should be_valid
+        new_tree.nodes.should == [:one, :two]
+        new_tree.should be_valid
+      end
+    end
+
+    describe "a populate" do
+      before :each do
+        @tree.add_branch! 1, 2
+        @tree.add_branch! 2, 3
+        @tree.add_branch! 3, 4
+      end
+
+      it "should create a new, extended, valid tree when a branch is added" do
+        @tree.add_branch 5, 4
+        @tree.add_branch 3, 6
+        @tree.nodes.size.should == 4
+
+        new_tree = @tree.add_branch 5, 4
+        new_tree.nodes.size.should == @tree.nodes.size + 1
+        new_tree.nodes.should == [1, 2, 3, 4, 5]
+        new_tree.should be_valid
+      end
+    end
+  end
+
+  describe "#remove_node" do
+    describe "an empty tree" do
+      it "should raise an error when trying to remove a node" do
+        lambda { @tree.remove_node :null }.should raise_error, RawTreeError
+      end
+    end
+
+    describe "a tree that's one node only" do
+      before :each do
+        @tree.add_node! 1
+      end
+
+      it "should create a new, empty, valid tree" do
+        new_tree = @tree.remove_node 1
+        @tree.nodes.should == [1]
+        @tree.should be_valid
+        new_tree.should be_empty
+        new_tree.should be_valid
+      end
+    end
+  end
+
+  describe "#remove_branch" do
+    describe "an empty tree" do
+      it "should not allow for removing a branch (even if forced to)" do
+        lambda { @tree.remove_branch 1, 2 }.should raise_error, RawTreeError
+        lambda { @tree.remove_branch 1, 2, :force => true }.should raise_error, RawTreeError
+      end
+    end
+
+    describe "a tree that's one node" do
+      before :each do
+        @tree.add_node! 1
+      end
+
+      it "should not allow for removing a branch (even if forced to)" do
+        lambda { @tree.remove_branch 1, 2 }.should raise_error, RawTreeError
+        lambda { @tree.remove_branch 1, 2, :force => true }.should raise_error, RawTreeError
+      end
+    end
+
+    describe "a tree with at least two nodes" do
+      before :each do
+        @tree.add_branch! 1, 2
+        @tree.add_branch! 2, 3
+      end
+
+      it "should allow for removing a branch, creating a new, valid tree" do
+        lambda { @tree.remove_branch 1, 2, :force => true }.should_not raise_error
+        new_tree = @tree.remove_branch 1, 2, :force => true
+        @tree.nodes.should == [1, 2, 3]
+        new_tree.nodes.should == [2, 3]
+        new_tree.should be_valid
+      end
+    end
+  end
+
+  describe "#add_nodes!" do
+    describe "an empty tree" do
+      it "should allow for adding its first nodes, by pairs and branches" do
+        @tree.add_nodes! 1,2, 2,3, 3,4
+        @tree.nodes.should == [1, 2, 3, 4]
+        @tree.should be_valid
+
+        @tree.add_nodes! Branch.new(5, 2)
+        @tree.nodes.should == [1, 2, 3, 4, 5]
+        @tree.should be_valid
+
+        @tree.add_nodes! 3,4, 1,10, Branch.new(10, 11), -1,1
+        @tree.nodes.size.should == 8
+        @tree.should be_valid
+
+        lambda { @tree.add_nodes! 10, 11 }.should_not raise_error
+        lambda { @tree.add_nodes! 1,  11 }.should     raise_error, RawTreeError # cycle
+
+        @tree = Tree.new
+        lambda { @tree.add_nodes! 1,2, 3,4 }.should      raise_error, RawTreeError # not connected
+        lambda { @tree.add_nodes! 1,2, 2,3, 3,1 }.should raise_error, RawTreeError # cycle
+        lambda { @tree.add_nodes! 1, 2, 3 }.should       raise_error, RawTreeError # even number of nodes
+      end
+    end
+  end
+
+  describe "#add_nodes" do
+    describe "an empty tree" do
+      it "should allow for adding its first nodes, by pairs and branches, creating a new, valid tree" do
+        new_tree = @tree.add_nodes 1,2, 2,3, 3,4
+        @tree.should be_empty
+        new_tree.nodes.should == [1, 2, 3, 4]
+        new_tree.should be_valid
+
+        new_tree = @tree.add_nodes Branch.new(4, 5)
+        @tree.should be_empty
+        new_tree.nodes.should == [4, 5]
+        new_tree.should be_valid
+
+        new_tree = @tree.add_nodes 3,4, 4,10, Branch.new(10, 11), -1,3
+        @tree.should be_empty
+        new_tree.nodes.size.should == 5
+        new_tree.should be_valid
+
+        lambda { @tree.add_nodes 10, 11 }.should_not raise_error
+
+        @tree = Tree.new
+        lambda { @tree.add_nodes 1,2, 3,4 }.should      raise_error, RawTreeError # not connected
+        lambda { @tree.add_nodes 1,2, 2,3, 3,1 }.should raise_error, RawTreeError # cycle
+        lambda { @tree.add_nodes 1, 2, 3 }.should       raise_error, RawTreeError # even number of nodes
+      end
+    end
+  end
+
+  describe "#add_branches!" do
+    describe "an empty tree" do
+      it "should allow for adding its first branches" do
+        @tree.add_branches! Branch.new(1, 2), 1,3, 3,4
+        @tree.nodes.should == [1, 2, 3, 4]
+        @tree.should be_valid
+
+        branch = Branch.new(1, 4)
+        lambda { @tree.add_branches! branch }.should raise_error, RawTreeError
+      end
+    end
+
+    describe "a populated tree" do
+      before :each do
+        @tree.add_nodes! 1, 2
+      end
+
+      it "should allow for adding new branches" do
+        @tree.add_branches! 2, 3
+        @tree.nodes.should == [1, 2, 3]
+        @tree.should be_valid
+
+        @tree.add_branches! Branch.new(0,1), 3,4, Branch.new(4,5)
+        [0..5].all? { |n| @tree.nodes.include? n } and @tree.nodes.size.should == 5
+        @tree.should be_valid
+
+        lambda { @tree.add_branches! Branch.new(2, 5) }.should raise_error, RawTreeError
+      end
+    end
+  end
+
+  describe "add_branches" do
+    describe "an empty tree" do
+      it "should create a new, valid tree populated with its first branches" do
+        b1, b2, b3 = Branch.new(1, 2), Branch.new(2, 3), Branch.new(3, 4)
+        new_tree = @tree.add_branches b1, b2, b3
+        @tree.should be_empty
+        new_tree.nodes.should == [1, 2, 3, 4]
+        new_tree.should be_valid
+
+        lambda { @tree.add_branches 1,2, 2,3, 3,1 }.should raise_error, RawTreeError
+      end
+    end
+
+    describe "a populated tree" do
+      before :each do
+        @tree.add_nodes! 1,2, 2,3, 3,4
+      end
+
+      it "should create a new, valid tree extended with its new branches" do
+        new_tree = @tree.add_branches 4, :five, Branch.new(:five, "six")
+        @tree.nodes.should == (1..4).to_a
+        new_tree.nodes.should == [1, 2, 3, 4, :five, "six"]
+        new_tree.should be_valid
+
+        lambda { @tree.add_branches 10, 11 }.should   raise_error, RawTreeError
+        lambda { @tree.add_branches Branch.new 1,4 }.should     raise_error, RawTreeError
+      end
+    end
+  end
+
+  describe "#remove_nodes!" do
+    describe "an empty tree" do
+      it "should not allow for removing nodes" do
+        lambda { @tree.remove_nodes! :foo, :bar }.should raise_error, RawTreeError
+      end
+    end
+
+    describe "a tree that's one node" do
+      before :each do
+        @tree.add_node! :one
+      end
+
+      it "should allow for removing its sole node only (bad semantic)" do
+        @tree.remove_nodes! :one
+        @tree.nodes.should be_empty
+        @tree.should be_valid
+
+        lambda { @tree.remove_nodes! :foo, :bar }.should raise_error, RawTreeError
+      end
+    end
+
+    describe "a populated tree" do
+      before :each do
+        @tree.add_nodes! 1,2, 2,3, 3,4
+      end
+
+      it "should allow for removing its nodes until it's empty" do
+        @tree.remove_nodes! (1..4).to_a
+        @tree.should be_empty
+        @tree.should be_valid
+
+        lambda { @tree.remove_nodes! :null }.should raise_error, RawTreeError
+      end
+    end
+  end
+
+  describe "#remove_nodes" do
+    describe "an empty tree" do
+      it "should not allow for removing nodes" do
+        lambda { @tree.remove_nodes :foo, :bar }.should raise_error, RawTreeError
+      end
+    end
+
+    describe "a populated tree" do
+      before :each do
+        @tree.add_nodes! 1,2, 2,3, 3,4
+      end
+
+       it "should allow for removing nodes, creating a new, valid tree" do
+        new_tree = @tree.remove_nodes 1, 2, 3, 4
+        @tree.nodes.should == [1, 2, 3, 4]
+        new_tree.should be_empty
+        new_tree.should be_valid
+
+        lambda { @tree.remove_nodes! :null }.should raise_error, RawTreeError
+       end
+    end
+  end
+
+  describe "#remove_branches!" do
+    describe "an empty tree" do
+      it "should not allow for removing branches" do
+        lambda { @tree.remove_branches Branch.new(:foo, :bar), 1,2 }.should raise_error, RawTreeError
+      end
+    end
+
+    describe "a tree that's only one node" do
+      before :each do
+        @tree.add_node! :solo
+      end
+
+      it "should not allow for removing branches" do
+        lambda { @tree.remove_branches! :solo, :null }.should raise_error, RawTreeError
+      end
+    end
+
+    describe "a populated tree" do
+     before :each do
+        @tree.add_nodes! 1,2, 2,3, 3,4
+      end
+
+      it "should allow for removing branches until it has no more branches or a sole node" do
+        @tree.remove_branches! 1,2, Branch.new(2,3), 3,4
+        @tree.should be_empty
+        @tree.should be_valid
+
+        lambda { @tree.remove_branches! Branch.new(:foo, :bar), Branch.new(1, 2) }.should raise_error, RawTreeError
+      end
+    end
+  end
+
+  describe "#remove_branches" do
+    describe "an empty tree" do
+      it "should not allow for removing branches" do
+        lambda { @tree.remove_branches :foo, :bar, Branch.new(1, 2) }.should raise_error, RawTreeError
+      end
+    end
+
+    describe "a tree that's one node" do
+      before :each do
+        @tree.add_node! :solo
+      end
+
+      it "should not allow for removing branches" do
+        lambda { @tree.remove_branches :solo, :null }.should raise_error, RawTreeError
+      end
+    end
+
+    describe "a populated tree" do
+     before :each do
+        @tree.add_nodes! 1,2, 2,3, 3,4
+      end
+
+      it "should allow for removing branches until it has no more branches or a sole node, creating a new, valid tree" do
+        new_tree = @tree.remove_branches 1,2, Branch.new(2,3), 3,4
+        @tree.nodes.should == [1, 2, 3, 4]
+        new_tree.should be_empty
+        new_tree.should be_valid
+
+        lambda { @tree.remove_branches Branch.new(:foo, :bar), Branch.new(1, 2) }.should raise_error, RawTreeError
+      end
+    end
+  end
+
+  describe "#node?" do
+    describe "an empty tree" do
+      it "should not report having any node" do
+        @tree.node?(:null).should be_false
+      end
+    end
+
+    describe "a populated tree" do
+     before :each do
+        @tree.add_nodes! 1,2, 2,3, 3,4
+      end
+
+      it "should be aware of which nodes belong to itself" do
+        @tree.node?(1).should be_true
+        @tree.has_node?(:null).should be_false
+      end
+    end
+  end
+
+  describe "#nodes?" do
+    describe "an empty tree" do
+      it "should not report having any node" do
+        @tree.nodes?(:null, :foo, 0).should be_false
+      end
+    end
+
+    describe "a populated tree" do
+     before :each do
+        @tree.add_nodes! 1,2, 2,3, 3,4
+      end
+
+      it "should be aware of which nodes belong to itself" do
+        @tree.nodes?(1, 4).should be_true
+        @tree.has_nodes?(:null, 1, 2).should be_false
+      end
+    end
+  end
+
+  describe "#nodes_among?" do
+    describe "an empty tree" do
+      it "should not report having any node" do
+        @tree.nodes_among?(:null, :foo, 0).should be_false
+      end
+    end
+
+    describe "a populated tree" do
+     before :each do
+        @tree.add_nodes! 1,2, 2,3, 3,4
+      end
+
+      it "should be aware of which nodes belong to itself" do
+        @tree.nodes_among?(1, 4).should be_true
+        @tree.has_node_among?(:foo, 2, :bar).should be_true
+        @tree.has_nodes_among?(:foo, 2, :bar, 3, 4, Array.new).should be_true
+        @tree.has_nodes_among?(:null, :foo, :bar).should be_false
+      end
+    end
+  end
+
+  describe "#branch?" do
+    describe "an empty tree" do
+      it "should not have any branch" do
+        @tree.has_branch?(1,2).should be_false
+      end
+    end
+
+    describe "a tree that's one node" do
+      before :each do
+        @tree.add_node! :solo
+      end
+
+      it "should not have any branch" do
+        @tree.has_branch?(1,2).should be_false
+      end
+    end
+
+    describe "a populated tree" do
+     before :each do
+        @tree.add_nodes! 1,2, 2,3, 3,4
+      end
+
+      it "should be aware of which branches belong to itself" do
+        @tree.has_branch?(2,3).should be_true
+        @tree.has_branch?(1,3).should be_false
+        @tree.has_branch?(1,:null).should be_false
+      end
+    end
+  end
+
+  # TODO: tests for #branches? and #branches_among?
+  # (actually, done within the tests for #add_consecutive_nodes!)
+
+  describe "#num_nodes" do
+    describe "an empty tree" do
+      it "should report having no node" do
+        @tree.number_of_nodes.should == 0
+      end
+    end
+
+    describe "a populated tree" do
+     before :each do
+        @tree.add_nodes! 1,2, 2,3, 3,4
+      end
+
+      it "should report how many nodes belong to it" do
+        @tree.number_of_nodes.should == 4
+      end
+    end
+  end
+
+  describe "#num_branches" do
+    describe "an empty tree" do
+      it "should report having no branch" do
+        @tree.number_of_nodes.should == 0
+      end
+    end
+
+    describe "a tree that's one node" do
+      before :each do
+        @tree.add_node! :solo
+      end
+
+      it "should report having no branch" do
+        @tree.number_of_branches.should == 0
+      end
+    end
+
+    describe "a populated tree" do
+     before :each do
+        @tree.add_nodes! 1,2, 2,3, 3,4
+      end
+
+      it "should report how many branches belong to it" do
+        @tree.number_of_branches.should == @tree.number_of_nodes - 1
+      end
+    end
+  end
+
+  describe "#add_consecutive_nodes!" do
+    describe "a tree" do
+      it "should grow as a valid, populated tree if all specified nodes define a valid tree structure" do
+        @tree.add_consecutive_nodes!(1, 2, 3, :four, Branch.new(:foo, "bar"))
+        @tree.has_branches?(1,2, 2,3, Branch.new(3, :four), :four,:foo, :foo,"bar").should be_true # each specified branch exist
+        @tree.has_branches?(1,2, 2,3, Branch.new(3, :four), :four,:foo).should be_true # each specified branch exist
+        @tree.has_branches_among?(1,2, 2,3, Branch.new(3, :four), :four,:foo).should be_false # do not list every existing branch
+        @tree.has_branches_among?(1,2, 2,3, Branch.new(3, :four), :four,:foo, :foo,"bar").should be_true # list all existing branches
+        @tree.has_branches_among?(1,2, 2,3, Branch.new(3, :four), :four,:foo, :foo,"bar", Array.new, "NIL").should be_true # list all existing branches
+        @tree.should be_valid
+      end
+    end
+  end
+
+  describe "#add_consecutive_nodes" do
+    describe "a tree" do
+      it "should create a new, valid, populated tree if all specified nodes define a valid tree structure" do
+        new_tree = @tree.add_consecutive_nodes(1, 2, 3, :four, Branch.new(:foo, "bar"))
+        @tree.should be_empty
+        new_tree.has_branches?(1,2, 2,3, Branch.new(3, :four), :four,:foo, :foo,"bar").should be_true
+        new_tree.has_branches?(1,2, 2,3, Branch.new(3, :four), :four,:foo).should be_true
+        new_tree.should be_valid
+      end
+    end
+  end
+end
+