rubytree 0.8.3 → 0.9.0

data/examples/example_basic.rb

@@ -0,0 +1,53 @@
+#!/usr/bin/env ruby
+#
+# example_basic.rb:: Basic usage of the tree library.
+#
+# Author:  Anupam Sengupta
+# Time-stamp: <2013-12-28 12:14:20 anupam>
+# Copyright (C) 2013 Anupam Sengupta <anupamsg@gmail.com>
+#
+# The following example implements this tree structure:
+#
+#                    +------------+
+#                    |    ROOT    |
+#                    +-----+------+
+#            +-------------+------------+
+#            |                          |
+#    +-------+-------+          +-------+-------+
+#    |  CHILD 1      |          |  CHILD 2      |
+#    +-------+-------+          +---------------+
+#            |
+#            |
+#    +-------+-------+
+#    | GRANDCHILD 1  |
+#    +---------------+
+
+# ..... 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")
+root_node.print_tree
+
+# ..... 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.print_tree
+
+# ..... 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"]
+
+# ..... Now lets retrieve siblings of the current node as an array.
+siblings_of_child1 = child1.siblings
+
+# ..... Lets retrieve immediate children of the root node as an array.
+children_of_root = root_node.children
+
+# ..... This is a depth-first and L-to-R pre-ordered traversal.
+root_node.each { |node| node.content.reverse }
+
+# ..... Lets remove a child node from the root node.
+root_node.remove!(child1)

data/lib/tree.rb

@@ -9,7 +9,7 @@
 # Author:: Anupam Sengupta (anupamsg@gmail.com)
 #
 
-# Copyright (c) 2006, 2007, 2008, 2009, 2010, 2011, 2012 Anupam Sengupta
+# Copyright (c) 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013 Anupam Sengupta
 #
 # All rights reserved.
 #
@@ -41,17 +41,21 @@
 
 require 'tree/tree_deps'
 require 'tree/version'
+require 'tree/utils/metrics_methods'
+require 'tree/utils/camel_case_method_handler'
+require 'tree/utils/json_converter'
+require 'tree/utils/tree_merge_handler'
 
-# This module provides a TreeNode class which is the primary class for representing
-# nodes in the tree.
+# This module provides a *TreeNode* class whose instances are the primary objects
+# for representing nodes in the tree.
 #
-# This module also acts as the namespace for all classes in the RubyTree package.
+# This module also acts as the namespace for all classes in the *RubyTree* package.
 module Tree
 
   # == TreeNode Class Description
   #
-  # 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.,
+  # This class models the nodes for an *N-ary* tree data structure. 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 (as the name is implicitly used as an _ID_ within
   # the data structure).
@@ -78,58 +82,20 @@ module Tree
   # However, having duplicate nodes within the structure is likely to
   # cause unpredictable behavior.
   #
-  #
   # == Example
   #
-  # The following example implements this tree structure:
-  #
-  #                    +------------+
-  #                    |    ROOT    |
-  #                    +-----+------+
-  #            +-------------+------------+
-  #            |                          |
-  #    +-------+-------+          +-------+-------+
-  #    |  CHILD 1      |          |  CHILD 2      |
-  #    +-------+-------+          +---------------+
-  #            |
-  #            |
-  #    +-------+-------+
-  #    | GRANDCHILD 1  |
-  #    +---------------+
-  #
-  #    # ..... 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")
-  #    root_node.print_tree
-  #
-  #    # ..... 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.print_tree
-  #
-  #    # ..... 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"]
-  #
-  #    # ..... Now lets retrieve siblings of the current node as an array.
-  #    siblings_of_child1 = child1.siblings
-  #
-  #    # ..... Lets retrieve immediate children of the root node as an array.
-  #    children_of_root = root_node.children
-  #
-  #    # ..... This is a depth-first and L-to-R pre-ordered traversal.
-  #    root_node.each { |node| node.content.reverse }
-  #
-  #    # ..... Lets remove a child node from the root node.
-  #    root_node.remove!(child1)
+  # {include:file:examples/example_basic.rb}
   #
   # @author Anupam Sengupta
   class TreeNode
     include Enumerable
+    include Comparable
+    include Tree::Utils::TreeMetricsHandler
+    include Tree::Utils::CamelCaseMethodHandler
+    include Tree::Utils::JSONConverter
+    include Tree::Utils::TreeMergeHandler
+
+    # @!group Core Attributes
 
     # @!attribute [r] name
     #
@@ -147,7 +113,6 @@ module Tree
     attr_reader   :name
 
     # @!attribute [rw] content
-    #
     # Content of this node.  Can be +nil+.  Note that there is no
     # uniqueness constraint related to this attribute.
     #
@@ -155,10 +120,78 @@ module Tree
     attr_accessor :content
 
     # @!attribute [r] parent
-    #
     # Parent of this node.  Will be +nil+ for a root node.
     attr_reader   :parent
 
