closure_tree 1.0.0 → 2.0.0.beta1

data/README.md

@@ -16,7 +16,7 @@ Note that closure_tree is being developed for Rails 3.1.0.rc1
 
 2.  Run ```bundle install```
 
-3.  Add ```acts_as_tree``` to your hierarchical model(s).
+3.  Add ```acts_as_tree``` to your hierarchical model(s) (see the <a href="#options">available options</a>).
 
 4.  Add a migration to add a ```parent_id``` column to the model you want to act_as_tree.
 
@@ -35,19 +35,19 @@ Note that closure_tree is being developed for Rails 3.1.0.rc1
     "_hierarchy". Note that by calling ```acts_as_tree```, a "virtual model" (in this case, ```TagsHierarchy```) will be added automatically, so you don't need to create it.
 
       ```ruby
-      class CreateTagHierarchy < ActiveRecord::Migration
+      class CreateTagHierarchies < ActiveRecord::Migration
         def change
-          create_table :tags_hierarchy, :id => false do |t|
+          create_table :tag_hierarchies, :id => false do |t|
             t.integer  :ancestor_id, :null => false   # ID of the parent/grandparent/great-grandparent/... tag
             t.integer  :descendant_id, :null => false # ID of the target tag
             t.integer  :generations, :null => false   # Number of generations between the ancestor and the descendant. Parent/child = 1, for example.
           end
 
           # For "all progeny of..." selects:
-          add_index :tags_hierarchy, [:ancestor_id, :descendant_id], :unique => true
+          add_index :tag_hierarchies, [:ancestor_id, :descendant_id], :unique => true
 
           # For "all ancestors of..." selects
-          add_index :tags_hierarchy, [:descendant_id]
+          add_index :tag_hierarchies, [:descendant_id]
         end
       end
       ```
@@ -106,6 +106,19 @@ You can ```find``` as well as ```find_or_create``` by "ancestry paths". Ancestry
 
 Note that the other columns will be null if nodes are created, other than auto-generated columns like ID and created_at timestamp. Only the specified column will receive the path element value.
 
+### Available options
+<a id="options" />
+
+When you include ```acts_as_tree``` in your model, you can provide a hash to override the following defaults:
+
+* ```:parent_column_name``` to override the column name of the parent foreign key in the model's table
+* ```:hierarchy_table_name``` to override the hierarchy table name. This defaults to the singular name of the model + "_hierarchies".
+* ```:name_column``` used by #```find_or_create_by_path```, #```find_by_path```, and ```ancestry_path``` instance methods. This is primarily useful if the model only has one required field (like a "tag").
+* ```:dependent``` determines what happens when a node is destroyed. Defaults to ```nil```.
+    * ```nil``` will simply set the parent column to null. Each child node will be considered a "root" node
+    * ```:delete_all``` will delete all descendant nodes (which circumvents the destroy hooks)
+    * ```:destroy``` will destroy all descendant nodes (which runs the destroy hooks on each child node)
+
 ## Accessing Data
 
 ### Class methods
@@ -121,15 +134,26 @@ Note that the other columns will be null if nodes are created, other than auto-g
 * ``` tag.child?``` returns true if this is a child node. It has a parent.
 * ``` tag.leaf?``` returns true if this is a leaf node. It has no children.
 * ``` tag.leaves``` returns an array of all the nodes in self_and_descendants that are leaves.
