rubytree 0.8.2 → 0.8.3

data/lib/rubytree.rb

@@ -0,0 +1,41 @@
+# rubytree.rb - This file is part of the RubyTree package.
+#
+
+# = rubytree.rb - Generic implementation of an N-ary tree data structure.
+#
+# This file provides an alternative mechanism to require 'tree.rb', in case
+# there is a conflict with another gem or Ruby package.
+#
+# Author:: Anupam Sengupta (anupamsg@gmail.com)
+#
+# Copyright (c) 2012 Anupam Sengupta
+#
+# All rights reserved.
+#
+# Redistribution and use in source and binary forms, with or without modification,
+# are permitted provided that the following conditions are met:
+#
+# - Redistributions of source code must retain the above copyright notice, this
+#   list of conditions and the following disclaimer.
+#
+# - Redistributions in binary form must reproduce the above copyright notice, this
+#   list of conditions and the following disclaimer in the documentation and/or
+#   other materials provided with the distribution.
+#
+# - Neither the name of the organization nor the names of its contributors may
+#   be used to endorse or promote products derived from this software without
+#   specific prior written permission.
+#
+#   THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+# DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
+# ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+# (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+# LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
+# ANY THEORY OF LIABILITY, 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.
+#
+
+require "tree.rb"

data/lib/tree.rb

@@ -1,7 +1,5 @@
 # tree.rb - This file is part of the RubyTree package.
 #
-# $Revision$ by $Author$ on $Date$
-#
 # = tree.rb - Generic implementation of an N-ary tree data structure.
 #
 # Provides a generic tree data structure with ability to
@@ -11,7 +9,7 @@
 # Author:: Anupam Sengupta (anupamsg@gmail.com)
 #
 
-# Copyright (c) 2006, 2007, 2008, 2009, 2010, 2011 Anupam Sengupta
+# Copyright (c) 2006, 2007, 2008, 2009, 2010, 2011, 2012 Anupam Sengupta
 #
 # All rights reserved.
 #
@@ -41,37 +39,44 @@
 # SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 #
 
+require 'tree/tree_deps'
+require 'tree/version'
+
 # This module provides a TreeNode class which is the primary class for representing
 # nodes in the tree.
 #
 # This module also acts as the namespace for all classes in the RubyTree package.
 module Tree
 
-  # Rubytree Package Version
-  VERSION = '0.8.2'
-
   # == 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., _content_ of the node). The node
-  # names are required to be *unique* within 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 (as the name is implicitly used as an _ID_ within
+  # the data structure).
   #
-  # The node's _content_ is *not* required to be unique across different nodes in the tree, and
-  # can be +nil+ as well.
+  # The node's _content_ is *not* required to be unique across
+  # different nodes in the tree, and can be +nil+ as well.
   #
-  # The class provides various methods to navigate the tree, traverse the structure,
-  # modify contents of the node, change position of the node in the tree,
-  # and to make structural changes to the tree.
+  # The class provides various methods to navigate the tree, traverse
+  # the structure, modify contents of the node, change position of the
+  # node in the tree, and to make structural changes to the tree.
   #
-  # 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.
+  # 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* node as well as other superior parents in the path to
-  # root of the tree.  In addition, a node can also access its *sibling* nodes, if present.
+  # The node also provides direct access to its *parent* node as well
+  # as 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.
+  # 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.
+  # However, having duplicate nodes within the structure is likely to
+  # cause unpredictable behavior.
   #
   #
   # == Example
@@ -126,28 +131,62 @@ module Tree
   class TreeNode
     include Enumerable
 
+    # @!attribute [r] name
+    #
     # Name of this node.  Expected to be unique within the tree.
+    #
+    # Note that the name attribute really functions as an *ID* within
+    # the tree structure, and hence the uniqueness constraint is
+    # required.
+    #
+    # This may be changed in the future, but for now it is best to
+    # retain unique names within the tree structure, and use the
+    # +content+ attribute for any non-unique node requirements.
+    #
+    # @see content
     attr_reader   :name
 
-    # Content of this node.  Can be +nil+.
+    # @!attribute [rw] content
+    #
+    # Content of this node.  Can be +nil+.  Note that there is no
+    # uniqueness constraint related to this attribute.
+    #
+    # @see name
     attr_accessor :content
 
+    # @!attribute [r] parent
+    #
     # Parent of this node.  Will be +nil+ for a root node.
     attr_reader   :parent
 
+    # @!group Node Creation
+
     # Creates a new node with a name and optional content.
     # The node name is expected to be unique within the tree.
     #
     # The content can be of any type, and defaults to +nil+.
     #
