jnicklas-eb_nested_set 0.3.2 → 0.3.5

data/README.md

@@ -2,6 +2,30 @@
 
 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:
@@ -38,4 +62,12 @@ EvenBetterNestedSet will not automatically cache children for you, because it as
     
 or more conveniently:
 
-    d = Directory.find_with_nested_set(42)
+    d = Directory.find_with_nested_set(42)
+
+## I18n
+
+Add these keys to your translation file:
+
+    even_better_nested_set:
+      parent_not_in_scope: "nay, thy parent not be in scope {{scope_name}}"
+      illegal_nesting: "arr tis be illegal nesting"

data/Rakefile

@@ -3,9 +3,10 @@ require 'rake/gempackagetask'
 require 'rubygems/specification'
 require 'date'
 require 'spec/rake/spectask'
+require 'yard'
 
 GEM = "eb_nested_set"
-GEM_VERSION = "0.3.2"
+GEM_VERSION = "0.3.5"
 AUTHOR = "Jonas Nicklas"
 EMAIL = "jonas.nicklas@gmail.com"
 HOMEPAGE = "http://github.com/jnicklas/even_better_nested_set/tree/master"
@@ -27,6 +28,10 @@ spec = Gem::Specification.new do |s|
   s.files = %w(LICENSE README.md Rakefile init.rb) + Dir.glob("{lib,spec}/**/*")
 end
 
+YARD::Rake::YardocTask.new do |t|
+  t.files   = ["README.md", "LICENSE", "TODO", 'lib/**/*.rb']
+end
+
 Rake::GemPackageTask.new(spec) do |pkg|
   pkg.gem_spec = spec
 end

data/lib/eb_nested_set.rb

@@ -1,13 +1,57 @@
 module EvenBetterNestedSet
   
-  def self.included(base)
-    super
-    base.extend ClassMethods
-  end
-  
   class NestedSetError < StandardError; end
   class IllegalAssignmentError < NestedSetError; end
-  
+
+  ##
+  # Declare this model as a nested set. Automatically adds all methods in +NestedSet+ to the model, as
+  # well as parent and children associations.
+  #
+  # == Options
+  # left [Symbol]:: the name of the column that contains the left boundary [Defaults to +left+]
+  # right [Symbol]:: the name of the column that contains the right boundary [Defaults to +right+]
+  # scope [Symbol]:: the name of an association to scope this nested set to
+  #
+  # @param [Hash] options a set of options
+  #
+  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 :children, :class_name => self.name, :foreign_key => :parent_id, :order => "#{nested_set_column(:left)} asc"
+    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
+
   module NestedSet
     
     def self.included(base)
@@ -19,10 +63,20 @@ module EvenBetterNestedSet
       
       attr_accessor :nested_set_options
       
+      ##
+      # Finds the last root, used internally to find the point to insert new roots
+      #
+      # @return [ActiveRecord::Base] the last root node
+      #
       def find_last_root
         find(:first, :order => "#{nested_set_column(:right)} DESC", :conditions => { :parent_id => nil })
       end
 
+      ##
+      # Finds the left and right boundaries of a node given an id.
+      #
+      # @return [Array[Integer]] left and right boundaries
+      #
       def find_boundaries(id)
         query = "SELECT #{nested_set_column(:left)}, #{nested_set_column(:right)}" +
                 "FROM #{quote_db_property(table_name)}" +
@@ -30,10 +84,21 @@ module EvenBetterNestedSet
         connection.select_rows(query).first
       end
 
+      ##
+      # Returns all nodes with children cached to a nested set
+      #
+      # @return [Array[ActiveRecord::Base]] an array of root nodes with cached children
+      #
       def nested_set
         sort_nodes_to_nested_set(find(:all, :order => "#{nested_set_column(:left)} ASC"))
       end
       
+      ##
+      # Finds all nodes matching the criteria provided, and caches their descendants
+      #
+      # @param [Object] *args same parameters as ordinary find calls
+      # @return [Array[ActiveRecord::Base], ActiveRecord::Base] the found nodes
+      #
       def find_with_nested_set(*args)
         result = find(*args)
         if result.respond_to?(:cache_nested_set)
@@ -46,6 +111,12 @@ module EvenBetterNestedSet
         result
       end
 
+      ##
+      # Given a flat list of nodes, sorts them to a tree, caching descendants in the process
+      #
+      # @param [Array[ActiveRecord::Base]] nodes an array of nodes
+      # @return [Array[ActiveRecord::Base]] an array of nodes with children cached
+      #
       def sort_nodes_to_nested_set(nodes)
         roots = []
         hashmap = {}
@@ -69,11 +140,18 @@ module EvenBetterNestedSet
         return roots
       end
       
+      ##
+      # Returns the properly quoted column name given the generic term
+      #
+      # @param [Symbol] name the name of the column to find
+      # @return [String]
       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
@@ -83,29 +161,59 @@ module EvenBetterNestedSet
         end
       end
       
+      ##
+      # Properly quotes a column name
+      #
+      # @param [String] property
+      # @return [String] quoted property
+      #
       def quote_db_property(property)
         "`#{property}`".gsub('.','`.`')
       end
       
     end
     
+    ##
+    # Checks if this root is a root node
+    #
+    # @return [Boolean] whether this node is a root node or not
+    #
     def root?
       not parent_id?
     end
     
+    ##
+    # Checks if this node is a descendant of node
+    #
+    # @param [ActiveRecord::Base] node the node to check agains
+    # @return [Boolean] whether this node is a descendant
+    #
     def descendant_of?(node)
       node.left < self.left && self.right < node.right
     end
   