+    # @!attribute [r] root
+    # Root node for the (sub)tree to which this node belongs.
+    # A root node's root is itself.
+    #
+    # @return [Tree::TreeNode] Root of the (sub)tree.
+    def root
+      root = self
+      root = root.parent while !root.is_root?
+      root
+    end
+
+    # @!attribute [r] is_root?
+    # Returns +true+ if this is a root node.  Note that
+    # orphaned children will also be reported as root nodes.
+    #
+    # @return [Boolean] +true+ if this is a root node.
+    def is_root?
+      @parent == nil
+    end
+
+    # @!attribute [r] has_content?
+    # +true+ if this node has content.
+    #
+    # @return [Boolean] +true+ if the node has content.
+    def has_content?
+      @content != nil
+    end
+
+    # @!attribute [r] is_leaf?
+    # +true+ if this node is a _leaf_ - i.e., one without
+    # any children.
+    #
+    # @return [Boolean] +true+ if this is a leaf node.
+    #
+    # @see #has_children?
+    def is_leaf?
+      !has_children?
+    end
+
+    # @!attribute [r] parentage
+    # An array of ancestors of this node in reversed order
+    # (the first element is the immediate parent of this node).
+    #
+    # Returns +nil+ if this is a root node.
+    #
+    # @return [Array<Tree::TreeNode>] An array of ancestors of this node
+    # @return [nil] if this is a root node.
+    def parentage
+      return nil if is_root?
+
+      parentage_array = []
+      prev_parent = self.parent
+      while (prev_parent)
+        parentage_array << prev_parent
+        prev_parent = prev_parent.parent
+      end
+      parentage_array
+    end
+
+    # @!attribute [r] has_children?
+    # +true+ if the this node has any child node.
+    #
+    # @return [Boolean] +true+ if child nodes exist.
+    #
+    # @see #is_leaf?
+    def has_children?
+      @children.length != 0
+    end
+
     # @!group Node Creation
 
     # Creates a new node with a name and optional content.
@@ -172,10 +205,10 @@ module Tree
     #
     # @raise [ArgumentError] Raised if the node name is empty.
     #
-    # @note If the name is an +Integer+, then the semantics of +TreeNode[]+ can
-    #   be surprising, as an +Integer+ parameter to that method normally acts
-    #   as an index to the <em>children array</em>, and follows the
-    #   <em>zero-based</em> indexing convention.
+    # @note If the name is an +Integer+, then the semantics of {#[]} access
+    #   method can be surprising, as an +Integer+ parameter to that method
+    #   normally acts as an index to the children array, and follows the
+    #   _zero-based_ indexing convention.
     #
     # @see #[]
     def initialize(name, content = nil)
@@ -192,20 +225,20 @@ module Tree
       @children = []
     end
 
-    # Returns a copy of the receiver node, with its parent and children links removed.
+    # Returns a copy of this node, with its parent and children links removed.
     # The original node remains attached to its tree.
     #
-    # @return [Tree::TreeNode] A copy of the receiver node.
+    # @return [Tree::TreeNode] A copy of this node.
     def detached_copy
       Tree::TreeNode.new(@name, @content ? @content.clone : nil)
     end
 
-    # Returns a copy of entire (sub-)tree from receiver node.
+    # Returns a copy of entire (sub-)tree from this node.
     #
     # @author Vincenzo Farruggia
     # @since 0.8.0
     #
-    # @return [Tree::TreeNode] A copy of (sub-)tree from receiver node.
+    # @return [Tree::TreeNode] A copy of (sub-)tree from this node.
     def detached_subtree_copy
       new_node = detached_copy
       children { |child| new_node << child.detached_subtree_copy }
@@ -217,9 +250,52 @@ module Tree
     # @see Tree::TreeNode#detached_subtree_copy
     alias :dup :detached_subtree_copy
 
+    # Returns a {marshal-dump}[http://ruby-doc.org/core-1.8.7/Marshal.html]
+    # represention of the (sub)tree rooted at this node.
+    #
+    def marshal_dump
+      self.collect { |node| node.create_dump_rep }
+    end
+
+    # Creates a dump representation of this node and returns the same as
+    # a hash.
+    def create_dump_rep           # :nodoc:
+      { :name => @name, :parent => (is_root? ? nil : @parent.name),  :content => Marshal.dump(@content)}
+    end
+
+    protected :create_dump_rep
+
+    # Loads a marshalled dump of a tree and returns the root node of the
+    # reconstructed tree. See the
+    # {Marshal}[http://ruby-doc.org/core-1.8.7/Marshal.html] 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 = { }
+      dumped_tree_array.each do |node_hash|
+        name        = node_hash[:name]
+        parent_name = node_hash[:parent]
+        content     = Marshal.load(node_hash[:content])
+
+        if parent_name then
+          nodes[name] = current_node = Tree::TreeNode.new(name, content)
+          nodes[parent_name].add current_node
+        else
+          # This is the root node, hence initialize self.
+          initialize(name, content)
+
+          nodes[name] = self    # Add self to the list of nodes
+        end
+      end
+    end
+
     # @!endgroup
 
-    # Returns string representation of the receiver node.
+    # Returns string representation of this node.
     # This method is primarily meant for debugging purposes.
     #
     # @return [String] A string representation of the node.
