rubytree 0.9.7 → 2.0.0

data/Rakefile

@@ -2,7 +2,7 @@
 #
 # Rakefile - This file is part of the RubyTree package.
 #
-# Copyright (c) 2006-2015  Anupam Sengupta
+# Copyright (c) 2006-2022  Anupam Sengupta
 #
 # All rights reserved.
 #
@@ -31,49 +31,54 @@
 # 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 'rubygems'
-GEM_SPEC = eval(File.read("rubytree.gemspec")) # Load the gemspec.
+
+# @todo: Check if Bundler needs to be `require`d.
+GEM_SPEC = Bundler.load_gemspec(File.join(__dir__, 'rubytree.gemspec'))
 
 PKG_NAME = GEM_SPEC.name
 PKG_VER  = GEM_SPEC.version
 GEM_NAME = "#{PKG_NAME}-#{PKG_VER}.gem"
 
-desc "Default Task (Run the tests)"
+desc 'Default Task (Run the tests)'
 task :default do
-  if ENV["COVERAGE"]
-    Rake::Task["test:coverage"].invoke
+  if ENV['COVERAGE']
+    Rake::Task['test:coverage'].invoke
   else
-    Rake::Task["test:unit"].invoke
-    Rake::Task["spec"].invoke
+    Rake::Task['test:unit'].invoke
+    Rake::Task['spec'].invoke
   end
 end
 
-desc "Display the current gem version"
+desc 'Display the current gem version'
 task :version do
   puts "Current Version: #{GEM_NAME}"
 end
 
 require 'rake/clean'
-task :clean => 'gem:clobber_package'
+desc 'Remove all generated files.'
+task clean: 'gem:clobber_package'
 CLEAN.include('coverage')
-task :clobber => [:clean, 'doc:clobber_rdoc', 'doc:clobber_yard']
+task clobber: [:clean, 'doc:clobber_rdoc', 'doc:clobber_yard']
 
-desc "Open an irb session preloaded with this library"
+desc 'Open an irb session preloaded with this library'
 task :console do
-  sh "irb -rubygems -r ./lib/tree.rb"
+  sh 'irb -rubygems -r ./lib/tree.rb'
 end
 
-namespace :doc do               # ................................ Documentation
+namespace :doc do # ................................ Documentation
   begin
-    gem 'rdoc', ">= 2.4.2"      # To get around a stupid bug in Ruby 1.9.2 Rake.
+    gem 'rdoc', '>= 6.4.0' # To get around a stupid bug in Ruby 1.9.2 Rake.
     require 'rdoc/task'
     Rake::RDocTask.new do |rdoc|
       rdoc.rdoc_dir = 'rdoc'
-      rdoc.title    = "#{PKG_NAME}-#{PKG_VER}"
-      rdoc.main     = 'README.rdoc'
+      rdoc.title    = "RubyTree Documenation: #{PKG_NAME}-#{PKG_VER}"
+      rdoc.main     = 'README.md'
       rdoc.rdoc_files.include(GEM_SPEC.extra_rdoc_files)
-      rdoc.rdoc_files.include('lib/**/*.rb')
+      rdoc.rdoc_files.include('./lib/**/*.rb')
     end
   rescue LoadError
     # Oh well.
@@ -83,22 +88,25 @@ namespace :doc do               # ................................ Documentation
     require 'yard'
     YARD::Rake::YardocTask.new do |t|
       t.files   = ['lib/**/*.rb', '-', GEM_SPEC.extra_rdoc_files]
-      t.options = ['--no-private', '--embed-mixins']
+      t.options = %w[--no-private --embed-mixins]
     end
   rescue LoadError
     # Oh well.
   end
 
-  desc "Remove YARD Documentation"
+  desc 'Remove YARD Documentation'
   task :clobber_yard do
     rm_rf 'doc'
   end
 end
 
-desc "Run the test cases"
-task :test => 'test:unit'
+desc 'Run the unit tests'
+task test: %w[test:unit]
 
-namespace :test do              # ................................ Test related
+# ................................ Test related
+namespace :test do
+  desc 'Run all the tests'
+  task all: %w[test:unit test:spec test:examples]
 
   require 'rake/testtask'
   Rake::TestTask.new(:unit) do |test|
@@ -107,7 +115,19 @@ namespace :test do              # ................................ Test related
     test.verbose = false
   end
 
-  desc "Run the examples"
+  # ................................ rspec tests
+  begin
+    require 'rspec/core/rake_task'
+
+    RSpec::Core::RakeTask.new(:spec) do |t|
+      t.fail_on_error = false
+      t.rspec_opts = ['--color', '--format doc']
+    end
+  rescue LoadError
+    # Cannot load rspec.
+  end
+
+  desc 'Run the examples'
   Rake::TestTask.new(:examples) do |example|
     example.libs << 'lib' << 'examples'
     example.pattern = 'examples/**/example_*.rb'
@@ -115,7 +135,7 @@ namespace :test do              # ................................ Test related
     example.warning = false
   end
 
-  desc "Run the code coverage"
+  desc 'Run the code coverage'
   task :coverage do
     ruby 'test/run_test.rb'
   end
@@ -123,7 +143,7 @@ namespace :test do              # ................................ Test related
   begin
     require 'rcov/rcovtask'
     Rcov::RcovTask.new(:rcov) do |t|
-      t.libs << "test"
+      t.libs << 'test'
       t.test_files = FileList['test/**/test_*.rb']
       t.verbose = true
       t.rcov_opts << '--exclude /gems/,/Library/,/usr/,spec,lib/tasks'
@@ -131,41 +151,38 @@ namespace :test do              # ................................ Test related
   rescue LoadError
     # Oh well. Can't have everything.
   end
-
 end
 