-    def root
-      transaction do
+    ##
+    # Finds the root node that this node descends from
+    #
+    # @param [Boolean] force_reload forces the root node to be reloaded
+    # @return [ActiveRecord::Base] node the root node this descends from
+    #
+    def root(force_reload=nil)
+      @root = nil if force_reload
+      @root ||= transaction do
         reload_boundaries
-        @root ||= base_class.roots.find(:first, :conditions => ["#{nested_set_column(:left)} <= ? AND #{nested_set_column(:right)} >= ?", left, right])
+        base_class.roots.find(:first, :conditions => ["#{nested_set_column(:left)} <= ? AND #{nested_set_column(:right)} >= ?", left, right])
       end
     end
     
     alias_method :patriarch, :root
     
+    ##
+    # Returns a list of ancestors this node belongs to
+    #
+    # @param [Boolean] force_reload forces the list to be reloaded
+    # @return [Array[ActiveRecord::Base]] a list of nodes that this node descends from
+    #
     def ancestors(force_reload=false)
       @ancestors = nil if force_reload
       @ancestors ||= base_class.find(
@@ -114,26 +222,55 @@ module EvenBetterNestedSet
       )
     end
     
+    ##
+    # Returns a list of the node itself and all of its ancestors
+    #
+    # @param [Boolean] force_reload forces the list to be reloaded
+    # @return [Array[ActiveRecord::Base]] a list of nodes that this node descends from
+    #
     def lineage(force_reload=false)
       [self, *ancestors(force_reload)]
     end
     
+    ##
+    # Returns all nodes that descend from the same root node as this node
+    #
+    # @return [Array[ActiveRecord::Base]]
+    #
     def kin
       patriarch.family
     end
     
+    ##
+    # Returns all nodes that descend from this node
+    #
+    # @return [Array[ActiveRecord::Base]]
+    #
     def descendants
       base_class.descendants(self)
     end
     
+    ##
+    # Caches the children of this node
+    #
     def cache_nested_set
       @cached_children || base_class.sort_nodes_to_nested_set(family)
     end
     
+    ##
+    # Returns the node and all nodes that descend from it.
+    #
+    # @return [Array[ActiveRecord::Base]]
+    #
     def family
       [self, *descendants]
     end
     
+    ##
+    # Returns the ids of the node and all nodes that descend from it.
+    #
+    # @return [Array[Integer]]
+    #
     def family_ids(force_reload=false)
       return @family_ids unless @family_ids.nil? or force_reload
       
@@ -146,14 +283,29 @@ module EvenBetterNestedSet
       end
     end
     
+    ##
+    # Returns all nodes that share the same parent as this node.
+    #
+    # @return [Array[ActiveRecord::Base]]
+    #
     def generation
       root? ? base_class.roots : parent.children
     end
     
+    ##
+    # Returns all nodes that are siblings of this node
+    #
+    # @return [Array[ActiveRecord::Base]]
+    #
     def siblings
       generation - [self]
     end
     
+    ##
+    # Returns how deeply this node is nested, that is how many ancestors it has.
+    #
+    # @return [Integer] the number of ancestors of this node.
+    #
     def level
       if root?
         0
@@ -164,36 +316,46 @@ module EvenBetterNestedSet
       end
     end
     
+    ##
+    # @return [Range] the left to the right boundary of this node
+    #
     def bounds
       left..right
     end
     
-    def children
-      @cached_children || uncached_children
+    ##
+    # @return [Integer] the left boundary of this node
+    #
+    def left
+      read_attribute(self.class.nested_set_options[:left])
     end
     
-    def children?
-      children.empty?
+    ##
+    # @return [Integer] the right boundary of this node
+    #
+    def right
+      read_attribute(self.class.nested_set_options[:right])
     end
     
+    ##
+    # Caches the node as this node's parent.
+    #
     def cache_parent(parent) #:nodoc:
       self.parent = parent
     end
     
+    ##
+    # Caches the nodes as this node's children.
+    #
     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])
+      children.target = @cached_children.push(*nodes)
     end
-    
-    def recalculate_nested_set(left)
+
+    ##
+    # Rebuild this node's childrens boundaries
+    #
+    def recalculate_nested_set(left) #:nodoc:
       child_left = left + 1
       children.each do |child|
         child_left = child.recalculate_nested_set(child_left)
@@ -208,7 +370,7 @@ module EvenBetterNestedSet
     
     def illegal_nesting
       if parent_id? and family_ids.include?(parent_id)
-        errors.add(:parent_id, 'cannot move node to its own descendant')
+        errors.add(:parent_id, I18n.t('even_better_nested_set.illegal_nesting', :default => 'cannot move node to its own descendant'))
       end
     end
     
@@ -293,57 +455,16 @@ module EvenBetterNestedSet
       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")
+          message = I18n.t('even_better_nested_set.parent_not_in_scope',
+            :default => "cannot be a record with a different {{scope_name}} to this record",
+            :scope_name => self.class.nested_set_options[:scope]
+          )
+          errors.add(:parent_id, message)
         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)
+ActiveRecord::Base.extend EvenBetterNestedSet if defined?(ActiveRecord)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: jnicklas-eb_nested_set
 version: !ruby/object:Gem::Version 
-  version: 0.3.2
+  version: 0.3.5
 platform: ruby
 authors: 
 - Jonas Nicklas
@@ -9,7 +9,7 @@ autorequire: eb_nested_set
 bindir: bin
 cert_chain: []
 
-date: 2009-02-15 00:00:00 -08:00
+date: 2009-02-16 00:00:00 -08:00
 default_executable: 
 dependencies: []