@@ -231,36 +307,6 @@ module Tree
         " Total Nodes: #{size()}"
     end
 
-    # @!attribute [r] parentage
-    # 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.
-    #
-    # @return [Array, nil] An array of ancestors of the receiver node, or +nil+ if this is a root node.
-    def parentage
-      return nil if is_root?
-
-      parentage_array = []
-      prev_parent = self.parent
-      while (prev_parent)
-        parentage_array << prev_parent
-        prev_parent = prev_parent.parent
-      end
-
-      parentage_array
-    end
-
-    # Protected method to set the parent node for the receiver node.
-    # This method should *NOT* be invoked by client code.
-    #
-    # @param [Tree::TreeNode] parent The parent node.
-    #
-    # @return [Tree::TreeNode] The parent node.
-    def parent=(parent)         # :nodoc:
-      @parent = parent
-    end
-
     # @!group Structure Modification
 
     # Convenience synonym for {Tree::TreeNode#add} method.
@@ -280,14 +326,15 @@ module Tree
       add(child)
     end
 
-    # Adds the specified child node to the receiver node.
+    # Adds the specified child node to this 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).
+    # This method can also be used for *grafting* a subtree into this
+    # 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
+    # this 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.
+    # children of this node.
     #
     # Additionally you can specify a insert position. The new node will be inserted
     # BEFORE that position. If you don't specify any position the node will be
@@ -313,7 +360,9 @@ module Tree
     def add(child, at_index = -1)
       raise ArgumentError, "Attempting to add a nil node" unless child # Only handles the immediate child scenario
       raise ArgumentError, "Attempting add node to itself" if self == child
-      raise "Child #{child.name} already added!" if @children_hash.has_key?(child.name)
+
+      # Lazy mans unique test, won't test if children of child are unique in this tree too.
+      self.root.each { |node| raise "Child #{child.name} already added!" if node.name == child.name }
 
       if insertion_range.include?(at_index)
         @children.insert(at_index, child)
@@ -326,7 +375,16 @@ module Tree
       return child
     end
 
-    # Removes the specified child node from the receiver node.
+    # Return a range of valid insertion positions.  Used in the #add method.
+    def insertion_range
+      max = @children.size
+      min = -(max+1)
+      min..max
+    end
+
+    private :insertion_range
+
+    # Removes the specified child node from this node.
     #
     # This method can also be used for *pruning* a sub-tree, in cases where the removed child node is
     # the root of the sub-tree to be pruned.
@@ -349,21 +407,33 @@ module Tree
       child
     end
 
-    # Removes the receiver node from its parent.  The reciever node becomes the new root for its subtree.
+    # Protected method to set the parent node for this node.
+    # This method should *NOT* be invoked by client code.
+    #
+    # @param [Tree::TreeNode] parent The parent node.
+    #
+    # @return [Tree::TreeNode] The parent node.
+    def parent=(parent)         # :nodoc:
+      @parent = parent
+    end
+
+    protected :parent=
+
+    # Removes this node from its parent. This node becomes the new root for its subtree.
     #
     # If this is the root node, then does nothing.
     #
-    # @return [Tree:TreeNode] +self+ (the removed receiver node) if the operation is successful, +nil+ otherwise.
+    # @return [Tree:TreeNode] +self+ (the removed node) if the operation is successful, +nil+ otherwise.
     #
     # @see #remove_all!
     def remove_from_parent!
       @parent.remove!(self) unless is_root?
     end
 
-    # Removes all children from the receiver node.  If an indepedent reference exists to the child
+    # Removes all children from this node.  If an independent reference exists to the child
     # nodes, then these child nodes report themselves as roots after this operation.
     #
-    # @return [Tree::TreeNode] The receiver node (+self+)
+    # @return [Tree::TreeNode] this node (+self+)
     #
     # @see #remove!
     # @see #remove_from_parent!
@@ -375,126 +445,163 @@ module Tree
       self
     end
 
-    # Returns +true+ if the receiver node has content.
-    #
-    # @return [Boolean] +true+ if the node has content.
-    def has_content?
-      @content != nil
-    end
-
-    # Protected method which sets the receiver node as a root node.
+    # Protected method which sets this node as a root node.
     #
     # @return +nil+.
     def set_as_root!              # :nodoc:
       @parent = nil
     end
 
-    # @!endgroup
+    protected :set_as_root!
 
-    # Returns +true+ if the receiver is a root node.  Note that
-    # orphaned children will also be reported as root nodes.
+    # Freezes all nodes in the (sub)tree rooted at this node.
     #
-    # @return [Boolean] +true+ if this is a root node.
-    def is_root?
-      @parent == nil
+    # The nodes become immutable after this operation.  In effect, the entire tree's
+    # structure and contents become _read-only_ and cannot be changed.
+    def freeze_tree!
+      each {|node| node.freeze}
     end
 
-    # Returns +true+ if the receiver node has any child node.
+    # @!endgroup
+
+    # @!group Tree Traversal
+
+    # Returns the requested node from the set of immediate children.
     #
