chrislloyd-eb_nested_set 0.3.2

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2008 Jonas Nicklas
+
+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,65 @@
+# EvenBetterNestedSet
+
+A nested set is a datastruture in a database, sort of like a tree, but unlike a tree it allows you to find all descendants of a node with a single query. Loading a deeply nested structure with nested sets is therefore a lot more efficient than using a tree. So what's the disadvantage? Nested sets are a lot harder to maintain, since inserting and moving records requires management and it is easy to corrupt the dataset. Enter: EvenBetterNestedSet. Amount of micromanaging you need to do: 0. EvenBetterNestedSet does it all for you.
+
+## Installation
+
+Stable:
+
+    [sudo] gem install eb_nested_set
+    
+Edge:
+
+    [sudo] gem install jnicklas-eb_nested_set --source http://gems.github.com
+
+From source:
+
+    git clone git://github.com/jnicklas/even_better_nested_set.git
+    cd even_better_nested_set
+    rake install
+
+If you're running Rails, just add it to your environment.rb file
+
+    config.gem 'eb_nested_set'
+
+You can also install it as a Rails plugin.
+
+    script/plugin install git://github.com/jnicklas/even_better_nested_set.git
+
+## Declaring nested sets
+
+This is how you declare a nested set:
+
+    class Directory < ActiveRecord::Base
+    
+      acts_as_nested_set
+    
+    end
+    
+The directories table should have the columns 'parent_id', 'left' and 'right'.
+
+Now just set the parent to wherever you want your node to be located and EvenBetterNestedSet will do the rest for you.
+    
+    d = Directory.new
+    
+    d.children.create!(:name => 'blah')
+    d.children.create!(:name => 'gurr')
+    d.children.create!(:name => 'doh')
+    
+    d.bounds #=> 1..8
+    d.children[1].bounds #=> 4..5
+    d.children[1].name #=> 'gurr'
+    d.children[1].parent #=> d
+    
+    c = Directory.create!(:name => 'test', :parent => d.directory[1]
+
+## Finding with nested sets
+
+EvenBetterNestedSet will not automatically cache children for you, because it assumes that this is not always the preferred behaviour. If you want to cache children to a nested set, just do:
+
+    d = Directory.find(42)
+    d.cache_nested_set
+    
+or more conveniently:
+
+    d = Directory.find_with_nested_set(42)

data/Rakefile

@@ -0,0 +1,87 @@
+require 'rubygems'
+require 'rake/gempackagetask'
+require 'rubygems/specification'
+require 'date'
+require 'spec/rake/spectask'
+
+GEM = "eb_nested_set"
+GEM_VERSION = "0.3.3"
+AUTHOR = "Jonas Nicklas"
+EMAIL = "jonas.nicklas@gmail.com"
+HOMEPAGE = "http://github.com/jnicklas/even_better_nested_set/tree/master"
+SUMMARY = "A cool acts_as_nested_set alternative"
+
+spec = Gem::Specification.new do |s|
+  s.name = GEM
+  s.version = GEM_VERSION
+  s.platform = Gem::Platform::RUBY
+  s.has_rdoc = true
+  s.extra_rdoc_files = ['README.md', 'LICENSE']
+  s.summary = SUMMARY
+  s.description = s.summary
+  s.author = AUTHOR
+  s.email = EMAIL
+  s.homepage = HOMEPAGE
+  s.require_path = 'lib'
+  s.autorequire = GEM
+  s.files = %w(LICENSE README.md Rakefile init.rb) + Dir.glob("{lib,spec}/**/*")
+end
+
+Rake::GemPackageTask.new(spec) do |pkg|
+  pkg.gem_spec = spec
+end
+
+desc "install the plugin locally"
+task :install => [:package] do
+  sh %{sudo gem install pkg/#{GEM}-#{GEM_VERSION} --no-update-sources}
+end
+
+desc "create a gemspec file"
+task :make_spec do
+  File.open("#{GEM}.gemspec", "w") do |file|
+    file.puts spec.to_ruby
+  end
+end
+
+namespace :jruby do
+
+  desc "Run :package and install the resulting .gem with jruby"
+  task :install => :package do
+    sh %{#{SUDO} jruby -S gem install pkg/#{GEM}-#{GEM_VERSION}.gem --no-rdoc --no-ri}
+  end
+  
+end
+
+spec_files = FileList['spec/*_spec.rb']
+
+desc 'Default: run unit tests.'
+task :default => 'spec'
+
+task :specs => :spec
+desc "Run all examples"
+Spec::Rake::SpecTask.new('spec') do |t|
+  t.spec_opts = ['--color']
+  t.spec_files = spec_files
+end
+
+namespace :spec do
+  desc "Run all examples with RCov"
+  Spec::Rake::SpecTask.new('rcov') do |t|
+    t.spec_files = spec_files
+    t.rcov = true
+    t.rcov_dir = "doc/coverage"
+    t.rcov_opts = ['--exclude', 'spec,rspec-*,rcov-*,gems']
+    t.spec_opts = ['--color']
+  end
+  
+  desc "Generate an html report"
+  Spec::Rake::SpecTask.new('report') do |t|
+    t.spec_files = spec_files
+    t.rcov = true
+    t.rcov_dir = "doc/coverage"
+    t.rcov_opts = ['--exclude', 'spec']
+    t.spec_opts = ['--color', "--format", "html:doc/reports/specs.html"]
+    t.fail_on_error = false
+  end
+
+end

data/init.rb

@@ -0,0 +1 @@
+require File.join(File.dirname(__FILE__), 'lib', 'even_better_nested_set')

data/lib/eb_nested_set.rb

@@ -0,0 +1,349 @@
+module EvenBetterNestedSet
+  
+  def self.included(base)
+    super
+    base.extend ClassMethods
+  end
+  
+  class NestedSetError < StandardError; end
+  class IllegalAssignmentError < NestedSetError; end
+  
+  module NestedSet
+    
+    def self.included(base)
+      super
+      base.extend ClassMethods
+    end
+    
+    module ClassMethods
+      
+      attr_accessor :nested_set_options
+      
+      def find_last_root
+        find(:first, :order => "#{nested_set_column(:right)} DESC", :conditions => { :parent_id => nil })
+      end
+
+      def find_boundaries(id)
+        query = "SELECT #{nested_set_column(:left)}, #{nested_set_column(:right)}" +
+                "FROM #{quote_db_property(table_name)}" +
+                "WHERE #{quote_db_property(primary_key)} = #{id}"
+        connection.select_rows(query).first
+      end
+
+      def nested_set
+        sort_nodes_to_nested_set(find(:all, :order => "#{nested_set_column(:left)} ASC"))
+      end
+      
+      def find_with_nested_set(*args)
+        result = find(*args)
+        if result.respond_to?(:cache_nested_set)
+          result.cache_nested_set
+        elsif result.respond_to?(:each)
+          result.each do |node|
+            node.cache_nested_set
+          end
+        end
+        result
+      end
+
+      def sort_nodes_to_nested_set(nodes)
+        roots = []
+        hashmap = {}
+        for node in nodes.sort_by { |n| n.left }
+          # if the parent is not in the hashmap, parent will be nil, therefore node will be a root node
+          # in that case
+          parent = node.parent_id ? hashmap[node.parent_id] : nil
+          
+          # make sure this is called at least once on every node, so leaves know that they have *no* children
+          node.cache_children()
+
+          if parent
+            node.cache_parent(parent)
+            parent.cache_children(node)
+          else
+            roots << node
+          end
+
+          hashmap[node.id] = node
+        end
+        return roots
+      end
+      
+      def nested_set_column(name)
+        quote_db_property(nested_set_options[name])
+      end
+      
+      # Recalculates the left and right values for the entire tree
+      def recalculate_nested_set
+        transaction do
+          left = 1
+          roots.each do |root|
+            left = root.recalculate_nested_set(left)
+          end
+        end
+      end
+      
+      def quote_db_property(property)
+        "`#{property}`".gsub('.','`.`')
+      end
+      
+    end
+    
+    def root?
+      not parent_id?
+    end
+    
+    def descendant_of?(node)
+      node.left < self.left && self.right < node.right
+    end
+  
+    def root
+      transaction do
+        reload_boundaries
+        @root ||= base_class.roots.find(:first, :conditions => ["#{nested_set_column(:left)} <= ? AND #{nested_set_column(:right)} >= ?", left, right])
+      end
+    end
+    
+    alias_method :patriarch, :root
+    
+    def ancestors(force_reload=false)
+      @ancestors = nil if force_reload
+      @ancestors ||= base_class.find(
+        :all,:conditions => ["#{nested_set_column(:left)} < ? AND #{nested_set_column(:right)} > ?", left, right],
+        :order => "#{nested_set_column(:left)} DESC"
+      )
+    end
+    
+    def lineage(force_reload=false)
+      [self, *ancestors(force_reload)]
+    end
+    
+    def kin
+      patriarch.family
+    end
+    
+    def descendants
+      base_class.descendants(self)
+    end
+    
+    def cache_nested_set
+      @cached_children || base_class.sort_nodes_to_nested_set(family)
+    end
+    
+    def family
+      [self, *descendants]
+    end
+    
+    def family_ids(force_reload=false)
+      return @family_ids unless @family_ids.nil? or force_reload
+      
+      transaction do
+        reload_boundaries
+        query = "SELECT id FROM #{self.class.quote_db_property(base_class.table_name)} " + 
+                "WHERE #{nested_set_column(:left)} >= #{left} AND #{nested_set_column(:right)} <= #{right} " +
+                "ORDER BY #{nested_set_column(:left)}"
+        @family_ids = base_class.connection.select_values(query).map(&:to_i)
+      end
+    end
+    
+    def generation
+      root? ? base_class.roots : parent.children
+    end
+    
+    def siblings
+      generation - [self]
+    end
+    
+    def level
+      if root?
+        0
+      elsif @ancestors
+        @ancestors.size
+      else
+        base_class.count :conditions => ["#{nested_set_column(:left)} < ? AND #{nested_set_column(:right)} > ?", left, right]
+      end
+    end
+    
+    def bounds
+      left..right
+    end
+    
+    def children
+      @cached_children || uncached_children
+    end
+    
+    def children?
+      children.empty?
+    end
+    
+    def cache_parent(parent) #:nodoc:
+      self.parent = parent
+    end
+    
+    def cache_children(*nodes) #:nodoc:
+      @cached_children ||= []
+      @cached_children.push(*nodes)
+    end
+    
+    def left
+      read_attribute(self.class.nested_set_options[:left])
+    end
+    
+    def right
+      read_attribute(self.class.nested_set_options[:right])
+    end
+    
+    def recalculate_nested_set(left)
+      child_left = left + 1
+      children.each do |child|
+        child_left = child.recalculate_nested_set(child_left)
+      end
+      set_boundaries(left, child_left)
+      save_without_validation!
+      
+      right + 1
+    end
+    
+    protected
+    
+    def illegal_nesting
+      if parent_id? and family_ids.include?(parent_id)
+        errors.add(:parent_id, 'cannot move node to its own descendant')
+      end
+    end
+    
+    def remove_node
+      base_class.delete_all ["#{nested_set_column(:left)} > ? AND #{nested_set_column(:right)} < ?", left, right] # TODO: Figure out what to do with children's destroy callbacks
+      
+      shift!(-node_width, right)
+    end
+    
+    def append_node
+      boundary = 1
+      
+      if parent_id?
+        transaction do
+          boundary = parent(true).right
+          shift! 2, boundary
+        end      
+      elsif last_root = base_class.find_last_root
+        boundary = last_root.right + 1
+      end
+      
+      set_boundaries(boundary, boundary + 1)
+    end
+    
+    def move_node
+      if parent_id_changed?
+        transaction do
+          reload_boundaries
+          
+          if parent_id.blank? # moved to root
+            shift_difference = base_class.find_last_root.right - left + 1
+          else # moved to non-root
+            new_parent = base_class.find_by_id(parent_id)
+
+            # open up a space
+            boundary = new_parent.right
+            shift! node_width, boundary
+            
+            reload_boundaries
+            
+            shift_difference = (new_parent.right - left)
+          end
+          # move itself and children into place
+          shift! shift_difference, left, right
+          
+          # close up the space that was left behind after move
+          shift! -node_width, left
+          
+          reload_boundaries
+        end
+      end
+    end
+    
+    def shift!(positions, left_boundary, right_boundary=nil)
+      if right_boundary
+        base_class.update_all "#{nested_set_column(:left)}  = (#{nested_set_column(:left)}  + #{positions})", ["#{nested_set_column(:left)}  >= ? AND #{nested_set_column(:left)}  <= ?", left_boundary, right_boundary]
+        base_class.update_all "#{nested_set_column(:right)} = (#{nested_set_column(:right)} + #{positions})", ["#{nested_set_column(:right)} >= ? AND #{nested_set_column(:right)} <= ?", left_boundary, right_boundary]
+      else
+        base_class.update_all "#{nested_set_column(:left)}  = (#{nested_set_column(:left)}  + #{positions})", ["#{nested_set_column(:left)} >= ?", left_boundary]
+        base_class.update_all "#{nested_set_column(:right)} = (#{nested_set_column(:right)} + #{positions})", ["#{nested_set_column(:right)} >= ?", left_boundary]
+      end
+    end
+    
+    def node_width
+      right - left + 1
+    end
+    
+    def set_boundaries(left, right)
+      write_attribute(self.class.nested_set_options[:left], left)
+      write_attribute(self.class.nested_set_options[:right], right)
+    end
+        
+    def reload_boundaries
+      set_boundaries(*base_class.find_boundaries(id))
+    end
+    
+    def base_class
+      self.class.base_class
+    end
+    
+    def validate_parent_is_within_scope
+      if self.class.nested_set_options[:scope] && parent_id
+        parent.reload # Make sure we are testing the record corresponding to the parent_id
+        if self.send(self.class.nested_set_options[:scope]) != parent.send(self.class.nested_set_options[:scope])
+          errors.add(:parent_id, "cannot be a record with a different #{self.class.nested_set_options[:scope]} to this record")
+        end
+      end
+    end
+  end
+  
+  module ClassMethods
+    
+    def acts_as_nested_set(options = {})
+      options = { :left => :left, :right => :right }.merge!(options)
+      options[:scope] = "#{options[:scope]}_id" if options[:scope]
+      
+      include NestedSet
+      
+      self.nested_set_options = options
+      
+      class_eval <<-RUBY, __FILE__, __LINE__+1
+        def #{options[:left]}=(left)
+          raise EvenBetterNestedSet::IllegalAssignmentError, "#{options[:left]} is an internal attribute used by EvenBetterNestedSet, do not assign it directly as is may corrupt the data in your database"
+        end
+
+        def #{options[:right]}=(right)
+          raise EvenBetterNestedSet::IllegalAssignmentError, "#{options[:right]} is an internal attribute used by EvenBetterNestedSet, do not assign it directly as is may corrupt the data in your database"
+        end
+      RUBY
+      
+      named_scope :roots, :conditions => { :parent_id => nil }, :order => "#{nested_set_column(:left)} asc"
+      
+      has_many :uncached_children, :class_name => self.name, :foreign_key => :parent_id, :order => "#{nested_set_column(:left)} asc"
+      protected :uncached_children, :uncached_children=
+      
+      belongs_to :parent, :class_name => self.name, :foreign_key => :parent_id
+      
+      named_scope :descendants, lambda { |node|
+        left, right = find_boundaries(node.id)
+        { :conditions => ["#{nested_set_column(:left)} > ? and #{nested_set_column(:right)} < ?", left, right],
+          :order => "#{nested_set_column(:left)} asc" }
+      }
+      
+      before_create :append_node
+      before_update :move_node
+      before_destroy :reload
+      after_destroy :remove_node
+      validate_on_update :illegal_nesting
+      validate :validate_parent_is_within_scope
+      
+      delegate :nested_set_column, :to => "self.class"
+    end
+    
+  end
+  
+end
+
+ActiveRecord::Base.send(:include, EvenBetterNestedSet) if defined?(ActiveRecord)