JohnSmall-acts-as-hausdorff-space 0.1.3

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2009 John Small
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.rdoc

@@ -0,0 +1,184 @@
+== acts_as_hausdorff_space
+
+acts_as_hausdorff_space is a gemified mixin for Rails ActiveRecord. It implements the nested set model for maintaining recursive
+trees in a database, but using real numbers rather than integers because real numbers are a {Hausdorff Space}[http://en.wikipedia.org/wiki/Hausdorff_space]
+and the integers aren't
+
+== Caveats
+This version 0.1.0 is a proof of concept and a run through of all the github/lighthouse/google-group ecology of a gem. It works and 
+you're welcome to play with it and make comments, but don't trust it in production code just yet.
+ 
+== Installation 
+1. It's not a drop in replacement for acts_as_nested_set so watch out.
+2. Make sure you have http://gems.github.com set up in your gem sources
+3. sudo gem install acts-as-hausdorff-space
+4. In environment.rb add 
+   <tt> config.gem "acts-as-hausdorff-space"</tt>
+5. Create a migration with left and right columns using the biggest decimal representations available on your database.
+6. Add 
+    <tt> acts_as_hausdorff_space </tt> 
+   to your model.
+
+
+== Other references
+
+1. Source is at  git://github.com/JohnSmall/acts-as-hausdorff-space.git
+2. Wiki is at http://wiki.github.com/JohnSmall/acts-as-hausdorff-space
+3. Lighthouse bugtracking is at http://mindoro.lighthouseapp.com/projects/29279-acts_as_hausdorff_space/overview
+4. Google group for discussion is at http://groups.google.com/group/acts_as_hausdorff_space 
+5. I'm at {John Small}[http://www.mindoro-marine.co.uk] 
+
+
+== A Problem with Nested Sets - Mega Peformance Issues
+
+I was using the better_nested_set plugin in a territories model and trying to load all the countries in the world and all the regions and sub-regions
+and it was taking utterly ages. So I set about thinking what could be done to improve performance. I'd written the
+code for nested sets before a long time ago using Delphi & Interbase,  so I knew the problems. But in the meantime I'd
+learned some topology theory so I had a name and a concept to put to what must have been starting everyone in the face
+. Hausdorff Spaces! Integers aren't a Hausdorff space but we're trying to implement a concept, namely nested sets,
+which are the defining characteristic of a Hausdorff space, so we have to write extra code to fudge integers to behave
+like they are a Hausdorff space and that is the source of the performance hit. So the obvious thing to do is to use
+real numbers which are a Hausdorff space and then the extra code and associated performance hit melts away. After some
+fussing about version 0.1.0 is now released. For small trees the overhead of using BigDecimal rather than integers makes this
+method slower, but as the trees get bigger the relative performance soon switches in favour of using BigDecimals.
+check the  table at the bottom to see how big the performance improvements can be.
+
+== A bit of history 
+
+Joe Celko, an SQL guru, popularized the idea of using nested sets for databases back in his 1996 article reproduced 
+{here}[http://www.dbmsmag.com/9603d06.html].
+Though the earliest description is in {Kamfonas}[http://www.kamfonas.com/id3.html].
+Since it's usually a bad idea to go against the advice of an SQL guru every implementation I've seen follows his example in using integers to
+set the nesting boundaries. So every implementation has had to deal with the awkwardness that comes with using integers
+in a way they can't inherently be used. The description in {Kamfonas}[http://www.kamfonas.com/id3.html] recomends using a SKIP-VALUE
+to make sure you've got some space to put new entries in. Though the code for that is obviously going to be complicated because
+you'd need to work out a skip value for each node if you're adding a collection of nodes inside an already existing node. This is the
+kind of coding fudge people have to do to make nested sets maintainable.
+
+== The Basic Idea
+This is copied from {ThreeBit}[http://threebit.net/tutorials/nestedset/tutorial1.html] and is the example used in
+better_nested_sets. The example uses integers.
+
+An easy way to visualize how a nested set works is to think of a parent entity surrounding all
+of its children, and its parent surrounding it, etc. So this tree:
+  root
+    |_ Child 1
+      |_ Child 1.1
+      |_ Child 1.2
+    |_ Child 2
+      |_ Child 2.1
+      |_ Child 2.2
+
+Could be visualized like this:
+    ___________________________________________________________________
+   |  Root                                                             |
+   |    ____________________________    ____________________________   |
+   |   |  Child 1                  |   |  Child 2                  |   |
+   |   |   __________   _________  |   |   __________   _________  |   |
+   |   |  |  C 1.1  |  |  C 1.2 |  |   |  |  C 2.1  |  |  C 2.2 |  |   |
+   1   2  3_________4  5________6  7   8  9_________10 11_______12 13  14
+   |   |___________________________|   |___________________________|   |
+   |___________________________________________________________________| 
+
+The numbers represent the left and right boundaries.  The table then might
+look like this:
+   id | parent_id | lft  | rgt  | data
+    1 |           |    1 |   14 | root
+    2 |         1 |    2 |    7 | Child 1
+    3 |         2 |    3 |    4 | Child 1.1
+    4 |         2 |    5 |    6 | Child 1.2
+    5 |         1 |    8 |   13 | Child 2
+    6 |         5 |    9 |   10 | Child 2.1
+    7 |         5 |   11 |   12 | Child 2.2
+
+To get all children of an entry +parent+, you
+    SELECT * WHERE lft IS BETWEEN parent.lft AND parent.rgt
+
+To get the number of children, it's 
+    (right - left - 1)/2
+
+To get a node and all its ancestors going back to the root, you
+    SELECT * WHERE node.lft IS BETWEEN lft AND rgt
+    
+== Notes.
+
+Pretty obviously if you wanted to add a new child with C.1.1 as parent you'll have to update the entire tree from 4 onwards
+because there is no integer between 3 and 4.    
+
+
+== A bit of topological theory
+
+There is no integer between 3 and 4, but there are an uncountable infinity of real numbers between 3 and 4. That is the crux of the problem.
+Between any two real numbers there is always another real number, no matter how close they are. This property was first described
+by Archimedes and it's called the {Archimedean property of real numbers}[http://en.wikipedia.org/wiki/Archimedean_property#Archimedean_property_of_the_real_numbers]
+
+What that means is that for real numbers we can surround any two of them with disjoint open neighbourhoods and that is the defining
+property of a {Hausdorff Space}[http://en.wikipedia.org/wiki/Hausdorff_space]. That property of being able to put any two points
+inside disjoint sets of nearby points means you can have infinite levels of nesting. The notion of nested sets is inherently part
+of a Hausdorff space, but not of the integers, which is why you have to write lots of awkward slow code to maintain nested sets implemented
+with integers
+
+== The Implementation in Abstract
+
+The implementation is the same as above, with two differences. I'm not using parent_id because that defeats the main advantage of the nested set model over the adjaceny list model
+and I'm using real numbers. That means if we want to add a record between 3 and 4, we can make lft = 3.25 and rgt = 3.5, and we
+can keep on adding records to any depth or width of tree we like, without having to update the rest of the tree.
+
+== The Real Life Implementation Constraints
+
+Computers don't use real numbers, they use binary arithmetic to emulate real numbers. That means the lovely idea has
+to get ugly when it meets the real world. There are maximum sizes for the real numbers used and also minimum sizes depending
+on the real number precision limits. But within those constraints we can implement the concept of nested sets using real numbers 
+fairly easily. We just have to keep our calculations away from bumping up against the lower and upper limits. It means that
+there's going to be a limit to the number of children a parent node can own, and also a limit to the depth of the tree. Most trees
+used in nested sets in relational databases aren't very deep, but they can be very wide. When we add a new node into a gap in
+the tree we have to make sure it leaves a gap between itself and its siblings or the parent lefts and rights. That way we will
+always have some space to put a new record in the gap, as long as the gap isn't so small that we're bumping up against the limits
+of decimal precision. So when you set up your tables always choose the maximum precision for that database.
+
+The other issue when we add a new record, we want to leave space for more records but we don't know in advance how many
+records to leave space for. We could do what's done in the integer implementations of nested sets, move every lft and rgt along
+a bit, but that is where the performance hit comes from. So we have to leave gaps and fill them as best we can. If each new node 
+were to take up half of the remaining space between its siblings and the boundaries
+of its parent, then we'd pretty soon bump up against the decimal precision limit. To avoid that I've set things up so that there's
+a number called the #bias, which is a division factor. It works like this, I add a new child to a parent, I use the bias
+to work out where to place the child inside what ever gap remains, roughly (remaining gap)/bias. So the bigger the bias the less
+of the remaining gap is taken up. The default bias is one million, to allow for wide and shallow trees. 
+
+== Implementation Details
+see 
+
+== Relative Performance 
+
+For small trees integers are faster, for large trees acts_as_hausdorff_space using BigDecimals are faster by a large margin. To get a rough estimate of
+performance I wrote a test which adds 1000 children to a root node, then goes through each child node adding children. This really
+hammers the integer implementation of nested sets since every new insertion requires updating every node to the right of the new
+insertion. The full test description and updated results are {here}[http://mindoro-marine.co.uk/nested_sets_tests].
+
+No. of children added is the number of child nodes added to each of the 1000 children of the root. aahs = acts_as_hausdorff_space,
+bns = using the better_nested_set mixin.
+
+              |      SQLite3       |          MySQL           |
+  No of       | aahs    | bns      | aahs       | bns         |
+  children
+  added  
+  0           | 28 secs | 15 secs  | 28 secs    | 9 secs      |
+  1           | 39      | 55       | 40         | 150         |
+  2           | 51      | 116      | 51         | 7,692       |
+  3           | 62      | 203      | 63         | 24,555      |
+  4           | 73      | 312      | 75         | I gave up   |
+  5           | 84      | 444      | 87         |             |
+  6           | 96      | 596      | 99         |             |
+  7           | 109     | 765      | 113        |             |
+  8           | 121     | 952      | 129        |             |
+  9           | 131     | 1156     | 144        |             |
+
+As you can see adding children into large trees using acts_as_hausdorff_space (aahs) is nice and linear in the number
+of children added. Using the integer method implemented by better_nested_set things are much slower 
+and on MySQL the time taken blows up quite quickly. 
+
+I'll be testing Postgres and trying to work out why MySQL blows up so badly. 
+
+== Copyright
+
+Copyright (c) 2009 John Small. See LICENSE for details.

data/Rakefile

@@ -0,0 +1,66 @@
+require 'rubygems'
+require 'rake'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = "acts-as-hausdorff-space"
+    gem.summary = %Q{Use real numbers instead of integers for nested sets because real numbers are a Hausdorff space}
+    gem.email = "jds340@gmail.com"
+    gem.homepage = "http://github.com/JohnSmall/acts-as-hausdorff-space"
+    gem.authors = ["John Small"]
+
+    # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
+  end
+rescue LoadError
+  puts "Jeweler not available. Install it with: sudo gem install technicalpickles-jeweler -s http://gems.github.com"
+end
+
+require 'rake/testtask'
+#Rake::TestTask.new(:test) do |test|
+#  test.libs << 'lib' << 'test'
+#  test.pattern = 'test/**/*_test.rb'
+#  test.verbose = true
+#end
+
+desc 'Run tests on all database adapters.'
+task :default => [:test_mysql, :test_sqlite3, :test_postgresql]
+for adapter in %w(mysql postgresql sqlite3)
+  Rake::TestTask.new("test_#{adapter}") do |t|
+    t.libs << 'lib'
+    t.pattern = "test/#{adapter}.rb"
+    t.verbose = true
+  end
+end
+
+begin
+  require 'rcov/rcovtask'
+  Rcov::RcovTask.new do |test|
+    test.libs << 'test'
+    test.pattern = 'test/**/*_test.rb'
+    test.verbose = true
+  end
+rescue LoadError
+  task :rcov do
+    abort "RCov is not available. In order to run rcov, you must: sudo gem install spicycode-rcov"
+  end
+end
+
+task :default => :test
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  if File.exist?('VERSION.yml')
+    config = YAML.load(File.read('VERSION.yml'))
+    version = "#{config[:major]}.#{config[:minor]}.#{config[:patch]}"
+  else
+    version = ""
+  end
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "acts-as-hausdorff-space #{version}"
+  rdoc.rdoc_files.include('*.rdoc')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+
+

data/VERSION.yml

@@ -0,0 +1,4 @@
+--- 
+:major: 0
+:minor: 1
+:patch: 3

data/lib/acts-as-hausdorff-space.rb

@@ -0,0 +1,7 @@
+# acts_as_hausdorff_space
+# (c) John Small 2009
+require "acts_as_hausdorff_space"
+
+ActiveRecord::Base.class_eval do
+  include MindoroMarine::Acts::HausdorffSpace
+end

data/lib/acts_as_hausdorff_space.rb

@@ -0,0 +1,425 @@
+# ActsAsHausdorffSpace
+module MindoroMarine
+  module Acts #:nodoc:
+    module HausdorffSpace #:nodoc:
+    
+     def self.included(base)
+        base.extend(ActMethods)              
+      end
+    module ActMethods
+      # Configuration options are:        
+        # * +left_column+ - Column name for the left index (default: +lft+). 
+        # * +right_column+ - Column name for the right index (default: +rgt+). NOTE: 
+        #   Don't use +left+ and +right+, since these are reserved database words.        
+        # * +bias+ - A divisor used to calculate where in a gap a new record should go. Bigger numbers are preferred for wide shallow trees
+        #   Default is 1E6
+        # * +max_double+ - This is the outer left and right boundaries of all the trees. Set it according to the precision and scale you're
+        #  using in your database columns. Default is 1E20
+        def acts_as_hausdorff_space(options = {}) 
+        #[TODO] use reverse merge here
+        write_inheritable_attribute(:acts_as_hausdorff_space_options,
+             { :left_column    => (options[:left_column]   || 'lft'),
+               :right_column   => (options[:right_column]  || 'rgt'),
+               :bias           => (options[:bias]  || 1E6),
+               :max_double     => (options[:max_double] || 1E20 ),                          
+               :class          => self , # for single-table inheritance
+               :virtual_root   => VirtualRoot.new(-(options[:max_double] || 1E20 ),
+                                                   (options[:max_double] || 1E20 ))
+              } )
+          
+          class_inheritable_reader :acts_as_hausdorff_space_options
+          unless included_modules.include? MindoroMarine::Acts::HausdorffSpace::InstanceMethods
+             include MindoroMarine::Acts::HausdorffSpace::InstanceMethods
+             extend MindoroMarine::Acts::HausdorffSpace::ClassMethods
+          end
+        end
+    end  
+    
+    # Each branch has branches and/or leaves and gaps to put new things in
+    # A gap has attributes left_col_val and right_col_val 
+    class Gap 
+     attr_accessor :left_col_val,:right_col_val
+    end   
+    
+    # An instance of VirtualRoot is a hidden root that "owns" the actual roots. It's only here so we can use the same code for
+    # real roots and children. Otherwise we have to write special code for the top level parents.
+    # Note: This is very different from the concept of virtual roots in better_nested_set which is the equivalent of <Klass>.root.children
+    # to get the immediate children of a top level root    
+    class VirtualRoot
+    attr_accessor :left_col_val,:right_col_val
+    attr_reader :children
+    
+    # initialize with a left and right value that will be the bounds of the entire tree of all the roots
+    def initialize( left_val,right_val)
+     self.left_col_val = left_val
+     self.right_col_val = right_val
+     @children = HSArray.new
+     @children.parent = self
+    end
+    
+    end #VirtualRoot
+    
+    # We need an array to hold children, but because we don't use parent_id we can't return the children as an AR has_many association
+    # Therefore we use an array.  Because we want to be able to write 
+    # <tt>parent.children << SomeModel.new</tt>
+    # then we need to do special stuff in "<<". But we don't want to mixin into Array because that might (almost certainly would)
+    # mess up other code, so we'll get very Java-like and subclass Array
+    class HSArray < Array
+    attr_accessor :parent
+    
+        # subclass << to set the parent on the new items being added
+        def <<(elem)
+        if elem.is_a?(Array) # if it is an array then load each item into the HSArray in turn
+         elem.each do |item| 
+         self << item
+         end
+        else
+         super  
+         elem.parent = self.parent if self.parent && elem.respond_to?('parent') 
+        end         
+       end #<<(elem) 
+    end #HSArray
+    
+   
+    module ClassMethods
+        
+    # Get all the top level roots. This does a find of all records with no immediate parent in the database. 
+    # When they're loaded they get a virtual root attached as their parent. This is to make sure that every node has a parent which helps to
+    # generalise and simplify the code for working out left and right boundaries.    
+    def roots
+     top_levels =    self.find( :all, :conditions => "not exists (select t1.id from #{self.table_name} t1
+                                                                       where t1.#{left_col_name} <#{self.table_name}.#{left_col_name} 
+                                                                       and t1.#{right_col_name} > #{self.table_name}.#{right_col_name})",:order=>"#{left_col_name}")
+     self.virtual_root.children.clear
+     top_levels.each do |tl|
+     begin
+     tl.in_tree = true
+     self.virtual_root.children << tl
+     tl.in_tree = false
+     rescue
+     tl.in_tree = false
+     raise
+     end
+     end 
+    end
+    # get the first root from roots
+    def root
+        roots.first
+    end
+    # use the instance method <tt>build_full_tree</tt> on the root to get all the children set up in a tree
+    def full_tree
+      root.build_full_tree
+    end
+ 
+    # Return the left column name. Either the one supplied in the options to acts_as_hausdorff_space or the default "lft"
+    def left_col_name
+        acts_as_hausdorff_space_options[:left_column]
+    end
+    
+    # Return the right column name. Either the one supplied in the options to acts_as_hausdorff_space or the default "rgt"
+    def right_col_name
+        acts_as_hausdorff_space_options[:right_column]
+    end
+    
+    # Return the max_double supplied in the options to to acts_as_hausdorff_space or the default 1E20
+    def max_double
+      acts_as_hausdorff_space_options[:max_double]
+    end
+    
+     # Return the bias supplied in the options to to acts_as_hausdorff_space or the default 1E6
+    def bias
+      acts_as_hausdorff_space_options[:bias]
+    end
+    # Return the virtual root. This is an in memory only parent to all the roots, the left is set to -max_double and the right to max_double
+    def virtual_root 
+     acts_as_hausdorff_space_options[:virtual_root]
+    end
+        
+    end #module ClassMethods
+    
+    ############################ INSTANCE METHODS ######################################################
+    module InstanceMethods
+    attr_accessor :parent,:in_tree
+    
+    # initialize isn't always called so we can't do this in initialize. This sets up things we need to hold the tree together 
+    def after_initialize 
+     @parent = nil    
+     @children = HSArray.new
+     @children.parent = self
+     @root = nil
+     @is_root=false
+     @in_tree = false
+     @prev_left = nil
+     @prev_right = nil
+    end
+    
+    # Short hand method to save typing self.class.left_col_name
+    def left_col_name
+      self.class.left_col_name
+    end
+    
+    # Short hand method to save typing self.class.right_col_name
+    def right_col_name
+      self.class.right_col_name
+    end
+    
+    # get the left col value
+    def left_col_val
+       read_attribute(left_col_name)
+    end
+    
+    # set the left col value
+    def left_col_val=(value)
+       write_attribute(left_col_name,value)
+    end  
+    
+    # get the right col value
+    def right_col_val
+      read_attribute(right_col_name)
+    end
+    
+    # set the right col value
+    def right_col_val=(value)
+       write_attribute(right_col_name,value)
+    end 
+    
+    # Get the parent.
+    # If the parent hasn't already been set, and if we're not building the full tree (which sets parents) and if we've
+    # got a valid lft and right then construct the SQL to get the parent from the DB. If none is found then it's a root so
+    # set the parent to be the class.virtual_root
+    # If the parent is already set then don't go to the database to look for it, just return it
+    def parent
+     if !in_tree && left_col_val && right_col_val && !@parent # only get the parent by SQL if we don't know what it is
+     @parent = self.class.find :first, :conditions => " #{left_col_val} > #{self.class.left_col_name} and #{left_col_val} < #{self.class.right_col_name} ",:order =>'#{self.class.left_col_name} DESC'
+         if !@parent        
+          # @is_root = (lft == rgt) || (id == root.id)
+           return self.class.virtual_root
+         end 
+     else
+     @parent
+     end
+    end
+    
+    # set a new parent. This will save the parent, which will force a save of this child after the parent has had its lft and rgt set
+    # If we're loading a full tree, we don't save the parent and child as that would be daft
+    def parent=(new_parent)
+     if @parent != new_parent
+        @parent = new_parent
+        needs_moving!
+        @is_root  = @parent.is_a?(VirtualRoot) 
+     end  
+     # [TODO] clean this up with parent.save_children  
+     parent.save unless in_tree || @parent.is_a?(VirtualRoot) 
+     return @parent
+    end
+    
+    # sets the in_tree flag, pulls in all the children of this record with the level set correctly and ordered by lft.
+    # Then it executes a private method which does a depth first recursion of the returned dataset to build the tree.
+    # Returns this record as the root of the tree
+    def build_full_tree
+    self.in_tree = true
+    begin
+    # get all the children with levels counted and ordered in one SQL statement - this is what nested sets are all about 
+    # then do a depth first traversal of all the entire list to build the tree in memory
+      child_list = self.class.find_by_sql("SELECT t1.*,(select count(*) from #{self.class.table_name} t2 where t2.#{left_col_name}<t1.#{left_col_name} and t2.#{right_col_name} > t1.#{right_col_name}) as depth from #{self.class.table_name} t1 where t1.#{left_col_name} >#{left_col_val} and t1.#{right_col_name} <#{right_col_val} order by #{left_col_name} desc")
+      child_list.each{|r| r.in_tree = true}
+    #for some strange reason depth comes back as a string in Postgresql hence the .to_i
+      build_tree_by_recursion(self,child_list.last.depth.to_i,child_list)
+    rescue
+    self.in_tree = false
+    raise
+    end
+    return self  
+end
+
+# get the gap on the left of this record
+def lft_gap
+ # puts " in lft gap #{parent.class.name}"
+  gap = Gap.new
+  gap.right_col_val = self.left_col_val
+ if parent.children.first == self  
+  gap.left_col_val = parent.left_col_val 
+ else
+ # puts "get prev index"
+  prev_index = parent.children.index(self)-1
+ # puts "prev index = #{prev_index} count = #{parent.children.size}"
+  gap.left_col_val = parent.children[prev_index].right_col_val
+ end
+ return gap 
+end
+
+# get the gap on the right of this record
+def rgt_gap
+# puts " in rgt gap #{parent.class.name}"
+ gap = Gap.new
+ gap.left_col_val = self.right_col_val
+ if parent.children.last == self  
+  gap.right_col_val = parent.right_col_val 
+ else
+# puts "get next index"
+ next_index = parent.children.index(self)+1
+# puts "next index = #{next_index} count = #{parent.children.size}"
+ gap.right_col_val =  parent.children[next_index].left_col_val
+ end 
+ return gap
+end # rgt_gap
+
+# is this record a root
+def is_root?
+  @is_root
+end
+
+# find the root that owns this record. This is called "my_root" rather than "root" so you don't mix it up with <class>.root
+# This is different to how it's done in acts_as_nested_set
+def my_root
+  unless @root
+  @root = (self.class.find :first, :conditions => " #{left_col_val} >= #{left_col_name} and #{right_col_val}<= #{right_col_name} ",:order =>"#{left_col_name}") #between includes the end points
+  else
+  @root
+  end
+end
+
+# Find the immediate children of this record. If the children have already been loaded before either via build_full_tree or
+# a previous call to children then this just returns what was previously loaded. Otherwise it goes to the database.
+# The sql is a bit more involved than used in acts_as_nested_set because this is a pure nested set model and there's no parent_id
+# Because we're not using parent_id the returned array is not an AR associattion, unlike acts_as_nested_set. You have been warned.
+def children    
+    unless ( @children.size>0 || ( left_col_val == right_col_val ) || in_tree) # don't get children unless lft is not equal to rgt 
+     # puts "load_tree = #{in_tree}"    
+      @children << self.class.find( :all,:conditions => " #{self.class.table_name}.#{left_col_name} >#{left_col_val} and #{self.class.table_name}.#{right_col_name} < #{right_col_val} and #{left_col_val} = (select max(t1.#{left_col_name}) from #{self.class.table_name} t1 where #{self.class.table_name}.#{left_col_name} between t1.#{left_col_name} and t1.#{right_col_name})" )
+   else
+      @children
+   end
+end
+
+# Where most of the clever action happens.
+# 1. If there's no parent then set the <class>.virtual_root to be the parent before continuing
+# 2. Find the left boundary and the right boundary from the parent or the siblings or both
+# 3. If this record has no children then set lft=rgt and put it well on the left of the gap
+# 4. If there are children then set the lft and rgt to a comfortable size to hold the children
+def before_save
+ if !@parent
+   self.class.roots # this loads virtual_root with roots
+   self.class.virtual_root.children << self  # if we haven't got a parent then make the virtual root the parent
+ end
+far_left =  furthrest_left
+far_right = furthrest_right
+#puts "furthrest_right = #{far_right} furthrest_left = #{far_left}"
+gap = far_right - far_left
+  if  @children.size>0 
+     self.left_col_val = far_left + gap/4 
+     self.right_col_val = far_right - gap/4   
+  else    
+     self.left_col_val = self.right_col_val = far_left+(gap/self.class.bias)       
+  end
+end
+
+# Where most of the remaining action happens
+# If we've moved the record into a new parent from somewhere else then we need to update the old child records
+# to bring those into place. This requires a scaling, to fit into the new gap, and a translation to move into the corrent place
+# The code works out the values required for a single SQL statement that pulls the entire branch across
+#
+# If we haven't moved from elsewhere then save each child that needs saving
+def after_save
+  if @prev_left && @prev_right && @children.size > 0 # if we're moving from somewhere else
+        @children.clear
+        scale = ((right_col_val-left_col_val)/(@prev_right - @prev_left)).abs
+        old_mid_point = (@prev_right + @prev_left)/2
+        new_mid_point = (right_col_val+left_col_val)/2
+        sql = "update #{self.class.table_name} t1 set t1.#{left_col_name} = ((t1.#{left_col_name} - #{old_mid_point})*#{scale})+#{new_mid_point}, t1.#{right_col_name} = ((t1.#{right_col_name} - #{old_mid_point})*#{scale})+#{new_mid_point} where t1.#{left_col_name} >#{@prev_left} and t1.#{right_col_name} < #{@prev_right} "       
+        connection.update_sql(sql)
+        build_full_tree # get the children back
+  else   
+        @children.each{|child| child.save if !(child.left_col_val && child.right_col_val) } # save only the ones that need lft and rgt
+  end
+  @prev_left = @prev_right = nil  
+end
+
+# get the siblings. All immediate children of the parent minus self
+def siblings
+  if parent
+   self_and_siblings.reject{|r| r == self}
+  end
+end
+
+# get all children of the parent of this record
+def self_and_siblings
+ if parent
+   parent.children
+  end
+end
+# get the line of owners with the root first 
+def self_and_ancestors
+  self.class.find :all, :conditions =>"#{left_col_name} <= #{left_col_val} and #{right_col_name} >= #{right_col_val} ",:order=>"#{left_col_name}"
+end
+
+# self_and_ancestors with self removed
+def ancestors
+ self_and_ancestors.reject{|r| r == self}
+end
+
+# find all children at any depth with lft=rgt
+def leaf_nodes
+  self.class.find :all,:conditions => " #{left_col_name} >#{left_col_val} and #{right_col_name} < #{right_col_val} and #{left_col_name} = #{right_col_name}" 
+end
+
+# find the mid point of the gap this record fits in
+def mid_point
+   (furthrest_left+furthrest_right)/2
+end
+
+# if the record needs moving then save the old lft and rgt and set the current lft and rgt to nil
+def needs_moving!
+   if left_col_val && right_col_val && !in_tree
+    @prev_left = left_col_val
+    self.left_col_val = nil
+    @prev_right = right_col_val
+    self.right_col_val = nil
+   end  
+end 
+ 
+=begin  
+def scale_and_translate(move_to_origin,scale_by,translate_by)
+ self.lft = ((self.lft - move_to_origin)*scale_by) + translate_by
+ self.lft = ((self.lft - move_to_origin)*scale_by) + translate_by
+ children.each{|child| child.scale_and_translate(move_to_origin,scale_by,translate_by)}
+end
+=end
+
+private
+
+
+def furthrest_left
+   lft_gap.left_col_val 
+end
+
+def furthrest_right
+  rgt_gap.right_col_val 
+end 
+
+# this assumes a nicely ordered tree such that the next depth is always one more tha the existing depth
+# otherwise throw a wobbly
+# the strange .to_i has to be there because depth can come back from the db as a string
+def build_tree_by_recursion(parent,depth,ar_results)
+ while ar_results.size > 0 && ar_results.last.depth.to_i >= depth
+     if ar_results.last.depth.to_i == depth 
+        current_record = ar_results.pop
+       # puts "curr record in tree =#{current_record.in_tree} parent in tree = #{parent.in_tree}"
+        parent.children << current_record
+        current_record.in_tree = false
+      #  puts "+++"
+     elsif ar_results.last.depth.to_i == (depth + 1) 
+        current_record.in_tree = true
+        build_tree_by_recursion(current_record,ar_results.last.depth.to_i,ar_results)
+        current_record.in_tree = false
+     elsif ar_results.last.depth.to_i > (depth + 1)  
+       raise "badly formed nested set result set"          
+     end
+ end # while
+end # def build_tree_by_recursion(parent,depth,ar_results)
+    
+    
+    end #module InstanceMethods
+    end # module HausdorffSpace
+  end #module Acts 
+end#module MindoroMarine 

data/test/acts_as_hausdorff_space_test.rb

@@ -0,0 +1,183 @@
+require File.dirname(__FILE__) +'/test_helper'
+
+MindoroMarine::Acts::Tests.open_db(ENV['DB'])
+class ActsAsHausdorffSpaceTest < Test::Unit::TestCase
+  
+  def teardown
+  HausdorffSpaceTest.delete_all # irritating. I can't get user_transactional_fixtures = true to work outside the rails testing framework
+  end
+# check all the methods are mixed in  
+  should 'mixin methods' do
+    rns = HausdorffSpaceTest.new   
+    check_method_mixins(rns)
+    check_class_method_mixins(HausdorffSpaceTest)
+  end
+# add one and check that tear down removes it - hence the aa to keep them at the very front of all other tests  
+  should "aa add one " do
+    r = HausdorffSpaceTest.new(:name=>'top')
+    assert r.save
+    assert_equal r.left_col_val,r.right_col_val,'for a single record left should equal right'
+  end
+  
+  should 'aa check one' do
+    assert_equal 0, HausdorffSpaceTest.count, "the teardown didn't clear out the test table" 
+  end
+  
+  should 'set left and right cols' do
+    assert_equal('left_col',HausdorffSpaceTest.left_col_name,'class attribute left col not working')
+    assert_equal('right_col',HausdorffSpaceTest.right_col_name,'class attribute right col not working')
+  end
+  
+####### Test Class Methods #######
+context 'Class Methods - Add a Root' do
+   setup do
+   @hst = HausdorffSpaceTest.create(:name=>'top 1')
+   end
+   
+   should 'read root and virtual root' do
+       read_root = HausdorffSpaceTest.root
+       assert_equal @hst,HausdorffSpaceTest.root,'The first root should be the saved record' 
+       assert_equal(HausdorffSpaceTest.virtual_root, HausdorffSpaceTest.root.parent,'The virtual root should be the parent of a root node')
+       assert_not_nil read_root.right_col_val, 'read_root.rgt is nil'
+       assert_equal read_root.right_col_val, read_root.left_col_val, 'left != rgt'
+       assert_equal [],read_root.children, 'hs_children is not empty'
+   end 
+   
+   should 'allow other roots to be added' do
+       HausdorffSpaceTest.create(:name=>'top 2')
+       read_roots = HausdorffSpaceTest.roots
+       assert_equal(2,read_roots.size,'failed to get multiple roots')
+       assert_not_equal(read_roots[0].left_col_val,read_roots[1].left_col_val,'the roots have the same left col values')
+    end  
+ end # context
+# instance methods
+context 'Instance Methods - Add a Root' do
+   setup do
+   @hst = HausdorffSpaceTest.create(:name=>'top 1')
+   end
+   
+ context 'add one child to root' do
+   setup do
+    @sub_level = HausdorffSpaceTest.new(:name=>'child 1')
+    @hst.children << @sub_level 
+   end 
+   
+  should 'link parent and child' do
+    validate_parent_one_child_settings(@hst,@sub_level)
+    assert_equal @hst,@sub_level.my_root
+   end 
+   
+  should 'read parent and child back' do
+   full_tree = HausdorffSpaceTest.full_tree
+   validate_parent_one_child_settings(full_tree,full_tree.children[0])
+   assert_equal full_tree,full_tree.children[0].my_root
+   end   
+  end # context "add one child to root" 
+  
+  context 'add many children' do
+   setup do
+   (0..4).each{|n| @hst.children << HausdorffSpaceTest.new(:name=>"child #{n}")  }
+   end
+   
+   should 'have gaps between children' do
+    read_root = HausdorffSpaceTest.full_tree
+    (1..4).each do |n| 
+    assert read_root.children[n-1].right_col_val < read_root.children[n].left_col_val,' there should be a gap between each child' 
+    end
+   end
+   
+   should 'move a child to an child of another' do    
+    @hst.children.first.children << @hst.children.last 
+    read_root = HausdorffSpaceTest.full_tree
+    assert_equal 4,read_root.children.size,"the child didn't get moved"
+    assert_equal 1,read_root.children.first.children.size,"the child didn't appear in the right place"     
+   end
+  end # context 'add many children' 
+  
+  context 'add many grandchildren' do
+   setup do
+   (0..4).each do |n1|
+   new_child =  HausdorffSpaceTest.new(:name=>"child #{n1}")
+   @hst.children << new_child
+     (0..4).each do |n2| 
+     new_child.children << HausdorffSpaceTest.new(:name=>"grandchild #{n2} of child #{n1} ")
+     end
+   end
+   end # setup
+   
+   should 'count all leaf nodes ' do
+    assert_equal 25,@hst.leaf_nodes.size,'error counting leaf nodes'
+   end
+   
+   should 'move whole branches' do
+   @hst.children.first.children << @hst.children.last
+   read_root = HausdorffSpaceTest.full_tree
+   assert_equal 4,read_root.children.size
+   assert_equal 6,read_root.children.first.children.size
+   assert_equal 10,read_root.children.first.leaf_nodes.size 
+   end
+   
+   should 'get self and ancestors' do
+   saa = @hst.children.first.children.first.self_and_ancestors
+   assert_equal 3, saa.size, 'There should be three records'
+   assert_equal @hst,saa[0], 'The first ancestor should be the top level owner'
+   assert_equal @hst.children.first, saa[1],'The second ancestor should be child of the top level '
+   assert_equal @hst.children.first.children.first, saa[2],'The third ancestor should be this record'
+   end
+   
+   should 'get only ancestors' do
+   a = @hst.children.first.children.first.ancestors
+   assert_equal 2, a.size, 'There should be two records'
+   assert !a.include?(@hst.children.first.children.first),' this record should not be in the array'
+   end
+   
+   should 'get self and siblings' do
+   sas = @hst.children.first.children.first.self_and_siblings
+   assert_equal 5,sas.size, 'There should be five records in self and siblings'
+   sas.each do |rec|
+     assert_equal @hst.children.first,rec.parent,'each sibling must have the same parent'
+   end
+   end
+   
+   should 'get only siblings' do
+   s = @hst.children.first.children.first.siblings
+   assert_equal 4,s.size, 'There should be four records in siblings'
+   assert !s.include?(@hst.children.first.children.first),'This record should not be in the array of siblings'
+   end
+   
+  end # context 'add many grandchildren' do
+  
+end # context  'Instance Methods - Add a Root'    
+private ############################ PRIVATE ##########################################  
+ def check_method_mixins(obj)
+   [:build_full_tree,
+    :before_save,
+    :siblings,
+    :left_col_val,
+    :right_col_val].each{|symbol| assert(obj.respond_to?(symbol),"instance method #{symbol} is missing")}
+  end
+  
+  def check_class_method_mixins(klass)
+    [:root, 
+     :roots,
+     :left_col_name,
+     :right_col_name,
+     :full_tree,
+     :virtual_root].each do |symbol|
+    assert(klass.respond_to?(symbol),"class method #{symbol} is missing")
+    end   
+  end
+  
+ def validate_parent_one_child_settings(parent,child)
+   assert_equal parent,child.parent,'the sublevel should have a parent'
+   assert_equal child,parent.children[0], 'the parent should own the child'
+   assert_not_equal parent.left_col_val,child.left_col_val, 'there should be a gap between the parent left and the child left'
+   assert_not_equal parent.right_col_val,child.right_col_val, 'there should be a gap between the parent right and the child right '
+   assert parent.left_col_val < child.left_col_val,' the parent left should be less that the child left'
+   assert parent.right_col_val > child.right_col_val, ' the parent right should be more that the child right'
+   assert_equal parent.left_col_val,child.lft_gap.left_col_val,'the parent left should be the left of the childs left gap'
+   assert_equal child.left_col_val,child.lft_gap.right_col_val,'the child left should be the right of the child left gap'
+   assert_equal parent.right_col_val,child.rgt_gap.right_col_val,'the parent right should be the right of the child right gap'
+   assert_equal child.right_col_val,child.rgt_gap.left_col_val,' the child right should the the left of the child right gap'
+ end
+end

data/test/database.yml

@@ -0,0 +1,15 @@
+mysql:
+  :adapter: mysql
+  :host: localhost
+  :username: gem_test
+  :password: gem_test_password
+  :database: gem_test
+postgresql:
+  :adapter: postgresql
+  :host: localhost
+  :username: gem_test
+  :password: gem_test_password
+  :database: gem_test
+sqlite3:
+  :adapter: sqlite3
+  :dbfile: test/acts_as_hausdorff_space_gem_test.db

data/test/mysql.rb

@@ -0,0 +1,3 @@
+ENV['DB'] = 'mysql'
+require File.dirname(__FILE__) + '/acts_as_hausdorff_space_test'
+

data/test/postgresql.rb

@@ -0,0 +1,2 @@
+ENV['DB'] = 'postgresql'
+require File.dirname(__FILE__) + '//acts_as_hausdorff_space_test'

data/test/schema.rb

@@ -0,0 +1,12 @@
+ActiveRecord::Schema.define(:version => 0) do
+
+  create_table "hausdorff_space_tests", :force => true do |t|
+    t.string   "name"
+    t.decimal  "left_col",        :precision => 63, :scale => 30
+    t.decimal  "right_col",        :precision => 63, :scale => 30
+  end
+
+  add_index "hausdorff_space_tests", ["left_col"], :name => "lft_idx"
+  add_index "hausdorff_space_tests", ["right_col"], :name => "rgt_idx"
+
+end

data/test/sqlite3.rb

@@ -0,0 +1,2 @@
+ENV['DB'] = 'sqlite3'
+require File.dirname(__FILE__) + '/acts_as_hausdorff_space_test'

data/test/test_helper.rb

@@ -0,0 +1,29 @@
+ENV["RAILS_ENV"] = "test"
+require 'rubygems'
+require 'activerecord'
+require 'acts-as-hausdorff-space'
+require 'test/unit'
+require 'shoulda'
+
+class HausdorffSpaceTest < ActiveRecord::Base
+acts_as_hausdorff_space :left_column=>'left_col',:right_column=>'right_col'
+end
+
+
+#class Test::Unit::TestCase
+# use_transactional_fixtures = true
+#end
+
+module MindoroMarine
+  module Acts
+    module Tests
+     def self.open_db(db_name='sqlite3')
+     config = YAML::load(IO.read(File.dirname(__FILE__) + '/database.yml'))
+     ActiveRecord::Base.logger = Logger.new(File.dirname(__FILE__) + '/debug.log')
+     cs = ActiveRecord::Base.establish_connection(config[db_name])
+     puts "Using #{cs.connection.class.to_s} adapter" 
+     load(File.dirname(__FILE__) + '/schema.rb')
+     end
+    end
+  end
+end

metadata

@@ -0,0 +1,71 @@
+--- !ruby/object:Gem::Specification 
+name: JohnSmall-acts-as-hausdorff-space
+version: !ruby/object:Gem::Version 
+  version: 0.1.3
+platform: ruby
+authors: 
+- John Small
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-04-25 00:00:00 -07:00
+default_executable: 
+dependencies: []
+
+description: 
+email: jds340@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- LICENSE
+- README.rdoc
+files: 
+- LICENSE
+- README.rdoc
+- Rakefile
+- VERSION.yml
+- lib/acts-as-hausdorff-space.rb
+- lib/acts_as_hausdorff_space.rb
+- test/acts_as_hausdorff_space_test.rb
+- test/database.yml
+- test/mysql.rb
+- test/postgresql.rb
+- test/schema.rb
+- test/sqlite3.rb
+- test/test_helper.rb
+has_rdoc: true
+homepage: http://github.com/JohnSmall/acts-as-hausdorff-space
+post_install_message: 
+rdoc_options: 
+- --charset=UTF-8
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.2.0
+signing_key: 
+specification_version: 2
+summary: Use real numbers instead of integers for nested sets because real numbers are a Hausdorff space
+test_files: 
+- test/schema.rb
+- test/sqlite3.rb
+- test/mysql.rb
+- test/test_helper.rb
+- test/acts_as_hausdorff_space_test.rb
+- test/postgresql.rb