-    # @return [Boolean] +true+ if child nodes exist.
+    # - If the +name+ argument is an _Integer_, then the in-sequence
+    #   array of children is accessed using the argument as the
+    #   *index* (zero-based).  However, if the second _optional_
+    #   +num_as_name+ argument is +true+, then the +name+ is used
+    #   literally as a name, and *NOT* as an *index*
     #
-    # @see #is_leaf?
-    def has_children?
-      @children.length != 0
-    end
-
-    # Returns +true+ if the receiver node is a 'leaf' - i.e., one without
-    # any children.
+    # - If the +name+ argument is *NOT* an _Integer_, then it is taken to
+    #   be the *name* of the child node to be returned.
     #
-    # @return [Boolean] +true+ if this is a leaf node.
+    # If a non-+Integer+ +name+ is passed, and the +num_as_name+
+    # parameter is also +true+, then a warning is thrown (as this is a
+    # redundant use of the +num_as_name+ flag.)
     #
-    # @see #has_children?
-    def is_leaf?
-      !has_children?
-    end
-
-    # @!attribute [rw] children
-    # An array of all the immediate children of the receiver
-    # node.  The child nodes are ordered "left-to-right" in the
-    # returned array.
+    # @param [String|Number] name_or_index Name of the child, or its
+    #   positional index in the array of child nodes.
     #
-    # If a block is given, yields each child node to the block
-    # traversing from left to right.
+    # @param [Boolean] num_as_name Whether to treat the +Integer+
+    #   +name+ argument as an actual name, and *NOT* as an _index_ to
+    #   the children array.
     #
-    # @yield [child] Each child is passed to the block, if given
-    # @yieldparam [Tree::TreeNode] child Each child node.
+    # @return [Tree::TreeNode] the requested child node.  If the index
+    #   in not in range, or the name is not present, then a +nil+
+    #   is returned.
     #
-    # @return [Array<Tree::TreeNode>] An array of the child nodes, if no block is given.
-    def children
-      if block_given?
-        @children.each {|child| yield child}
-      else
-        @children
-      end
-    end
-
-    # @!attribute [rw] first_child
-    # First child of the receiver node.
-    # Will be +nil+ if no children are present.
+    # @note The use of +Integer+ names is allowed by using the optional +num_as_name+ flag.
     #
-    # @return [Tree::TreeNode] The first child, or +nil+ if none is present.
-    def first_child
-      children.first
-    end
-
-    # @!attribute [rw] last_child
-    # Last child of the receiver node.
-    # Will be +nil+ if no children are present.
+    # @raise [ArgumentError] Raised if the +name_or_index+ argument is +nil+.
     #
-    # @return [Tree::TreeNode] The last child, or +nil+ if none is present.
-    def last_child
-      children.last
-    end
+    # @see #add
+    # @see #initialize
+    def [](name_or_index, num_as_name=false)
+      raise ArgumentError, "Name_or_index needs to be provided!" if name_or_index == nil
 
-    # @!group Tree Traversal
+      if name_or_index.kind_of?(Integer) and not num_as_name
+        @children[name_or_index]
+      else
+        if num_as_name and not name_or_index.kind_of?(Integer)
+          warn StandardWarning, "Redundant use of the `num_as_name` flag for non-integer node name"
+        end
+        @children_hash[name_or_index]
+      end
+    end
 
-    # Traverses each node (including the receiver node) of the (sub)tree rooted at this node
+    # Traverses each node (including this node) of the (sub)tree rooted at this node
     # by yielding the nodes to the specified block.
     #
     # The traversal is *depth-first* and from *left-to-right* in pre-ordered sequence.
     #
-    # @yield [child] Each node is passed to the block.
-    # @yieldparam [Tree::TreeNode] child Each node.
+    # @yieldparam node [Tree::TreeNode] Each node.
     #
     # @see #preordered_each
     # @see #breadth_each
+    #
+    # @return [Tree::TreeNode] this node, if a block if given
+    # @return [Enumerator] an enumerator on this tree, if a block is *not* given
     def each(&block)             # :yields: node
-      yield self
-      children { |child| child.each(&block) }
+
+     return self.to_enum unless block_given?
+
+      node_stack = [self]   # Start with this node
+
+      until node_stack.empty?
+        current = node_stack.shift    # Pop the top-most node
+        if current                    # The node might be 'nil' (esp. for binary trees)
+          yield current               # and process it
+          # Stack children of the current node at top of the stack
+          node_stack = current.children.clone.concat(node_stack)
+        end
+      end
+
+      return self if block_given?
     end
 
-    # Traverses the (sub)tree rooted at the receiver node in pre-ordered sequence.
+    # Traverses the (sub)tree rooted at this node in pre-ordered sequence.
     # This is a synonym of {Tree::TreeNode#each}.
     #
-    # @yield [child] Each child is passed to the block.
-    # @yieldparam [Tree::TreeNode] node Each node.
+    # @yieldparam node [Tree::TreeNode] Each node.
     #
     # @see #each
     # @see #breadth_each