-* ``` tag.level``` returns the level, or "generation", for this node in the tree. A root node = 0
-* ``` tag.parent``` returns the node's immediate parent
-* ``` tag.children``` returns an array of immediate children (just those in the next level).
-* ``` tag.ancestors``` returns an array of all parents, parents' parents, etc, excluding self.
-* ``` tag.self_and_ancestors``` returns an array of all parents, parents' parents, etc, including self.
+* ``` tag.level``` returns the level, or "generation", for this node in the tree. A root node == 0.
+* ``` tag.parent``` returns the node's immediate parent. Root nodes will return nil.
+* ``` tag.children``` returns an array of immediate children (just those nodes whose parent is the current node).
+* ``` tag.ancestors``` returns an array of [ parent, grandparent, great grandparent, ... ]. Note that the size of this array will always equal ```tag.level```.
+* ``` tag.self_and_ancestors``` returns an array of self, parent, grandparent, great grandparent, etc.
 * ``` tag.siblings``` returns an array of brothers and sisters (all at that level), excluding self.
 * ``` tag.self_and_siblings``` returns an array of brothers and sisters (all at that level), including self.
 * ``` tag.descendants``` returns an array of all children, childrens' children, etc., excluding self.
 * ``` tag.self_and_descendants``` returns an array of all children, childrens' children, etc., including self.
