rubytree 0.6.1 → 0.6.2

data/COPYING

@@ -2,7 +2,7 @@
 
 http://rubytree.rubyforge.org
 
-Copyright (c) 2006-2010 Anupam Sengupta
+Copyright (c) 2006, 2007, 2008, 2009, 2010 Anupam Sengupta (anupamsg at gmail dot com)
 
 All rights reserved.
 
@@ -26,4 +26,4 @@ SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSE
 WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
 THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 
-$Id: COPYING 163 2010-01-03 19:38:25Z anupamsg $
+$Id$

data/ChangeLog

@@ -1,3 +1,28 @@
+2010-01-30  Anupam Sengupta  <anupamsg@gmail.com>
+
+	* lib/tree.rb (Tree): Update the example code to use Ruby
+	conventions for the variable names.
+	(Tree): updated the documentation.
+
+	* README: Updated the example to use Ruby conventions for the
+	variable names.
+
+2010-01-28  Anupam Sengupta  <anupamsg@gmail.com>
+
+	* Rakefile: Minor documentation change.
+
+	* README (DOCUMENTATION): Added comments to the example code.
+
+	* test/test_tree.rb: Documentation clean up.
+
+	* test/test_binarytree.rb: Documentation clean up.
+
+	* lib/tree.rb (Tree): Cleaned up documentation.  Also some minor
+	code refactoring done.
+
+	* lib/tree/binarytree.rb (Tree): Cleaned up documentation.  Minor
+	readability improvement in the isLeftChild? and isRightChild? methods.
+
 2010-01-05  Anupam Sengupta  <anupamsg@gmail.com>
 
 	* README: Updated the requirements section.
@@ -207,4 +232,4 @@
 
 	* Changelog: Added the Changelog file.
 
-$Id: ChangeLog 164 2010-01-04 19:27:12Z anupamsg $
+$Id$

data/History.txt

@@ -1,3 +1,7 @@
+=== 0.6.2 / 2010-01-30
+
+* Updated the documentation.
+
 === 0.6.1 / 2010-01-04
 
 * Changed the hard-dependency on the 'structured_warnings' RubyGem to a soft-dependency - which lets Rubytree still
@@ -40,4 +44,4 @@
 
 * Minor code refactoring. Changes in the Rakefile.
 
-$Id: History.txt 164 2010-01-04 19:27:12Z anupamsg $
+$Id$

data/README

@@ -6,15 +6,16 @@
  \/ \_/\__,_|_.__/ \__, |\__|_|  \___|\___|
                   |___/
 
-  (c) 2006, 2007, 2008, 2009, 2010 Anupam Sengupta
+  Copyright (c) 2006, 2007, 2008, 2009, 2010 Anupam Sengupta (anupamsg at gmail dot com)
   http://rubytree.rubyforge.org
 
 == DESCRIPTION:
 
-RubyTree is a Ruby implementation of the generic Tree data structure.  It provides a generic tree data-structure with
-ability to store keyed node-elements in the tree.  This implementation is node-centric, where the individual nodes on
-the tree are the primary objects and form the leafs of the structure.  The implementation mixes in the Enumerable
-module.
+RubyTree is a Ruby implementation of the generic tree data structure.  It provides a node-based model to store keyed
+node-elements in the tree and simple APIs to access, modify and traverse the structure.  RubyTree is node-centric, where
+individual nodes on the tree are the primary compositional and structural elements.
+
+This implementation also mixes in the Enumerable module to allow standard access to the tree as a collection.
 
 == SYNOPSIS:
 
@@ -34,24 +35,34 @@ As an example, the following code-snippet implements this tree structure:
  | GRANDCHILD 1  |
  +---------------+
 
- # Example
- require 'tree'
+ # ..... Example starts.
+ require 'tree'                 # Load the library
+
+ # ..... Create the root node first.  Note that every node has a name and an optional content payload.
+ root_node = Tree::TreeNode.new("ROOT", "Root Content")
+
+ # ..... Now insert the child nodes.  Note that you can "chain" the child insertions for a given path to any depth.
+ root_node << Tree::TreeNode.new("CHILD1", "Child1 Content") << Tree::TreeNode.new("GRANDCHILD1", "GrandChild1 Content")
+ root_node << Tree::TreeNode.new("CHILD2", "Child2 Content")
+
+ # ..... Lets print the representation to stdout.  This is primarily used for debugging purposes.
+ root_node.printTree
 
- myTreeRoot = Tree::TreeNode.new("ROOT", "Root Content")
- myTreeRoot << Tree::TreeNode.new("CHILD1", "Child1 Content") << Tree::TreeNode.new("GRANDCHILD1", "GrandChild1 Content")
- myTreeRoot << Tree::TreeNode.new("CHILD2", "Child2 Content")
+ # ..... Lets directly access children and grandchildren of the root.  The can be "chained" for a given path to any depth.
+ child1 = root_node["CHILD1"]
+ grand_child1 = root_node["CHILD1"]["GRANDCHILD1"]
 
- myTreeRoot.printTree
+ # ..... Now lets retrieve siblings of the current node as an array.
+ siblings_of_child1 = child1.siblings
 
- child1 = myTreeRoot["CHILD1"]
- grandChild1 = myTreeRoot["CHILD1"]["GRANDCHILD1"]
+ # ..... Lets retrieve immediate children of the root node as an array.
+ children_of_root = root_node.children
 