+    #
+    # @return [Tree::TreeNode] this node, if a block if given
+    # @return [Enumerator] an enumerator on this tree, if a block is *not* given
     def preordered_each(&block)  # :yields: node
       each(&block)
     end
 
-    # Performs breadth-first traversal of the (sub)tree rooted at the receiver node. The
-    # traversal at a given level is from *left-to-right*.  The receiver node itself is the first
+    # Traverses the (sub)tree rooted at this node in post-ordered sequence.
+    #
+    # @yieldparam node [Tree::TreeNode] Each node.
+    #
+    # @see #preordered_each
+    # @see #breadth_each
+    # @return [Tree::TreeNode] this node, if a block if given
+    # @return [Enumerator] an enumerator on this tree, if a block is *not* given
+    def postordered_each(&block)
+      return self.to_enum unless block_given?
+
+      # Using a marked node in order to skip adding the children of nodes that
+      # have already been visited. This allows the stack depth to be controlled,
+      # and also allows stateful backtracking.
+      markednode = Struct.new(:node, :visited)
+      node_stack = [markednode.new(self, false)] # Start with self
+
+      until node_stack.empty?
+        peek_node = node_stack[0]
+        if peek_node.node.has_children? and not peek_node.visited
+          peek_node.visited = true
+          # Add the children to the stack. Use the marking structure.
+          marked_children = peek_node.node.children.map {|node| markednode.new(node, false)}
+          node_stack = marked_children.concat(node_stack)
+          next
+        else
+          yield node_stack.shift.node           # Pop and yield the current node
+        end
+      end
+
+      return self if block_given?
+    end
+
+    # Performs breadth-first traversal of the (sub)tree rooted at this node. The
+    # traversal at a given level is from *left-to-right*.  this node itself is the first
     # node to be traversed.
     #
-    # @yield [child] Each node is passed to the block.
-    # @yieldparam [Tree::TreeNode] node Each node.
+    # @yieldparam node [Tree::TreeNode] Each node.
     #
     # @see #preordered_each
     # @see #breadth_each
+    #
+    # @return [Tree::TreeNode] this node, if a block if given
+    # @return [Enumerator] an enumerator on this tree, if a block is *not* given
     def breadth_each(&block)
+      return self.to_enum unless block_given?
+
       node_queue = [self]       # Create a queue with self as the initial entry
 
       # Use a queue to do breadth traversal
@@ -504,131 +611,77 @@ module Tree
         # Enqueue the children from left to right.
         node_to_traverse.children { |child| node_queue.push child }
       end
+
+      return self if block_given?
     end
 
-    # Yields every leaf node of the (sub)tree rooted at the receiver node to the specified block.
+    # An array of all the immediate children of this node. The child
+    # nodes are ordered "left-to-right" in the returned array.
     #
-    # May yield this node as well if this is a leaf node.
-    # Leaf traversal is *depth-first* and *left-to-right*.
+    # If a block is given, yields each child node to the block
+    # traversing from left to right.
     #
-    # @yield [node] Each leaf node is passed to the block.
-    # @yieldparam [Tree::TreeNode] node Each leaf node.
+    # @yieldparam child [Tree::TreeNode] Each child node.
     #
-    # @see #each
-    # @see #breadth_each
-    def each_leaf &block
+    # @return [Tree::TreeNode] This node, if a block is given
+    # @return [Array<Tree::TreeNode>] An array of the child nodes, if no block is given.
+    def children
       if block_given?
-        self.each { |node| yield(node) if node.is_leaf? }
+        @children.each {|child| yield child}
+        return self
       else
-        self.select { |node| node.is_leaf?}
+        return @children.clone
       end
     end
 
-    # Returns the requested node from the set of immediate children.
+    # Yields every leaf node of the (sub)tree rooted at this node to the specified block.
     #
-    # - If the +name+ argument is an _Integer_, then the in-sequence
-    #   array of children is accessed using the argument as the
-    #   *index* (zero-based).  However, if the second _optional_
-    #   +num_as_name+ argument is +true+, then the +name+ is used
-    #   literally as a name, and *NOT* as an *index*
-    #
-    # - If the +name+ argument is *NOT* an _Integer_, then it is taken to
-    #   be the *name* of the child node to be returned.
-    #
-    # If a non-+Integer+ +name+ is passed, and the +num_as_name+
-    # parameter is also +true+, then a warning is thrown (as this is a
-    # redundant use of the +num_as_name+ flag.)
-    #
-    # @param [String|Number] name_or_index Name of the child, or its
-    #   positional index in the array of child nodes.
-    #
-    # @param [Boolean] num_as_name Whether to treat the +Integer+
-    #   +name+ argument as an actual name, and *NOT* as an _index_ to
-    #   the children array.
-    #
-    # @return [Tree::TreeNode] the requested child node.  If the index
-    #   in not in range, or the name is not present, then a +nil+
-    #   is returned.
+    # May yield this node as well if this is a leaf node.
+    # Leaf traversal is *depth-first* and *left-to-right*.
     #
