rubytree 0.8.2 → 0.8.3

data/.dir-locals.el

@@ -0,0 +1,5 @@
+;;; Directory Local Variables
+;;; See Info node `(emacs) Directory Variables' for more information.
+
+((nil . ((projectile-mode . t)
+         (fill-column . 80))))

data/{API-CHANGES → API-CHANGES.rdoc}

@@ -1,3 +1,5 @@
+# @markup rdoc
+
 = API Changes in RubyTree
 
 This file documents various API level changes that have been made to the RubyTree package.
@@ -5,6 +7,10 @@ This file documents various API level changes that have been made to the RubyTre
 Note: API level changes are expected to reduce dramatically after the 1.x release.  In most cases, an alternative will
 be provided to ensure relatively smooth transition to the new APIs.
 
+== Release 8.8.3 Changes
+
+- {Tree::TreeNode#siblings} will now return an empty array for the root node.
+
 == Release 0.8.0 Changes
 
 - Added the ability to specify an optional insertion position in the {Tree::TreeNode#add} method.  Idea and original
@@ -24,28 +30,25 @@ be provided to ensure relatively smooth transition to the new APIs.
   - {Tree::TreeNode#[]}
   - {Tree::BinaryTreeNode#add}
 
-- Added {Tree::TreeNode#level} as an alias for {Tree::TreeNode#nodeDepth}
+- Added {Tree::TreeNode#level} as an alias for {Tree::TreeNode#node_depth}
 
 - Added new methods {Tree::TreeNode#in_degree} and {Tree::TreeNode#out_degree} to report the node's degree stats
 
-- {Tree::TreeNode#isOnlyChild?} now returns +true+ for a root node.
+- {Tree::TreeNode#is_only_child?} now returns +true+ for a root node.
 
-- {Tree::TreeNode#nextSibling} and {Tree::TreeNode#previousSibling} now return +nil+ for a root node.
+- {Tree::TreeNode#next_sibling} and {Tree::TreeNode#previous_sibling} now return +nil+ for a root node.
 
 - {Tree::TreeNode#add} and {Tree::TreeNode#<<} now throw an ArgumentError exception if a +nil+ node is passed as an argument.
 
-- Added new methods {Tree::TreeNode#to_json} and {Tree::TreeNode::json_create} to convert to/from the JSON format.
+- Added new methods {Tree::TreeNode#to_json} and Tree::TreeNode::json_create to convert to/from the JSON format.
   Thanks to Dirk[http://github.com/railsbros-dirk] for this change.
 
 == Release 0.6.1 Changes
 
 - Deprecated the {Tree::TreeNode#depth} method as it was returning an incorrect depth value.  Have introduced a new replacement
-  method {Tree::TreeNode#nodeDepth} which returns the correct result.
-
-
-
+  method {Tree::TreeNode#node_depth} which returns the correct result.
 
 # Local Variables:
-# mode: text
+# mode: rdoc
 # coding: utf-8-unix
 # End:

data/{COPYING → COPYING.rdoc}

@@ -2,7 +2,7 @@
 
 http://rubytree.rubyforge.org
 
-Copyright (c) 2006, 2007, 2008, 2009, 2010 Anupam Sengupta (anupamsg at gmail dot com)
+Copyright (c) 2006, 2007, 2008, 2009, 2010, 2011, 2012 Anupam Sengupta (anupamsg at gmail dot com)
 
 All rights reserved.
 
@@ -26,18 +26,7 @@ SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSE
 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.
 
-$Id$
-
-
-
-
-
-
-
-
-
-
 # Local Variables:
-# mode: text
+# mode: rdoc
 # coding: utf-8-unix
 # End:

data/Gemfile

@@ -0,0 +1,8 @@
+source 'http://rubygems.org'
+
+# Specify your gem's dependencies in rubytree.gemspec
+gemspec
+
+# Local Variables:
+# mode: ruby
+# End:

data/Gemfile.lock

@@ -0,0 +1,28 @@
+PATH
+  remote: .
+  specs:
+    rubytree (0.8.3)
+      json (>= 1.7.5)
+      structured_warnings (>= 0.1.3)
+
+GEM
+  remote: http://rubygems.org/
+  specs:
+    json (1.7.5)
+    rake (0.9.2.2)
+    rcov (0.9.11)
+    rtags (0.98)
+    rtagstask (0.0.4)
+      rtags (> 0.0.0)
+    structured_warnings (0.1.3)
+    yard (0.8.2.1)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  rake (>= 0.9.2.2)
+  rcov (~> 0.9.0)
+  rtagstask (>= 0.0.4)
+  rubytree!
+  yard (>= 0.8.2.1)

data/{History.txt → History.rdoc}

@@ -1,3 +1,35 @@
+# @markup rdoc
+
+= History of Changes
+
+=== 0.8.3 / 2012-08-31
+
+This is a primarily a bug-fix release, with some packaging changes.
+
+* Have removed the dependency on Hoe.  The build is now vanilla gemspec based.
+
+* Included support for {gem-testers}[http://test.rubygems.org/].
+
+* Included support for {Bundler}[http://gembundler.com/].
+
+* Implemented the +as_json+ method to support Rails' JSON encoding,
+  by pulling in the changes by Eric Cline (https://github.com/escline).
+
+* Partial fix for {Github Bug
+  #5}[https://github.com/evolve75/RubyTree/issues/5].  This is to
+  prevent infinite looping is an existing node is added again
+  elsewhere in the tree.
+
+* Fixed the issue with using +integers+ as node names, and its
+  interaction with the +TreeNode#[]+ access method {Github Bug
+  #6}[https://github.com/evolve75/RubyTree/issues/6].
+
+* Clarified the need to have unique node names {Github Bug
+  #7}[https://github.com/evolve75/RubyTree/issues/7] (documentation).
+
+* Fixed +siblings+ method to return an empty array for the root node as
+  well (it returned +nil+ earlier).
+
 === 0.8.2 / 2011-12-15
 
 * Minor bug-fix release to address bug #1215 (Tree::TreeNode#to_s
@@ -107,4 +139,6 @@
 
 * Minor code refactoring. Changes in the Rakefile.
 
-$Id$
+;; Local Variables:
+;; mode: rdoc
+;; End:

data/{README → README.rdoc}

@@ -6,7 +6,7 @@
  \/ \_/\__,_|_.__/ \__, |\__|_|  \___|\___|
                   |___/
 
-Copyright (c) 2006, 2007, 2008, 2009, 2010, 2011 Anupam Sengupta (anupamsg at gmail dot com)
+Copyright (c) 2006, 2007, 2008, 2009, 2010, 2011, 2012 Anupam Sengupta (anupamsg at gmail dot com)
 
 http://rubytree.rubyforge.org
 
@@ -70,10 +70,10 @@ As an example, the following code-snippet implements this tree structure:
 
 * Ruby 1.8+  (http://www.ruby-lang.org)
 
-* Optional but recommended:
-  * structured_warnings (http://github.com/schmidt/structured_warnings) Rubygem
+* Run-time Dependencies:
+  * structured_warnings (http://github.com/schmidt/structured_warnings) rubygem
   * Yard (http://yardoc.org) Rubygem for the documentation
-  * JSON (http://flori.github.com/json) Rubygem for converting to/from the JSON format
+  * JSON (http://flori.github.com/json) rubygem for converting to/from the JSON format
 
 * Development dependencies (not required for installing the gem):
   * Hoe (http://seattlerb.rubyforge.org/hoe/Hoe.html) Rubygem
@@ -184,6 +184,7 @@ I would like to acknowledge the following contributors for helping improve RubyT
 
 1. Dirk Breuer (http://github.com/railsbros-dirk) for contributing the JSON conversion code.
 2. Vincenzo Farruggia for contributing the (sub)tree cloning code.
+3. Eric Cline (https://github.com/escline) for the Rails JSON encoding fix.
 
 == LICENSE:
 
@@ -212,10 +213,7 @@ SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSE
 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.
 
-
-(Document Revision: $Revision$ by $Author$)
-
 # Local Variables:
-# mode: text
+# mode: rdoc
 # coding: utf-8-unix
 # End:

data/Rakefile

@@ -2,9 +2,7 @@
 #
 # Rakefile - This file is part of the RubyTree package.
 #
-# $Revision$ by $Author$ on $Date$
-#
-# Copyright (c) 2006, 2007, 2009, 2010  Anupam Sengupta
+# Copyright (c) 2006, 2007, 2009, 2010, 2011, 2012  Anupam Sengupta
 #
 # All rights reserved.
 #
@@ -34,114 +32,92 @@
 # SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 #
 
-PKG_NAME        = "rubytree"
-
-# Default is to create a rubygem.
-desc "Default Task (create the gem)"
-task :default => :gem
-
-# Use Hoe to define the rake tasks.
-begin
-  require 'hoe'
-  Hoe.plugin :yard
-
-  Hoe.spec PKG_NAME do
-    # The GemSpec settings
-    self.rubyforge_name = PKG_NAME
-    developer "Anupam Sengupta", "anupamsg@gmail.com"
-
-    self.url                        =  "http://rubytree.rubyforge.org"
-    self.readme_file                = 'README'
-
-    # Set the Yard Options
-    extra_docs                      = ["COPYING", "API-CHANGES"]
-    extra_docs.each { |file| self.yard_files << file }
-    self.yard_options = ["--files", extra_docs.join(",") ]
-
-    # Now the publishing settings
-    self.remote_rdoc_dir            = 'rdoc'
+require 'rubygems'
+GEM_SPEC = eval(File.read("rubytree.gemspec")) # Load the gemspec.
 
-    # Support additional package formats
-    self.need_tar                   = true
-    self.need_zip                   = true
+PKG_NAME = GEM_SPEC.name
+PKG_VER  = GEM_SPEC.version
+GEM_NAME = "#{PKG_NAME}-#{PKG_VER}.gem"
 
-    # Post installation message
-    self.post_install_message       = <<MSGEND
-========================================================================
+desc "Default Task (Run the tests)"
+task :default => 'test:rcov'
 
- Thank you for installing #{PKG_NAME}.
-
-              WARNING: SIGNIFICANT API CHANGE in 0.8.0 !
-              ------------------------------------------
-
- Please note that as of 0.8.0 the CamelCase method names are DEPRECATED.
+desc "Display the current gem version"
+task :version do
+  puts "Current Version: #{GEM_NAME}"
+end
 
- The new method names follow the ruby_convention (separated by '_').
+require 'rake/clean'
+task :clean => 'gem:clobber_package'
+CLEAN.include('coverage')
+task :clobber => [:clean, 'doc:clobber_rdoc', 'doc:clobber_yard', 'tag:clobber_tags']
 
- The old CamelCase methods still work (a warning will be displayed),
- but may go away in the future.
+desc "Open an irb session preloaded with this library"
+task :console do
+  sh "irb -rubygems -r ./lib/tree.rb"
+end
 
- Details of the API changes are documented in the API-CHANGES file.
+namespace :doc do               # ................................ Documentation
 
-========================================================================
-MSGEND
+  require 'rdoc/task'
+  Rake::RDocTask.new do |rdoc|
+    rdoc.rdoc_dir = 'rdoc'
+    rdoc.title    = "#{PKG_NAME}-#{PKG_VER}"
+    rdoc.main     = 'README.rdoc'
+    rdoc.rdoc_files.include(GEM_SPEC.extra_rdoc_files)
+    rdoc.rdoc_files.include('lib/**/*.rb')
+  end
 
-    # Code Metrics ...
-    self.flay_threshold             = timebomb 1200, 100 # Default is 1200, 100
-    self.flog_threshold             = timebomb 1200, 100 # Default is 1200, 100
+  require 'yard'
+  YARD::Rake::YardocTask.new do |t|
+    t.files   = ['lib/**/*.rb', '-', GEM_SPEC.extra_rdoc_files]
+    t.options = ['--no-private', '--embed-mixins']
   end
 
-rescue LoadError                # If Hoe is not found ...
-  $stderr.puts <<-END
-  ERROR!!! You do not seem to have Hoe installed!
+  desc "Remove YARD Documentation"
+  task :clobber_yard do
+    rm_rf 'doc'
+  end
+end
 
-  The Hoe gem is required for running the rake tasks for building the rubytree gem.
+desc "Run the test cases"
+task :test => 'test:unit'
 
-  You can download Hoe as a Rubygem by running as root (or sudo):
+namespace :test do              # ................................ Test related
 
-    $ gem install hoe
+  require 'rake/testtask'
+  Rake::TestTask.new(:unit) do |test|
+    test.libs << 'lib' << 'test'
+    test.pattern = 'test/**/test_*.rb'
+    test.verbose = false
+  end
 
-  More details can be found at http://seattlerb.rubyforge.org/hoe/Hoe.html
+  require 'rcov/rcovtask'
+  Rcov::RcovTask.new(:rcov) do |t|
+    t.libs << "test"
+    t.test_files = FileList['test/**/test_*.rb']
+    t.verbose = true
+    t.rcov_opts << '--exclude /gems/,/Library/,/usr/,spec,lib/tasks'
+  end
 
-  END
 end
 
-
-# The following tasks are loaded independently of Hoe
-# ===================================================
-
-# Optional TAGS Task.
-# Needs http://rubyforge.org/projects/rtagstask/
-begin
+namespace :tag do               # ................................ Emacs Tags
   require 'rtagstask'
-  RTagsTask.new do |rd|
+  RTagsTask.new(:tags) do |rd|
     rd.vi = false
   end
-rescue LoadError
-  $stderr.puts <<-END
-  ERROR!!! You need to have the rtagstask (https://rubyforge.org/projects/rtagstask/) for generating the TAGS file.
-
-  You can install the rtags gem by running the following command as root (or sudo):
-
-    $ gem install rtagstask
-
-  END
 end
 
-begin
-  require 'reek/rake/task'
-  Reek::Rake::Task.new do |t|
-    t.verbose = false
-    t.source_files = 'lib/**/*.rb'
+namespace :gem do               # ................................ Gem related
+  require 'rubygems/package_task'
+  Gem::PackageTask.new(GEM_SPEC) do |pkg|
+    pkg.need_zip = true
+    pkg.need_tar = true
   end
-rescue LoadError
-  $stderr.puts <<-END
-  ERROR!!! You need to have reek (http://github.com/kevinrutherford/reek) for detecing the code smell.
-
-  You can install the reek gem by running the following command as root (or sudo):
-
-    $ gem install reek
-
-  END
 
+  desc "Push the gem into the Rubygems repository"
+  task :push => :gem do
+    sh "gem push pkg/#{GEM_NAME}"
+  end
 end

data/TODO.org

@@ -0,0 +1,174 @@
+# -*- mode: org; coding: utf-8-unix; fill-column: 120; -*-
+#+OPTIONS: ^:{}
+
+* R0.7.0                                                                                  :ARCHIVE:
+*** DONE Start using signed tags from R0.7.0                                              :ARCHIVE:
+*** DONE Add a check in the Tree::TreeNode.add method to prevent addition of nil child nodes :ARCHIVE:
+    CLOSED: [2010-02-23 Tue 23:07]
+*** DONE Fix the edge condition for Tree::TreeNode.isOnlyChild? when the root node is the receiver. :ARCHIVE:
+    CLOSED: [2010-02-23 Tue 22:03]
+    There really is no good default to this situation.  We will return 'true' simply because there is no other sibling
+    to a root.  However, a good case can be made that a root node does not have any parent either.
+*** DONE Add a convenience 'level' method to the TreeNode class (will be an alias to nodeDepth) :ARCHIVE:
+    CLOSED: [2010-02-21 Sun 01:02]
+*** DONE Add a API-CHANGES file to document the various API changes made till date        :ARCHIVE:
+    CLOSED: [2010-01-31 Sun 00:52]
+*** DONE Add new methods to return the degree counts of the receiver node (in-degree and out-degree) :ARCHIVE:
+    CLOSED: [2010-01-30 Sat 23:56]
+
+
+
+
+* R0.8.0                                                                                  :ARCHIVE:
+*** DONE Convert all method names to the canonical /^[_a-z<>=\[|+-\/\*`]+[_a-z0-9_<>=~@\[\]]*[=!\?]?$/ pattern :ARCHIVE:
+    See Roodi report at http://getcaliper.com/caliper/tool?tool=roodi&repo=git://github.com/evolve75/RubyTree.git
+*** DONE Integrate the subtree cloning patch submitted by Vincenzo Farrugia.              :ARCHIVE:
+
+
+
+* R0.8.1                                                                                  :ARCHIVE:
+*** DONE Fix [[http://rubyforge.org/tracker/index.php?func%3Ddetail&aid%3D28613&group_id%3D1215&atid%3D4793][bug #28613]] which was affecting the `leftChild=' and `rightChild=' methods for binary trees. :ARCHIVE:
+
+
+
+* R0.8.3
+
+  This is a bugfix release.
+
+*** TODO [#A] Resolve the infinite loop bug if a node is added to itself as a child       :Partial:
+    Issue https://github.com/evolve75/RubyTree/issues/5
+
+    This is a subtle problem to resolve.  The specific case of a node
+    being added to itself is trivial to resolve, and the fix has been
+    put in for 0.8.3.
+
+    However, the general problem is that in the current code, a node
+    can be added as a child to any portion of the tree down the
+    hierarchy (e.g., as a grandchild), which will need a more thorough
+    detection code in the ~TreeNode#add~ method, if it is to be done at
+    runtime.
+
+    The issue is really to prevent the tree becoming a graph.  Note
+    that the issue is with duplicate nodes, /not/ duplicated content.
+
+    A few options exist:
+    1. Perform a runtime check in the ~TreeNode#add~ method.  This will
+       cause a performance hit as the tree becomes larger.
+    2. Allow the additions to go through, but create a new ~validate~
+       method that checks for such cycles.
+    3. Create separate configuration object which can be attached to
+       the root of the tree, which allows per-tree configuration of
+       the behavior - this does allow for the user to take control,
+       but also introduces complications during tree mergers and
+       spitting subtrees.
+    4. Create a registry (to be maintained at the root?) of all nodes,
+       and use this for validating the node additions (and preventing
+       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.
+
+
+*** DONE Make Rubytree compatible with Bundler                                            :ARCHIVE:
+    CLOSED: [2012-08-21 Tue 21:04]
+
+*** DONE Make Rubytree compatible wth gem-testers                                         :ARCHIVE:
+    CLOSED: [2012-08-21 Tue 21:04]
+
+*** DONE Remove the dependency on Hoe                                                     :ARCHIVE:
+    CLOSED: [2012-08-21 Tue 21:05]
+*** DONE Resolve the _tree.rb_ file conflict with the [[http://netaddr.rubyforge.org/][netaddr gem]]                           :ARCHIVE:
+    CLOSED: [2012-08-20 Mon 01:03]
+    Issue https://github.com/evolve75/RubyTree/issues/8
+
+*** DONE Update documentation to be more explicit about duplicate node names              :ARCHIVE:
+    CLOSED: [2012-08-19 Sun 21:46]
+    Issue https://github.com/evolve75/RubyTree/issues/7
+    Update documentation for :name attribute in tree.rb.  There is no
+    specific code fix needed.
+
+*** DONE Allow integers to be used as node names (clarify the scenario). Fixed issue #6.  :ARCHIVE:
+    CLOSED: [2012-08-19 Sun 15:17]
+    Issue https://github.com/evolve75/RubyTree/issues/6
+    We will need to warn the user when an Integer is used as a name
+    for the node (but still allow the usage),
+    and
+    also add an optional flag to the TreeNode#[] method to allow the
+    user to explicitly indicate use of the Integer parameter as a
+    literal name, and not as an /index/ to the children array.
+
+*** DONE Clarify (or fix) the scenario whether a root node without children is a leaf     :ARCHIVE:
+    CLOSED: [2012-08-19 Sun 15:09]
+    Issue http://rubyforge.org/tracker/index.php?func=detail&aid=29549&group_id=1215&atid=4793
+
+#+begin_src ruby -n :eval no
+  tree.each_leaf do |tree_leaf|
+    tree_leaf_parent = tree_leaf.parent
+    tree_leaf.remove_from_parent!
+    puts tree_leaf_parent.is_leaf?
+  end
+#+end_src
+
+    will return ~false~, while technically ~tree_leaf_parent~ becomes leaf itself when ~tree_leaf~ is removed.
+
+    The problem here is that the code above is trying to concurrently modify the collection over which the ~each_leaf~
+    iterator is looping, which has unpredicable results.  As an example, try this with an array:
+
+#+begin_src ruby -n
+    a = Array(1..5)
+    a.each do |e|
+      a.delete(e)
+    end
+    a
+#+end_src
+
+#+RESULTS:
+| 2 | 4 |
+
+    The result is surprising, as not all elements are being deleted.  A good explanation is available in [[https://groups.google.com/forum/?fromgroups#!topic/ruby-talk-google/iEDF8qhojss%255B1-25%255D][this thread]] on
+    Ruby-Talk @ Google.
+
+    The correct way to handle the original need is:
+
+#+begin_src ruby -n :eval no
+  leafs = @root.each_leaf
+  parents = leafs.collect {|leaf| leaf.parent }
+  leafs.each {|leaf| leaf.remove_from_parent!}
+  parents.each {|parent| assert(parent.is_leaf?) if not parent.has_children?}
+#+end_src
+
+    Basically, the parent removal is done in a separate block, and *then* the check for the parents becoming leafs is done.
+
+*** DONE Fix the ~first_sibling~ and ~last_sibling~ for the root                              :ARCHIVE:
+    CLOSED: [2012-08-19 Sun 21:01]
+    The current behavior is correct, and has been left as is.
+*** DONE Fix the ~siblings~ method to return an empty array for root                        :ARCHIVE:
+    CLOSED: [2012-08-19 Sun 21:03]
+*** DONE Fix the TreeNode#root method to return nil for root's root.                      :ARCHIVE:
+    CLOSED: [2012-08-19 Sun 21:13]
+
+    Left the code as-is, since we need some way to un-ambiguously find the root, regardless of the node given.
+
+
+* R0.9.0
+*** TODO Fix the inconsistency of returning root as its first sibling, and returning a nil instead.  Ditto for last sibling.
+*** TODO fix the inconsistency of returning nil for the root, and an empty array for nodes which have no siblings.
+*** TODO We should perhaps return nil as root's root.
+*** TODO The semantic of length is probably unclear.  Should return the node_depth instead (or remove the method)
+    The current equivalence of length to size should also be removed.
+
+
+* Unplanned / Not assigned to any release
+*** TODO Create the basic UML diagrams and upload to the Site
+    DEADLINE: <2010-01-04 Mon>
+
+*** 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 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]
+
+*** DONE Get the version control moved from CVS to Subversion (request submitted to RubyForge) :ARCHIVE:
+    CLOSED: [2010-01-02 Sat 17:58]
+
+*** DONE Add logic in Rakefile to read the file list from Manifest.txt file.              :ARCHIVE:
+  CLOSED: [2009-12-31 Thu 23:37]