jumoku 0.2.0 → 0.2.1

data/Gemfile

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

data/lib/jumoku.rb

@@ -1,6 +1,5 @@
 libpath = File.expand_path(File.dirname(__FILE__))
 $:.unshift File.dirname(__FILE__) unless $:.include?(File.dirname(__FILE__)) || $:.include?(libpath)
-$: << libpath + '/../vendor/git/plexus/lib'
 
 require 'pathname'
 require 'pp'
@@ -24,8 +23,7 @@ require 'plexus'
 # (from the Facets library), both turning nodes into versatile handlers.
 #
 module Jumoku
-  # API, core implementations
-  autoload :TreeAPI,                  'jumoku/tree_api'
+  # core implementations
   autoload :Shared,                   'jumoku/builders/shared'
   autoload :Extended,                 'jumoku/builders/extended'
 
@@ -46,6 +44,7 @@ module Jumoku
   autoload :Arborescence,             'jumoku/classes/tree_classes'
 
   # support
+  require 'jumoku/support/ruby_compatibility'
   require 'jumoku/support/support'
   require 'jumoku/ext/ext'
 end

data/lib/jumoku/builders/extended.rb

@@ -1,5 +1,5 @@
 module Jumoku
-  # This module provides methods extending the core TreeAPI. Most of those
+  # This module provides methods extending the core implementation. Most of those
   # methods are cloning the receiver tree and perform their operation on the
   # duplicated object. Some other are helpers adding reflexivity to trees.
   # There are also a few in-place methods.
@@ -163,11 +163,16 @@ module Jumoku
     #
     # The process relies on {RawTreeBuilder#remove_node! remove_node!}.
     #
-    # @param [#each] *a an Enumerable nodes set
+    # @param [#each] *nodes an Enumerable nodes set; may contain Range
     # @return [Tree] `self`
     #
-    def remove_nodes!(*a)
-      a.flatten.each { |v| remove_node! v }
+    # @example
+    #
+    #   remove_nodes! 1, 3..5
+    #
+    def remove_nodes!(*nodes)
+      nodes = nodes.to_a.map { |i| i.is_a?(Range) ? i.to_a : i }.flatten
+      nodes.each { |v| remove_node! v }
       self
     end
     alias delete_nodes! remove_nodes!
@@ -265,18 +270,11 @@ module Jumoku
     # @return [Boolean]
     #
     def branches?(*maybe_branches)
-      list = maybe_branches.create_branches_list(_branch_type)
-      all = true
-
-      # Branch objects are really Edge objects within Plexus, therefore
-      # cannot rely on #eql? to compare those structures and must drop
-      # down to the attributes.
-      list.each do |e| # Jumoku::Branch structs
-        all = branches.any? do |b| # Plexus::Edge structs
-          (b[:source] == e[:source]) and (b[:target] == e[:target])
+      maybe_branches.create_branches_list(_branch_type).all? do |maybe_branch|
+        branches.any? do |branch|
+          maybe_branch == branch
         end
       end
-      all
     end
     alias has_branches? branches?
 
@@ -292,17 +290,11 @@ module Jumoku
     #
     def branches_among?(*maybe_branches)
       list = maybe_branches.create_branches_list(_branch_type)
-      all = true
-
-      # Branch objects are really Edge objects within Plexus, therefore
-      # cannot rely on #eql? to compare those structures and must drop
-      # down to the attributes.
-      branches.each do |e| # Plexus::Edge structs
-        all = list.any? do |b| # Jumoku::Branch structs
-          (b[:source] == e[:source]) and (b[:target] == e[:target])
+      branches.all? do |branch|
+        list.any? do |maybe_branch|
+          branch == maybe_branch
         end
       end
-      all
     end
     alias has_branches_among? branches_among?
 

data/lib/jumoku/builders/raw_directed_tree.rb

@@ -22,6 +22,21 @@ module Jumoku
     #
     def initialize(*params)
       super(*params) # Delegates to Plexus.
+      class << self; self; end.module_eval do
+        alias has_branch? has_arc?
+      end
+    end
+
+    # Checks whether the tree is *really* a valid tree, that is if the
+    # following conditions are fulfilled:
+    #
+    # * directed
+    # * acyclic
+    # * connected
+    #
+    # @return [Boolean]
+    def valid?
+      super and directed?
     end
 
     private

data/lib/jumoku/builders/raw_undirected_tree.rb

@@ -26,6 +26,21 @@ module Jumoku
     #
     def initialize(*params)
       super(*params) # Delegates to Plexus.
+      class << self; self; end.module_eval do
+        alias has_branch? has_edge?
+      end
+    end
+
+    # Checks whether the tree is *really* a valid tree, that is if the
+    # following conditions are fulfilled:
+    #
+    # * undirected
+    # * acyclic
+    # * connected
+    #
+    # @return [Boolean]
+    def valid?
+      super && !directed?
     end
 
     private

data/lib/jumoku/builders/shared.rb

@@ -1,15 +1,12 @@
 module Jumoku
   # This module provides the basic routines needed to implement the specialized
