ancestry 1.0.0

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2009 Stefan Kroes
+
+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,151 @@
+= Ancestry
+
+Ancestry allows the records of a ActiveRecord model to be organised in a tree structure, using a single, intuitively formatted database column. It exposes all the standard tree structure relations (ancestors, parent, root, children, siblings, descendants) and all of them can be fetched in a single sql query. Additional features are named_scopes, integrity checking, integrity restoration, arrangement of (sub)tree into hashes and different strategies for dealing with orphaned records.
+
+= Installation
+
+To apply Ancestry to any ActiveRecord model, follow these simple steps:
+
+1. Install gem
+   - Install gemcutter gem: sudo gem install gemcutter (maybe you need: gem update --system)
+   - Add gemcutter.org as default gem source: gem tumble
+   - Add to config/environment.rb: config.gem 'ancestry'
+   - Install required gems: sudo rake gems:install
+   - Alternatively: sudo gem install ancestry
+   - If you don't want gemcutter: config.gem 'ancestry', :source => 'gemcutter.org'
+   - Alternatively: sudo gem install ancestry --source gemcutter.org
+
+2. Add ancestry column to your table
+   - Create migration: ./script/generate migration add_ancestry_to_[table] ancestry:string
+   - Add index to migration: add_index [table], :ancestry / remove_index [table], :ancestry
+   - Migrate your database: rake db:migrate
+
+3. Add ancestry to your model
+   - Add to app/models/[model].rb: acts_as_tree
+
+Your model is now a tree!
+
+= Organising Records Into A Tree
+
+You can use the parent attribute to organise your records into a tree. If you have the id of the record you want to use as a parent and don't want to fetch it, you can also use parent_id. Like any virtual model attributes, parent and parent_id can be set using parent= and parent_id= on a record or by including them in the hash passed to new, create, create!, update_attributes and update_attributes!. For example:
+
+  TreeNode.create! :name => 'Stinky', :parent => TreeNode.create!(:name => 'Squeeky')
+
+You can also create children through the children relation on a node:
+
+  node.children.create :name => 'Stinky'
+
+= Navigating Your Tree
+
+To navigate an Ancestry model, use the following methods on any instance / record:
+
+  parent         Returns the parent of the record
+  root           Returns the root of the tree the record is in
+  root_id        Returns the id of the root of the tree the record is in
+  is_root?       Returns true if the record is a root node, false otherwise
+  ancestor_ids   Returns a list of ancestor ids, starting with the root id and ending with the parent id
+  ancestors      Scopes the model on ancestors of the record
+  path_ids       Returns a list the path ids, starting with the root is and ending with the node's own id
+  path           Scopes model on path records of the record
+  children       Scopes the model on children of the record
+  child_ids      Returns a list of child ids
+  has_children?  Returns true if the record has any children, false otherwise
+  is_childless?  Returns true is the record has no childen, false otherwise
+  siblings       Scopes the model on siblings of the record, the record itself is included
+  sibling_ids    Returns a list of sibling ids
+  has_siblings?  Returns true if the record's parent has more than one child
+  is_only_child? Returns true if the record is the only child of its parent
+  descendants    Scopes the model on direct and indirect children of the record
+  descendant_ids Returns a list of a descendant ids
+  subtree        Scopes the model on descendants and itself
+  subtree_ids    Returns a list of all ids in the record's subtree
+
+= (Named) Scopes
+
+Where possible, the navigation methods return scopes instead of records, this means additional ordering, conditions, limits, etc. can be applied and that the result can be either retrieved, counted or checked for existence. For example:
+
+  node.children.exists?(:name => 'Mary')
+  node.subtree.all(:order => :name, :limit => 10).each do; ...; end
+  node.descendants.count
+
+For convenience, a couple of named scopes are included at the class level:
+
+  roots                Only root nodes
+  ancestors_of(node)   Only ancestors of node, node can be either a record or an id
+  children_of(node)    Only children of node, node can be either a record or an id
+  descendants_of(node) Only descendants of node, node can be either a record or an id
+  siblings_of(node)    Only siblings of node, node can be either a record or an id
+
+Thanks to some convenient rails magic, it is even possible to create nodes through the children and siblings scopes:
+
+  node.children.create
+  node.siblings.create!
+  TestNode.children_of(node_id).new
+  TestNode.siblings_of(node_id).create
+
+= acts_as_tree Options
+
+The acts_as_tree methods supports two options:
+
+  ancestry_column     Pass in a symbol to instruct Ancestry to use a different column name to store record ancestry
+  orphan_strategy     Instruct Ancestry what to do with children of a node that is destroyed:
+    :destroy  All children are destroyed as well (default)
+    :rootify  The children of the destroyed node become root nodes
+    :restrict An AncestryException is raised if any children exist
+
+= Arrangement
+
+Ancestry can arrange an entire subtree into nested hashes for easy navigation after retrieval from the database.  TreeNode.arrange could for example return:
+
+  { #<TreeNode id: 100018, name: "Stinky", ancestry: nil>
+    => { #<TreeNode id: 100019, name: "Crunchy", ancestry: "100018">
+      => { #<TreeNode id: 100020, name: "Squeeky", ancestry: "100018/100019">
+        => {}
+      }
+    }
+  }
+
+The arrange method also works on a scoped class, for example:
+
+  TreeNode.find_by_name('Crunchy').subtree.arrange
+
+= Integrity Checking and Restoration
+
+I don't see any way Ancestry tree integrity could get compromised without explicitly setting cyclic parents or invalid ancestry and circumventing validation with update_attribute, if you do, please let me know. I did include methods for detecting integrity problems and restoring integrity just to be sure. To check integrity use: [Model].check_ancestry_integrity. An AncestryIntegrityException will be raised if there are any problems. To restore integrity use: [Model].restore_ancestry_integrity.
+
+For example, from IRB:
+
+  >> stinky = TreeNode.create :name => 'Stinky'
+  $  #<TreeNode id: 1, name: "Stinky", ancestry: nil>
+  >> squeeky = TreeNode.create :name => 'Squeeky', :parent => stinky
+  $  #<TreeNode id: 2, name: "Squeeky", ancestry: "1">
+  >> stinky.update_attribute :parent, squeeky
+  $  true
+  >> TreeNode.all
+  $  [#<TreeNode id: 1, name: "Stinky", ancestry: "1/2">, #<TreeNode id: 2, name: "Squeeky", ancestry: "1/2/1">]
+  >> TreeNode.check_ancestry_integrity
+  !! Ancestry::AncestryIntegrityException: Conflicting parent id in node 1: 2 for node 1, expecting nil
+  >> TreeNode.restore_ancestry_integrity
+  $  [#<TreeNode id: 1, name: "Stinky", ancestry: 2>, #<TreeNode id: 2, name: "Squeeky", ancestry: nil>]
+
+= Testing
+
+The Ancestry gem comes with a unit test suite consisting of about 1500 assertions in 20 tests. It takes about 4 seconds to run on sqlite. To run it yourself, install Ancestry as a plugin, go to the ancestry folder and type 'rake'. The test suite is located in 'test/acts_as_tree_test.rb'.
+
+= Internals
+
+As can be seen in the previous section, Ancestry stores a path from the root to the parent for every node. This is a variation on the materialised path database pattern. It allows Ancestry to fetch any relation (siblings, descendants, etc.) in a single sql query without the complicated algorithms and incomprehensibility associated with left and right values. Additionally, any inserts, deletes and updates only affect nodes within the affected node's own subtree.
+
+In the example above, the ancestry column is created as a string. This puts a limitation on the depth of the tree of about 40 or 50 levels, which I think may be enough for most users. To increase the maximum depth of the tree, increase the size of the string that is being used or change it to a text to remove the limitation entirely. Changing it to a text will however decrease performance because a index cannot be put on the column in that case.
+
+= Future Work
+
+I will try to keep Ancestry up to date with changing versions of Rails and Ruby and also with any bug reports I might receive. I will implement new features on request as I see fit. Something that definitely needs to be added in the future is constraints on depth, something like: tree_node.subtree.to_depth(4)
+
+= Feedback
+
+Question? Bug report? Faulty/incomplete documentation? Feature request? Please contact me at s.a.kroes[at]gmail.com
+
+
+
+Copyright (c) 2009 Stefan Kroes, released under the MIT license

data/Rakefile

@@ -0,0 +1,22 @@
+require 'rake'
+require 'rake/testtask'
+require 'rake/rdoctask'
+
+desc 'Default: run unit tests.'
+task :default => :test
+
+desc 'Test the ancestry plugin.'
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = true
+end
+
+desc 'Generate documentation for the ancestry plugin.'
+Rake::RDocTask.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'Ancestry'
+  rdoc.options << '--line-numbers' << '--inline-source'
+  rdoc.rdoc_files.include('README')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/ancestry.gemspec

@@ -0,0 +1,18 @@
+require 'rake'
+
+Gem::Specification.new do |s|
+  s.name        = 'ancestry'
+  s.description = 'Organise ActiveRecord model into a tree structure'
+  s.summary     = 'Ancestry allows the records of a ActiveRecord model to be organised in a tree structure, using a single, intuitively formatted database column. It exposes all the standard tree structure relations (ancestors, parent, root, children, siblings, descendants) and all of them can be fetched in a single sql query. Additional features are named_scopes, integrity checking, integrity restoration, arrangement of (sub)tree into hashes and different strategies for dealing with orphaned records.'
+
+  s.version = '1.0.0'
+  s.date    = '2009-10-16'
+
+  s.author   = 'Stefan Kroes'
+  s.email    = 's.a.kroes@gmail.com'
+  s.homepage = 'http://github.com/stefankroes/ancestry'
+
+  s.files = FileList['ancestry.gemspec', '*.rb', 'lib/**/*.rb', 'rails/*', 'test/*', 'Rakefile', 'MIT-LICENSE', 'README.rdoc']
+  
+  s.add_dependency 'activerecord', '>= 2.1.0'
+end

data/init.rb

@@ -0,0 +1 @@
+require 'ancestry'

data/install.rb

@@ -0,0 +1 @@
+# Install hook code here

data/lib/ancestry.rb

@@ -0,0 +1 @@
+require 'ancestry/acts_as_tree'

data/lib/ancestry/acts_as_tree.rb

@@ -0,0 +1,302 @@
+module Ancestry
+  class AncestryException < RuntimeError
+  end
+
+  class AncestryIntegrityException < AncestryException
+  end
+  
+  def self.included base
+    base.send :extend, ClassMethods
+  end
+  
+  module ClassMethods
+    def acts_as_tree options = {}
+      # Include instance methods
+      send :include, InstanceMethods
+
+      # Include dynamic class methods
+      send :extend, DynamicClassMethods
+
+      # Create ancestry column accessor and set to option or default
+      self.cattr_accessor :ancestry_column
+      self.ancestry_column = options[:ancestry_column] || :ancestry
+
+      # Create orphan strategy accessor and set to option or default (writer comes from DynamicClassMethods)
+      self.cattr_reader :orphan_strategy
+      self.orphan_strategy = options[:orphan_strategy] || :destroy
+
+      # Validate format of ancestry column value
+      validates_format_of ancestry_column, :with => /^[0-9]+(\/[0-9]+)*$/, :allow_nil => true
+      
+      # Validate that the ancestor ids don't include own id
+      validate :ancestry_exclude_self
+      
+      # Named scopes
+      named_scope :roots, :conditions => {ancestry_column => nil}
+      named_scope :ancestors_of, lambda{ |object| {:conditions => to_node(object).ancestor_conditions} }
+      named_scope :children_of, lambda{ |object| {:conditions => to_node(object).child_conditions} }
+      named_scope :descendants_of, lambda{ |object| {:conditions => to_node(object).descendant_conditions} }
+      named_scope :siblings_of, lambda{ |object| {:conditions => to_node(object).sibling_conditions} }
+      
+      # Update descendants with new ancestry before save
+      before_save :update_descendants_with_new_ancestry
+
+      # Apply orphan strategy before destroy
+      before_destroy :apply_orphan_strategy
+    end
+  end
+  
+  module DynamicClassMethods
+    # Fetch tree node if necessary
+    def to_node object
+      object.is_a?(self) ? object : find(object)
+    end 
+    
+    # Orhpan strategy writer
+    def orphan_strategy= orphan_strategy
+      # Check value of orphan strategy, only rootify, restrict or destroy is allowed
+      if [:rootify, :restrict, :destroy].include? orphan_strategy
+        class_variable_set :@@orphan_strategy, orphan_strategy
+      else
+        raise AncestryException.new("Invalid orphan strategy, valid ones are :rootify, :restrict and :destroy.")
+      end
+    end
+    
+    # Arrangement
+    def arrange
+      # Get all nodes ordered by ancestry and start sorting them into an empty hash
+      all(:order => ancestry_column).inject({}) do |arranged_nodes, node|
+        # Find the insertion point for that node by going through its ancestors
+        node.ancestor_ids.inject(arranged_nodes) do |insertion_point, ancestor_id|
+          insertion_point.each do |parent, children|
+            # Change the insertion point to children if node is a descendant of this parent
+            insertion_point = children if ancestor_id == parent.id
+          end; insertion_point
+        end[node] = {}; arranged_nodes
+      end
+    end
+
+    # Integrity checking
+    def check_ancestry_integrity
+      parents = {}
+      # For each node ...
+      all.each do |node|
+        # ... check validity of ancestry column
+        if node.errors.invalid? node.class.ancestry_column
+          raise AncestryIntegrityException.new "Invalid format for ancestry column of node #{node.id}: #{node.read_attribute node.ancestry_column}."
+        end
+        # ... check that all ancestors exist
+        node.ancestor_ids.each do |node_id|
+          unless exists? node_id
+            raise AncestryIntegrityException.new "Reference to non-existent node in node #{node.id}: #{node_id}."
+          end
+        end
+        # ... check that all node parents are consistent with values observed earlier
+        node.path_ids.zip([nil] + node.path_ids).each do |node_id, parent_id|
+          parents[node_id] = parent_id unless parents.has_key? node_id
+          unless parents[node_id] == parent_id
+            raise AncestryIntegrityException.new "Conflicting parent id in node #{node.id}: #{parent_id || 'nil'} for node #{node_id}, expecting #{parents[node_id] || 'nil'}"
+          end
+        end
+      end
+    end
+
+    # Integrity restoration
+    def restore_ancestry_integrity
+      parents = {}
+      # For each node ...
+      all.each do |node|
+        # ... set its ancestry to nil if invalid
+        if node.errors.invalid? node.class.ancestry_column
+          node.update_attributes :ancestry => nil
+        end
+        # ... save parent of this node in parents array if it exists
+        parents[node.id] = node.parent_id if exists? node.parent_id
+
+        # Reset parent id in array to nil if it introduces a cycle
+        parent = parents[node.id]
+        until parent.nil? || parent == node.id
+          parent = parents[parent]
+        end
+        parents[node.id] = nil if parent == node.id 
+      end
+      # For each node ...
+      all.each do |node|
+        # ... rebuild ancestry from parents array
+        ancestry, parent = nil, parents[node.id]
+        until parent.nil?
+          ancestry, parent = ancestry.nil? ? parent : "#{parent}/#{ancestry}", parents[parent]
+        end
+        node.update_attributes node.ancestry_column => ancestry
+      end
+    end
+  end
+
+  module InstanceMethods 
+    # Validate that the ancestors don't include itself
+    def ancestry_exclude_self
+      errors.add_to_base "#{self.class.name.humanize} cannot be a descendant of itself." if ancestor_ids.include? self.id
+    end
+
+    # Update descendants with new ancestry
+    def update_descendants_with_new_ancestry
+      # If node is valid, not a new record and ancestry was updated ...
+      if changed.include?(self.class.ancestry_column.to_s) && !new_record? && valid?
+        # ... for each descendant ...
+        descendants.each do |descendant|
+          # ... replace old ancestry with new ancestry
+          descendant.update_attributes(
+            self.class.ancestry_column =>
+            descendant.read_attribute(descendant.class.ancestry_column).gsub(
+              /^#{self.child_ancestry}/, 
+              (read_attribute(self.class.ancestry_column).blank? ? id.to_s : "#{read_attribute self.class.ancestry_column }/#{id}")
+            )
+          )
+        end
+      end
+    end
+
+    # Apply orphan strategy
+    def apply_orphan_strategy
+      # If this isn't a new record ...
+      unless new_record?
+        # ... make al children root if orphan strategy is rootify
+        if self.class.orphan_strategy == :rootify
+          descendants.each do |descendant|
+            descendant.update_attributes descendant.class.ancestry_column => descendant.ancestry == child_ancestry ? nil : descendant.ancestry.gsub(/^#{child_ancestry}\//, '')
+          end
+        # ... destroy all descendants if orphan strategy is destroy
+        elsif self.class.orphan_strategy == :destroy
+          self.class.destroy_all descendant_conditions
+        # ... throw an exception if it has children and orphan strategy is restrict
+        elsif self.class.orphan_strategy == :restrict
+          raise Ancestry::AncestryException.new('Cannot delete record because it has descendants.') unless is_childless?
+        end
+      end
+    end
+    
+    # The ancestry value for this record's children
+    def child_ancestry
+      # New records cannot have children
+      raise Ancestry::AncestryException.new('No child ancestry for new record. Save record before performing tree operations.') if new_record?
+
+      self.send("#{self.class.ancestry_column}_was").blank? ? id.to_s : "#{self.send "#{self.class.ancestry_column}_was"}/#{id}"
+    end
+
+    # Ancestors
+    def ancestor_ids
+      read_attribute(self.class.ancestry_column).to_s.split('/').map(&:to_i)
+    end
+
+    def ancestor_conditions
+      {:id => ancestor_ids}
+    end
+
+    def ancestors
+      self.class.scoped :conditions => ancestor_conditions
+    end
+    
+    def path_ids
+      ancestor_ids + [id]
+    end
+
+    def path
+      ancestors + [self]
+    end
+
+    # Parent
+    def parent= parent
+      write_attribute(self.class.ancestry_column, parent.blank? ? nil : parent.child_ancestry)
+    end
+
+    def parent_id= parent_id
+      self.parent = parent_id.blank? ? nil : self.class.find(parent_id)
+    end
+
+    def parent_id
+      ancestor_ids.empty? ? nil : ancestor_ids.last
+    end
+
+    def parent
+      parent_id.blank? ? nil : self.class.find(parent_id)
+    end
+
+    # Root
+    def root_id
+      ancestor_ids.empty? ? id : ancestor_ids.first
+    end
+
+    def root
+      root_id == id ? self : self.class.find(root_id)
+    end
+
+    def is_root?
+      read_attribute(self.class.ancestry_column).blank?
+    end
+
+    # Children
+    def child_conditions
+      {self.class.ancestry_column => child_ancestry}
+    end
+
+    def children
+      self.class.scoped :conditions => child_conditions
+    end
+
+    def child_ids
+      children.all(:select => :id).map(&:id)
+    end
+
+    def has_children?
+      self.children.exists?
+    end
+
+    def is_childless?
+      !has_children?
+    end
+
+    # Siblings
+    def sibling_conditions
+      {self.class.ancestry_column => read_attribute(self.class.ancestry_column)}
+    end
+
+    def siblings
+      self.class.scoped :conditions => sibling_conditions
+    end
+
+    def sibling_ids
+       siblings.all(:select => :id).collect(&:id)
+    end
+
+    def has_siblings?
+      self.siblings.count > 1
+    end
+
+    def is_only_child?
+      !has_siblings?
+    end
+
+    # Descendants
+    def descendant_conditions
+      ["#{self.class.ancestry_column} like ? or #{self.class.ancestry_column} = ?", "#{child_ancestry}/%", child_ancestry]
+    end
+
+    def descendants
+      self.class.scoped :conditions => descendant_conditions
+    end
+
+    def descendant_ids
+      descendants.all(:select => :id).collect(&:id)
+    end
+    
+    def subtree
+      [self] + descendants
+    end
+
+    def subtree_ids
+      [self.id] + descendant_ids
+    end
+  end
+end
+
+ActiveRecord::Base.send :include, Ancestry