rubytree 0.9.7 → 2.0.0

data/lib/tree/utils/hash_converter.rb

@@ -5,9 +5,9 @@
 #
 # Author::  Jen Hamon (http://www.github.com/jhamon)
 #
-# Time-stamp: <2015-05-30 14:19:16 anupam>
+# Time-stamp: <2022-06-20 22:16:39 anupam>
 #
-# Copyright (C) 2014, 2015 Jen Hamon (http://www.github.com/jhamon) and
+# Copyright (C) 2014, 2015, 2022, 2022 Jen Hamon (http://www.github.com/jhamon) and
 #                    Anupam Sengupta <anupamsg@gmail.com>
 #
 # All rights reserved.
@@ -36,140 +36,146 @@
 # 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.
+#
+# frozen_string_literal: true
 
-module Tree::Utils::HashConverter
-
-  def self.included(base)
-    base.extend(ClassMethods)
-  end
+module Tree
+  module Utils
+    # Provides a utility for marshalling/unmarshalling TreeNode objects to Ruby
+    # +hash+ objects.
+    #
+    # @author Jen Hamon (https://www.github.com/jhamon)
+    module HashConverter
+      def self.included(base)
+        base.extend(ClassMethods)
+      end
 
-  # Methods in {Tree::Utils::HashConverter::ClassMethods} will be added as
-  # class methods on any class mixing in the {Tree::Utils::HashConverter}
-  # module.
-  module ClassMethods
+      # Methods in {Tree::Utils::HashConverter::ClassMethods} will be added as
+      # class methods on any class mixing in the {Tree::Utils::HashConverter}
+      # module.
+      module ClassMethods
+        # Factory method builds a {Tree::TreeNode} from a +Hash+.
+        #
+        # This method will interpret each key of your +Hash+ as a {Tree::TreeNode}.
+        # Nested hashes are expected and child nodes will be added accordingly. If
+        # a hash key is a single value that value will be used as the name for the
+        # node.  If a hash key is an Array, both node name and content will be
+        # populated.
+        #
+        # A leaf element of the tree should be represented as a hash key with
+        # corresponding value +nil+ or +{}+.
+        #
+        # @example
+        #   TreeNode.from_hash({:A => {:B => {}, :C => {:D => {}, :E => {}}}})
+        #   # would be parsed into the following tree structure:
+        #   #    A
+        #   #   / \
+        #   #  B   C
+        #   #     / \
+        #   #    D   E
+        #
+        #   # The same tree would result from this nil-terminated Hash
+        #   {:A => {:B => nil, :C => {:D => nil, :E => nil}}}
+        #
+        #   # A tree with equivalent structure but with content present for
+        #   # nodes A and D could be built from a hash like this:
+        #   {[:A, "A content"] => {:B => {},
+        #                          :C => { [:D, "D content"] => {},
+        #                                   :E => {}  }}}
+        #
+        # @author Jen Hamon (http://www.github.com/jhamon)
+        # @param [Hash] hash Hash to build tree from.
+        #
+        # @return [Tree::TreeNode] The {Tree::TreeNode} instance representing the
+        #                          root of your tree.
+        #
+        # @raise [ArgumentError] This exception is raised if a non-Hash is passed.
+        #
+        # @raise [ArgumentError] This exception is raised if the hash has multiple
+        #                        top-level elements.
+        #
+        # @raise [ArgumentError] This exception is raised if the hash contains
+        #                        values that are not hashes or nils.
 
-    # Factory method builds a {Tree::TreeNode} from a +Hash+.
-    #
-    # This method will interpret each key of your +Hash+ as a {Tree::TreeNode}.
-    # Nested hashes are expected and child nodes will be added accordingly. If
-    # a hash key is a single value that value will be used as the name for the
-    # node.  If a hash key is an Array, both node name and content will be
-    # populated.
-    #
-    # A leaf element of the tree should be represented as a hash key with
-    # corresponding value +nil+ or +{}+.
-    #
-    # @example
-    #   TreeNode.from_hash({:A => {:B => {}, :C => {:D => {}, :E => {}}}})
-    #   # would be parsed into the following tree structure:
-    #   #    A
-    #   #   / \
-    #   #  B   C
-    #   #     / \
-    #   #    D   E
-    #
-    #   # The same tree would result from this nil-terminated Hash
-    #   {:A => {:B => nil, :C => {:D => nil, :E => nil}}}
-    #
-    #   # A tree with equivalent structure but with content present for
-    #   # nodes A and D could be built from a hash like this:
-    #   {[:A, "A content"] => {:B => {},
-    #                          :C => { [:D, "D content"] => {},
-    #                                   :E => {}  }}}
-    #
-    # @author Jen Hamon (http://www.github.com/jhamon)
-    # @param [Hash] hash Hash to build tree from.
-    #
-    # @return [Tree::TreeNode] The {Tree::TreeNode} instance representing the
-    #                          root of your tree.
-    #
-    # @raise [ArgumentError] This exception is raised if a non-Hash is passed.
-    #
-    # @raise [ArgumentError] This exception is raised if the hash has multiple
-    #                        top-level elements.
-    #
-    # @raise [ArgumentError] This exception is raised if the hash contains
-    #                        values that are not hashes or nils.
+        def from_hash(hash)
+          raise ArgumentError, 'Argument must be a type of hash'\
+                               unless hash.is_a?(Hash)
 