-    # @note The use of +Integer+ names is allowed by using the optional +num_as_name+ flag.
+    # @yieldparam node [Tree::TreeNode] Each leaf node.
     #
-    # @raise [ArgumentError] Raised if the +name_or_index+ argument is +nil+.
+    # @see #each
+    # @see #breadth_each
     #
-    # @see #add
-    # @see #initialize
-    def [](name_or_index, num_as_name=false)
-      raise ArgumentError, "Name_or_index needs to be provided!" if name_or_index == nil
-
-      if name_or_index.kind_of?(Integer) and not num_as_name
-        @children[name_or_index]
+    # @return [Tree::TreeNode] this node, if a block if given
+    # @return [Array<Tree::TreeNode>] An array of the leaf nodes
+    def each_leaf &block
+      if block_given?
+        self.each { |node| yield(node) if node.is_leaf? }
+        return self
       else
-        if num_as_name and not name_or_index.kind_of?(Integer)
-          warn StandardWarning, "Redundant use of the `num_as_name` flag for non-integer node name"
-        end
-        @children_hash[name_or_index]
+        self.select { |node| node.is_leaf?}
       end
     end
 
     # @!endgroup
 
-    # @!attribute [r] size
-    # Total number of nodes in this (sub)tree, including the receiver node.
-    #
-    # Size of the tree is defined as:
-    #
-    # Size:: Total number nodes in the subtree including the receiver node.
-    #
-    # @return [Integer] Total number of nodes in this (sub)tree.
-    def size
-      @children.inject(1) {|sum, node| sum + node.size}
-    end
+    # @!group Navigating the Child Nodes
 
-    # Convenience synonym for {Tree::TreeNode#size}.
-    #
-    # @deprecated This method name is ambiguous and may be removed.  Use TreeNode#size instead.
+    # First child of this node.
+    # Will be +nil+ if no children are present.
     #
-    # @return [Integer] The total number of nodes in this (sub)tree.
-    # @see #size
-    def length
-      size()
+    # @return [Tree::TreeNode] The first child, or +nil+ if none is present.
+    def first_child
+      children.first
     end
 
-    # Pretty prints the (sub)tree rooted at the receiver node.
+    # Last child of this node.
+    # Will be +nil+ if no children are present.
     #
-    # @param [Integer] level The indentation level (4 spaces) to start with.
-    def print_tree(level = 0)
-      if is_root?
-        print "*"
-      else
-        print "|" unless parent.is_last_sibling?
-        print(' ' * (level - 1) * 4)
-        print(is_last_sibling? ? "+" : "|")
-        print "---"
-        print(has_children? ? "+" : ">")
-      end
-
-      puts " #{name}"
-
-      children { |child| child.print_tree(level + 1)}
+    # @return [Tree::TreeNode] The last child, or +nil+ if none is present.
+    def last_child
+      children.last
     end
 
-    # @!attribute [rw] root
-    # root node for the (sub)tree to which the receiver node belongs.
-    # A root node's root is itself.
-    #
-    # @return [Tree::TreeNode] Root of the (sub)tree.
-    def root
-      root = self
-      root = root.parent while !root.is_root?
-      root
-    end
+    # @!group Navigating the Sibling Nodes
 
-    # @!attribute [rw] first_sibling
-    # First sibling of the receiver node. If this is the root node, then returns
+    # First sibling of this node. If this is the root node, then 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
+    # First sibling:: The left-most child of this node's parent, which may be this node itself
     #
     # @return [Tree::TreeNode] The first sibling node.
     #
@@ -638,7 +691,7 @@ module Tree
       is_root? ? self : parent.children.first
     end
 
-    # Returns +true+ if the receiver node is the first sibling at its level.
+    # Returns +true+ if this node is the first sibling at its level.
     #
     # @return [Boolean] +true+ if this is the first sibling.
     #
@@ -648,12 +701,11 @@ module Tree
       first_sibling == self
     end
 
-    # @!attribute [rw] last_sibling
-    # Last sibling of the receiver node.  If this is the root node, then returns
+    # Last sibling of this node.  If this is the root node, then 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
+    # Last sibling:: The right-most child of this node's parent, which may be this node itself
     #
     # @return [Tree::TreeNode] The last sibling node.
     #
@@ -663,7 +715,7 @@ module Tree
       is_root? ? self : parent.children.last
     end
 
-    # Returns +true+ if the receiver node is the last sibling at its level.
+    # Returns +true+ if this node is the last sibling at its level.
     #
     # @return [Boolean] +true+ if this is the last sibling.
     #
@@ -673,32 +725,31 @@ module Tree
       last_sibling == self
     end
 
-    # @!attribute [rw] siblings
-    # An array of siblings for the receiver node.  The receiver node is excluded.
+    # An array of siblings for this node. This node is excluded.
     #
     # If a block is provided, yields each of the sibling nodes to the block.
     # The root always has +nil+ siblings.
     #
-    # @yield [sibling] Each sibling is passed to the block.
-    # @yieldparam [Tree::TreeNode] sibling Each sibling node.
+    # @yieldparam sibling [Tree::TreeNode] Each sibling node.
     #
