rubytree 1.0.2 → 2.0.0

data/lib/tree.rb

@@ -9,9 +9,7 @@
 # Author:: Anupam Sengupta (anupamsg@gmail.com)
 #
 
-# Copyright (c) 2006-2021 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:
@@ -38,6 +36,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 'tree/tree_deps'
 
@@ -88,7 +87,6 @@ module Tree
     include Comparable
     include Tree::Utils::TreeMetricsHandler
     include Tree::Utils::TreePathHandler
-    include Tree::Utils::CamelCaseMethodHandler
     include Tree::Utils::JSONConverter
     include Tree::Utils::TreeMergeHandler
     include Tree::Utils::HashConverter
@@ -132,38 +130,44 @@ module Tree
     # @return [Tree::TreeNode] Root of the (sub)tree.
     def root
       root = self
-      root = root.parent until root.is_root?
+      root = root.parent until root.root?
       root
     end
 
-    # @!attribute [r] is_root?
+    # @!attribute [r] 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?
+    def root?
       @parent.nil?
     end
 
-    # @!attribute [r] has_content?
+    alias is_root? root? # @todo: Aliased for eventual replacement
+
+    # @!attribute [r] content?
     # +true+ if this node has content.
     #
     # @return [Boolean] +true+ if the node has content.
-    def has_content?
+    def content?
       @content != nil
     end
 
-    # @!attribute [r] is_leaf?
+    alias has_content? content? # @todo: Aliased for eventual replacement
+
+    # @!attribute [r] 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?
+    # @see #children?
+    def leaf?
+      !children?
     end
 
+    alias is_leaf? leaf? # @todo: Aliased for eventual replacement
+
     # @!attribute [r] parentage
     # An array of ancestors of this node in reversed order
     # (the first element is the immediate parent of this node).
@@ -173,7 +177,7 @@ module Tree
     # @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?
+      return nil if root?
 
       parentage_array = []
       prev_parent = parent
@@ -184,16 +188,18 @@ module Tree
       parentage_array
     end
 
-    # @!attribute [r] has_children?
+    # @!attribute [r] 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
+    # @see #leaf?
+    def children?
+      !@children.empty?
     end
 
+    alias has_children? children? # @todo: Aliased for eventual replacement
+
     # @!group Node Creation
 
     # Creates a new node with a name and optional content.
@@ -217,16 +223,10 @@ module Tree
     def initialize(name, content = nil)
       raise ArgumentError, 'Node name HAS to be provided!' if name.nil?
 
+      name = name.to_s if name.is_a?(Integer)
       @name = name
       @content = content
 
-      if name.is_a?(Integer)
-        warn StructuredWarnings::StandardWarning,
-             'Using integer as node name.'\
-             ' Semantics of TreeNode[] may not be what you expect!'\
-             " #{name} #{content}"
-      end
-
       set_as_root!
       @children_hash = {}
       @children = []
@@ -237,7 +237,13 @@ module Tree
     #
     # @return [Tree::TreeNode] A copy of this node.
     def detached_copy
-      self.class.new(@name, @content ? @content.clone : nil)
+      cloned_content =
+        begin
+          @content&.clone
+        rescue TypeError
+          @content
+        end
+      self.class.new(@name, cloned_content)
     end
 
     # Returns a copy of entire (sub-)tree from this node.
@@ -261,14 +267,14 @@ module Tree
     # representation of the (sub)tree rooted at this node.
     #
     def marshal_dump
-      collect { |node| node.create_dump_rep }
+      collect(&: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),
+        parent: (root? ? nil : @parent.name),
         content: Marshal.dump(@content) }
     end
 
@@ -279,6 +285,9 @@ module Tree
     # {Marshal}[http://ruby-doc.org/core-1.8.7/Marshal.html] class for
     # additional details.
     #
+    # NOTE: This is a potentially *unsafe* method with similar concerns as with
+    # the Marshal#load method, and should *not* be used with untrusted user
+    # provided data.
     #
     # @todo This method probably should be a class method. It currently clobbers
     #       self and makes itself the root.