-    def from_hash(hash)
-      raise ArgumentError, "Argument must be a type of hash"\
-                           unless hash.is_a?(Hash)
+          raise ArgumentError, 'Hash must have one top-level element'\
+                               if hash.size != 1
 
-      raise ArgumentError, "Hash must have one top-level element"\
-                           if hash.size != 1
+          root, children = hash.first
 
-      root, children = hash.first
+          raise ArgumentError, 'Invalid child. Must be nil or hash.' unless [Hash, NilClass].include?(children.class)
 
-      unless [Hash, NilClass].include?(children.class)
-        raise ArgumentError, "Invalid child. Must be nil or hash."
+          node = new(*root)
+          node.add_from_hash(children) unless children.nil?
+          node
+        end
       end
 
-      node = self.new(*root)
-      node.add_from_hash(children) unless children.nil?
-      node
-    end
-  end
+      # Instantiate and insert child nodes from data in a Ruby +Hash+
+      #
+      # This method is used in conjunction with from_hash to provide a
+      # convenient way of building and inserting child nodes present in a Ruby
+      # hashes.
+      #
+      # This method will instantiate a node instance for each top-
+      # level key of the input hash, to be inserted as children of the receiver
+      # instance.
+      #
+      # Nested hashes are expected and further child nodes will be created and
+      # added accordingly. If a hash key is a single value that value will be
+      # used as the name for the node.  If a hash key is an Array, both node
+      # name and content will be populated.
+      #
+      # A leaf element of the tree should be represented as a hash key with
+      # corresponding value +nil+ or {}.
+      #
+      # @example
+      #   root = Tree::TreeNode.new(:A, "Root content!")
+      #   root.add_from_hash({:B => {:D => {}}, [:C, "C content!"] => {}})
+      #
+      # @author Jen Hamon (http://www.github.com/jhamon)
+      # @param [Hash] children The hash of child subtrees.
+      # @raise [ArgumentError] This exception is raised if a non-hash is passed.
+      # @return [Array] Array of child nodes added
+      # @see ClassMethods#from_hash
+      def add_from_hash(children)
+        raise ArgumentError, 'Argument must be a type of hash'\
+                             unless children.is_a?(Hash)
 
-    # Instantiate and insert child nodes from data in a Ruby +Hash+
-    #
-    # This method is used in conjunction with from_hash to provide a
-    # convenient way of building and inserting child nodes present in a Ruby
-    # hashes.
-    #
-    # This method will instantiate a node instance for each top-
-    # level key of the input hash, to be inserted as children of the receiver
-    # instance.
-    #
-    # Nested hashes are expected and further child nodes will be created and
-    # added accordingly. If a hash key is a single value that value will be
-    # used as the name for the node.  If a hash key is an Array, both node
-    # name and content will be populated.
-    #
-    # A leaf element of the tree should be represented as a hash key with
-    # corresponding value +nil+ or {}.
-    #
-    # @example
-    #   root = Tree::TreeNode.new(:A, "Root content!")
-    #   root.add_from_hash({:B => {:D => {}}, [:C, "C content!"] => {}})
-    #
-    # @author Jen Hamon (http://www.github.com/jhamon)
-    # @param [Hash] children The hash of child subtrees.
-    # @raise [ArgumentError] This exception is raised if a non-hash is passed.
-    # @return [Array] Array of child nodes added
-    # @see ClassMethods#from_hash
-    def add_from_hash(children)
-      raise ArgumentError, "Argument must be a type of hash"\
-                           unless children.is_a?(Hash)
+        child_nodes = []
+        children.each do |child, grandchildren|
+          child_node = self.class.from_hash({ child => grandchildren })
+          child_nodes << child_node
+          self << child_node
+        end
 
