rubytree 0.8.3 → 0.9.0

data/lib/tree/binarytree.rb

@@ -8,7 +8,7 @@
 # Author:: Anupam Sengupta (anupamsg@gmail.com)
 #
 
-# Copyright (c) 2007, 2008, 2009, 2010, 2012 Anupam Sengupta
+# Copyright (c) 2007, 2008, 2009, 2010, 2012, 2013 Anupam Sengupta
 #
 # All rights reserved.
 #
@@ -51,21 +51,7 @@ module Tree
   #
   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 added will be the second node.
-    #
-    # If only one child is present, then this will be the left child.
-    #
-    # @param [Tree::BinaryTreeNode] child The child to add.
-    #
-    # @raise [ArgumentError] This exception is raised if two children are already present.
-    def add(child)
-      raise ArgumentError, "Already has two child nodes" if @children.size == 2
-
-      super(child)
-    end
+    # @!group Core Attributes
 
     # @!attribute [rw] left_child
     # Left child of the receiver node. Note that left Child == first Child.
@@ -89,6 +75,78 @@ module Tree
       children[1]
     end
 
+    # @!attribute is_left_child?
+    # +true+ if the receiver node is the left child of its parent.
+    # Always returns +false+ if it is a root node.
+    #
+    # @return [Boolean] +true+ if this is the left child of its parent.
+    def is_left_child?
+      return false if is_root?
+      self == parent.left_child
+    end
+
+    # @!attribute [r] is_right_child?
+    # +true+ if the receiver node is the right child of its parent.
+    # Always returns +false+ if it is a root node.
+    #
+    # @return [Boolean] +true+ if this is the right child of its parent.
+    def is_right_child?
+      return false if is_root?
+      self == parent.right_child
+    end
+
+    # @!group Structure Modification
+
+    # 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.
+    #
+    # @param [Tree::BinaryTreeNode] child The child to add.
+    #
+    # @raise [ArgumentError] This exception is raised if two children are already present.
+    def add(child)
+      raise ArgumentError, "Already has two child nodes" if @children.size == 2
+
+      super(child)
+    end
+
+    # Performs inorder traversal (including this node).
+    #
+    # @yieldparam node [Tree::BinaryTreeNode]  Each node (in-order).
+    #
+    # @return [Tree::BinaryTreeNode] This node, if a block is given
+    # @return [Enumerator] An enumerator on this tree, if a block is *not* given
+    #
+    # @since 0.9.0
+    #
+    # @see #each
+    # @see #preordered_each
+    # @see #postordered_each
+    def inordered_each(&block)
+
+      return self.to_enum unless block_given?
+
+      node_stack = []
+      current_node = self
+
+      until node_stack.empty? and current_node == nil
+        if current_node
+          node_stack.push(current_node)
+          current_node = current_node.left_child
+        else
+          current_node = node_stack.pop()
+          yield current_node
+          current_node = current_node.right_child
+        end
+      end
+
+      return self if block_given?
+
+    end
+
     # A protected method to allow insertion of child nodes at the specified location.
     # Note that this method allows insertion of +nil+ nodes.
     #
@@ -107,6 +165,8 @@ module Tree
       child
     end
 
+    protected :set_child_at
+
     # Sets the left child of the receiver node. If a previous child existed, it is replaced.
     #
     # @param [Tree::BinaryTreeNode] child The child to add as the left-side node.
@@ -131,31 +191,11 @@ module Tree
       set_child_at child, 1
     end
 
-    # Returns +true+ if the receiver node is the left child of its parent.
-    # Always returns +false+ if it is a root node.
-    #
-    # @return [Boolean] +true+ if this is the left child of its parent.
-    def is_left_child?
-      return false if is_root?
-      self == parent.left_child
-    end
-
-    # Returns +true+ if the receiver node is the right child of its parent.
-    # Always returns +false+ if it is a root node.
-    #
-    # @return [Boolean] +true+ if this is the right child of its parent.
-    def is_right_child?
-      return false if is_root?
-      self == parent.right_child
-    end
-
     # Swaps the left and right child nodes of the receiver node with each other.
     def swap_children
       self.left_child, self.right_child = self.right_child, self.left_child
     end
 
-    protected :set_child_at
-
   end
 
 end

data/lib/tree/utils/camel_case_method_handler.rb