@@ -291,7 +300,7 @@ module Tree
         content     = Marshal.load(node_hash[:content])
 
         if parent_name
-          nodes[name] = current_node = Tree::TreeNode.new(name, content)
+          nodes[name] = current_node = self.class.new(name, content)
           nodes[parent_name].add current_node
         else
           # This is the root node, hence initialize self.
@@ -309,7 +318,9 @@ module Tree
     #
     # @return [String] A string representation of the node.
     def to_s
-      "Node Name: #{@name} Content: #{@content.to_s || '<Empty>'} Parent: #{is_root? ? '<None>' : @parent.name.to_s} Children: #{@children.length} Total Nodes: #{size}"
+      "Node Name: #{@name} Content: #{@content.to_s || '<Empty>'} " \
+        "Parent: #{root? ? '<None>' : @parent.name.to_s} "       \
+        "Children: #{@children.length} Total Nodes: #{size}"
     end
 
     # @!group Structure Modification
@@ -422,7 +433,7 @@ module Tree
     def rename(new_name)
       old_name = @name
 
-      if is_root?
+      if root?
         self.name = new_name
       else
         @parent.rename_child old_name, new_name
@@ -516,7 +527,7 @@ module Tree
     #
     # @see #remove_all!
     def remove_from_parent!
-      @parent.remove!(self) unless is_root?
+      @parent.remove!(self) unless root?
     end
 
     # Removes all children from this node. If an independent reference exists to
@@ -528,7 +539,7 @@ module Tree
     # @see #remove!
     # @see #remove_from_parent!
     def remove_all!
-      @children.each { |child| child.set_as_root! }
+      @children.each(&:remove_all!)
 
       @children_hash.clear
       @children.clear
@@ -549,7 +560,7 @@ module Tree
     # 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 }
+      each(&:freeze)
     end
 
     # @!endgroup
@@ -560,45 +571,31 @@ module Tree
     #
     # - 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*
+    #   *index* (zero-based).
     #
     # - 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.)
+    # - To use an _Integer_ as the name, convert it to a _String_ first using
+    #   +<integer>.to_s+.
     #
     # @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.
     #
-    # @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
     # @see #initialize
-    def [](name_or_index, num_as_name = false)
+    def [](name_or_index)
       raise ArgumentError, 'Name_or_index needs to be provided!' if name_or_index.nil?
 
-      if name_or_index.is_a?(Integer) && !num_as_name
+      if name_or_index.is_a?(Integer)
         @children[name_or_index]
       else
-        if num_as_name && !name_or_index.is_a?(Integer)
-          warn StructuredWarnings::StandardWarning,
-               'Redundant use of the `num_as_name` flag for non-integer node name'
-        end
         @children_hash[name_or_index]
       end
     end
@@ -609,7 +606,6 @@ module Tree
     # The traversal is *depth-first* and from *left-to-right* in pre-ordered
     # sequence.
     #
-    # @param [Object] block
     # @yieldparam node [Tree::TreeNode] Each node.
     #
     # @see #preordered_each
@@ -651,7 +647,6 @@ module Tree
 
     # Traverses the (sub)tree rooted at this node in post-ordered sequence.
     #
-    # @param [Object] block
     # @yieldparam node [Tree::TreeNode] Each node.
     #
     # @see #preordered_each
@@ -670,7 +665,7 @@ module Tree
 
       until node_stack.empty?
         peek_node = node_stack[0]
-        if peek_node.node.has_children? && !peek_node.visited
+        if peek_node.node.children? && !peek_node.visited
           peek_node.visited = true
           # Add the children to the stack. Use the marking structure.
           marked_children =
@@ -689,7 +684,6 @@ module Tree
     # traversal at a given level is from *left-to-right*. this node itself is
     # the first node to be traversed.
     #
-    # @param [Object] block
     # @yieldparam node [Tree::TreeNode] Each node.
     #
     # @see #preordered_each
@@ -741,7 +735,6 @@ module Tree
     # May yield this node as well if this is a leaf node.
     # Leaf traversal is *depth-first* and *left-to-right*.
     #
-    # @param [Object] block
     # @yieldparam node [Tree::TreeNode] Each leaf node.
     #
     # @see #each