-    # @param [Object] name Name of the node.  Usual usage is to pass a String.
+    # @param [Object] name Name of the node.  Conventional usage is to pass a String
+    #   (Integer names may cause *surprises*)
     # @param [Object] content Content of the node.
     #
     # @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.
+    #
+    # @see #[]
     def initialize(name, content = nil)
       raise ArgumentError, "Node name HAS to be provided!" if name == nil
       @name, @content = name, content
 
+      if name.kind_of?(Integer)
+        warn StandardWarning,
+             "Using integer as node name. Semantics of TreeNode[] may not be what you expect! #{name} #{content}"
+      end
+
       self.set_as_root!
       @children_hash = Hash.new
       @children = []
@@ -178,6 +217,8 @@ module Tree
     # @see Tree::TreeNode#detached_subtree_copy
     alias :dup :detached_subtree_copy
 
+    # @!endgroup
+
     # Returns string representation of the receiver node.
     # This method is primarily meant for debugging purposes.
     #
@@ -190,7 +231,8 @@ module Tree
         " Total Nodes: #{size()}"
     end
 
-    # Returns an array of ancestors of the receiver node in reversed order
+    # @!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.
@@ -219,6 +261,8 @@ module Tree
       @parent = parent
     end
 
+    # @!group Structure Modification
+
     # Convenience synonym for {Tree::TreeNode#add} method.
     #
     # This method allows an easy mechanism to add node hierarchies to the tree
@@ -267,7 +311,8 @@ module Tree
     #
     # @see #<<
     def add(child, at_index = -1)
-      raise ArgumentError, "Attempting to add a nil node" unless child
+      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)
 
       if insertion_range.include?(at_index)
@@ -281,8 +326,6 @@ module Tree
       return child
     end
 
-
-
     # Removes the specified child node from the receiver node.
     #
     # This method can also be used for *pruning* a sub-tree, in cases where the removed child node is
@@ -346,6 +389,8 @@ module Tree
       @parent = nil
     end
 
+    # @!endgroup
+
     # Returns +true+ if the receiver is a root node.  Note that
     # orphaned children will also be reported as root nodes.
     #
@@ -373,10 +418,13 @@ module Tree
       !has_children?
     end
 
-    # Returns an array of all the immediate children of the receiver node.  The child nodes are ordered
-    # "left-to-right" in the returned array.
+    # @!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.
     #
-    # If a block is given, yields each child node to the block traversing from left to right.
+    # If a block is given, yields each child node to the block
+    # traversing from left to right.
     #
     # @yield [child] Each child is passed to the block, if given
     # @yieldparam [Tree::TreeNode] child Each child node.
@@ -390,24 +438,26 @@ module Tree
       end
     end
 
-    # Returns the first child of the receiver node.
-    #
-    # Will return +nil+ if no children are present.
+    # @!attribute [rw] first_child
+    # First child of the receiver node.
+    # Will be +nil+ if no children are present.
     #
     # @return [Tree::TreeNode] The first child, or +nil+ if none is present.
     def first_child
       children.first
     end
 
-    # Returns the last child of the receiver node.
-    #
-    # Will return +nil+ if no children are present.
+    # @!attribute [rw] last_child
+    # Last child of the receiver node.
+    # Will be +nil+ if no children are present.
     #
     # @return [Tree::TreeNode] The last child, or +nil+ if none is present.
     def last_child
       children.last
     end
 
+    # @!group Tree Traversal
+
     # Traverses each node (including the receiver node) of the (sub)tree rooted at this node
     # by yielding the nodes to the specified block.
     #
@@ -467,55 +517,77 @@ module Tree
     # @see #each
     # @see #breadth_each
     def each_leaf &block
-      self.each { |node| yield(node) if node.is_leaf? }
+      if block_given?
+        self.each { |node| yield(node) if node.is_leaf? }
+      else
+        self.select { |node| node.is_leaf?}
+      end
     end
 
     # Returns the requested node from the set of immediate children.
     #
-    # If the argument is _numeric_, then the in-sequence array of children is accessed using
-    # the argument as the *index* (zero-based).
+    # - 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 argument is *NOT* _numeric_, then it is taken to be the *name* of the child node to be returned.
+    # - If the +name+ argument is *NOT* an _Integer_, then it is taken to
+    #   be the *name* of the child node to be returned.
     #
-    # An ArgumentError exception is raised if neither name nor an index is provided.
+    # 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 [String|Number] name_or_index Name of the child, or its
+    #   positional index in the array of child nodes.
     #
-    # @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.
+    # @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.
     #
-    # @raise [ArgumentError] Raised if neither name nor index is provided.
+    # @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.
+    #
+    # @note The use of +Integer+ names is allowed by using the optional +num_as_name+ flag.
+    #
+    # @raise [ArgumentError] Raised if the +name_or_index+ argument is +nil+.
     #
     # @see #add