-begin                            # ................................ rspec tests
-  require 'rspec/core/rake_task'
-
-  RSpec::Core::RakeTask.new(:spec) do |t|
-    t.fail_on_error = false
-    t.rspec_opts = ["--color", "--format doc"]
+# ................................ Emacs Tags
+namespace :tag do
+  require 'rtagstask'
+  RTagsTask.new(:tags) do |rd|
+    rd.vi = false
+    CLEAN.include('TAGS')
   end
 rescue LoadError
-  # Cannot load rspec.
+  # Oh well. Can't have everything.
 end
 
- namespace :tag do               # ................................ Emacs Tags
-  begin
-    require 'rtagstask'
-    RTagsTask.new(:tags) do |rd|
-      rd.vi = false
-      CLEAN.include('TAGS')
-    end
-  rescue LoadError
-    # Oh well. Can't have everything.
-  end
- end
-
-namespace :gem do               # ................................ Gem related
+# ................................ Gem related
+namespace :gem do
   require 'rubygems/package_task'
   Gem::PackageTask.new(GEM_SPEC) do |pkg|
     pkg.need_zip = true
     pkg.need_tar = true
   end
 
-  desc "Push the gem into the Rubygems repository"
-  task :push => :gem do
+  desc 'Push the gem into the Rubygems repository'
+  task push: :gem do
     sh "gem push pkg/#{GEM_NAME}"
   end
 end
+
+# ................................ Ruby linting
+require 'rubocop/rake_task'
+
+RuboCop::RakeTask.new(:rubocop) do |t|
+  t.options = ['--display-cop-names']
+  t.requires << 'rubocop-rake'
+  t.requires << 'rubocop-rspec'
+end

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,24 +21,31 @@
 #    +-------+-------+
 #    | GRANDCHILD 1  |
 #    +---------------+
+#
+# frozen_string_literal: true
 
 # ..... Example starts.
-require 'tree'                 # Load the library
+require 'tree' # Load the library
 
-# ..... 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")
+# ..... 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")
-root_node << Tree::TreeNode.new("CHILD2", "Child2 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.
-child1       = root_node["CHILD1"]
-grand_child1 = root_node["CHILD1"]["GRANDCHILD1"]
+# ..... 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']
 
 # ..... Now lets retrieve siblings of the current node as an array.
 siblings_of_child1 = child1.siblings

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.rb"
+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,11 +35,11 @@
 # 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'
+require_relative '../tree'
 
 module Tree
-
   # Provides a Binary tree implementation. This node allows only two child nodes
   # (left and right child). It also provides direct access to the left or right
   # child, including assignment to the same.
@@ -51,7 +49,6 @@ module Tree
   # @author Anupam Sengupta
   #
   class BinaryTreeNode < TreeNode
-
     # @!group Core Attributes
 
     # @!attribute [rw] left_child
@@ -78,26 +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
@@ -114,12 +117,11 @@ module Tree
     # @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
+      raise ArgumentError, 'Already has two child nodes' if @children.size == 2
 
       super(child)
     end
 
-
     # Instantiate and insert child nodes from data in a Ruby +Hash+
     #
     # This method is used in conjunction with {Tree::TreeNode.from_hash} to
@@ -150,12 +152,13 @@ module Tree
     # @raise [ArgumentError] This exception is raised if a non-hash is passed.
     # @return [Array] Array of child nodes added
     def add_from_hash(hashed_subtree)
-      raise ArgumentError, "Too many children"\
+      raise ArgumentError, 'Too many children'\
                            if hashed_subtree.size + @children.size > 2
+
       super(hashed_subtree)
     end
 
-    # Performs inorder traversal (including this node).
+    # Performs in-order traversal (including this node).
     #
     # @yieldparam node [Tree::BinaryTreeNode]  Each node (in-order).
     #
@@ -167,26 +170,25 @@ module Tree
     # @see #each
     # @see #preordered_each
     # @see #postordered_each
-    def inordered_each(&block)
-
-      return self.to_enum unless block_given?
+    # noinspection RubyUnusedLocalVariable
+    def inordered_each
+      return to_enum unless block_given?
 
       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
         else
-          current_node = node_stack.pop()
+          current_node = node_stack.pop
           yield current_node
           current_node = current_node.right_child
         end
       end
 
-      return self if block_given?
-
+      self if block_given?
     end
 
     # A protected method to allow insertion of child nodes at the specified
@@ -201,7 +203,7 @@ module Tree
     #
     # @raise [ArgumentError] If the index is out of limits.
     def set_child_at(child, at_index)
-      raise ArgumentError "A binary tree cannot have more than two children."\
+      raise ArgumentError 'A binary tree cannot have more than two children.'\
                           unless (0..1).include? at_index
 
       @children[at_index]        = child
@@ -242,9 +244,7 @@ module Tree
 
     # 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
+      self.left_child, self.right_child = right_child, left_child
     end
-
   end
-
 end

data/lib/tree/tree_deps.rb

@@ -2,14 +2,12 @@
 #
 # = rubytree_deps.rb - Dependencies for RubyTree
 #
-# Centralizes and lists the dependencies forthe RubyTree gem.
+# Centralizes and lists the dependencies for the RubyTree gem.
 #
 # 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 'tree/version'
-require 'tree/utils/metrics_methods'
-require 'tree/utils/path_methods'
-require 'tree/utils/camel_case_method_handler'
-require 'tree/utils/json_converter'
-require 'tree/utils/tree_merge_handler'
-require 'tree/utils/hash_converter'
+require_relative '../tree/version'
+require_relative '../tree/utils/metrics_methods'
+require_relative '../tree/utils/path_methods'
+require_relative '../tree/utils/json_converter'
+require_relative '../tree/utils/tree_merge_handler'
+require_relative '../tree/utils/hash_converter'