acts_as_nested_interval 0.0.1

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2012 YOURNAME
+
+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.md

@@ -0,0 +1,171 @@
+# ActsAsNestedInterval
+
+## About
+
+* Pythonic's acts_as_nested_interval updated to Rails 3 and gemified.
+* This: https://github.com/clyfe/acts_as_nested_interval
+* Original: https://github.com/pythonic/acts_as_nested_interval
+* Acknowledgement: http://arxiv.org/html/cs.DB/0401014 by Vadim Tropashko.
+
+This act implements a nested-interval tree. You can find all descendants or all
+ancestors with just one select query. You can insert and delete records without
+a full table update.
+
+## Install
+
+```ruby
+# add to Gemfile
+gem 'acts_as_nested_interval'
+```
+
+```sh
+# install
+bundle install
+```
+
+* requires a `parent_id` foreign key column, and `lftp` and `lftq` integer columns.
+* if your database does not support stored procedures then you also need `rgtp` and `rgtq` integer columns
+* if your database does not support functional indexes then you also need a `rgt` float column
+* the `lft` float column is optional
+
+Example:
+
+```ruby
+create_table :regions do |t|
+  t.integer :parent_id
+  t.integer :lftp, :null => false
+  t.integer :lftq, :null => false
+  t.integer :rgtp, :null => false
+  t.integer :rgtq, :null => false
+  t.float :lft, :null => false
+  t.float :rgt, :null => false
+  t.string :name, :null => false
+end
+add_index :regions, :parent_id
+add_index :regions, :lftp
+add_index :regions, :lftq
+add_index :regions, :lft
+add_index :regions, :rgt
+```
+
+## Usage
+
+The size of the tree is limited by the precision of the integer and floating
+point data types in the database.
+
+This act provides these named scopes:
+
+```ruby
+Region.roots    # returns roots of tree.
+Region.preorder # returns records for preorder traversal.
+```
+
+This act provides these instance methods:
+
+```ruby
+Region.parent      # returns parent of record.
+Region.children    # returns children of record.
+Region.ancestors   # returns scoped ancestors of record.
+Region.descendants # returns scoped descendants of record.
+Region.depth       # returns depth of record.
+```
+
+Example:
+
+```ruby
+class Region < ActiveRecord::Base
+  acts_as_nested_interval
+end
+
+earth = Region.create :name => "Earth"
+oceania = Region.create :name => "Oceania", :parent => earth
+australia = Region.create :name => "Australia", :parent => oceania
+new_zealand = Region.new :name => "New Zealand"
+oceania.children << new_zealand
+earth.descendants      # => [oceania, australia, new_zealand]
+earth.children         # => [oceania]
+oceania.children       # => [australia, new_zealand]
+oceania.depth          # => 1
+australia.parent       # => oceania
+new_zealand.ancestors  # => [earth, oceania]
+Region.roots           # => [earth]
+```
+
+## How it works
+
+The `mediant` of two rationals is the rational with the sum of the two
+numerators for the numerator, and the sum of the two denominators for the
+denominator (where the denominators are positive). The mediant is numerically
+between the two rationals.
+Example: `3 / 5` is the mediant of `1 / 2` and `2 / 3`, and `1 / 2 < 3 / 5 < 2 / 3`.
+
+Each record `covers` a half-open interval `(lftp / lftq, rgtp / rgtq]`. The tree
+root covers `(0 / 1, 1 / 1]`. The first child of a record covers interval
+`(mediant{lftp / lftq, rgtp / rgtq}, rgtp / rgtq]`; the next child covers the interval
+`(mediant{lftp / lftq, mediant{lftp / lftq, rgtp / rgtq}}, mediant{lftp / lftq, rgtp / rgtq}]`.
+
+With this construction each lftp and lftq are relatively prime and the identity
+`lftq * rgtp = 1 + lftp * rgtq holds`.
+
+Example:
+
+                 0/1                           1/2   3/5 2/3                 1/1
+    earth         (-----------------------------------------------------------]
+    oceania                                     (-----------------------------]
+    australia                                             (-------------------]
+    new zealand                                       (---]
+
+The descendants of a record are those records that cover subintervals of the
+interval covered by the record, and the ancestors are those records that cover
+superintervals.
+
+Only the left end of an interval needs to be stored, since the right end can be
+calculated (with special exceptions) using the above identity:
+
+    rgtp := x
+    rgtq := (x * lftq - 1) / lftp
+
+where x is the inverse of lftq modulo lftp.
+
+Similarly, the left end of the interval covered by the parent of a record can
+be calculated using the above identity:
+
+    lftp := (x * lftp - 1) / lftq
+    lftq := x
+
+where x is the inverse of lftp modulo lftq.
+
+## Moving nodes
+
+To move a record from old.lftp, old.lftq to new.lftp, new.lftq, apply this
+linear transform to lftp, lftq of all descendants:
+
+    lftp := (old.lftq * new.rgtp - old.rgtq * new.lftp) * lftp
+             + (old.rgtp * new.lftp - old.lftp * new.rgtp) * lftq
+    lftq := (old.lftq * new.rgtq - old.rgtq * new.lftq) * lftp
+             + (old.rgtp * new.lftq - old.lftp * new.rgtq) * lftq
+
+You should acquire a table lock before moving a record.
+
+Example:
+
+```ruby
+pacific = Region.create :name => "Pacific", :parent => earth
+oceania.parent = pacific
+oceania.save!
+```
+
+## Migrating from acts_as_tree
+
+If you come from acts_as_tree or another system where you only have a parent_id,
+to rebuild the intervals based on `acts_as_nested_set`, after you migrated the DB
+and created the columns required by `acts_as_nested_set` run:
+
+```ruby
+Region.rebuild_nested_interval_tree!
+```
+
+NOTE! About `rebuild_nested_interval_tree!`:
+* zeroes all your tree intervals before recomputing them!
+* does a lot of N+1 queries of type `record.parent` and not only.
+  This might change once the AR identity_map is finished.

