rubytree 1.0.2 → 2.0.0

data/TODO.org

@@ -183,10 +183,7 @@
     This proposed change does make sense at one level (since the root node does not have any parent), but returning root
     as root's root (no pun intended) makes accessing the root from anywhere in the tree much easier.
 
-
-
-
-* R0.9.5
+* R0.9.5                                                                                   :ARCHIVE:
 ** DONE Add the `#get_path_as_string` method from feature request #48                     :ARCHIVE:
    CLOSED: [2015-05-30 Sat 15:55]
 ** DONE Fix [[Issue:32][Issue #32]] and enable move semantics on the TreeNode#add method.               :ARCHIVE:
@@ -202,11 +199,20 @@
    CLOSED: [2014-11-01 Sat 20:11]
 
 
+* R2.0.0
+
+  This is primarily a *modernization* of the library, with removal of deprecated methods, the much-hated dependency on
+  ~structured_warnings~, and cleanup of other cruft.
+
+  In addition, the CI pipeline has been moved from <https://travis.ci> to ~Github Actions~.
 
+- [X] Merge the modernization PR from @jmortlock (multiple changes).
+- [X] Update the documentation to reflect the modernization changes.
 
-* Next Release
-  DEADLINE: <2014-12-01 Mon>
-** STARTED [#A] Resolve the infinite loop bug if a node is added to itself as a child     :Partial:
+
+* Unplanned / Not assigned to any release
+*** STARTED Convert all documentation to markdown mode.
+*** STARTED [#A] Resolve the infinite loop bug if a node is added to itself as a child     :Partial:
    [[Issue:5][Issue #5.]]
 
    This is a subtle problem to resolve.  The specific case of a node
@@ -237,15 +243,8 @@
       duplicates).  This needs to be a hash (to allow O(1) access),
       and will sacrifice memory.  There might be a need to
       restructure the internals to make better use of memory.
-** STARTED Convert all documentation to markdown mode.
-** TODO Expand the examples section, and add supporting documentation
+*** TODO Expand the examples section, and add supporting documentation
 
-* Unplanned / Not assigned to any release
-*** DONE [#A] Migrate the website and references from http://rubyforge.org/               :ARCHIVE:
-    CLOSED: [2014-07-04 Fri 22:18]
-*** DONE Revert the forced install of rubygem 2.1.11 from [[file:.travis.yml][.travis.yml]]                     :ARCHIVE:
-    CLOSED: [2014-01-12 Sun 19:06]
-    The issue seems to have been resolved with the 2.2.1 release of Rubygems.
 *** TODO Create a cycle-detection/validation mechanism to prevent cyclic graphs of nodes.
 *** TODO Create a generic validation method to check for various issues in the created tree.
 *** TODO Add a FAQ document to the project.
@@ -258,6 +257,11 @@
 *** TODO Add a YAML export method to the TreeNode class.
 
 *** TODO marshal_load method probably should be a class method.  It currently clobbers self.
+*** DONE Revert the forced install of rubygem 2.1.11 from [[file:.travis.yml][.travis.yml]]                     :ARCHIVE:
+    CLOSED: [2014-01-12 Sun 19:06]
+    The issue seems to have been resolved with the 2.2.1 release of Rubygems.
+*** DONE [#A] Migrate the website and references from http://rubyforge.org/               :ARCHIVE:
+    CLOSED: [2014-07-04 Fri 22:18]
 *** DONE Fix bug # [[http://rubyforge.org/tracker/index.php%3Ffunc%3Ddetail&aid%3D22535&group_id%3D1215&atid%3D4793][22535]]: The method Tree::TreeNode#depth is a misnomer.  The current definition actually provides the height function. :ARCHIVE:
     DEADLINE: <2010-01-09 Sat> CLOSED: [2010-01-03 Sun 22:15]
 

data/examples/example_basic.rb

@@ -3,8 +3,8 @@
 # example_basic.rb:: Basic usage of the tree library.
 #
 # Author:  Anupam Sengupta
-# Time-stamp: <2015-12-31 22:17:30 anupam>
-# Copyright (C) 2013, 2015 Anupam Sengupta <anupamsg@gmail.com>
+# Time-stamp: <2022-06-19 22:52:29 anupam>
+# Copyright (C) 2013, 2015, 2022 Anupam Sengupta <anupamsg@gmail.com>
 #
 # The following example implements this tree structure:
 #
@@ -21,22 +21,29 @@
 #    +-------+-------+
 #    | GRANDCHILD 1  |
 #    +---------------+
+#
+# frozen_string_literal: true
 
 # ..... Example starts.
 require 'tree' # Load the library
 
-# ..... Create the root node first.  Note that every node has a name and an optional content payload.
+# ..... 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')
+# ..... 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.
+# ..... 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.
+# ..... 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']
 

data/lib/rubytree.rb

@@ -8,9 +8,7 @@
 #
 # Author:: Anupam Sengupta (anupamsg@gmail.com)
 #
-# Copyright (c) 2012, 2015 Anupam Sengupta
-#
-# All rights reserved.
+# Copyright (c) 2012-2022 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:
@@ -37,5 +35,6 @@
 # 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 'tree'

data/lib/tree/binarytree.rb

@@ -8,9 +8,7 @@
 # Author:: Anupam Sengupta (anupamsg@gmail.com)
 #
 
-# Copyright (c) 2007, 2008, 2009, 2010, 2012, 2013, 2014, 2015 Anupam Sengupta
-#
-# All rights reserved.
+# Copyright (c) 2007-2022 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:
@@ -37,6 +35,7 @@
 # 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_relative '../tree'
 
@@ -76,28 +75,32 @@ module Tree
       children[1]
     end
 
-    # @!attribute is_left_child?
+    # @!attribute 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?
+    def left_child?
+      return false if root?
 
       self == parent.left_child
     end
 
-    # @!attribute [r] is_right_child?
+    alias is_left_child? left_child? # @todo: Aliased for eventual replacement
+
+    # @!attribute [r] 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?
+    def right_child?
+      return false if root?
 
       self == parent.right_child
     end
 
+    alias is_right_child? right_child? # @todo: Aliased for eventual replacement
+
     # @!group Structure Modification
 
     # Adds the specified child node to the receiver node. The child node's
@@ -164,8 +167,6 @@ module Tree
     #
     # @since 0.9.0
     #
-    # @param [Object] block
-    #
     # @see #each
     # @see #preordered_each
     # @see #postordered_each
@@ -176,7 +177,7 @@ module Tree
       node_stack = []
       current_node = self
 
-      until node_stack.empty? and current_node.nil?
+      until node_stack.empty? && current_node.nil?
         if current_node
           node_stack.push(current_node)
           current_node = current_node.left_child

data/lib/tree/tree_deps.rb

@@ -7,9 +7,7 @@
 # Author:: Anupam Sengupta (anupamsg@gmail.com)
 #
 
-# Copyright (c) 2006-2015 Anupam Sengupta
-#
-# All rights reserved.
+# Copyright (c) 2006-2022 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:
@@ -36,14 +34,13 @@
 # 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'
 require 'json'
 
 require_relative '../tree/version'
 require_relative '../tree/utils/metrics_methods'
 require_relative '../tree/utils/path_methods'
-require_relative '../tree/utils/camel_case_method_handler'
 require_relative '../tree/utils/json_converter'
 require_relative '../tree/utils/tree_merge_handler'
 require_relative '../tree/utils/hash_converter'

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,138 +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
 
-require_relative '../../../lib/tree/utils/utils'
+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
 
-module Tree::Utils::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
+        # 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.
 
-  # 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.
+        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)
 
-      raise ArgumentError, 'Invalid child. Must be nil or hash.' unless [Hash, NilClass].include?(children.class)
+          node = new(*root)
+          node.add_from_hash(children) unless children.nil?
+          node
+        end
+      end
 
-      node = 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
-    end
+        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
     end
-
-    { key => children_hash }
   end
 end