-    # @return [Array<Tree::TreeNode>] Array of siblings of this node.
+    # @return [Array<Tree::TreeNode>] Array of siblings of this node. Will return an empty array for *root*
+    # @return [Tree::TreeNode] This node, if no block is given
     #
     # @see #first_sibling
     # @see #last_sibling
     def siblings
-      return [] if is_root?
-
       if block_given?
         parent.children.each { |sibling| yield sibling if sibling != self }
+        return self
       else
+        return [] if is_root?
         siblings = []
         parent.children {|my_sibling| siblings << my_sibling if my_sibling != self}
         siblings
       end
     end
 
-    # Returns +true+ if the receiver node is the only child of its parent.
+    # +true+ if this node is the only child of its parent.
     #
     # As a special case, a root node will always return +true+.
     #
@@ -709,11 +760,10 @@ module Tree
       is_root? ? true : parent.children.size == 1
     end
 
-    # @!attribute [rw] next_sibling
-    # Next sibling for the receiver node.
-    # The 'next' node is defined as the node to right of the receiver node.
+    # Next sibling for this node.
+    # The _next_ node is defined as the node to right of this node.
     #
-    # Will return +nil+ if no subsequent node is present, or if the receiver is a root node.
+    # Will return +nil+ if no subsequent node is present, or if this is a root node.
     #
     # @return [Tree::treeNode] the next sibling node, if present.
     #
@@ -726,11 +776,10 @@ module Tree
       parent.children.at(myidx + 1) if myidx
     end
 
-    # @!attribute [rw] previous_sibling
-    # Previous sibling of the receiver node.
-    # 'Previous' node is defined to be the node to left of the receiver node.
+    # Previous sibling of this node.
+    # _Previous_ node is defined to be the node to left of this node.
     #
-    # Will return +nil+ if no predecessor node is present, or if the receiver is a root node.
+    # Will return +nil+ if no predecessor node is present, or if this is a root node.
     #
     # @return [Tree::treeNode] the previous sibling node, if present.
     #
@@ -743,9 +792,11 @@ module Tree
       parent.children.at(myidx - 1) if myidx && myidx > 0
     end
 
+    # @!endgroup
+
     # Provides a comparision operation for the nodes.
     #
-    # Comparision is based on the natural character-set ordering of the node name.
+    # Comparision is based on the natural ordering of the node name objects.
     #
     # @param [Tree::TreeNode] other The other node to compare against.
     #
@@ -755,246 +806,23 @@ module Tree
       self.name <=> other.name
     end
 
-    # Freezes all nodes in the (sub)tree rooted at the receiver node.
+    # Pretty prints the (sub)tree rooted at this node.
     #