data/Rakefile

@@ -0,0 +1,38 @@
+#!/usr/bin/env rake
+begin
+  require 'bundler/setup'
+rescue LoadError
+  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+end
+begin
+  require 'rdoc/task'
+rescue LoadError
+  require 'rdoc/rdoc'
+  require 'rake/rdoctask'
+  RDoc::Task = Rake::RDocTask
+end
+
+RDoc::Task.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'ActsAsNestedInterval'
+  rdoc.options << '--line-numbers'
+  rdoc.rdoc_files.include('README.rdoc')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+
+
+
+Bundler::GemHelper.install_tasks
+
+require 'rake/testtask'
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib'
+  t.libs << 'test'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = false
+end
+
+
+task :default => :test

data/lib/acts_as_nested_interval/core_ext/integer.rb

@@ -0,0 +1,21 @@
+# Copyright (c) 2007, 2008 Pythonic Pty Ltd
+# http://www.pythonic.com.au/
+
+class Integer
+  # Returns modular multiplicative inverse.
+  # Examples:
+  #   2.inverse(7) # => 4
+  #   4.inverse(7) # => 2
+  def inverse(m)
+    u, v = m, self
+    x, y = 0, 1
+    while v != 0
+      q, r = u.divmod(v)
+      x, y = y, x - q * y
+      u, v = v, r
+    end
+    if u.abs == 1
+      x < 0 ? x + m : x
+    end
+  end
+end

data/lib/acts_as_nested_interval/version.rb

@@ -0,0 +1,3 @@
+module ActsAsNestedInterval
+  VERSION = "0.0.1"
+end

data/lib/acts_as_nested_interval.rb