-    def [](name_or_index)
+    # @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)
+      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
 
-    # Returns the total number of nodes in this (sub)tree, including the receiver node.
+    # @!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 [Number] Total number of nodes in this (sub)tree.
+    # @return [Integer] Total number of nodes in this (sub)tree.
     def size
       @children.inject(1) {|sum, node| sum + node.size}
     end
 
     # Convenience synonym for {Tree::TreeNode#size}.
     #
-    # @todo The semantic of length is probably unclear.  Should return the node depth instead
-    #       to reflect the path length.
-    #
     # @deprecated This method name is ambiguous and may be removed.  Use TreeNode#size instead.
     #
-    # @return [Number] The total number of nodes in this (sub)tree.
+    # @return [Integer] The total number of nodes in this (sub)tree.
     # @see #size
     def length
       size()
@@ -523,7 +595,7 @@ module Tree
 
     # Pretty prints the (sub)tree rooted at the receiver node.
     #
-    # @param [Number] level The indentation level (4 spaces) to start with.
+    # @param [Integer] level The indentation level (4 spaces) to start with.
     def print_tree(level = 0)
       if is_root?
         print "*"
@@ -540,11 +612,9 @@ module Tree
       children { |child| child.print_tree(level + 1)}
     end
 
-    # 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.
+    # @!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
@@ -553,15 +623,13 @@ module Tree
       root
     end
 
-    # Returns the first sibling of the receiver node. If this is the root node, then returns
+    # @!attribute [rw] first_sibling
+    # First sibling of the receiver 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
     #
-    # @todo Fix the inconsistency of returning root as its first sibling, and returning
-    #       a +nil+ array for siblings of the node.
-    #
     # @return [Tree::TreeNode] The first sibling node.
     #
     # @see #is_first_sibling?
@@ -580,15 +648,13 @@ module Tree
       first_sibling == self
     end
 
-    # Returns the last sibling of the receiver node.  If this is the root node, then returns
+    # @!attribute [rw] last_sibling
+    # Last sibling of the receiver 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
     #
-    # @todo Fix the inconsistency of returning root as its last sibling, and returning
-    #       a +nil+ array for siblings of the node.
-    #
     # @return [Tree::TreeNode] The last sibling node.
     #
     # @see #is_last_sibling?
@@ -607,16 +673,12 @@ module Tree
       last_sibling == self
     end
 
-    # Returns an array of siblings for the receiver node.  The receiver node is excluded.
+    # @!attribute [rw] siblings
+    # 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 own first/last sibling, and returning
-    #       a +nil+ array for siblings of the same root node.
-    # @todo Also fix the inconsistency of returning +nil+ for a root node, and an empty array for nodes
-    #       which have no siblings.
-    #
     # @yield [sibling] Each sibling is passed to the block.
     # @yieldparam [Tree::TreeNode] sibling Each sibling node.
     #
@@ -625,7 +687,7 @@ module Tree
     # @see #first_sibling
     # @see #last_sibling
     def siblings
-      return nil if is_root?
+      return [] if is_root?
 
       if block_given?
         parent.children.each { |sibling| yield sibling if sibling != self }
@@ -647,7 +709,8 @@ module Tree
       is_root? ? true : parent.children.size == 1
     end
 
-    # Returns the next sibling for the receiver node.
+    # @!attribute [rw] next_sibling
+    # 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, or if the receiver is a root node.
@@ -663,7 +726,8 @@ module Tree
       parent.children.at(myidx + 1) if myidx
     end
 
-    # Returns the previous sibling of the receiver node.
+    # @!attribute [rw] previous_sibling
+    # Previous sibling of the receiver node.
     # 'Previous' node is defined to be the node to left of the receiver node.
     #
     # Will return +nil+ if no predecessor node is present, or if the receiver is a root node.
@@ -685,7 +749,7 @@ module Tree
     #
     # @param [Tree::TreeNode] other The other node to compare against.
     #
-    # @return [Number] +1 if this node is a 'successor', 0 if equal and -1 if this node is a 'predecessor'.
+    # @return [Integer] +1 if this node is a 'successor', 0 if equal and -1 if this node is a 'predecessor'.
     def <=>(other)
       return +1 if other == nil
       self.name <=> other.name
@@ -735,19 +799,18 @@ module Tree
       end
     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.
+    # Creates a JSON ready Hash for the #to_json method.
     #
-    # @author Dirk Breuer (http://github.com/railsbros-dirk)
-    # @since 0.7.0
+    # @author Eric Cline (https://github.com/escline)
+    # @since 0.8.3
     #
-    # @return The JSON representation of this subtree.
+    # @return A hash based representation of the JSON
     #
