mongoid-tree 0.7.0 → 1.0.0

data/Gemfile

@@ -2,5 +2,5 @@ source :rubygems
 
 gemspec
 
-gem 'bson_ext',    '>= 1.0.4', :platform => :ruby
-gem 'SystemTimer', '>= 1.2.0', :platform => :ruby_18
+gem 'guard-rspec', '>= 0.6.0'
+gem 'ruby_gntp',   '>= 0.3.4'

data/LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2010 Benedikt Deicke
+Copyright (c) 2010-2012 Benedikt Deicke
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/README.md

@@ -0,0 +1,215 @@
+# mongoid-tree [![Build Status](https://secure.travis-ci.org/benedikt/mongoid-tree.png?branch=master)](http://travis-ci.org/benedikt/mongoid-tree) [![Dependency Status](https://gemnasium.com/benedikt/mongoid-tree.png)](http://gemnasium.com/benedikt/mongoid-tree)
+
+A tree structure for Mongoid documents using the materialized path pattern
+
+## Requirements
+
+* mongoid (~> 3.0)
+
+For a mongoid 2.x compatible version, please use mongoid-tree 0.7.x!
+
+
+## Install
+
+To install mongoid_tree, simply add it to your Gemfile:
+
+    gem 'mongoid-tree', :require => 'mongoid/tree'
+
+In order to get the latest development version of mongoid-tree:
+
+    gem 'mongoid-tree', :git => 'git://github.com/benedikt/mongoid-tree', :require => 'mongoid/tree'
+
+You might want to remove the `:require => 'mongoid/tree'` option and explicitly `require 'mongoid/tree'` where needed and finally run
+
+    bundle install
+
+
+## Usage
+
+Read the API documentation at http://benedikt.github.com/mongoid-tree and take a look at the `Mongoid::Tree` module
+
+```ruby
+class Node
+  include Mongoid::Document
+  include Mongoid::Tree
+end
+```
+
+### Utility methods
+
+There are several utility methods that help getting to other related documents in the tree:
+
+```ruby
+Node.root
+Node.roots
+Node.leaves
+
+node.root
+node.parent
+node.children
+node.ancestors
+node.ancestors_and_self
+node.descendants
+node.descendants_and_self
+node.siblings
+node.siblings_and_self
+node.leaves
+```
+
+In addition it's possible to check certain aspects of the document's position in the tree:
+
+```ruby
+node.root?
+node.leaf?
+node.depth
+node.ancestor_of?(other)
+node.descendant_of?(other)
+node.sibling_of?(other)
+```
+
+See `Mongoid::Tree` for more information on these methods.
+
+
+### Ordering
+
+`Mongoid::Tree` doesn't order children by default. To enable ordering of tree nodes include the `Mongoid::Tree::Ordering` module. This will add a `position` field to your document and provide additional utility methods:
+
+```ruby
+node.lower_siblings
+node.higher_siblings
+node.first_sibling_in_list
+node.last_sibling_in_list
+
+node.move_up
+node.move_down
+node.move_to_top
+node.move_to_bottom
+node.move_above(other)
+node.move_below(other)
+
+node.at_top?
+node.at_bottom?
+```
+
+Example:
+
+```ruby
+class Node
+  include Mongoid::Document
+  include Mongoid::Tree
+  include Mongoid::Tree::Ordering
+end
+```
+
+See `Mongoid::Tree::Ordering` for more information on these methods.
+
+### Traversal
+
+It's possible to traverse the tree using different traversal methods using the `Mongoid::Tree::Traversal` module.
+
+Example:
+
+```ruby
+class Node
+  include Mongoid::Document
+  include Mongoid::Tree
+  include Mongoid::Tree::Traversal
+end
+
+node.traverse(:breadth_first) do |n|
+  # Do something with Node n
+end
+```
+
+### Destroying
+
+`Mongoid::Tree` does not handle destroying of nodes by default. However it provides several strategies that help you to deal with children of deleted documents. You can simply add them as `before_destroy` callbacks.
+
+Available strategies are:
+
+* `:nullify_children` -- Sets the children's parent_id to null
+* `:move_children_to_parent` -- Moves the children to the current document's parent
+* `:destroy_children` -- Destroys all children by calling their `#destroy` method (invokes callbacks)
+* `:delete_descendants` -- Deletes all descendants using a database query (doesn't invoke callbacks)
+
+Example:
+
+```ruby
+class Node
+  include Mongoid::Document
+  include Mongoid::Tree
+
+  before_destroy :nullify_children
+end
+```
+
+
+### Callbacks
+
+There are two callbacks that are called before and after the rearranging process. This enables you to do additional computations after the documents position in the tree is updated. See `Mongoid::Tree` for details.
+
+Example:
+  
+```ruby 
+class Page
+  include Mongoid::Document
+  include Mongoid::Tree
+
+  after_rearrange :rebuild_path
+
+  field :slug
+  field :path
+
+  private
+
+  def rebuild_path
+    self.path = self.ancestors_and_self.collect(&:slug).join('/')
+  end
+end
+```
+
+### Validations
+
+`Mongoid::Tree` currently does not validate the document's children or parent associations by default. To explicitly enable validation for children and parent documents it's required to add a `validates_associated` validation.
+
+Example:
+
+```ruby
+class Node
+  include Mongoid::Document
+  include Mongoid::Tree
+
+  validates_associated :parent, :children
+end
+```
+
+## Build Status
+
+mongoid-tree is on [Travis CI](http://travis-ci.org/benedikt/mongoid-tree) running the specs on Ruby Head, Ruby 1.9.3, JRuby (1.9 mode), and Rubinius (1.9 mode).
+
+## Known issues
+
+See [https://github.com/benedikt/mongoid-tree/issues](https://github.com/benedikt/mongoid-tree/issues)
+
+
+## Repository
+
+See [https://github.com/benedikt/mongoid-tree](https://github.com/benedikt/mongoid-tree) and feel free to fork it!
+
+
+## Contributors
+
+See a list of all contributors at [https://github.com/benedikt/mongoid-tree/contributors](https://github.com/benedikt/mongoid-tree/contributors). Thanks a lot everyone!
+
+
+## Support
+
+If you like mongoid-tree and want to support the development, I would appreciate a small donation:
+
+[![Pledgie](http://www.pledgie.com/campaigns/12137.png?skin_name=chrome)](http://www.pledgie.com/campaigns/12137)
+
+[![Flattr](https://api.flattr.com/button/flattr-badge-large.png)](https://flattr.com/submit/auto?user_id=benediktdeicke&url=https://github.com/benedikt/mongoid-tree&title=mongoid-tree&language=&tags=github&category=software)
+
+## Copyright
+
+Copyright (c) 2010-2012 Benedikt Deicke. See LICENSE for details.

data/Rakefile

@@ -1,5 +1,5 @@
 require 'rspec/core/rake_task'
-require 'rdoc/task'
+require 'yard'
 
 spec = Gem::Specification.load("mongoid-tree.gemspec")
 
@@ -7,13 +7,7 @@ RSpec::Core::RakeTask.new(:spec)
 
 task :default => :spec
 
-RDoc::Task.new do |rdoc|
-  rdoc.rdoc_dir = 'doc'
-  rdoc.title = "#{spec.name} #{spec.version}"
-  rdoc.options += spec.rdoc_options
-  rdoc.rdoc_files.include(spec.extra_rdoc_files)
-  rdoc.rdoc_files.include('lib/**/*.rb')
-end
+YARD::Rake::YardocTask.new(:doc)
 
 desc "Build the .gem file"
 task :build do

data/lib/mongoid/tree.rb

@@ -1,4 +1,4 @@
-module Mongoid # :nodoc:
+module Mongoid
   ##
   # = Mongoid::Tree
   #
@@ -83,12 +83,12 @@ module Mongoid # :nodoc:
     autoload :Traversal, 'mongoid/tree/traversal'
 
     included do
-      references_many :children, :class_name => self.name, :foreign_key => :parent_id, :inverse_of => :parent, :autosave => true, :validate => false
+      has_many :children, :class_name => self.name, :foreign_key => :parent_id, :inverse_of => :parent, :validate => false
 
-      referenced_in :parent, :class_name => self.name, :inverse_of => :children, :index => true, :validate => false
+      belongs_to :parent, :class_name => self.name, :inverse_of => :children, :index => true, :validate => false
 
       field :parent_ids, :type => Array, :default => []
-      index :parent_ids
+      index :parent_ids => 1
 
       set_callback :save, :after, :rearrange_children, :if => :rearrange_children?
       set_callback :validation, :before do
@@ -103,29 +103,39 @@ module Mongoid # :nodoc:
     end
 
     ##
-    # :singleton-method: root
-    # Returns the first root document
-
-    ##
-    # :singleton-method: roots
-    # Returns all root documents
-
-    ##
-    # :singleton-method: leaves
-    # Returns all leaves (be careful, currently involves two queries)
-
-    ##
-    # This module includes those methods documented above
-    module ClassMethods # :nodoc:
-
+    # This module implements class methods that will be available 
+    # on the document that includes Mongoid::Tree
+    module ClassMethods
+
+      ##
+      # Returns the first root document
+      #
+      # @example
+      #   Node.root
+      #
+      # @return [Mongoid::Document] The first root document
       def root
-        first(:conditions => { :parent_id => nil })
+        roots.first
       end
 
+      ##
+      # Returns all root documents
+      #
+      # @example
+      #   Node.roots
+      #
+      # @return [Mongoid::Criteria] Mongoid criteria to retrieve all root documents
       def roots
         where(:parent_id => nil)
       end
 
+      ##
+      # Returns all leaves (be careful, currently involves two queries)
+      #
+      # @example
+      #   Node.leaves
+      #
+      # @return [Mongoid::Criteria] Mongoid criteria to retrieve all leave nodes
       def leaves
         where(:_id.nin => only(:parent_id).collect(&:parent_id))
       end
@@ -133,140 +143,236 @@ module Mongoid # :nodoc:
     end
 
     ##
-    # :singleton-method: before_rearrange
-    # Sets a callback that is called before the document is rearranged
-    # (Generated by ActiveSupport)
+    # @!method before_rearrange
+    #   @!scope class
+    #
+    #   Sets a callback that is called before the document is rearranged
+    #
+    #   @example
+    #     class Node
+    #       include Mongoid::Document
+    #       include Mongoid::Tree
+    #
+    #       before_rearrage :do_something
+    #
+    #     private
+    #
+    #       def do_something
+    #         # ...
+    #       end
+    #     end
+    #
+    #   @note Generated by ActiveSupport
+    #
+    #   @return [undefined]
 
     ##
-    # :singleton-method: after_rearrange
-    # Sets a callback that is called after the document is rearranged
-    # (Generated by ActiveSupport)
+    # @!method after_rearrange
+    #   @!scope class
+    #
+    #   Sets a callback that is called after the document is rearranged
+    #
+    #   @example
+    #     class Node
+    #       include Mongoid::Document
+    #       include Mongoid::Tree
+    #
+    #       after_rearrange :do_something
+    #
+    #     private
+    #
+    #       def do_something
+    #         # ...
+    #       end
+    #     end
+    #
+    #   @note Generated by ActiveSupport
+    #
+    #   @return [undefined]
 
     ##
-    # :method: children
-    # Returns a list of the document's children. It's a <tt>references_many</tt> association.
-    # (Generated by Mongoid)
+    # @!method children
+    #   Returns a list of the document's children. It's a <tt>references_many</tt> association.
+    #
+    #   @note Generated by Mongoid
+    #
+    #   @return [Mongoid::Criteria] Mongoid criteria to retrieve the document's children
 
     ##
-    # :method: parent
-    # Returns the document's parent (unless it's a root document).  It's a <tt>referenced_in</tt> association.
-    # (Generated by Mongoid)
+    # @!method parent
+    #   Returns the document's parent (unless it's a root document).  It's a <tt>referenced_in</tt> association.
+    #
+    #   @note Generated by Mongoid
+    #
+    #   @return [Mongoid::Document] The document's parent document
 
     ##
-    # :method: parent=
-    #call-seq:
-    #   parent= document
+    # @!method parent=(document)
+    #   Sets this documents parent document.
     #
-    # Sets this documents parent document.
-    # (Generated by Mongoid)
-
+    #   @note Generated by Mongoid
+    #
+    #   @param [Mongoid::Tree] document
+    
     ##
-    # :method: parent_ids
-    # Returns a list of the document's parent_ids, starting with the root node.
-    # (Generated by Mongoid)
+    # @!method parent_ids
+    #   Returns a list of the document's parent_ids, starting with the root node.
+    #
+    #   @note Generated by Mongoid
+    #
+    #   @return [Array<BSON::ObjectId>] The ids of the document's ancestors
 
     ##
     # Is this document a root node (has no parent)?
+    #
+    # @return [Boolean] Whether the document is a root node
     def root?
       parent_id.nil?
     end
 
     ##
     # Is this document a leaf node (has no children)?
+    #
+    # @return [Boolean] Whether the document is a leaf node
     def leaf?
       children.empty?
     end
 
     ##
     # Returns the depth of this document (number of ancestors)
+    #
+    # @example
+    #   Node.root.depth # => 0
+    #   Node.root.children.first.depth # => 1
+    #
+    # @return [Fixnum] Depth of this document
     def depth
       parent_ids.count
     end
 
     ##
-    # Returns this document's root node
+    # Returns this document's root node. Returns `self` if the
+    # current document is a root node
+    #
+    # @example
+    #   node = Node.find(...)
+    #   node.root
+    #
+    # @return [Mongoid::Document] The documents root node
     def root
       if parent_ids.present?
-        return base_class.find(parent_ids.first)
+        base_class.find(parent_ids.first)
       else
-        return self.root? ? self : self.parent.root
+        self.root? ? self : self.parent.root
       end
     end
 
     ##
     # Returns a chainable criteria for this document's ancestors
+    #
+    # @return [Mongoid::Criteria] Mongoid criteria to retrieve the documents ancestors
     def ancestors
       base_class.where(:_id.in => parent_ids)
     end
 
     ##
     # Returns an array of this document's ancestors and itself
+    #
+    # @return [Array<Mongoid::Document>] Array of the document's ancestors and itself
     def ancestors_and_self
       ancestors + [self]
     end
 
     ##
     # Is this document an ancestor of the other document?
+    #
+    # @param [Mongoid::Tree] other document to check against
+    #
+    # @return [Boolean] The document is an ancestor of the other document
     def ancestor_of?(other)
       other.parent_ids.include?(self.id)
     end
 
     ##
     # Returns a chainable criteria for this document's descendants
+    #
+    # @return [Mongoid::Criteria] Mongoid criteria to retrieve the document's descendants
     def descendants
       base_class.where(:parent_ids => self.id)
     end
 
     ##
-    # Returns and array of this document's descendants and itself
+    # Returns and array of this document and it's descendants
+    #
+    # @return [Array<Mongoid::Document>] Array of the document itself and it's descendants
     def descendants_and_self
       [self] + descendants
     end
 
     ##
     # Is this document a descendant of the other document?
+    #
+    # @param [Mongoid::Tree] other document to check against
+    #
+    # @return [Boolean] The document is a descendant of the other document
     def descendant_of?(other)
       self.parent_ids.include?(other.id)
     end
 
     ##
     # Returns this document's siblings
+    #
+    # @return [Mongoid::Criteria] Mongoid criteria to retrieve the document's siblings
     def siblings
       siblings_and_self.excludes(:id => self.id)
     end
 
     ##
     # Returns this document's siblings and itself
+    #
+    # @return [Mongoid::Criteria] Mongoid criteria to retrieve the document's siblings and itself
     def siblings_and_self
       base_class.where(:parent_id => self.parent_id)
     end
 
     ##
     # Is this document a sibling of the other document?
+    #
+    # @param [Mongoid::Tree] other document to check against
+    #
+    # @return [Boolean] The document is a sibling of the other document
     def sibling_of?(other)
       self.parent_id == other.parent_id
     end
 
     ##
     # Returns all leaves of this document (be careful, currently involves two queries)
+    #
+    # @return [Mongoid::Criteria] Mongoid criteria to retrieve the document's leaves
     def leaves
       base_class.where(:_id.nin => base_class.only(:parent_id).collect(&:parent_id)).and(:parent_ids => self.id)
     end
 
     ##
     # Forces rearranging of all children after next save
+    #
+    # @return [undefined]
     def rearrange_children!
       @rearrange_children = true
     end
 
     ##
     # Will the children be rearranged after next save?
+    #
+    # @return [Boolean] Whether the children will be rearranged
     def rearrange_children?
       !!@rearrange_children
     end
 
     ##
     # Nullifies all children's parent_id
+    #
+    # @return [undefined]
     def nullify_children
       children.each do |c|
         c.parent = c.parent_id = nil
@@ -276,6 +382,8 @@ module Mongoid # :nodoc:
 
     ##
     # Moves all children to this document's parent
+    #
+    # @return [undefined]
     def move_children_to_parent
       children.each do |c|
         c.parent_id = self.parent_id
@@ -285,17 +393,28 @@ module Mongoid # :nodoc:
 
     ##
     # Deletes all descendants using the database (doesn't invoke callbacks)
+    #
+    # @return [undefined]
     def delete_descendants
       base_class.delete_all(:conditions => { :parent_ids => self.id })
     end
 
     ##
     # Destroys all children by calling their #destroy method (does invoke callbacks)
+    #
+    # @return [undefined]
     def destroy_children
       children.destroy_all
     end
 
   private
+
+    ##
+    # Updates the parent_ids and marks the children for
+    # rearrangement when the parent_ids changed
+    #
+    # @private
+    # @return [undefined]
     def rearrange
       if self.parent_id
         self.parent_ids = parent.parent_ids + [self.parent_id]