@@ -752,10 +745,10 @@ module Tree
     # noinspection RubyUnusedLocalVariable
     def each_leaf
       if block_given?
-        each { |node| yield(node) if node.is_leaf? }
+        each { |node| yield(node) if node.leaf? }
         self
       else
-        self.select { |node| node.is_leaf? }
+        self.select(&:leaf?)
       end
     end
 
@@ -813,22 +806,24 @@ module Tree
     #
     # @return [Tree::TreeNode] The first sibling node.
     #
-    # @see #is_first_sibling?
+    # @see #first_sibling?
     # @see #last_sibling
     def first_sibling
-      is_root? ? self : parent.children.first
+      root? ? self : parent.children.first
     end
 
     # Returns +true+ if this node is the first sibling at its level.
     #
     # @return [Boolean] +true+ if this is the first sibling.
     #
-    # @see #is_last_sibling?
+    # @see #last_sibling?
     # @see #first_sibling
-    def is_first_sibling?
+    def first_sibling?
       first_sibling == self
     end
 
+    alias is_first_sibling? first_sibling? # @todo: Aliased for eventual replacement
+
     # Last sibling of this node.  If this is the root node, then returns
     # itself.
     #
@@ -839,22 +834,24 @@ module Tree
     #
     # @return [Tree::TreeNode] The last sibling node.
     #
-    # @see #is_last_sibling?
+    # @see #last_sibling?
     # @see #first_sibling
     def last_sibling
-      is_root? ? self : parent.children.last
+      root? ? self : parent.children.last
     end
 
     # Returns +true+ if this node is the last sibling at its level.
     #
     # @return [Boolean] +true+ if this is the last sibling.
     #
-    # @see #is_first_sibling?
+    # @see #first_sibling?
     # @see #last_sibling
-    def is_last_sibling?
+    def last_sibling?
       last_sibling == self
     end
 
+    alias is_last_sibling? last_sibling? # @todo: Aliased for eventual replacement
+
     # 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.
@@ -874,7 +871,7 @@ module Tree
         parent.children.each { |sibling| yield sibling if sibling != self }
         self
       else
-        return [] if is_root?
+        return [] if root?
 
         siblings = []
         parent.children do |my_sibling|
@@ -891,10 +888,12 @@ module Tree
     # @return [Boolean] +true+ if this is the only child of its parent.
     #
     # @see #siblings
-    def is_only_child?
-      is_root? ? true : parent.children.size == 1
+    def only_child?
+      root? ? true : parent.children.size == 1
     end
 
+    alias is_only_child? only_child? # @todo: Aliased for eventual replacement
+
     # Next sibling for this node.
     # The _next_ node is defined as the node to right of this node.
     #
@@ -906,7 +905,7 @@ module Tree
     # @see #previous_sibling
     # @see #siblings
     def next_sibling
-      return nil if is_root?
+      return nil if root?
 
       idx = parent.children.index(self)
       parent.children.at(idx + 1) if idx
@@ -923,10 +922,10 @@ module Tree
     # @see #next_sibling
     # @see #siblings
     def previous_sibling
-      return nil if is_root?
+      return nil if root?
 
       idx = parent.children.index(self)
-      parent.children.at(idx - 1) if idx && idx > 0
+      parent.children.at(idx - 1) if idx&.positive?
     end
 
     # @!endgroup
@@ -941,7 +940,7 @@ module Tree
     #                   this node is a 'predecessor'. Returns 'nil' if the other
     #                   object is not a 'Tree::TreeNode'.
     def <=>(other)
-      return nil if other.nil? || other.class != Tree::TreeNode
+      return nil if other.nil? || !other.is_a?(Tree::TreeNode)
 
       name <=> other.name
     end
@@ -956,16 +955,16 @@ module Tree
                    block = lambda { |node, prefix|
                              puts "#{prefix} #{node.name}"
                            })
-      prefix = ''
+      prefix = ''.dup # dup NEEDs to be invoked to make this mutable.
 
-      if is_root?
+      if root?
         prefix << '*'
       else