@@ -0,0 +1,78 @@
+# camel_case_methods.rb - This file is part of the RubyTree package.
+#
+# = camel_case_methods.rb - Provides conversion from CamelCase to snake_case.
+#
+# Author::  Anupam Sengupta (anupamsg@gmail.com)
+#
+# Time-stamp: <2013-12-31 20:48:13 anupam>
+#
+# Copyright (C) 2012, 2013 Anupam Sengupta <anupamsg@gmail.com>
+#
+# 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 'structured_warnings'
+
+module Tree::Utils
+  # Provides utility functions to handle CamelCase methods, and redirect
+  # invocation of such methods to the snake_case equivalents.
+  module CamelCaseMethodHandler
+    def self.included(base)
+      # @!visibility private
+      # Allow the deprecated CamelCase method names.  Display a warning.
+      # :nodoc:
+      def method_missing(meth, *args, &blk)
+        if self.respond_to?(new_method_name = to_snake_case(meth))
+          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
+
+      private
+
+      # @!visibility private
+      # Convert a CamelCasedWord to a underscore separated camel_cased_word.
+      #
+      # @param [String] camel_cased_word The word to be converted to snake_case.
+      # @return [String] the snake_cased_word.
+      def to_snake_case(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
+
+    end # self.included
+  end
+end

data/lib/tree/utils/json_converter.rb

@@ -0,0 +1,125 @@
+# json.rb - This file is part of the RubyTree package.
+#
+# = json.rb - Provides conversion to and from JSON.
+#
+# Author::  Anupam Sengupta (anupamsg@gmail.com)
+#
+# Time-stamp: <2013-12-31 21:57:42 anupam>
+#
+# Copyright (C) 2012, 2013 Anupam Sengupta <anupamsg@gmail.com>
+#
+# 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 'json'
+
+# Provides utility methods to convert a {Tree::TreeNode} to and from
+# JSON[http://flori.github.com/json/].
+module Tree::Utils::JSONConverter
+
+  def self.included(base)
+    base.extend(ClassMethods)
+  end
+
+  # @!group Converting to/from JSON
+
+  # 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 #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.
+  #
+  # @author Dirk Breuer (http://github.com/railsbros-dirk)
+  # @since 0.7.0
+  #
+  # @return The JSON representation of this subtree.
+  #
+  # @see ClassMethods#json_create
+  # @see #as_json
+  # @see http://flori.github.com/json
+  def to_json(*a)
+    as_json.to_json(*a)
+  end
+
+  # ClassMethods for the {JSONConverter} module.  Will become class methods in the +include+ target.
+  module ClassMethods
+    # 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}[http://flori.github.com/json/] 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 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
+  end
+end

data/lib/tree/utils/metrics_methods.rb

@@ -0,0 +1,172 @@
+# metrics_methods.rb - This file is part of the RubyTree package.
+#
+# = metrics_methods.rb - Provides methods for various tree measurements
+#
+# Author::  Anupam Sengupta (anupamsg@gmail.com)
+#
+# Time-stamp: <2013-12-31 21:45:35 anupam>
+#
+# Copyright (C) 2013 Anupam Sengupta <anupamsg@gmail.com>
+#
+# 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 'structured_warnings'
+
+module Tree::Utils
+  # Provides utility functions to measure various tree metrics.
+  module TreeMetricsHandler
+    def self.included(base)
+
+      # @!group Metrics and Measures
+
+      # @!attribute [r] size
+      # Total number of nodes in this (sub)tree, including this node.
+      #
+      # Size of the tree is defined as:
+      #
+      # Size:: Total number nodes in the subtree including this node.
+      #
+      # @return [Integer] Total number of nodes in this (sub)tree.
+      def size
+        inject(0) {|sum, node| sum + 1 if node}
+      end
+
+      # @!attribute [r] length
+      # Convenience synonym for {#size}.
+      #
+      # @deprecated This method name is ambiguous and may be removed.  Use {#size} instead.
+      #
+      # @return [Integer] The total number of nodes in this (sub)tree.
+      # @see #size
+      def length
+        size()
+      end
+
+      # @!attribute [r] node_height
+      # Height of the (sub)tree from this 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 this 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 {#depth} was incorrectly computing this value.
+      # Please replace all calls to the old method with {#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
+
+      # @!attribute [r] level
+      # Alias for {#node_depth}
+      #
+      # @see #node_depth
+      def level
+        node_depth
+      end
+
+      # @!attribute [r] depth
+      # Depth of the tree from this 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 {#node_depth} and
+      # {#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
+
+      # @!attribute [r] breadth
+      # Breadth of the tree at this 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 this 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 this 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
+
+      # @!endgroup
+    end # self.included
+  end
+end