-  # builders: {UndirectedTreeBuilder} and {DirectedTreeBuilder}. Those
-  # implementations are under the control of the {TreeAPI}.
+  # builders: {UndirectedTreeBuilder} and {DirectedTreeBuilder}.
   #
   module Shared
     def self.included(base)
       base.class_eval do
         # Late aliasing as it references methods provided by Plexus modules.
         alias has_node? has_vertex?
-        alias has_branch? has_edge?
-        include TreeAPI
       end
     end
 
@@ -176,7 +173,7 @@ module Jumoku
     #
     # @return [Boolean]
     def valid?
-      acyclic? and connected? and not directed?
+      acyclic? and connected?
     end
 
     # Is the node a terminal node?

data/lib/jumoku/support/ruby_compatibility.rb

@@ -0,0 +1,19 @@
+module Jukomu
+  if RUBY_VERSION < "1.9"
+    def ruby_18
+      yield
+    end
+
+    def ruby_19
+      false
+    end
+  else
+    def ruby_18
+      false
+    end
+
+    def ruby_19
+      yield
+    end
+  end
+end

data/lib/jumoku/version.rb

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

data/spec/arborescence_spec.rb

@@ -0,0 +1,14 @@
+require 'spec_helper'
+
+describe Arborescence do
+  subject { Arborescence.new }
+  let(:tree) { subject }
+  let(:tree_type) { subject.class }
+  let(:branch_type) { subject.send :_branch_type }
+
+  it_should_behave_like "a legacy tree"
+  it "should be a directed graph" do
+    tree.class.ancestors.should include RawDirectedTreeBuilder
+  end
+  it_should_behave_like "a tree with extended features"
+end

data/spec/behaviors/core_tree.rb

@@ -0,0 +1,281 @@
+require 'spec_helper'
+
+shared_examples_for "a legacy tree" do
+  describe "#new" do
+    it "should create a valid tree graph" do
+      tree.should be_valid
+      tree.nodes.should be_empty
+    end
+  end
+
+  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! 1 # adding a raw string as the first node
+        tree.nodes.size.should == 1
+        tree.nodes.should == [1]
+      end
+    end
+
+    describe "a tree with only one node" do
+      before :each do
+        tree.add_node! 1
+      end
+
+      it "should raise an error when trying to add a new, disconnected node" do
+        # again, I'll use childX for the sake of this specs, as it is easy to
+        # remember, but the node is not really a "child" of the previous node,
+        # it is just connected
+        lambda { tree.add_node! 2 }.should raise_error
+      end
+
+      it "should grow up as a valid tree when adding new, connected nodes" do
+        lambda { tree.add_node! 2, 1 }.should_not raise_error
+
+        tree.add_node! 3, 1
+        tree.add_node! 1, 4
+        tree.add_node! branch_type.new(3, 5)
+
+        tree.should be_valid
+        tree.nodes.size.should == 5
+        tree.nodes.sort.should == [1,2,3,4,5]
+      end
+
+      it "should raise an error when trying to form a cycle" do
+        tree.add_node! 2, 1
+        tree.add_node! 3, 1
+        tree.add_node! 4, 2
+
+        lambda { tree.add_node! 4, 1 }.should raise_error ForbiddenCycle
+      end
+    end
+  end
+
+  describe "#add_branch!" do
+    describe "an empty tree" do
+      it "should create a branch and return the updated tree" do
+        tree.add_branch!(:one, :two).should be_a tree_type
+        tree.should be_valid
+        tree.nodes.should == [:one, :two]
+      end
+    end
+
+    describe "a tree containing a single node" do
+      before :each do
+        tree.add_node! 1
+      end
+
+      it "should not allow 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.sort.should == [1, 2]
+
+        tree.add_branch! 2, 3
+        tree.nodes.size.should == 3
+        tree.nodes.sort.should == [1, 2, 3]
+
+        tree.add_branch! 3, 4
+        tree.add_branch! 2, 5
+        lambda { tree.add_branch! 5, 5 }.should raise_error ForbiddenCycle
+        lambda { tree.add_branch! 1, 5 }.should raise_error ForbiddenCycle
+        tree.add_branch! 5, 6
+        tree.nodes.size.should == 6
+        tree.nodes.sort.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! "undefinedNode" }.should raise_error UndefinedNode
+      end
+    end
+
+    describe "a tree containing 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 containing one branch" do
+      before :each do
+        tree.add_node! 1
+        tree.add_node! 2, 1
+      end
+
+      it "should allow to remove both nodes in any order" do
+        tree.remove_node! 1
+        tree.should be_valid
+        tree.nodes.sort.should == [2]
+        tree.should be_valid
+      end
+    end
+
+    describe "a tree containing several branches" 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 UndefinedNode
+        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 containing 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 containing several branches" 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_type.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 containing several nodes" do
+      it "should be aware of its nodes" 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 containing one node" do
+      it "should have one terminal node" do
+        tree.add_node! 1
+        tree.terminal_nodes.should == [1]
+      end
+    end
+
+    describe "a tree with several branches" 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.sort.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 containing one node" do
+      it "should not have any branch" do
+        tree.add_node! :solo
+        tree.branches.should be_empty
+      end
+    end
+
+    describe "a tree containing one branch" do
+      it "should have one branch only" do
+        tree.add_node! :one
+        tree.add_node! :two, :one
+        tree.branches.size.should == 1
+        tree.should be_valid
+      end
+    end
+  end
+end