-        prefix << '|' unless parent.is_last_sibling?
+        prefix << '|' unless parent.last_sibling?
         prefix << (' ' * (level - 1) * 4)
-        prefix << (is_last_sibling? ? '+' : '|')
+        prefix << (last_sibling? ? '+' : '|')
         prefix << '---'
-        prefix << (has_children? ? '+' : '>')
+        prefix << (children? ? '+' : '>')
       end
 
       block.call(self, prefix)
@@ -975,8 +974,7 @@ module Tree
 
       # Child might be 'nil'
       children do |child|
-        child&.print_tree(level + 1,
-                          max_depth, block)
+        child&.print_tree(level + 1, max_depth, block)
       end
     end
   end

data/rubytree.gemspec

@@ -3,51 +3,55 @@
 #
 # Author:: Anupam Sengupta (anupamsg@gmail.com)
 #
-# Copyright (c) 2012, 2013, 2014, 2015, 2017, 2020, 2021 Anupam Sengupta
-# All rights reserved.
+# Copyright (c) 2012-2022 Anupam Sengupta. All rights reserved.
+#
+# frozen_string_literal: true
 
 require './lib/tree/version'
 
 Gem::Specification.new do |s|
   s.name                  = 'rubytree'
-  s.date                  = '2021-12-29'
   s.version               = Tree::VERSION
   s.license               = 'BSD-3-Clause-Clear'
-
+  # NOTE: s.date should NOT be assigned. It is automatically set to pkg date.
   s.platform              = Gem::Platform::RUBY
   s.author                = 'Anupam Sengupta'
   s.email                 = 'anupamsg@gmail.com'
   s.homepage              = 'http://rubytree.anupamsg.me'
 
-  s.required_ruby_version = '>=2.7'
+  s.required_ruby_version = '>=2.6'
 
-  s.summary               = 'A generic tree data structure.'
-  s.description           = <<-END_OF_TEXT
+  s.summary               = 'A generic tree data structure for Ruby.'
 
-    RubyTree is a pure Ruby implementation of the generic tree data structure. It
-    provides a node-based model to store named nodes in the tree, and provides
-    simple APIs to access, modify and traverse the structure.
+  s.description           = <<-END_DESC
+    RubyTree is a pure Ruby implementation of the generic tree data
+    structure. It provides a node-based model to store named nodes in the tree,
+    and provides simple APIs to access, modify and traverse the structure.
 
-    The implementation is node-centric, where individual nodes in the tree are the
-    primary structural elements. All common tree-traversal methods (pre-order,
-    post-order, and breadth-first) are supported.
+    The implementation is node-centric, where individual nodes in the tree are
+    the primary structural elements. All common tree-traversal methods
+    (pre-order, post-order, and breadth-first) are supported.
 
-    The library mixes in the Enumerable and Comparable modules to allow access to
-    the tree as a standard collection (iteration, comparison, etc.).
+    The library mixes in the Enumerable and Comparable modules to allow access
+    to the tree as a standard collection (iteration, comparison, etc.).
 
     A Binary tree is also provided, which provides the in-order traversal in
     addition to the other methods.
 
-    RubyTree supports importing from, and exporting to JSON, and also supports the
-    Ruby's standard object marshaling.
+    RubyTree supports importing from, and exporting to JSON, and also supports
+    the Ruby's standard object marshaling.
 
     This is a BSD licensed open source project, and is hosted at
-    http://github.com/evolve75/RubyTree, and is available as a standard gem from
-    http://rubygems.org/gems/rubytree.
+    <https://github.com/evolve75/RubyTree>, and is available as a standard gem
+    from <https://rubygems.org/gems/rubytree>.
+
+    The home page for RubyTree is at <http://rubytree.anupamsg.me>.
 
-    The home page for RubyTree is at http://rubytree.anupamsg.me.
+  END_DESC
 
-  END_OF_TEXT
+  s.metadata = {
+    'rubygems_mfa_required' => 'true'
+  }
 
   s.files                = Dir['lib/**/*.rb']  # The actual code
   s.files               += Dir['[A-Z]*']       # Various documentation files