- siblingsOfChild1Array = child1.siblings
- immediateChildrenArray = myTreeRoot.children
+ # ..... This is a depth-first and L-to-R pre-ordered traversal.
+ root_node.each { |node| node.content.reverse }
 
- # Process all nodes
- myTreeRoot.each { |node| node.content.reverse }
- myTreeRoot.remove!(child1) # Remove the child
+ # ..... Lets remove a child node from the root node.
+ root_node.remove!(child1)
 
 
 == REQUIREMENTS:
@@ -127,7 +138,7 @@ tasks.
 
 RubyTree is licensed under the BSD[http://www.opensource.org/licenses/bsd-license.php] license.
 
-Copyright (c) 2006, 2007 Anupam Sengupta
+Copyright (c) 2006, 2007, 2008, 2009, 2010 Anupam Sengupta
 All rights reserved.
 
 Redistribution and use in source and binary forms, with or without modification, are permitted provided that the
@@ -151,4 +162,4 @@ WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWIS
 THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 
 
-(Document Revision: $Revision: 164 $ by $Author: anupamsg $)
+(Document Revision: $Revision$ by $Author$)

data/Rakefile

@@ -1,10 +1,10 @@
 # -*- mode: ruby; -*-
 #
-# Rakefile
+# Rakefile - This file is part of the RubyTree package.
 #
-# $Revision: 164 $ by $Author: anupamsg $ on $Date: 2010-01-05 00:57:12 +0530 (Tue, 05 Jan 2010) $
+# $Revision$ by $Author$ on $Date$
 #
-# Copyright (c) 2006, 2007 Anupam Sengupta
+# Copyright (c) 2006, 2007, 2009, 2010  Anupam Sengupta
 #
 # All rights reserved.
 #
@@ -61,6 +61,20 @@ begin
     self.need_tar                   = true
     self.need_zip                   = true
 
+    # Post installation message
+    self.post_install_message       = <<MSGEND
+========================================================================
+
+ Thank you for installing #{PKG_NAME.capitalize}.
+
+ Please note that a few APIs have been deprecated since Version 0.6.1
+
+ Specifically, the 'Tree::TreeNode#depth' method is now deprecated, and
+ a new nodeDepth() method has been introduced.
+
+========================================================================
+MSGEND
+
     # Code Metrics ...
     self.flay_threshold             = timebomb 1200, 100 # Default is 1200, 100
     self.flog_threshold             = timebomb 1200, 100 # Default is 1200, 100

data/TODO

@@ -1,5 +1,10 @@
 # -*- mode: org; coding: utf-8-unix; -*-
 
+* TODO Convert all method names to the canonical /^[_a-z<>=\[|+-\/\*`]+[_a-z0-9_<>=~@\[\]]*[=!\?]?$/ pattern
+  See Roodi report at http://getcaliper.com/caliper/tool?tool=roodi&repo=git://github.com/evolve75/RubyTree.git
+* TODO Fix the TreeNode#root method to return nil for root's root.
+* TODO Fix the marshal_load method.  This probably needs to be a class method.
+* TODO Fix the semantic inconsistency between the TreeNode#first|lastSibling method and the siblings method w.r.t. the root
 * TODO Create the basic UML diagrams and upload to the Site
   DEADLINE: <2010-01-04 Mon>
 
@@ -16,4 +21,4 @@
 
 
 
-$Id: TODO 154 2010-01-03 18:01:28Z anupamsg $
+$Id$

data/lib/tree.rb

@@ -1,11 +1,11 @@
-# tree.rb
+# tree.rb - This file is part of the RubyTree package.
 #
-# $Revision: 164 $ by $Author: anupamsg $ on $Date: 2010-01-05 00:57:12 +0530 (Tue, 05 Jan 2010) $
+# $Revision$ by $Author$ on $Date$
 #
-# = tree.rb - Generic Multi-way Tree implementation
+# = tree.rb - Generic implementation of an N-ary tree data structure.
 #
 # Provides a generic tree data structure with ability to
-# store keyed node elements in the tree. The implementation
+# store keyed node elements in the tree.  This implementation
 # mixes in the Enumerable module.
 #
 # Author:: Anupam Sengupta (anupamsg@gmail.com)
@@ -41,29 +41,42 @@
 # SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 #
 
-# This module provides a TreeNode class which is the primary class for all
-# nodes represented in the Tree.
-# This module mixes in the Enumerable module.
+# This module provides a TreeNode class which is the primary class for representing
+# nodes in the tree.
+#
+# This module mixes in the Enumerable module, and also acts as the namespace for all
+# classes in RubyTree.
 module Tree
 
   # Rubytree Package Version
-  VERSION = '0.6.1'
+  VERSION = '0.6.2'
 
   # == TreeNode Class Description
   #
-  # The node class for the tree representation. the nodes are +named+ and have a
-  # place-holder for the node data (i.e., the `content' of the node). The node
-  # names are required to be unique.  In addition, the node provides navigation
-  # methods to traverse the tree.
+  # This class models the nodes for an N-ary tree data structue. The nodes are +named+
+  # and have a place-holder for the node data (i.e., `content' of the node). The node
+  # names are required to be *unique* within the tree.
+  #
+  # The node content is not required to be unique across different nodes in the tree, and
+  # can be +nil+ as well.
+  #
+  # The class provides various traversal methods to navigate the tree,
+  # methods to modify contents of the node or to change position of the node in the tree
+  # and methods to change structure of the tree.
   #
-  # A node can have any number of child nodes attached to it.  Note that while
-  # this implementation does not support directed graphs, the class itself makes
-  # no restrictions on associating a node's CONTENT with multiple parent nodes.
+  # A node can have any number of child nodes attached to it and hence can be used to create N-ary trees.
+  # Access to the child nodes can be made in order (with the conventional left to right access), or
+  # randomly.
+  #
+  # The node also provides direct access to its parent and other superior parents in the path to
+  # root of the tree.  In addition, a node can also access its sibling nodes, if present.
+  # Note that while this implementation does not explicitly support directed graphs, the class itself makes
+  # no restrictions on associating a node's +CONTENT+ with multiple nodes in the tree.
   #
   #
   # == Example
   #
-  #  The following code-snippet implements this tree structure:
+  #  The following example implements this tree structure:
   #
   #                    +------------+
   #                    |    ROOT    |
@@ -81,36 +94,38 @@ module Tree
   #
   # require 'tree'
   #
-  # myTreeRoot = Tree::TreeNode.new("ROOT", "Root Content")
+  # root_node = Tree::TreeNode.new("ROOT", "Root Content")
   #
-  # myTreeRoot << Tree::TreeNode.new("CHILD1", "Child1 Content") << Tree::TreeNode.new("GRANDCHILD1", "GrandChild1 Content")
+  # root_node << Tree::TreeNode.new("CHILD1", "Child1 Content") << Tree::TreeNode.new("GRANDCHILD1", "GrandChild1 Content")
   #
-  # myTreeRoot << Tree::TreeNode.new("CHILD2", "Child2 Content")
+  # root_node << Tree::TreeNode.new("CHILD2", "Child2 Content")
   #
-  # myTreeRoot.printTree
+  # root_node.printTree
   #
-  # child1 = myTreeRoot["CHILD1"]
+  # child1       = root_node["CHILD1"]
   #
-  # grandChild1 = myTreeRoot["CHILD1"]["GRANDCHILD1"]
+  # grand_child1 = root_node["CHILD1"]["GRANDCHILD1"]
   #
-  # siblingsOfChild1Array = child1.siblings
+  # siblings_of_child1 = child1.siblings
   #
-  # immediateChildrenArray = myTreeRoot.children
+  # children_of_root   = root_node.children
   #
   # # Process all nodes
   #
-  # myTreeRoot.each { |node| node.content.reverse }
+  # root_node.each { |node| node.content.reverse }
   #
-  # myTreeRoot.remove!(child1) # Remove the child
+  # root_node.remove!(child1) # Remove the child
   #
   class TreeNode
     include Enumerable
 
-    # Name of this Node
+    # Name of this node.  Expected to be unique within the tree.
     attr_reader   :name
-    # Content of this Node
+
+    # Content of this node.  Can be +nil+.
     attr_accessor :content
-    # Parent of this Node
+
+    # Parent of this node.  Will be +nil+ for root nodes.
     attr_reader   :parent
 
 
@@ -128,8 +143,8 @@ module Tree
       @children = []
     end
 
-    # Returns a copy of this node, with the parent and children links removed.  The original node remains attached to
-    # its tree.
+    # Returns a copy of the receiver node, with its parent and children links removed.
+    # The original node remains attached to its tree.
     def detached_copy
       Tree::TreeNode.new(@name, @content ? @content.clone : nil)
     end
@@ -143,8 +158,10 @@ module Tree
         " Total Nodes: #{size()}"
     end
 
-    # Returns an array of ancestors in reversed order (the first element is the
-    # immediate parent). Returns +nil+ if this is the root node.
+    # Returns an array of ancestors of the receiver node in reversed order
+    # (the first element is the immediate parent of the receiver).
+    #
+    # Returns +nil+ if the receiver is a root node.
     def parentage
       return nil if isRoot?
 
@@ -158,23 +175,38 @@ module Tree
       parentageArray
     end
 
-    # Protected method to set the parent node.
-    # This method should NOT be invoked by client code.
-    def parent=(parent)
+    # Protected method to set the parent node for the receiver node.
+    # This method should *NOT* be invoked by client code.
+    #
+    # Returns the parent.
+    def parent=(parent)         # :nodoc:
       @parent = parent
     end
 
-    # Convenience synonym for TreeNode#add method.  This method allows a convenient
-    # method to add children hierarchies in the tree.
+    # Convenience synonym for TreeNode#add method.
+    #
+    # This method allows an easy method to add node hierarchies to the tree
+    # on a given path via chaining the method calls to successive child nodes.
     #
-    # E.g. root << child << grand_child
+    # Example: <tt>root << child << grand_child</tt>
+    #
+    # Returns the added child node.
     def <<(child)
       add(child)
     end
 
-    # Adds the specified child node to the receiver node.  The child node's
-    # parent is set to be the receiver.  The child is added as the last child in
-    # the current list of children for the receiver node.
+    # Adds the specified child node to the receiver node.
+    #
+    # This method can also be used for *grafting* a subtree into the receiver node's tree, if the specified child node
+    # is the root of a subtree (i.e., has child nodes under it).
+    #
+    # The receiver node becomes parent of the node passed in as the argument, and
+    # the child is added as the last child ("right most") in the current set of
+    # children of the receiver node.
+    #
+    # Returns the added child node.
+    #
+    # An exception is raised if another child node with the same name exists.
     def add(child)
       raise "Child already added" if @childrenHash.has_key?(child.name)
 
@@ -182,12 +214,15 @@ module Tree
       @children << child
       child.parent = self
       return child
-
     end
 
-    # Removes the specified child node from the receiver node.  The removed
-    # children nodes are orphaned but available if an alternate reference
-    # exists.
+    # Removes the specified child node from the receiver node.
+    #
+    # This method can also be used for *pruning* a subtree, in cases where the removed child node is
+    # the root of the subtree to be pruned.
+    #
+    # The removed child node is orphaned but accessible if an alternate reference exists.  If accesible via
+    # an alternate reference, the removed child will report itself as a root node for its subtree.
     #
     # Returns the child node.
     def remove!(child)
@@ -197,13 +232,18 @@ module Tree
       return child
     end
 
-    # Removes this node from its parent. If this is the root node, then does
-    # nothing.
+    # Removes the receiver node from its parent.  The reciever node becomes the new root for its subtree.
+    #
+    # If this is the root node, then does nothing.
+    #
+    # Returns self (the removed receiver node) if the operation is successful, and +nil+ otherwise.
     def removeFromParent!
       @parent.remove!(self) unless isRoot?
     end
 
     # Removes all children from the receiver node.
+    #
+    # Returns the receiver node.
     def removeAll!
       for child in @children
         child.setAsRoot!
@@ -213,35 +253,38 @@ module Tree
       self
     end
 
-    # Returns +true+ if this node has any associated content.
+    # Returns +true+ if the receiver node has any associated content.
     def hasContent?
       @content != nil
     end
 
-    # Protected method which sets this node as a root node.
-    def setAsRoot!
+    # Protected method which sets the receiver node as a root node.
+    #
+    # Returns +nil+.
+    def setAsRoot!              # :nodoc:
       @parent = nil
     end
 
-    # Returns +true+ if this is a root node. Note that
+    # Returns +true+ if the receiver is a root node.  Note that
     # orphaned children will also be reported as root nodes.
     def isRoot?
       @parent == nil
     end
 
-    # Returns +true+ if this node has any immediate child nodes.
+    # Returns +true+ if the receiver node has any immediate child nodes.
     def hasChildren?
       @children.length != 0
     end
 
-    # Returns +true+ if this node is a 'leaf' - i.e., one without
+    # Returns +true+ if the receiver node is a 'leaf' - i.e., one without
     # any children.
     def isLeaf?
       !hasChildren?
     end
 
-    # Returns an array of all the immediate children.  If a block is given,
-    # yields each child node to the block.
+    # Returns an array of all the immediate children of the receiver node.
+    #
+    # If a block is given, yields each child node to the block traversing from left to right.
     def children
       if block_given?
         @children.each {|child| yield child}
@@ -250,34 +293,37 @@ module Tree
       end
     end
 
-    # Returns the first child of this node. Will return nil if no children are
-    # present.
+    # Returns the first child of the receiver node.
+    #
+    # Will return +nil+ if no children are present.
     def firstChild
       children.first
     end
 
-    # Returns the last child of this node. Will return nil if no children are
-    # present.
+    # Returns the last child of the receiver node.
+    #
+    # Will return +nil+ if no children are present.
     def lastChild
       children.last
     end
 
-    # Returns every node (including the receiver node) from the tree to the
-    # specified block. The traversal is depth first and from left to right in
-    # pre-ordered sequence.
-    def each &block
+    # Traverses every node (including the receiver node) from the (sub)tree
+    # by yielding the node to the specified block.
+    #
+    # The traversal is depth-first and from left to right in pre-ordered sequence.
+    def each &block             # :yields: node
       yield self
       children { |child| child.each(&block) }
     end
 
-    # Traverses the tree in a pre-ordered sequence. This is equivalent to
+    # Traverses the tree in a pre-ordered sequence.  This is equivalent to
     # TreeNode#each
-    def preordered_each &block
+    def preordered_each &block  # :yields: node
       each(&block)
     end
 
-    # Performs breadth first traversal of the tree starting at this node. The
-    # traversal in a given level is from left to right.
+    # Performs breadth first traversal of the tree starting at the receiver node. The
+    # traversal at a given level is from left to right.
     def breadth_each &block
       node_queue = [self]       # Create a queue with self as the initial entry
 
@@ -290,18 +336,21 @@ module Tree
       end
     end
 
-    # Yields all leaf nodes from this node to the specified block. May yield
-    # this node as well if this is a leaf node.  Leaf traversal depth first and
-    # left to right.
+    # Yields all leaf nodes from the receiver node to the specified block.
+    #
+    # May yield this node as well if this is a leaf node.
+    # Leaf traversal is depth-first and left to right.
     def each_leaf &block
       self.each { |node| yield(node) if node.isLeaf? }
     end
 
     # Returns the requested node from the set of immediate children.
     #
-    # If the parameter is _numeric_, then the in-sequence array of children is
-    # accessed (see Tree#children).  If the parameter is not _numeric_, then it
-    # is assumed to be the *name* of the child node to be returned.
+    # If the argument is _numeric_, then the in-sequence array of children is
+    # accessed (see Tree#children).  If the argument is *NOT* _numeric_, then it
+    # is assumed to be *name* of the child node to be returned.
+    #
+    # Raises an exception is the requested child node is not found.
     def [](name_or_index)
       raise "Name_or_index needs to be provided" if name_or_index == nil
 
@@ -312,11 +361,11 @@ module Tree
       end
     end
 
-    # Returns the total number of nodes in this tree, including this node.
+    # Returns the total number of nodes in this (sub)tree, including the receiver node.
     #
     # Size of the tree is defined as:
     #
-    # Size:: The total number nodes in the subtree including this node.
+    # Size:: Total number nodes in the subtree including the receiver node.
     def size
       @children.inject(1) {|sum, node| sum + node.size}
     end
@@ -344,105 +393,131 @@ module Tree
       children { |child| child.printTree(level + 1)}
     end
 
-    # Returns the root for this tree. Root's root is itself (Hence beware of any loop that can become infinite!)
+    # Returns root node for the (sub)tree to which the receiver node belongs.
+    #
+    # Note that a root node's root is itself (*beware* of any loop construct that may become infinite!)
+    #--
+    # TODO: We should perhaps return nil as root's root.
+    #++
     def root
       root = self
       root = root.parent while !root.isRoot?
       root
     end
 
-    # Returns the first sibling for this node. If this is the root node, returns
+    # Returns the first sibling for the receiver node. If this is the root node, returns
     # itself.
+    #
+    # 'First' sibling is defined as follows:
+    # First sibling:: The left-most child of the receiver's parent, which may be the receiver itself
+    #--
+    # TODO: Fix the inconsistency of returning root as its first sibling, and returning a
+    #       a nil array for siblings for the node.
+    #++
     def firstSibling
-      if isRoot?
-        self
-      else
-        parent.children.first
-      end
+      isRoot? ? self : parent.children.first
     end
 
-    # Returns true if this node is the first sibling.
+    # Returns true if the receiver node is the first sibling.
     def isFirstSibling?
       firstSibling == self
     end
 
-    # Returns the last sibling for this node.  If this node is the root, returns
+    # Returns the last sibling for the receiver node.  If this is the root node, returns
     # itself.
+    #
+    # 'Last' sibling is defined as follows:
+    # Last sibling:: The right-most child of the receiver's parent, which may be the receiver itself
+    #--
+    # TODO: Fix the inconsistency of returning root as its last sibling, and returning a
+    #       a nil array for siblings for the node.
+    #++
     def lastSibling
-      if isRoot?
-        self
-      else
-        parent.children.last
-      end
+      isRoot? ? self : parent.children.last
     end
 
-    # Returns true if his node is the last sibling
+    # Returns true if the receivere node is the last sibling.
     def isLastSibling?
       lastSibling == self
     end
 
-    # Returns an array of siblings for this node.
-    # If a block is provided, yields each of the sibling
-    # nodes to the block. The root always has nil siblings.
+    # Returns an array of siblings for the receiver node.  The receiver node is excluded.
+    #
+    # If a block is provided, yields each of the sibling nodes to the block.
+    # The root always has +nil+ siblings.
+    #--
+    # TODO: Fix the inconsistency of returning root as its first/last sibling, and returning a
+    #       a nil array for siblings for the node.
+    #++
     def siblings
       return nil if isRoot?
+
       if block_given?
         for sibling in parent.children
           yield sibling if sibling != self
         end
       else
         siblings = []
-        parent.children {|sibling| siblings << sibling if sibling != self}
+        parent.children {|my_sibling| siblings << my_sibling if my_sibling != self}
         siblings
       end
     end
 
-    # Returns true if this node is the only child of its parent
+    # Returns true if the receiver node is the only child of its parent.
     def isOnlyChild?
       parent.children.size == 1
     end
 
-    # Returns the next sibling for this node. Will return nil if no subsequent
-    # node is present.
+    # Returns the next sibling for the receiver node.
+    # The 'next' node is defined as the node to right of the receiver node.
+    #
+    # Will return +nil+ if no subsequent node is present.
     def nextSibling
       if myidx = parent.children.index(self)
         parent.children.at(myidx + 1)
       end
     end
 
-    # Returns the previous sibling for this node. Will return nil if no
-    # subsequent node is present.
+    # Returns the previous sibling for the receiver node.
+    # The 'previous' node is defined as the node to left of the receiver node.
+    #
+    # Will return nil if no predecessor node is present.
     def previousSibling
       if myidx = parent.children.index(self)
         parent.children.at(myidx - 1) if myidx > 0
       end
     end
 
-    # Provides a comparision operation for the nodes. Comparision
-    # is based on the natural character-set ordering for the
-    # node names.
+    # Provides a comparision operation for the nodes.
+    #
+    # Comparision is based on the natural character-set ordering of the *node name*.
     def <=>(other)
       return +1 if other == nil
       self.name <=> other.name
     end
 
-    # Freezes all nodes in the tree
+    # Freezes all nodes in the (sub)tree rooted at the receiver node.
     def freezeTree!
       each {|node| node.freeze}
     end
 
-    # Creates the marshal-dump represention of the tree rooted at this node.
+    # Returns a marshal-dump represention of the (sub)tree rooted at the receiver node.
     def marshal_dump
       self.collect { |node| node.createDumpRep }
     end
 
-    # Creates a dump representation and returns the same as a hash.
-    def createDumpRep
+    # Creates a dump representation of the reciever node and returns the same as a hash.
+    def createDumpRep           # :nodoc:
       { :name => @name, :parent => (isRoot? ? nil : @parent.name),  :content => Marshal.dump(@content)}
     end
 
-    # Loads a marshalled dump of the tree and returns the root node of the
+    # Loads a marshalled dump of a tree and returns the root node of the
     # reconstructed tree. See the Marshal class for additional details.
+    #
+    #--
+    # TODO: This method probably should be a class method.  It currently clobbers self
+    #       and makes itself the root.
+    #++
     def marshal_load(dumped_tree_array)
       nodes = { }
       for node_hash in dumped_tree_array do
@@ -458,37 +533,41 @@ module Tree
           initialize(name, content)
 
           nodes[name] = self    # Add self to the list of nodes
-         end
+        end
       end
     end
 
-    # Returns height of the (sub)tree from this node.  Height of a node is defined as:
+    # Returns height of the (sub)tree from the receiver node.  Height of a node is defined as:
+    #
+    # Height:: Length of the longest downward path to a leaf from the node.
     #
-    # Height:: Length of the longest downward path to a leaf from the node.  Height of from the root node is height of
-    # the tree.  The height of a leaf node is zero.
+    # - Height from a root node is height of the entire tree.
+    # - The height of a leaf node is zero.
     def nodeHeight
       return 0 if isLeaf?
       1 + @children.collect { |child| child.nodeHeight }.max
     end
 
-    # Returns depth this node in its (sub)tree.  Depth of a node is defined as:
+    # Returns depth of the receiver node in its tree.  Depth of a node is defined as:
     #
     # Depth:: Length of the node's path to its root.  Depth of a root node is zero.
     #
-    # Note that the deprecated method Tree::TreeNode#depth was incorrectly computing this value.  Please replace all
-    # calls to the old method by this one.
+    # *Note* that the deprecated method Tree::TreeNode#depth was incorrectly computing this value.
+    # Please replace all calls to the old method with Tree::TreeNode#nodeDepth instead.
     def nodeDepth
       return 0 if isRoot?
       1 + parent.nodeDepth
     end
 
-    # Returns depth of the tree from this node. A single leaf node has a depth of 1.
+    # Returns depth of the tree from the receiver node. A single leaf node has a depth of 1.
+    #
+    # This method is *DEPRECATED* and may be removed in the subsequent releases.
+    # Note that the value returned by this method is actually the:
     #
-    # This method is *DEPRECATED* and may be removed in the subsequent releases.  Note that per convention, the value
-    # returned by this method is actually the _height_ + 1 of the node, *not* the _depth_.
+    # _height_ + 1 of the node, *NOT* the _depth_.
     #
-    # For correct and conventional behavior, please use Tree::TreeNode#nodeDepth and Tree::TreeNode#nodeHeight methods
-    # instead.
+    # For correct and conventional behavior, please use Tree::TreeNode#nodeDepth and
+    # Tree::TreeNode#nodeHeight methods instead.
     def depth
       begin
         require 'structured_warnings'   # To enable a nice way of deprecating of the depth method.
@@ -498,17 +577,17 @@ module Tree
         warn 'Tree::TreeNode#depth() method is deprecated.  Please use nodeDepth() or nodeHeight() instead (bug # 22535)'
       end
 
-
       return 1 if isLeaf?
       1 + @children.collect { |child| child.depth }.max
     end
 
-    # Returns breadth of the tree at this node level. A single node has a breadth of 1.  Breadth is defined to be the
-    # number of nodes present as siblings to this node + 1 (this node itself), i.e., the number of children the parent
-    # of this node has.
+    # Returns breadth of the tree at the receiver node's  level.
+    # A single node without siblings has a breadth of 1.
+    #
+    # Breadth is defined to be:
+    # Breadth:: Number of sibling nodes to this node + 1 (this node itself), i.e., the number of children the parent of this node has.
     def breadth
-      return 1 if isRoot?
-      parent.children.size
+      isRoot? ? 1 : parent.children.size
     end
 
     protected :parent=, :setAsRoot!, :createDumpRep

data/lib/tree/binarytree.rb

@@ -1,12 +1,11 @@
-# binarytree.rb
+# binarytree.rb - This file is part of the RubyTree package.
 #
-# $Revision: 160 $ by $Author: anupamsg $ on $Date: 2010-01-03 23:58:07 +0530 (Sun, 03 Jan 2010) $
+# $Revision$ by $Author$ on $Date$
 #
-# = binarytree.rb - Binary Tree implementation
+# = binarytree.rb - An implementation of the binary tree data structure.
 #
-# Provides a generic tree data structure with ability to
-# store keyed node elements in the tree. The implementation
-# mixes in the Enumerable module.
+# Provides a binary tree data structure with ability to
+# store two node elements as children at each node in the tree.
 #
 # Author:: Anupam Sengupta (anupamsg@gmail.com)
 #
@@ -45,61 +44,67 @@ require 'tree'
 
 module Tree
 
-  # Provides a Binary tree implementation. This tree node allows only two child nodes (left and right childs). It also
+  # Provides a Binary tree implementation. This node allows only two child nodes (left and right child).  It also
   # provides direct access to the left or right child, including assignment to the same.
+  #
+  # This inherits from the Tree::TreeNode class.
   class BinaryTreeNode < TreeNode
 
-    # Adds the specified child node to the receiver node.  The child node's parent is set to be the receiver.  The child
-    # nodes are added in the order of addition, i.e., the first child added becomes the left node, and the second child
-    # will be the second node.
+    # Adds the specified child node to the receiver node.  The child node's parent is set to be the receiver.
+    #
+    # The child nodes are added in the order of addition, i.e., the first child added becomes the left node, and the
+    # second child added will be the second node.
     #
     # If only one child is present, then this will be the left child.
+    #
+    # An exception is raised if two children are already present.
     def add(child)
       raise "Already has two child nodes" if @children.size == 2
 
       super(child)
     end
 
-    # Returns the left child node. Note that left Child == first Child.
+    # Returns the left child of the receiver node. Note that left Child == first Child.
     def leftChild
       children.first
     end
 
-    # Returns the right child node. Note that right child == last child unless there is only one child.  Returns +nil+
-    # if the right child does not exist.
+    # Returns the right child of the receiver node. Note that right child == last child unless there is only one child.
+    #
+    # Returns +nil+ if the right child does not exist.
     def rightChild
       children[1]
     end
 
-    # Sets the left child. If a previous child existed, it is replaced.
+    # Sets the left child of the receiver node. If a previous child existed, it is replaced.
     def leftChild=(child)
       @children[0] = child
       @childrenHash[child.name] = child if child # Assign the name mapping
     end
 
-    # Sets the right child. If a previous child existed, it is replaced.
+    # Sets the right child of the receiver node. If a previous child existed, it is replaced.
     def rightChild=(child)
       @children[1] = child
       @childrenHash[child.name] = child if child # Assign the name mapping
     end
 
-    # Returns +true+ if this is the left child of its parent.  Always returns +false+ if this is the root node.
+    # Returns +true+ if the receiver node is the left child of its parent.  Always returns +false+ if it is a root node.
     def isLeftChild?
-      return nil if isRoot?
+      return false if isRoot?
       self == parent.leftChild
     end
 
-    # Returns +true+ if this is the right child of its parent. Always returns +false+ if this is the root node.
+    # Returns +true+ if the receiver node is the right child of its parent. Always returns +false+ if it is a root node.
     def isRightChild?
-      return nil if isRoot?
+      return false if isRoot?
       self == parent.rightChild
     end
 
-    # Swaps the left and right child nodes with each other.
+    # Swaps the left and right child nodes of the receiver node with each other.
     def swap_children
-      tempChild = leftChild
-      self.leftChild= rightChild
-      self.rightChild= tempChild
+      tempChild       = leftChild
+      self.leftChild  = rightChild
+      self.rightChild = tempChild
     end
   end
 

data/test/test_binarytree.rb

@@ -1,8 +1,8 @@
 #!/usr/bin/env ruby
 
-# test_binarytree.rb
+# test_binarytree.rb - This file is part of the RubyTree package.
 #
-# $Revision: 146 $ by $Author: anupamsg $ on $Date: 2010-01-02 14:53:30 +0530 (Sat, 02 Jan 2010) $
+# $Revision$ by $Author$ on $Date$
 #
 # Copyright (c) 2006, 2007, 2008, 2009, 2010 Anupam Sengupta
 #
@@ -38,7 +38,7 @@ require 'test/unit'
 require 'tree/binarytree'
 
 module TestTree
-  # Test class for the Tree node.
+  # Test class for the binary tree node.
   class TestBinaryTreeNode < Test::Unit::TestCase
 
     def setup

data/test/test_tree.rb

@@ -1,8 +1,8 @@
 #!/usr/bin/env ruby
 
-# testtree.rb
+# testtree.rb - This file is part of the RubyTree package.
 #
-# $Revision: 164 $ by $Author: anupamsg $ on $Date: 2010-01-05 00:57:12 +0530 (Tue, 05 Jan 2010) $
+# $Revision$ by $Author$ on $Date$
 #
 # Copyright (c) 2006, 2007, 2008, 2009, 2010 Anupam Sengupta
 #
@@ -41,7 +41,7 @@ module TestTree
   # Test class for the Tree node.
   class TestTreeNode < Test::Unit::TestCase
 
-    Person = Struct::new(:First, :last)
+    Person = Struct::new(:First, :last) # A simple structure to use as the content for the nodes.
 
     def setup
       @root = Tree::TreeNode.new("ROOT", "Root Node")
@@ -83,16 +83,16 @@ module TestTree
 
     # This test is for the root alone - without any children being linked
     def test_root_setup
-      assert_not_nil(@root, "Root cannot be nil")
-      assert_nil(@root.parent, "Parent of root node should be nil")
-      assert_not_nil(@root.name, "Name should not be nil")
-      assert_equal("ROOT", @root.name, "Name should be 'ROOT'")
-      assert_equal("Root Node", @root.content, "Content should be 'Root Node'")
-      assert(@root.isRoot?, "Should identify as root")
-      assert(!@root.hasChildren?, "Cannot have any children")
-      assert(@root.hasContent?, "This root should have content")
-      assert_equal(1, @root.size, "Number of nodes should be one")
-      assert_nil(@root.siblings, "This root does not have any children")
+      assert_not_nil(@root       , "Root cannot be nil")
+      assert_nil(@root.parent    , "Parent of root node should be nil")
+      assert_not_nil(@root.name  , "Name should not be nil")
+      assert_equal("ROOT"        , @root.name, "Name should be 'ROOT'")
+      assert_equal("Root Node"   , @root.content, "Content should be 'Root Node'")
+      assert(@root.isRoot?       , "Should identify as root")
+      assert(!@root.hasChildren? , "Cannot have any children")
+      assert(@root.hasContent?   , "This root should have content")
+      assert_equal(1             , @root.size, "Number of nodes should be one")
+      assert_nil(@root.siblings  , "This root does not have any children")
 
       assert_equal(0, @root.nodeHeight, "Root's height before adding any children is 0")
       assert_raise(RuntimeError) { Tree::TreeNode.new(nil) }
@@ -102,16 +102,16 @@ module TestTree
     def test_root
       loadChildren
 
-      assert_same(@root, @root.root, "Root's root is self")
-      assert_same(@root, @child1.root, "Root should be ROOT")
-      assert_same(@root, @child4.root, "Root should be ROOT")
-      assert_equal(2, @root.nodeHeight, "Root's height after adding the children should be 2")
+      assert_same(@root , @root.root, "Root's root is self")
+      assert_same(@root , @child1.root, "Root should be ROOT")
+      assert_same(@root , @child4.root, "Root should be ROOT")
+      assert_equal(2    , @root.nodeHeight, "Root's height after adding the children should be 2")
     end
 
     def test_hasContent_eh
       aNode = Tree::TreeNode.new("A Node")
-      assert_nil(aNode.content, "The node should not have content")
-      assert(!aNode.hasContent?, "The node should not have content")
+      assert_nil(aNode.content  , "The node should not have content")
+      assert(!aNode.hasContent? , "The node should not have content")
 
       aNode.content = "Something"
       assert_not_nil(aNode.content, "The node should now have content")
@@ -496,8 +496,11 @@ module TestTree
       @root.content = "ABC"
       assert_equal("ABC", @root.content, "Content should be 'ABC'")
       @root.freezeTree!
-      assert_raise(TypeError) {@root.content = "123"}
-      assert_raise(TypeError) {@root[0].content = "123"}
+      # Note: The error raised here depends on the Ruby version.
+      # For Ruby > 1.9, RuntimeError is raised
+      # For Ruby ~ 1.8, TypeError is raised
+      assert_raise(RuntimeError, TypeError) {@root.content = "123"}
+      assert_raise(RuntimeError, TypeError) {@root[0].content = "123"}
     end
 
     # Test whether the content is accesible

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: rubytree
 version: !ruby/object:Gem::Version 
-  version: 0.6.1
+  version: 0.6.2
 platform: ruby
 authors: 
 - Anupam Sengupta
@@ -9,9 +9,29 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-01-05 00:00:00 +05:30
+date: 2010-01-30 00:00:00 +05:30
 default_executable: 
 dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: rubyforge
+  type: :development
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 2.0.3
+    version: 
+- !ruby/object:Gem::Dependency 
+  name: gemcutter
+  type: :development
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 0.3.0
+    version: 
 - !ruby/object:Gem::Dependency 
   name: hoe
   type: :development
@@ -20,13 +40,14 @@ dependencies:
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
-        version: 2.4.0
+        version: 2.5.0
     version: 
 description: |-
-  RubyTree is a Ruby implementation of the generic Tree data structure.  It provides a generic tree data-structure with
-  ability to store keyed node-elements in the tree.  This implementation is node-centric, where the individual nodes on
-  the tree are the primary objects and form the leafs of the structure.  The implementation mixes in the Enumerable
-  module.
+  RubyTree is a Ruby implementation of the generic tree data structure.  It provides a node-based model to store keyed
+  node-elements in the tree and simple APIs to access, modify and traverse the structure.  RubyTree is node-centric, where
+  individual nodes on the tree are the primary compositional and structural elements.
+  
+  This implementation also mixes in the Enumerable module to allow standard access to the tree as a collection.
 email: 
 - anupamsg@gmail.com
 executables: []
@@ -56,7 +77,18 @@ has_rdoc: true
 homepage: http://rubytree.rubyforge.org
 licenses: []
 
-post_install_message: 
+post_install_message: |
+  ========================================================================
+  
+   Thank you for installing Rubytree.
+  
+   Please note that a few APIs have been deprecated since Version 0.6.1
+  
+   Specifically, the 'Tree::TreeNode#depth' method is now deprecated, and
+   a new nodeDepth() method has been introduced.
+  
+  ========================================================================
+
 rdoc_options: 
 - --main
 - README
@@ -81,7 +113,7 @@ rubyforge_project: rubytree
 rubygems_version: 1.3.5
 signing_key: 
 specification_version: 3
-summary: RubyTree is a Ruby implementation of the generic Tree data structure
+summary: RubyTree is a Ruby implementation of the generic tree data structure
 test_files: 
 - test/test_binarytree.rb
 - test/test_tree.rb