@@ -0,0 +1,293 @@
+# Copyright (c) 2007, 2008 Pythonic Pty Ltd
+# http://www.pythonic.com.au/
+
+# Copyright (c) 2012 Nicolae Claudius
+# https://github.com/clyfe
+
+require 'acts_as_nested_interval/version'
+require 'acts_as_nested_interval/core_ext/integer'
+
+module ActsAsNestedInterval  
+  extend ActiveSupport::Concern
+
+  # This act implements a nested-interval tree. You can find all descendants
+  # or all ancestors with just one select query. You can insert and delete
+  # records without a full table update.
+  module ClassMethods
+  
+    # The +options+ hash can include:
+    # * <tt>:foreign_key</tt> -- the self-reference foreign key column name (default :parent_id).
+    # * <tt>:scope_columns</tt> -- an array of columns to scope independent trees.
+    # * <tt>:lft_index</tt> -- whether to use functional index for lft (default false).
+    # * <tt>:virtual_root</tt> -- whether to compute root's interval as in an upper root (default false)
+    def acts_as_nested_interval(options = {})
+      cattr_accessor :nested_interval_foreign_key
+      cattr_accessor :nested_interval_scope_columns
+      cattr_accessor :nested_interval_lft_index
+      
+      cattr_accessor :virtual_root
+      self.virtual_root = !!options[:virtual_root]
+      
+      self.nested_interval_foreign_key = options[:foreign_key] || :parent_id
+      self.nested_interval_scope_columns = Array(options[:scope_columns])
+      self.nested_interval_lft_index = options[:lft_index]
+      
+      belongs_to :parent, :class_name => name, :foreign_key => nested_interval_foreign_key
+      has_many :children, :class_name => name, :foreign_key => nested_interval_foreign_key, :dependent => :destroy
+      scope :roots, where(nested_interval_foreign_key => nil)
+      
+      if columns_hash["rgt"]
+        scope :preorder, order('rgt DESC, lftp ASC')
+      elsif columns_hash["rgtp"] && columns_hash["rgtq"]
+        scope :preorder, order('1.0 * rgtp / rgtq DESC, lftp ASC')
+      else
+        scope :preorder, order('nested_interval_rgt(lftp, lftq) DESC, lftp ASC')
+      end
+
+      class_eval do
+        include ActsAsNestedInterval::NodeInstanceMethods
+
+        # TODO make into before filters
+        before_create :create_nested_interval
+        before_destroy :destroy_nested_interval
+        before_update :update_nested_interval
+
+        if columns_hash["lft"]
+          def descendants
+            quoted_table_name = self.class.quoted_table_name
+            nested_interval_scope.where <<-SQL
+              #{lftp} < #{quoted_table_name}.lftp AND 
+              #{quoted_table_name}.lft BETWEEN #{1.0 * lftp / lftq} AND #{1.0 * rgtp / rgtq}
+            SQL
+          end
+        elsif nested_interval_lft_index
+          def descendants
+            quoted_table_name = self.class.quoted_table_name
+            nested_interval_scope.where <<-SQL
+              #{lftp} < #{quoted_table_name}.lftp AND 
+              1.0 * #{quoted_table_name}.lftp / #{quoted_table_name}.lftq BETWEEN 
+                #{1.0 * lftp / lftq} AND
+                #{1.0 * rgtp / rgtq}
+            SQL
+          end
+        elsif connection.adapter_name == "MySQL"
+          def descendants
+            quoted_table_name = self.class.quoted_table_name
+            nested_interval_scope.where <<-SQL
+              ( #{quoted_table_name}.lftp != #{rgtp} OR 
+                #{quoted_table_name}.lftq != #{rgtq}
+              ) AND
+              #{quoted_table_name}.lftp BETWEEN 
+                1 + #{quoted_table_name}.lftq * #{lftp} DIV #{lftq} AND 
+                #{quoted_table_name}.lftq * #{rgtp} DIV #{rgtq}
+            SQL
+          end
+        else
+          def descendants
+            quoted_table_name = self.class.quoted_table_name
+            nested_interval_scope.where <<-SQL
+              ( #{quoted_table_name}.lftp != #{rgtp} OR
+                #{quoted_table_name}.lftq != #{rgtq}
+              ) AND
+              #{quoted_table_name}.lftp BETWEEN
+                1 + #{quoted_table_name}.lftq * CAST(#{lftp} AS BIGINT) / #{lftq} AND
+                #{quoted_table_name}.lftq * CAST(#{rgtp} AS BIGINT) / #{rgtq}
+            SQL
+          end
+        end
+        
+        def self.rebuild_nested_interval_tree!
+          skip_callback :update, :before, :update_nested_interval
+          skip_callback :update, :before, :sync_childre
+          scope :roots, where(nested_interval_foreign_key => nil).where("#{quoted_table_name}.lftq > 0")
+          update_all(:lftp => 0, :lftq => 0)
+          update_all(:rgtp => 0) if columns_hash["rgtp"]
+          update_all(:rgtq => 0) if columns_hash["rgtq"]
+          update_all(:lft => 0) if columns_hash["lft"]
+          update_all(:rgt => 0) if columns_hash["rgt"]
+          clear_cache!
+
+          scoped.find_each do |d|
+            begin
+              d.create_nested_interval
+              unless d.save
+                puts "WARNING #{d.name} did not save because #{d.errors.inspect}"
+              end
+            rescue => e
+              puts "WARNING #{d.name} exception because #{e.message}"
+              puts "WARNING lftq: #{d.lftq}, llftp: #{d.lftp}"
+            end
+          end
+
+          set_callback :update, :before, :update_nested_interval
+          set_callback :update, :before, :sync_childre
+          scope :roots, where(nested_interval_foreign_key => nil)
+        end
+        
+      end
+      
+    end
+  end
+
+  module NodeInstanceMethods
+    def set_nested_interval(lftp, lftq)
+      self.lftp, self.lftq = lftp, lftq
+      self.rgtp = rgtp if has_attribute?(:rgtp)
+      self.rgtq = rgtq if has_attribute?(:rgtq)
+      self.lft = lft if has_attribute?(:lft)
+      self.rgt = rgt if has_attribute?(:rgt)
+    end
+    
+    def set_nested_interval_for_top
+      if self.class.virtual_root
+        set_nested_interval *next_root_lft
+      else
+        set_nested_interval 0, 1
+      end
+    end
+
+    # Creates record.
+    def create_nested_interval
+      if read_attribute(nested_interval_foreign_key).nil?
+        set_nested_interval_for_top
+      else
+        set_nested_interval *parent.lock!.next_child_lft
+      end
+    end
+
+    # Destroys record.
+    def destroy_nested_interval
+      lock! rescue nil
+    end
+
+    def nested_interval_scope
+      conditions = {}
+      nested_interval_scope_columns.each do |column_name|
+        conditions[column_name] = send(column_name)
+      end
+      self.class.where conditions
+    end
+
+    # Updates record, updating descendants if parent association updated,
+    # in which case caller should first acquire table lock.
+    def update_nested_interval
+      if read_attribute(nested_interval_foreign_key).nil?
+        set_nested_interval_for_top
+      elsif !association(:parent).updated?
+        db_self = self.class.find(id, :lock => true)
+        write_attribute(nested_interval_foreign_key, db_self.read_attribute(nested_interval_foreign_key))
+        set_nested_interval db_self.lftp, db_self.lftq
+      else # move
+        # No locking in this case -- caller should have acquired table lock.
+        update_nested_interval_move
+      end
+    end
+    
+    def update_nested_interval_move
+      db_self = self.class.find(id)
+      db_parent = self.class.find(read_attribute(nested_interval_foreign_key))
+      if db_self.ancestor_of?(db_parent)
+        errors.add nested_interval_foreign_key, "is descendant"
+        raise ActiveRecord::RecordInvalid, self
+      end
+      
+      set_nested_interval *parent.next_child_lft
+      mysql_tmp = "@" if ["MySQL", "Mysql2"].include?(connection.adapter_name)
+      cpp = db_self.lftq * rgtp - db_self.rgtq * lftp
+      cpq = db_self.rgtp * lftp - db_self.lftp * rgtp
+      cqp = db_self.lftq * rgtq - db_self.rgtq * lftq
+      cqq = db_self.rgtp * lftq - db_self.lftp * rgtq
+      
+      db_descendants = db_self.descendants
+      
+      if has_attribute?(:rgtp) && has_attribute?(:rgtq)
+        db_descendants.update_all %(
+          rgtp = #{cpp} * rgtp + #{cpq} * rgtq,
+          rgtq = #{cqp} * #{mysql_tmp}rgtp + #{cqq} * rgtq
+        ), mysql_tmp && %(@rgtp := rgtp)
+        db_descendants.update_all "rgt = 1.0 * rgtp / rgtq" if has_attribute?(:rgt)
+      end
+      
+      db_descendants.update_all %(
+        lftp = #{cpp} * lftp + #{cpq} * lftq,
+        lftq = #{cqp} * #{mysql_tmp}lftp + #{cqq} * lftq
+      ), mysql_tmp && %(@lftp := lftp)
+      
+      db_descendants.update_all %(lft = 1.0 * lftp / lftq) if has_attribute?(:lft)
+    end
+    
+    def ancestor_of?(node)
+      node.lftp == lftp && node.lftq == lftq ||
+        node.lftp > node.lftq * lftp / lftq &&
+        node.lftp <= node.lftq * rgtp / rgtq &&
+        (node.lftp != rgtp || node.lftq != rgtq)
+    end
+
+    def ancestors
+      sqls = ["NULL"]
+      p, q = lftp, lftq
+      while p != 0
+        x = p.inverse(q)
+        p, q = (x * p - 1) / q, x
+        sqls << "lftq = #{q} AND lftp = #{p}"
+      end
+      nested_interval_scope.where(sqls * ' OR ')
+    end
+
+    # Returns depth by counting ancestors up to 0 / 1.
+    def depth
+      n = 0
+      p, q = lftp, lftq
+      while p != 0
+        x = p.inverse(q)
+        p, q = (x * p - 1) / q, x
+        n += 1
+      end
+      n
+    end
+
+    def lft; 1.0 * lftp / lftq end
+    def rgt; 1.0 * rgtp / rgtq end
+
+    # Returns numerator of right end of interval.
+    def rgtp
+      case lftp
+      when 0 then 1
+      when 1 then 1
+      else lftq.inverse(lftp)
+      end
+    end
+
+    # Returns denominator of right end of interval.
+    def rgtq
+      case lftp
+      when 0 then 1
+      when 1 then lftq - 1
+      else (lftq.inverse(lftp) * lftq - 1) / lftp
+      end
+    end
+
+    # Returns left end of interval for next child.
+    def next_child_lft
+      if child = children.order('lftq DESC').first
+        return lftp + child.lftp, lftq + child.lftq
+      else
+        return lftp + rgtp, lftq + rgtq
+      end
+    end
+    
+    # Returns left end of interval for next root.
+    def next_root_lft
+      vr = self.class.new # a virtual root
+      vr.set_nested_interval 0, 1
+      if child = nested_interval_scope.roots.order('lftq DESC').first
+        return vr.lftp + child.lftp, vr.lftq + child.lftq
+      else
+        return vr.lftp + vr.rgtp, vr.lftq + vr.rgtq
+      end
+    end
+  end
+end
+
+ActiveRecord::Base.send :include, ActsAsNestedInterval
+

data/lib/tasks/acts_as_nested_interval_tasks.rake

@@ -0,0 +1,4 @@
+# desc "Explaining what the task does"
+# task :acts_as_nested_interval do
+#   # Task goes here
+# end