@@ -55,36 +59,55 @@ Gem::Specification.new do |s|
   s.files               += Dir['spec/**/*.rb'] # Rspec Test cases
   s.files               += Dir['examples/**/*.rb'] # Examples
 
+  # @todo: Check if this is really needed.
   s.files               += ['.gemtest'] # Support for gem-test
 
   s.require_paths        = ['lib']
 
   s.test_files           = Dir.glob('test/**/test_*.rb')
 
-  s.extra_rdoc_files     = %w[README.md LICENSE.md API-CHANGES.rdoc History.rdoc]
-  s.rdoc_options         = ['--title', 'Rubytree Documentation', '--quiet']
+  s.extra_rdoc_files     = %w[README.md LICENSE.md API-CHANGES.md History.md]
+  s.rdoc_options         = ['--title', "Rubytree Documentation: #{s.name}-#{s.version}",
+                            '--main', 'README.md',
+                            '--quiet']
 
-  s.add_runtime_dependency 'json', '~> 2.6.1'
-  s.add_runtime_dependency 'structured_warnings', '~> 0.4.0'
+  s.add_runtime_dependency 'json', '~> 2.0', '> 2.3.1'
 
-  # Development dependencies.
-  s.add_development_dependency 'bundler', '~> 2.3.4'
-  s.add_development_dependency 'coveralls', '>= 0.8.23'
-  s.add_development_dependency 'rake', '>= 13.0.6'
-  s.add_development_dependency 'rdoc', '>= 6.4.0'
-  s.add_development_dependency 'rspec', '~> 3.10.0'
+  # NOTE: Rake is added as a development and test dependency in the Gemfile.
+  s.add_development_dependency 'bundler', '~> 2.3'
+  s.add_development_dependency 'rake', '~> 13.0'
+  s.add_development_dependency 'rdoc', '~> 6.0'
+  s.add_development_dependency 'rspec', '~> 3.0', '> 3.10'
   s.add_development_dependency 'rtagstask', '~> 0.0.4'
-  s.add_development_dependency 'rubocop', '>= 1.24.0'
-  s.add_development_dependency 'test-unit', '>= 3.5.3'
-  s.add_development_dependency 'yard', '~> 0.9.27'
+  s.add_development_dependency 'rubocop', '~> 1.0'
+  s.add_development_dependency 'rubocop-rake', '~> 0.0'
+  s.add_development_dependency 'rubocop-rspec', '~> 2.0'
+  s.add_development_dependency 'test-unit', '~> 3.0'
+  s.add_development_dependency 'yard', '~> 0.0', '>= 0.9.20'
 
-  s.post_install_message = <<-END_OF_TEXT
+  s.post_install_message = <<-END_MESSAGE
     ========================================================================
                     Thank you for installing RubyTree.
 
-    Note:: As of 1.0.1, RubyTree can only support MRI Ruby >= 2.7.x
+    Note::
+
+    - 2.0.0 is a major release with BREAKING API changes.
+            See `API-CHANGES.md` for details.
+
+    - `Tree::TreeNode#depth` method has been removed (it was broken).
+
+    - Support for `CamelCase` methods names has bee removed.
+
+    - The predicate methods no longer have `is_` or `has_` prefixes. However,
+      aliases with these prefixes exist to support existing client code.
+
+    - Use of integers as node names does not require the optional
+      `num_as_name` flag.
+
+    - `structured_warnings` is no longer a dependency.
+
+    - Explicit support for rbx Ruby has been removed.
 
-    Details of the API changes are documented in the API-CHANGES file.
     ========================================================================
-  END_OF_TEXT
+  END_MESSAGE
 end

data/spec/spec_helper.rb

@@ -3,8 +3,10 @@
 # spec_helper.rb
 #
 # Author:  Anupam Sengupta
-# Time-stamp: <2015-12-31 21:00:36 anupam>
-# Copyright (C) 2015 Anupam Sengupta <anupamsg@gmail.com>
+# Time-stamp: <2022-06-19 22:38:14 anupam>
 #
+# Copyright (C) 2015, 2022 Anupam Sengupta <anupamsg@gmail.com>
+#
+# frozen_string_literal: true
 
 require 'tree'