-    # The nodes become immutable after this operation.  In effect, the entire tree's
-    # structure and contents become _read-only_ and cannot be changed.
-    def freeze_tree!
-      each {|node| node.freeze}
-    end
-
-    # Returns a marshal-dump represention of the (sub)tree rooted at the receiver node.
-    def marshal_dump
-      self.collect { |node| node.create_dump_rep }
-    end
-
-    # Creates a dump representation of the reciever node and returns the same as a hash.
-    def create_dump_rep           # :nodoc:
-      { :name => @name, :parent => (is_root? ? nil : @parent.name),  :content => Marshal.dump(@content)}
-    end
-
-    # 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 = { }
-      dumped_tree_array.each do |node_hash|
-        name        = node_hash[:name]
-        parent_name = node_hash[:parent]
-        content     = Marshal.load(node_hash[:content])
-
-        if parent_name then
-          nodes[name] = current_node = Tree::TreeNode.new(name, content)
-          nodes[parent_name].add current_node
-        else
-          # This is the root node, hence initialize self.
-          initialize(name, content)
-
-          nodes[name] = self    # Add self to the list of nodes
-        end
-      end
-    end
-
-    # Creates a JSON ready Hash for the #to_json method.
-    #
-    # @author Eric Cline (https://github.com/escline)
-    # @since 0.8.3
-    #
-    # @return A hash based representation of the JSON
-    #
-    # Rails uses JSON in ActiveSupport, and all Rails JSON encoding goes through as_json
-    #
-    # @see Tree::TreeNode.to_json
-    # @see http://stackoverflow.com/a/6880638/273808
-    def as_json(options = {})
-
-        json_hash = {
-          "name"         => name,
-          "content"      => content,
-          JSON.create_id => self.class.name
-        }
-
-        if has_children?
-          json_hash["children"] = children
-        end
-
-        return json_hash
-
-    end
-
-    # Creates a JSON representation of this node including all it's children.   This requires the JSON gem to be
-    # available, or else the operation fails with a warning message.
-    # Uses the Hash output of as_json method, defined above.
-    #
-    # @author Dirk Breuer (http://github.com/railsbros-dirk)
-    # @since 0.7.0
-    #
-    # @return The JSON representation of this subtree.
-    #
-    # @see Tree::TreeNode.json_create
-    # @see Tree::TreeNode.as_json
-    # @see http://flori.github.com/json
-    def to_json(*a)
-      as_json.to_json(*a)
-    end
-
-    # Helper method to create a Tree::TreeNode instance from the JSON hash representation.  Note that this method should
-    # *NOT* be called directly.  Instead, to convert the JSON hash back to a tree, do:
-    #
-    # tree = JSON.parse (the_json_hash)
-    #
-    # This operation requires the JSON gem to be available, or else the operation fails with a warning message.
-    #
-    # @author Dirk Breuer (http://github.com/railsbros-dirk)
-    # @since 0.7.0
-    #
-    # @param [Hash] json_hash The JSON hash to convert from.
-    #
-    # @return [Tree::TreeNode] The created tree.
-    #
-    # @see #to_json
-    # @see http://flori.github.com/json
-    def self.json_create(json_hash)
-
-      node = new(json_hash["name"], json_hash["content"])
-
-      json_hash["children"].each do |child|
-        node << child
-      end if json_hash["children"]
-
-      return node
-
-    end
-
-    # @!attribute [r] node_height
-    # 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 from a root node is height of the entire tree.
-    # - The height of a leaf node is zero.
-    #
-    # @return [Integer] Height of the node.
-    def node_height
-      return 0 if is_leaf?
-      1 + @children.collect { |child| child.node_height }.max
-    end
-
-    # @!attribute [r] node_depth
-    # 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 with Tree::TreeNode#node_depth instead.
-    #
-    # 'level' is an alias for this method.
-    #
-    # @return [Integer] Depth of this node.
-    def node_depth
-      return 0 if is_root?
-      1 + parent.node_depth
-    end
-
-    alias level node_depth       # Aliased level() method to the node_depth().
-
-    # 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:
-    #
-    # _height_ + 1 of the node, *NOT* the _depth_.
-    #
-    # For correct and conventional behavior, please use {Tree::TreeNode#node_depth} and
-    # {Tree::TreeNode#node_height} methods instead.
-    #
-    # @return [Integer] depth of the node.
-    # @deprecated This method returns an incorrect value.  Use the 'node_depth' method instead.
-    #
-    # @see #node_depth
-    def depth
-      warn DeprecatedMethodWarning, 'This method is deprecated.  Please use node_depth() or node_height() instead (bug # 22535)'
-
-      return 1 if is_leaf?
-      1 + @children.collect { |child| child.depth }.max
-    end
-
-    # Allow the deprecated CamelCase method names.  Display a warning.
-    # :nodoc:
-    def method_missing(meth, *args, &blk)
-      if self.respond_to?(new_method_name = underscore(meth))
-        warn DeprecatedMethodWarning, "The camelCased methods are deprecated. Please use #{new_method_name} instead of #{meth}"
-        return send(new_method_name, *args, &blk)
+    # @param [Integer] level The indentation level (4 spaces) to start with.
+    def print_tree(level = 0)
+      if is_root?
+        print "*"
       else
-        super
+        print "|" unless parent.is_last_sibling?
+        print(' ' * (level - 1) * 4)
+        print(is_last_sibling? ? "+" : "|")
+        print "---"
+        print(has_children? ? "+" : ">")
       end
-    end
-
-    # @!attribute [r] breadth
-    # 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.
-    #
-    # @return [Integer] breadth of the node's level.
-    def breadth
-      is_root? ? 1 : parent.children.size
-    end
-
-    # @!attribute [r] in_degree
-    # The incoming edge-count of the receiver node.
-    #
-    # In-degree is defined as:
-    # In-degree:: Number of edges arriving at the node (0 for root, 1 for all other nodes)
-    #
-    # - In-degree = 0 for a root or orphaned node
-    # - In-degree = 1 for a node which has a parent
-    #
-    # @return [Integer] The in-degree of this node.
-    def in_degree
-      is_root? ? 0 : 1
-    end
 
-    # @!attribute [r] out_degree
-    # The outgoing edge-count of the receiver node.
-    #
-    # Out-degree is defined as:
-    # Out-degree:: Number of edges leaving the node (zero for leafs)
-    #
-    # @return [Integer] The out-degree of this node.
-    def out_degree
-      is_leaf? ? 0 : children.size
-    end
-
-    protected :parent=, :set_as_root!, :create_dump_rep
-
-    private
-
-    # Convert a CamelCasedWord to a underscore separated camel_cased_word.
-    #
-    # Just copied from ActiveSupport::Inflector because it is only needed
-    # aliasing deprecated methods
-    def underscore(camel_cased_word)
-      word = camel_cased_word.to_s.dup
-      word.gsub!(/::/, '/')
-      word.gsub!(/([A-Z]+)([A-Z][a-z])/,'\1_\2')
-      word.gsub!(/([a-z\d])([A-Z])/,'\1_\2')
-      word.tr!("-", "_")
-      word.downcase!
-      word
-    end
+      puts " #{name}"
 
-    # Return a range of valid insertion positions.  Used in the #add method.
-    def insertion_range
-      max = @children.size
-      min = -(max+1)
-      min..max
+      children { |child| child.print_tree(level + 1) if child } # Child might be 'nil'
     end
 
   end