-    # @see Tree::TreeNode.json_create
-    # @see http://flori.github.com/json
-    def to_json(*a)
-      begin
-        require '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,
@@ -759,11 +822,24 @@ module Tree
           json_hash["children"] = children
         end
 
-        return json_hash.to_json
+        return json_hash
 
-      rescue LoadError
-        warn "The JSON gem couldn't be loaded. Due to this we cannot serialize the tree to a JSON representation"
-      end
+    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
@@ -783,35 +859,33 @@ module Tree
     # @see #to_json
     # @see http://flori.github.com/json
     def self.json_create(json_hash)
-      begin
-        require 'json'
 
-        node = new(json_hash["name"], json_hash["content"])
+      node = new(json_hash["name"], json_hash["content"])
 
-        json_hash["children"].each do |child|
-          node << child
-        end if json_hash["children"]
+      json_hash["children"].each do |child|
+        node << child
+      end if json_hash["children"]
+
+      return node
 
-        return node
-      rescue LoadError => e
-        warn "The JSON gem couldn't be loaded. Due to this we cannot serialize the tree to a JSON representation."
-      end
     end
 
-    # Returns height of the (sub)tree from the receiver node.  Height of a node is defined as:
+    # @!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 [Number] Height of the node.
+    # @return [Integer] Height of the node.
     def node_height
       return 0 if is_leaf?
       1 + @children.collect { |child| child.node_height }.max
     end
 
-    # Returns depth of the receiver node in its tree.  Depth of a node is defined as:
+    # @!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.
     #
@@ -820,7 +894,7 @@ module Tree
     #
     # 'level' is an alias for this method.
     #
-    # @return [Number] Depth of this node.
+    # @return [Integer] Depth of this node.
     def node_depth
       return 0 if is_root?
       1 + parent.node_depth
@@ -838,74 +912,62 @@ module Tree
     # For correct and conventional behavior, please use {Tree::TreeNode#node_depth} and
     # {Tree::TreeNode#node_height} methods instead.
     #
-    # @return [Number] depth of the node.
+    # @return [Integer] depth of the node.
     # @deprecated This method returns an incorrect value.  Use the 'node_depth' method instead.
     #
     # @see #node_depth
     def depth
-      begin
-        require 'structured_warnings'   # To enable a nice way of deprecating of the depth method.
-        warn DeprecatedMethodWarning, 'This method is deprecated.  Please use node_depth() or node_height() instead (bug # 22535)'
-      rescue LoadError
-        # Oh well. Will use the standard Kernel#warn.  Behavior will be identical.
-        warn 'Tree::TreeNode#depth() method is deprecated.  Please use node_depth() or node_height() instead (bug # 22535)'
-      end
+      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))
-        begin
-          require 'structured_warnings'   # To enable a nice way of deprecating of the invoked CamelCase method.
-          warn DeprecatedMethodWarning, "The camelCased methods are deprecated. Please use #{new_method_name} instead of #{meth}"
-
-        rescue LoadError
-          # Oh well. Will use the standard Kernel#warn.  Behavior will be identical.
-          warn "Tree::TreeNode##{meth}() method is deprecated. Please use #{new_method_name} instead."
-
-        ensure                  # Invoke the method now.
-          return send(new_method_name, *args, &blk)
-        end
-
+        warn DeprecatedMethodWarning, "The camelCased methods are deprecated. Please use #{new_method_name} instead of #{meth}"
+        return send(new_method_name, *args, &blk)
       else
         super
       end
     end
 
-    # Returns breadth of the tree at the receiver node's level.
+    # @!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 [Number] breadth of the node's level.
+    # @return [Integer] breadth of the node's level.
     def breadth
       is_root? ? 1 : parent.children.size
     end
 
-    # Returns the incoming edge-count of the receiver node.
+    # @!attribute [r] in_degree
+    # The incoming edge-count of the receiver node.
     #
     # In-degree is defined as:
-    # In-degree:: The number of edges arriving at the node (0 for root, 1 for all other nodes)
+    # 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 [Number] The in-degree of this node.
+    # @return [Integer] The in-degree of this node.
     def in_degree
       is_root? ? 0 : 1
     end
 
-    # Returns the outgoing edge-count of the receiver node.
+    # @!attribute [r] out_degree
+    # The outgoing edge-count of the receiver node.
     #
     # Out-degree is defined as:
-    # Out-degree:: The number of edges leaving the node (zero for leafs)
+    # Out-degree:: Number of edges leaving the node (zero for leafs)
     #
-    # @return [Number] The out-degree of this node.
+    # @return [Integer] The out-degree of this node.
     def out_degree
       is_leaf? ? 0 : children.size
     end