-      child_nodes = []
-      children.each do |child, grandchildren|
-        child_node = self.class.from_hash({child => grandchildren})
-        child_nodes << child_node
-        self << child_node
+        child_nodes
       end
 
-      child_nodes
-    end
+      # Convert a node and its subtree into a Ruby hash.
+      #
+      # @example
+      #    root = Tree::TreeNode.new(:root, "root content")
+      #    root << Tree::TreeNode.new(:child1, "child1 content")
+      #    root << Tree::TreeNode.new(:child2, "child2 content")
+      #    root.to_h # => {[:root, "root content"] =>
+      #                         { [:child1, "child1 content"] =>
+      #                                    {}, [:child2, "child2 content"] => {}}}
+      # @author Jen Hamon (http://www.github.com/jhamon)
+      # @return [Hash] Hash representation of tree.
+      def to_h
+        key = content? ? [name, content] : name
 
-    # Convert a node and its subtree into a Ruby hash.
-    #
-    # @example
-    #    root = Tree::TreeNode.new(:root, "root content")
-    #    root << Tree::TreeNode.new(:child1, "child1 content")
-    #    root << Tree::TreeNode.new(:child2, "child2 content")
-    #    root.to_h # => {[:root, "root content"] =>
-    #                         { [:child1, "child1 content"] =>
-    #                                    {}, [:child2, "child2 content"] => {}}}
-    # @author Jen Hamon (http://www.github.com/jhamon)
-    # @return [Hash] Hash representation of tree.
-    def to_h
-      key = has_content? ? [name, content] : name
+        children_hash = {}
+        children do |child|
+          children_hash.merge! child.to_h
+        end
 
-      children_hash = {}
-      children do |child|
-        children_hash.merge! child.to_h
+        { key => children_hash }
       end
-
-      { key => children_hash }
     end
+  end
 end

data/lib/tree/utils/json_converter.rb

@@ -4,9 +4,9 @@
 #
 # Author::  Anupam Sengupta (anupamsg@gmail.com)
 #
-# Time-stamp: <2015-05-30 14:20:20 anupam>
+# Time-stamp: <2022-06-20 22:16:46 anupam>
 #
-# Copyright (C) 2012, 2013, 2014, 2015 Anupam Sengupta <anupamsg@gmail.com>
+# Copyright (C) 2012, 2013, 2014, 2015, 2022 Anupam Sengupta <anupamsg@gmail.com>
 #
 # All rights reserved.
 #
@@ -34,94 +34,96 @@
 # 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.
+#
+# frozen_string_literal: true
 
 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 = {})
+module Tree
+  module Utils
+    # Provides utility methods to convert a {Tree::TreeNode} to and from
+    # JSON[http://flori.github.com/json/].
+    module JSONConverter
+      def self.included(base)
+        base.extend(ClassMethods)
+      end
 
-    json_hash = {
-      "name"         => name,
-      "content"      => content,
-      JSON.create_id => self.class.name
-    }
+      # @!group Converting to/from JSON
 
-    if has_children?
-      json_hash["children"] = children
-    end
-
-    return json_hash
+      # 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+.
+      #
+      # @param [Object] _options
+      #
+      # @see #to_json
+      # @see http://stackoverflow.com/a/6880638/273808
+      # noinspection RubyUnusedLocalVariable
+      def as_json(_options = {})
+        json_hash = {
+          name: name,
+          content: content,
+          JSON.create_id => self.class.name
+        }
 
-  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
+        json_hash['children'] = children if children?
 
-  # 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)
+        json_hash
+      end
 
-      node = new(json_hash["name"], json_hash["content"])
+      # 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(*args)
+        as_json.to_json(*args)
+      end
 
-      json_hash["children"].each do |child|
-        node << child
-      end if json_hash["children"]
+      # 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'])
 
-      return node
+          json_hash['children']&.each do |child|
+            node << child
+          end
 
+          node
+        end
+      end
     end
   end
 end

data/lib/tree/utils/metrics_methods.rb

@@ -4,9 +4,9 @@
 #
 # Author::  Anupam Sengupta (anupamsg@gmail.com)
 #
-# Time-stamp: <2015-05-30 14:23:23 anupam>
+# Time-stamp: <2022-06-20 22:17:00 anupam>
 #
-# Copyright (C) 2013, 2015 Anupam Sengupta <anupamsg@gmail.com>
+# Copyright (C) 2013, 2015, 2017, 2021, 2022 Anupam Sengupta <anupamsg@gmail.com>
 #
 # All rights reserved.
 #
@@ -35,14 +35,12 @@
 # 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.
 #