+* ``` tag.reparent``` lets you move a node (and all it's children) to a new parent.
+* ``` tag.destroy``` will destroy a node as well as possibly all of its children. See the ```:dependent``` option passed to ```acts_as_tree```.
+
+## Changelog
+
+### 2.0.0.beta1
+
+* Had to increment the major version, as rebuild! will need to be called by prior consumers to support the new ```leaves``` class and instance methods.
+* Tag deletion is supported now along with ```:dependent => :destroy``` and ```:dependent => :delete_all```
+* Added new instance method ```reparent```
+* Switched from default rails plugin directory structure to rspec
 
 ## Thanks to
 

data/Rakefile

@@ -4,22 +4,14 @@ rescue LoadError
   puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
 end
 
-Bundler::GemHelper.install_tasks
-
 require 'yard'
-
 YARD::Rake::YardocTask.new do |t|
-t.files = ['lib/**/*.rb', 'README.md']
+  t.files = ['lib/**/*.rb', 'README.md']
 end
 
-require 'rake/testtask'
-
-Rake::TestTask.new(:test) do |t|
-  t.libs << 'lib'
-  t.libs << 'test'
-  t.pattern = 'test/**/*_test.rb'
-  t.verbose = false
-end
+Bundler::GemHelper.install_tasks
 
+require "rspec/core/rake_task"
+RSpec::Core::RakeTask.new(:spec)
 
-task :default => :test
+task :default => :spec

data/lib/closure_tree/acts_as_tree.rb

@@ -1,12 +1,12 @@
-module ClosureTree #:nodoc:
-  module ActsAsTree #:nodoc:
-    def acts_as_tree options = {}
+module ClosureTree
+  module ActsAsTree
+    def acts_as_tree(options = {})
 
       class_attribute :closure_tree_options
+
       self.closure_tree_options = {
         :parent_column_name => 'parent_id',
-        :dependent => :delete_all, # or :destroy
-        :hierarchy_table_suffix => '_hierarchies',
+        :dependent => :nullify, # or :destroy or :delete_all -- see the README
         :name_column => 'name'
       }.merge(options)
 
@@ -25,53 +25,55 @@ module ClosureTree #:nodoc:
 
       include ClosureTree::Model
 
-      belongs_to :parent, :class_name => base_class.to_s,
-                 :foreign_key => parent_column_name
+      before_destroy :acts_as_tree_before_destroy
+      before_save :acts_as_tree_before_save
+      after_save :acts_as_tree_after_save
+
+      belongs_to :parent,
+        :class_name => base_class.to_s,
+        :foreign_key => parent_column_name
 
       has_many :children,
-               :class_name => base_class.to_s,
-               :foreign_key => parent_column_name,
-               :before_add => :add_child
-
-      has_and_belongs_to_many :ancestors,
-                              :class_name => base_class.to_s,
-                              :join_table => hierarchy_table_name,
-                              :foreign_key => "descendant_id",
-                              :association_foreign_key => "ancestor_id",
-                              :order => "generations asc"
-
-      has_and_belongs_to_many :descendants,
-                              :class_name => base_class.to_s,
-                              :join_table => hierarchy_table_name,
-                              :foreign_key => "ancestor_id",
-                              :association_foreign_key => "descendant_id",
-                              :order => "generations asc"
+        :class_name => base_class.to_s,
+        :foreign_key => parent_column_name,
+        :dependent => closure_tree_options[:dependent]
+
+      has_and_belongs_to_many :self_and_ancestors,
+        :class_name => base_class.to_s,
+        :join_table => hierarchy_table_name,
+        :foreign_key => "descendant_id",
+        :association_foreign_key => "ancestor_id",
+        :order => "generations asc"
+
+      has_and_belongs_to_many :self_and_descendants,
+        :class_name => base_class.to_s,
+        :join_table => hierarchy_table_name,
+        :foreign_key => "ancestor_id",
+        :association_foreign_key => "descendant_id",
+        :order => "generations asc"
 
       scope :roots, where(parent_column_name => nil)
 
-      scope :leaves, includes(:descendants).where("#{hierarchy_table_name}.descendant_id is null")
+      scope :leaves, where(" #{quoted_table_name}.#{primary_key} IN
+        (SELECT ancestor_id
+         FROM #{quoted_hierarchy_table_name}
+         GROUP BY 1
+         HAVING MAX(generations) = 0)")
     end
   end
 
   module Model
     extend ActiveSupport::Concern
     module InstanceMethods
-      def parent_id
-        self[parent_column_name]
-      end
-
-      def parent_id= new_parent_id
-        self[parent_column_name] = new_parent_id
-      end
 
       # Returns true if this node has no parents.
       def root?
-        parent_id.nil?
+        parent.nil?
       end
 
-      # Returns self if +root?+ or the root ancestor
-      def root
-        root? ? self : ancestors.last
+      # Returns true if this node has a parent, and is not a root.
+      def child?
+        !parent.nil?
       end
 
       # Returns true if this node has no children.
@@ -79,81 +81,126 @@ module ClosureTree #:nodoc:
         children.empty?
       end
 
-      def leaves
-        return [self] if leaf?
-        Tag.leaves.includes(:ancestors).where("ancestors_tags.id = ?", self.id)
+      # Returns the farthest ancestor, or self if +root?+
+      def root
+        root? ? self : ancestors.last
       end
 
-      # Returns true if this node has a parent, and is not a root.
-      def child?
-        !parent_id.nil?
+      def leaves
+        return [self] if leaf?
+        self.class.leaves.where(<<-SQL
+#{quoted_table_name}.#{self.class.primary_key} IN (
+            SELECT descendant_id
+            FROM #{quoted_hierarchy_table_name}
+            WHERE ancestor_id = #{id})
+        SQL
+        )
       end
 
       def level
         ancestors.size
       end
 
-      def self_and_ancestors
-        [self].concat ancestors.to_a
+      def ancestors
+        without_self(self_and_ancestors)
       end
 
       # Returns an array, root first, of self_and_ancestors' values of the +to_s_column+, which defaults
       # to the +name_column+.
       # (so child.ancestry_path == +%w{grandparent parent child}+
-      def ancestry_path to_s_column = name_column
+      def ancestry_path(to_s_column = name_column)
         self_and_ancestors.reverse.collect { |n| n.send to_s_column.to_sym }
       end
 
-      def self_and_descendants
-        [self].concat descendants.to_a
+      def descendants
+        without_self(self_and_descendants)
       end
 
       def self_and_siblings
-        self.class.scoped.where(:parent_id => parent_id)
+        self.class.scoped.where(:parent => parent)
       end
 
       def siblings
         without_self(self_and_siblings)
       end
 
-      # You must use this method, or add child nodes to the +children+ association, to
-      # make the hierarchy table stay consistent.
-      def add_child child_node
-        child_node.update_attribute :parent_id, self.id
-        self_and_ancestors.inject(1) do |gen, ancestor|
-          hierarchy_class.create!(:ancestor => ancestor, :descendant => child_node, :generations => gen)
-          gen + 1
-        end
-        nil
-      end
-
-      def move_to_child_of new_parent
-        connection.execute <<-SQL
-          DELETE FROM #{quoted_hierarchy_table_name}
-          WHERE descendant_id = #{child_node.id}
-        SQL
-        new_parent.add_child self
+      # alias for appending to the children collect
+      def add_child(child_node)
+        children << child_node
+        child_node
       end
 
       # Find a child node whose +ancestry_path+ minus self.ancestry_path is +path+.
       # If the first argument is a symbol, it will be used as the column to search by
-      def find_by_path *path
-        _find_or_create_by_path "find", path
+      def find_by_path(*path)
+        foc_by_path("find", *path)
       end
 
       # Find a child node whose +ancestry_path+ minus self.ancestry_path is +path+
-      def find_or_create_by_path *path
-        _find_or_create_by_path "find_or_create", path
+      def find_or_create_by_path(*path)
+        foc_by_path("find_or_create", *path)
       end
 
       protected
 
-      def _find_or_create_by_path method_prefix, path
-        to_s_column = path.first.is_a?(Symbol) ? path.shift.to_s : name_column
-        path.flatten!
+      def acts_as_tree_before_save
+        @was_new_record = new_record?
+        if changes[parent_column_name] &&
+          parent.present? &&
+          parent.self_and_ancestors.include?(self)
+          # TODO: raise Ouroboros or Philip J. Fry error:
+          raise ActiveRecord::ActiveRecordError "You cannot add an ancestor as a descendant"
+        end
+      end
+
+      def acts_as_tree_after_save
+        rebuild! if changes[parent_column_name] || @was_new_record
+      end
+
+      def rebuild!
+        delete_hierarchy_references unless @was_new_record
+        hierarchy_class.create!(:ancestor => self, :descendant => self, :generations => 0)
+        unless root?
+          connection.execute <<-SQL
+            INSERT INTO #{quoted_hierarchy_table_name}
+              (ancestor_id, descendant_id, generations)
+            SELECT x.ancestor_id, #{id}, x.generations + 1
+            FROM #{quoted_hierarchy_table_name} x
+            WHERE x.descendant_id = #{self._parent_id}
+          SQL
+        end
+        children.each { |c| c.rebuild! }
+      end
+
+      def acts_as_tree_before_destroy
+        delete_hierarchy_references
+        if closure_tree_options[:dependent] == :nullify
+          children.each { |c| c.rebuild! }
+        end
+      end
+
+      def delete_hierarchy_references
+        # The crazy double-wrapped sub-subselect works around MySQL's limitation of subselects on the same table that is being mutated.
+        # It shouldn't affect performance of postgresql.
+        # See http://dev.mysql.com/doc/refman/5.0/en/subquery-errors.html
+        connection.execute <<-SQL
+          DELETE FROM #{quoted_hierarchy_table_name}
+          WHERE descendant_id IN (
+            SELECT DISTINCT descendant_id
+            FROM ( SELECT descendant_id
+              FROM #{quoted_hierarchy_table_name}
+              WHERE ancestor_id = #{id}
+            ) AS x )
+            OR descendant_id = #{id}
+        SQL
+      end
+
+      def foc_by_path(method_prefix, *path)
+        path = path.flatten
+        return self if path.empty?
         node = self
-        while (s = path.shift and node)
-          node = node.children.send("#{method_prefix}_by_#{to_s_column}".to_sym, s)
+        while (!path.empty? && node)
+          node = node.children.send("#{method_prefix}_by_#{name_column}", path.shift)
         end
         node
       end
@@ -162,9 +209,13 @@ module ClosureTree #:nodoc:
         scope.where(["#{quoted_table_name}.#{self.class.primary_key} != ?", self])
       end
 
+      def _parent_id
+        send(parent_column_name)
+      end
     end
 
     module ClassMethods
+
       # Returns an arbitrary node that has no parents.
       def root
         roots.first
@@ -173,42 +224,39 @@ module ClosureTree #:nodoc:
       # Rebuilds the hierarchy table based on the parent_id column in the database.
       # Note that the hierarchy table will be truncated.
       def rebuild!
-        connection.execute <<-SQL
-          DELETE FROM #{quoted_hierarchy_table_name}
-        SQL
-        roots.each { |n| rebuild_node_and_children n }
+        hierarchy_class.delete_all # not destroy_all -- we just want a simple truncate.
+        roots.each { |n| n.send(:rebuild!) } # roots just uses the parent_id column, so this is safe.
         nil
       end
 
       # Find the node whose +ancestry_path+ is +path+
-      # If the first argument is a symbol, it will be used as the column to search by
-      def find_by_path *path
-        to_s_column = path.first.is_a?(Symbol) ? path.shift.to_s : name_column
-        path.flatten!
-        self.where(to_s_column => path.last).each do |n|
-          return n if path == n.ancestry_path(to_s_column)
-        end
-        nil
+      def find_by_path(*path)
+        path = path.flatten
+        r = roots.send("find_by_#{name_column}", path.shift)
+        r.nil? ? nil : r.find_by_path(*path)
       end
 
       # Find or create nodes such that the +ancestry_path+ is +path+
-      def find_or_create_by_path *path
-        # short-circuit if we can:
-        n = find_by_path path
-        return n if n
-
-        column_sym = path.first.is_a?(Symbol) ? path.shift : name_sym
-        path.flatten!
-        s = path.shift
-        node = roots.where(column_sym => s).first
-        node = create!(column_sym => s) unless node
-        node.find_or_create_by_path column_sym, path
+      def find_or_create_by_path(*path)
+        path = path.flatten
+        root = roots.send("find_or_create_by_#{name_column}", path.shift)
+        root.find_or_create_by_path(*path)
       end
 
-      private
-      def rebuild_node_and_children node
-        node.parent.add_child node if node.parent
-        node.children.each { |child| rebuild_node_and_children child }
+      # From https://github.com/collectiveidea/awesome_nested_set:
+      def in_tenacious_transaction(&block)
+        retry_count = 0
+        begin
+          transaction(&block)
+        rescue ActiveRecord::StatementInvalid => error
+          raise unless connection.open_transactions.zero?
+          raise unless error.message =~ /Deadlock found when trying to get lock|Lock wait timeout exceeded/
+          raise unless retry_count < 10
+          retry_count += 1
+          logger.info "Deadlock detected on retry #{retry_count}, restarting transaction"
+          sleep(rand(retry_count)*0.2) # Aloha protocol
+          retry
+        end
       end
     end
   end
@@ -220,6 +268,10 @@ module ClosureTree #:nodoc:
       closure_tree_options[:parent_column_name]
     end
 
+    def parent_column_sym
+      parent_column_name.to_sym
+    end
+
     def has_name?
       ct_class.new.attributes.include? closure_tree_options[:name_column]
     end
@@ -233,7 +285,8 @@ module ClosureTree #:nodoc:
     end
 
     def hierarchy_table_name
-      ct_table_name + closure_tree_options[:hierarchy_table_suffix]
+      # We need to use the table_name, not ct_class.to_s.demodulize, because they may have overridden the table name
+      closure_tree_options[:hierarchy_table_name] || ct_table_name.singularize + "_hierarchies"
     end
 
     def hierarchy_class_name
@@ -244,10 +297,6 @@ module ClosureTree #:nodoc:
       connection.quote_column_name hierarchy_table_name
     end
 
-    def scope_column_names
-      Array closure_tree_options[:scope]
-    end
-
     def quoted_parent_column_name
       connection.quote_column_name parent_column_name
     end
@@ -263,6 +312,5 @@ module ClosureTree #:nodoc:
     def quoted_table_name
       connection.quote_column_name ct_table_name
     end
-
   end
 end