+# frozen_string_literal: true
 
-require 'structured_warnings'
-
-module Tree::Utils
-  # Provides utility functions to measure various tree metrics.
-  module TreeMetricsHandler
-    def self.included(base)
-
+module Tree
+  module Utils
+    # Provides utility functions to measure various tree metrics.
+    module TreeMetricsHandler
       # @!group Metrics and Measures
 
       # @!attribute [r] size
@@ -54,7 +52,7 @@ module Tree::Utils
       #
       # @return [Integer] Total number of nodes in this (sub)tree.
       def size
-        inject(0) {|sum, node| sum + 1 if node}
+        inject(0) { |sum, node| sum + 1 if node }
       end
 
       # @!attribute [r] length
@@ -66,7 +64,7 @@ module Tree::Utils
       # @return [Integer] The total number of nodes in this (sub)tree.
       # @see #size
       def length
-        size()
+        size
       end
 
       # @!attribute [r] node_height
@@ -79,8 +77,9 @@ module Tree::Utils
       #
       # @return [Integer] Height of the node.
       def node_height
-        return 0 if is_leaf?
-        1 + @children.collect { |child| child.node_height }.max
+        return 0 if leaf?
+
+        1 + @children.collect(&:node_height).max
       end
 
       # @!attribute [r] node_depth
@@ -89,15 +88,12 @@ module Tree::Utils
       # 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?
+        return 0 if root?
+
         1 + parent.node_depth
       end
 
@@ -109,32 +105,6 @@ module Tree::Utils
         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.
@@ -145,7 +115,7 @@ module Tree::Utils
       #
       # @return [Integer] breadth of the node's level.
       def breadth
-        is_root? ? 1 : parent.children.size
+        root? ? 1 : parent.children.size
       end
 
       # @!attribute [r] in_degree
@@ -160,7 +130,7 @@ module Tree::Utils
       #
       # @return [Integer] The in-degree of this node.
       def in_degree
-        is_root? ? 0 : 1
+        root? ? 0 : 1
       end
 
       # @!attribute [r] out_degree
@@ -171,10 +141,10 @@ module Tree::Utils
       #
       # @return [Integer] The out-degree of this node.
       def out_degree
-        is_leaf? ? 0 : children.size
+        leaf? ? 0 : children.size
       end
 
       # @!endgroup
-    end # self.included
+    end
   end
 end

data/lib/tree/utils/path_methods.rb

@@ -4,9 +4,9 @@
 #
 # Author::  Marco Ziccardi and Anupam Sengupta (anupamsg@gmail.com)
 #
-# Time-stamp: <2015-05-30 16:04:00 anupam>
+# Time-stamp: <2022-06-20 02:00:11 anupam>
 #
-# Copyright (C) 2015 Anupam Sengupta <anupamsg@gmail.com>
+# Copyright (C) 2015, 2021, 2022 Anupam Sengupta <anupamsg@gmail.com>
 #
 # All rights reserved.
 #
@@ -35,12 +35,12 @@
 # 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.
 #
+# frozen_string_literal: true
 
-module Tree::Utils
-  # Provides utility methods for path extraction
-  module TreePathHandler
-    def self.included(base)
-
+module Tree
+  module Utils
+    # Provides utility methods for path extraction
+    module TreePathHandler
       # @!group Node Path
 
       # Returns the path of this node from the root as a string, with the node
@@ -53,7 +53,7 @@ module Tree::Utils
       # @return [String] The node path with names separated using the specified
       #                  separator.
       def path_as_string(separator = '=>')
-        path_as_array().join(separator)
+        path_as_array.join(separator)
       end
 
       # Returns the node-names from this node to the root as an array. The first
@@ -61,8 +61,8 @@ module Tree::Utils
       #
       # @return [Array] The array containing the node names for the path to this
       # node
-      def path_as_array()
-        get_path_name_array().reverse
+      def path_as_array
+        get_path_name_array.reverse
       end
 
       # @!visibility private
@@ -75,18 +75,16 @@ module Tree::Utils
       def get_path_name_array(current_array_path = [])
         path_array = current_array_path + [name]
 
-        if !parent              # If detached node or root node.
-          return path_array
-        else                    # Else recurse to parent node.
-          path_array = parent.get_path_name_array(path_array)
-          return path_array
+        if parent               # Recurse to parent node.
+          parent.get_path_name_array(path_array)
+        else                    # else If detached node or root node.
+          path_array
         end
       end
 
       protected :get_path_name_array
 
       # @!endgroup
-    end # self.included
+    end
   end
-
 end