mongoid-tree 0.1.0 → 0.2.0

data/Gemfile

@@ -2,4 +2,4 @@ source :rubygems
 
 gemspec
 
-gem 'bson_ext', '>= 1.0.4'
+gem 'bson_ext', '>= 1.0.4'

data/README.rdoc

@@ -10,12 +10,12 @@ A tree structure for Mongoid documents using the materialized path pattern
 
 To install mongoid_tree, simply add it to your Gemfile:
 
-  gem "mongoid-tree"
+  gem 'mongoid-tree'
 
 In order to get the latest development version of mongoid-tree:
 
-  gem "mongoid-tree" :git => "git://github.com/benedikt/mongoid-tree"
-  
+  gem 'mongoid-tree' :git => 'git://github.com/benedikt/mongoid-tree'
+
 You might want to add the <tt>:require => 'mongoid/tree'</tt> option as well and finally run
 
   bundle install
@@ -31,6 +31,47 @@ Read the API documentation at http://benedikt.github.com/mongoid-tree and take a
     include Mongoid::Tree
   end
 
+=== Utility methods
+
+There are several utility methods that help getting to other related documents in the tree:
+
+  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 documents position in the tree:
+
+  node.root?
+  node.leaf?
+  node.depth
+  node.ancestor_of?(other)
+  node.descendant_of?(other)
+
+See Mongoid::Tree for more information on these methods.
+
+=== Traversal
+
+It's possible to traverse the tree using different traversal methods. See Mongoid::Tree::Traversal for details
+
+  node.traverse(:breadth_first) do |n|
+    # Do something with Node n
+  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.
+
 == Known issues
 
 See http://github.com/benedikt/mongoid-tree/issues

data/Rakefile

@@ -19,8 +19,8 @@ desc "Build the .gem file"
 task :build do
   system "gem build #{spec.name}.gemspec"
 end
- 
+
 desc "Push the .gem file to rubygems.org"
 task :release => :build do
   system "gem push #{spec.name}-#{spec.version}.gem"
-end
+end

data/lib/mongoid/tree.rb

@@ -4,18 +4,18 @@ module Mongoid # :nodoc:
   ##
   # = Mongoid::Tree
   #
-  # This module extends any Mongoid document with tree functionality. 
-  # 
+  # This module extends any Mongoid document with tree functionality.
+  #
   # == Usage
   #
   # Simply include the module in any Mongoid document:
-  # 
+  #
   #   class Node
   #     include Mongoid::Document
   #     include Mongoid::Tree
   #   end
   #
-  # === Using the tree structure 
+  # === Using the tree structure
   #
   # Each document references many children. You can access them using the <tt>#children</tt> method.
   #
@@ -29,129 +29,218 @@ module Mongoid # :nodoc:
   #   node.parent # => nil
   #   node.children.create
   #   node.children.first.parent # => node
-  # 
+  #
+  # === Callbacks
+  #
+  # Mongoid::Tree offers callbacks for its rearranging process. This enables you to
+  # rebuild certain fields when the document was moved in the tree. Rearranging happens
+  # before the document is validated. This gives you a chance to validate your additional
+  # changes done in your callbacks. See ActiveModel::Callbacks and ActiveSupport::Callbacks
+  # for further details on callbacks.
+  #
+  # Example:
+  #
+  #   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
+  #
   module Tree
     extend ActiveSupport::Concern
 
     include Traversal
-  
+
     included do
-      reference_many :children, :class_name => self.name, :foreign_key => :parent_id, :inverse_of => :parent
+      references_many :children, :class_name => self.name, :foreign_key => :parent_id, :inverse_of => :parent
       referenced_in :parent, :class_name => self.name, :inverse_of => :children
-    
+
       field :parent_ids, :type => Array, :default => []
-    
-      set_callback :validation, :before, :rearrange
+
       set_callback :save, :after, :rearrange_children, :if => :rearrange_children?
+      set_callback :validation, :before do
+        run_callbacks(:rearrange) { rearrange }
+      end
+
+      define_model_callbacks :rearrange, :only => [:before, :after]
+    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:
+
+      def root
+        first(:conditions => { :parent_id => nil })
+      end
+
+      def roots
+        where(:parent_id => nil)
+      end
+
+      def leaves
+        where(:_id.nin => only(:parent_id).collect(&:parent_id))
+      end
+
     end
-    
+
+    ##
+    # :singleton-method: before_rearrange
+    # Sets a callback that is called before the document is rearranged
+    # (Generated by ActiveSupport)
+
+    ##
+    # :singleton-method: after_rearrange
+    # Sets a callback that is called after the document is rearranged
+    # (Generated by ActiveSupport)
+
     ##
     # :method: children
-    # Returns a list of the document's children. It's a <tt>reference_many</tt> association.
+    # Returns a list of the document's children. It's a <tt>references_many</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.
     # (Generated by Mongoid)
-    
+
+    ##
+    # :method: parent=
+    #call-seq:
+    #   parent= document
+    #
+    # Sets this documents parent document.
+    # (Generated by Mongoid)
+
     ##
     # :method: parent_ids
     # Returns a list of the document's parent_ids, starting with the root node.
     # (Generated by Mongoid)
-    
+
     ##
-    # Is this document a root node (has no parent)? 
+    # Is this document a root node (has no parent)?
     def root?
       parent_id.nil?
     end
-    
+
     ##
     # Is this document a leaf node (has no children)?
     def leaf?
       children.empty?
     end
-    
+
+    ##
+    # Returns the depth of this document (number of ancestors)
+    def depth
+      parent_ids.count
+    end
+
     ##
     # Returns this document's root node
     def root
       self.class.find(parent_ids.first)
     end
-    
+
     ##
     # Returns this document's ancestors
     def ancestors
-      self.class.find(:conditions => { :_id.in => parent_ids })
+      self.class.where(:_id.in => parent_ids)
     end
-    
+
     ##
     # Returns this document's ancestors and itself
     def ancestors_and_self
       ancestors + [self]
     end
-    
+
     ##
     # Is this document an ancestor of the other document?
     def ancestor_of?(other)
       other.parent_ids.include?(self.id)
-    end 
-    
+    end
+
     ##
     # Returns this document's descendants
     def descendants
-      self.class.find(:conditions => { :parent_ids => self.id })
+      self.class.where(:parent_ids => self.id)
     end
-    
+
     ##
     # Returns this document's descendants and itself
     def descendants_and_self
       [self] + descendants
     end
-    
+
     ##
     # Is this document a descendant of the other document?
     def descendant_of?(other)
       self.parent_ids.include?(other.id)
     end
-    
+
     ##
     # Returns this document's siblings
     def siblings
       siblings_and_self - [self]
     end
-    
-    ## 
+
+    ##
     # Returns this document's siblings and itself
     def siblings_and_self
-      self.class.find(:conditions => { :parent_id => self.parent_id })
+      self.class.where(:parent_id => self.parent_id)
     end
-    
+
+    ##
+    # Returns all leaves of this document (be careful, currently involves two queries)
+    def leaves
+      self.class.where(:_id.nin => self.class.only(:parent_id).collect(&:parent_id)).and(:parent_ids => self.id)
+    end
+
     ##
     # Forces rearranging of all children after next save
     def rearrange_children!
       @rearrange_children = true
     end
-  
+
     ##
     # Will the children be rearranged after next save?
     def rearrange_children?
       !!@rearrange_children
     end
-  
+
     private
-  
+
     def rearrange
       if self.parent_id
         self.parent_ids = self.class.find(self.parent_id).parent_ids + [self.parent_id]
       end
-    
+
       rearrange_children! if self.parent_ids_changed?
-      return true
     end
-  
+
     def rearrange_children
       @rearrange_children = false
       self.children.find(:all).each { |c| c.save }
     end
   end
-end
+end

data/lib/mongoid/tree/traversal.rb

@@ -12,8 +12,8 @@ module Mongoid # :nodoc:
     # == Depth First Traversal
     #
     # See http://en.wikipedia.org/wiki/Depth-first_search for a proper description.
-    # 
-    # Given a tree like: 
+    #
+    # Given a tree like:
     #
     #   node1:
     #    - node2:
@@ -46,7 +46,7 @@ module Mongoid # :nodoc:
     #   node1, node2, node3, node4, node5, node6, node7
     #
     module Traversal
-      
+
       ##
       # Traverses the tree using the given traversal method (Default is :depth_first)
       # and passes each document node to the block.
@@ -61,16 +61,16 @@ module Mongoid # :nodoc:
       #   end
       def traverse(type = :depth_first, &block)
         raise "No block given" unless block_given?
-        send("#{type}_traversal", &block) 
-      end      
-      
+        send("#{type}_traversal", &block)
+      end
+
       private
-      
+
       def depth_first_traversal(&block)
         block.call(self)
         self.children.each { |c| c.send(:depth_first_traversal, &block) }
       end
-      
+
       def breadth_first_traversal(&block)
         queue = [self]
         while queue.any? do
@@ -79,7 +79,7 @@ module Mongoid # :nodoc:
           queue += node.children
         end
       end
-      
+
     end
   end
-end
+end

data/spec/mongoid/tree/traversal_spec.rb

@@ -1,34 +1,34 @@
 require 'spec_helper'
 
 describe Mongoid::Tree::Traversal do
-  
+
   describe '#traverse' do
-    
+
     subject { Node.new }
-    
+
     it "should require a block" do
       expect { subject.traverse }.to raise_error(/No block given/)
     end
-    
+
     [:depth_first].each do |method|
       it "should support #{method} traversal" do
         expect { subject.traverse(method) {} }.to_not raise_error
       end
     end
-    
+
     it "should complain about unsupported traversal methods" do
       expect { subject.traverse('non_existing') {} }.to raise_error
     end
-    
+
     it "should default to depth_first traversal" do
       subject.should_receive(:depth_first_traversal)
       subject.traverse {}
     end
-    
+
   end
-  
+
   describe 'depth first traversal' do
-      
+
     it "should traverse correctly" do
       setup_tree <<-ENDTREE
         node1:
@@ -39,38 +39,38 @@ describe Mongoid::Tree::Traversal do
             - node6
           - node7
       ENDTREE
-      
+
       result = []
       node(:node1).traverse(:depth_first) { |node| result << node }
       result.collect { |n| n.name.to_sym }.should == [:node1, :node2, :node3, :node4, :node5, :node6, :node7]
     end
-    
+
     it "should traverse correctly on merged trees" do
-      
+
       setup_tree <<-ENDTREE
         - node4:
           - node5
           - node6:
             - node7
-          
+
         - node1:
           - node2:
             - node3
       ENDTREE
-      
-      
+
+
       node(:node1).children << node(:node4)
-      
-      
+
+
       result = []
       node(:node1).traverse(:depth_first) { |node| result << node }
       result.collect { |n| n.name.to_sym }.should == [:node1, :node2, :node3, :node4, :node5, :node6, :node7]
     end
-    
+
   end
-  
+
   describe 'breadth first traversal' do
-            
+
     it "should traverse correctly" do
       tree = setup_tree <<-ENDTREE
         node1:
@@ -81,12 +81,12 @@ describe Mongoid::Tree::Traversal do
             - node7
           - node4
       ENDTREE
-      
+
       result = []
       node(:node1).traverse(:breadth_first) { |n| result << n }
       result.collect { |n| n.name.to_sym }.should == [:node1, :node2, :node3, :node4, :node5, :node6, :node7]
     end
-    
+
   end
-  
-end
+
+end

data/spec/mongoid/tree_spec.rb

@@ -1,7 +1,7 @@
 require 'spec_helper'
 
 describe Mongoid::Tree do
-  
+
   it "should reference many children as inverse of parent" do
     a = Node.associations['children']
     a.should_not be_nil
@@ -10,7 +10,7 @@ describe Mongoid::Tree do
     a.options.foreign_key.should == 'parent_id'
     a.options.inverse_of.should == :parent
   end
-  
+
   it "should be referenced in one parent as inverse of children" do
     a = Node.associations['parent']
     a.should_not be_nil
@@ -18,16 +18,16 @@ describe Mongoid::Tree do
     a.options.class_name.should == 'Node'
     a.options.inverse_of.should == :children
   end
-  
+
   it "should store parent_ids as Array with [] as default" do
     f = Node.fields['parent_ids']
     f.should_not be_nil
     f.options[:type].should == Array
     f.options[:default].should == []
   end
-  
+
   describe 'when saved' do
-    
+
     before(:each) do
       setup_tree <<-ENDTREE
         - root:
@@ -38,125 +38,152 @@ describe Mongoid::Tree do
           - other_child
       ENDTREE
     end
-    
+
     it "should set the child's parent_id when added to parent's children" do
       root = Node.create; child = Node.create
       root.children << child
       child.parent.should == root
       child.parent_id.should == root.id
     end
-    
+
     it "should set the child's parent_id parent is set on child" do
       root = Node.create; child = Node.create
       child.parent = root
       child.parent.should == root
       child.parent_id.should == root.id
     end
-    
+
     it "should rebuild its parent_ids" do
       root = Node.create; child = Node.create
       root.children << child
       child.parent_ids.should == [root.id]
     end
-  
+
     it "should rebuild its children's parent_ids when its own parent_ids changed" do
       other_root = node(:other_root); child = node(:child); subchild = node(:subchild);
       other_root.children << child
       subchild.reload # To get the updated version
       subchild.parent_ids.should == [other_root.id, child.id]
     end
-  
+
     it "should correctly rebuild its descendants' parent_ids when moved into an other subtree" do
       subchild = node(:subchild); subsubchild = node(:subsubchild); other_child = node(:other_child)
       other_child.children << subchild
       subsubchild.reload
       subsubchild.parent_ids.should == [node(:other_root).id, other_child.id, subchild.id]
     end
-  
+
     it "should not rebuild its children's parent_ids when it's not required" do
       root = node(:root)
       root.should_not_receive(:rearrange_children)
       root.save
     end
-  
+
   end
-  
+
   describe 'utility methods' do
-    
+
     before(:each) do
       setup_tree <<-ENDTREE
-        root:
-          - child:
-            - subchild
-          - other_child
+        - root:
+           - child:
+             - subchild
+           - other_child
+        - other_root
       ENDTREE
     end
-    
-    describe '.root?' do
+
+    describe '.root' do
+      it "should return the first root document" do
+        Node.root.should == node(:root)
+      end
+    end
+
+    describe '.roots' do
+      it "should return all root documents" do
+        Node.roots.to_a.should == [node(:root), node(:other_root)]
+      end
+    end
+
+    describe '.leaves' do
+      it "should return all leaf documents" do
+        Node.leaves.to_a.should =~ [node(:subchild), node(:other_child), node(:other_root)]
+      end
+    end
+
+    describe '#root?' do
       it "should return true for root documents" do
         node(:root).should be_root
       end
-      
+
       it "should return false for non-root documents" do
         node(:child).should_not be_root
       end
     end
-    
-    describe '.leaf?' do
+
+    describe '#leaf?' do
       it "should return true for leaf documents" do
         node(:subchild).should be_leaf
         node(:other_child).should be_leaf
         Node.new.should be_leaf
       end
-      
+
       it "should return false for non-leaf documents" do
         node(:child).should_not be_leaf
         node(:root).should_not be_leaf
       end
     end
-    
-    describe '.root' do
+
+    describe '#depth' do
+      it "should return the depth of this document" do
+        node(:root).depth.should == 0
+        node(:child).depth.should == 1
+        node(:subchild).depth.should == 2
+      end
+    end
+
+    describe '#root' do
       it "should return the root for this document" do
         node(:subchild).root.should == node(:root)
       end
     end
-    
+
     describe 'ancestors' do
-      it ".ancestors should return the documents ancestors" do
+      it "#ancestors should return the documents ancestors" do
         node(:subchild).ancestors.to_a.should == [node(:root), node(:child)]
       end
-    
-      it ".ancestors_and_self should return the documents ancestors and itself" do
+
+      it "#ancestors_and_self should return the documents ancestors and itself" do
         node(:subchild).ancestors_and_self.to_a.should == [node(:root), node(:child), node(:subchild)]
       end
-      
-      describe '.ancestor_of?' do
+
+      describe '#ancestor_of?' do
         it "should return true for ancestors" do
           node(:child).should be_ancestor_of(node(:subchild))
         end
-        
+
         it "should return false for non-ancestors" do
           node(:other_child).should_not be_ancestor_of(node(:subchild))
         end
       end
     end
-    
+
     describe 'descendants' do
-      it ".descendants should return the documents descendants" do
+      it "#descendants should return the documents descendants" do
         node(:root).descendants.to_a.should =~ [node(:child), node(:other_child), node(:subchild)]
       end
-    
-      it ".descendants_and_self should return the documents descendants and itself" do
+
+      it "#descendants_and_self should return the documents descendants and itself" do
         node(:root).descendants_and_self.to_a.should =~ [node(:root), node(:child), node(:other_child), node(:subchild)]
       end
-      
-      describe '.descendant_of?' do
+
+      describe '#descendant_of?' do
         it "should return true for descendants" do
           subchild = node(:subchild)
           subchild.should be_descendant_of(node(:child))
           subchild.should be_descendant_of(node(:root))
         end
-        
+
         it "should return false for non-descendants" do
           node(:subchild).should_not be_descendant_of(node(:other_child))
         end
@@ -164,15 +191,60 @@ describe Mongoid::Tree do
     end
 
     describe 'siblings' do
-      it ".siblings should return the documents siblings" do
+      it "#siblings should return the documents siblings" do
         node(:child).siblings.to_a.should == [node(:other_child)]
       end
-      
-      it ".siblings_and_self should return the documents siblings and itself" do
+
+      it "#siblings_and_self should return the documents siblings and itself" do
         node(:child).siblings_and_self.to_a.should == [node(:child), node(:other_child)]
       end
     end
-    
+
+    describe '#leaves' do
+      it "should return this documents leaves" do
+        node(:root).leaves.to_a.should =~ [node(:other_child), node(:subchild)]
+      end
+    end
+
+  end
+
+  describe 'callbacks' do
+
+    after(:each) do
+      Node.reset_callbacks(:rearrange)
+    end
+
+    it "should provide a before_rearrange callback" do
+      Node.should respond_to :before_rearrange
+    end
+
+    it "should provida an after_rearrange callback" do
+      Node.should respond_to :after_rearrange
+    end
+
+    describe 'before rearrange callback' do
+
+      it "should be called before the document is rearranged" do
+        Node.before_rearrange :callback
+        node = Node.new
+        node.should_receive(:callback).ordered
+        node.should_receive(:rearrange).ordered
+        node.save
+      end
+
+    end
+
+    describe 'after rearrange callback' do
+
+      it "should be called after the document is rearranged" do
+        Node.after_rearrange :callback
+        node = Node.new
+        node.should_receive(:rearrange).ordered
+        node.should_receive(:callback).ordered
+        node.save
+      end
+
+    end
+
   end
-  
-end
+end

data/spec/spec_helper.rb

@@ -18,4 +18,4 @@ RSpec.configure do |config|
   config.after :each do
     Mongoid.master.collections.reject { |c| c.name =~ /^system\./ }.each(&:drop)
   end
-end
+end

data/spec/support/macros/tree_macros.rb

@@ -1,15 +1,15 @@
 require 'yaml'
 
 module Mongoid::Tree::TreeMacros
-  
+
   def setup_tree(tree)
     create_tree(YAML.load(tree))
   end
-  
-  def node(name) 
+
+  def node(name)
     @nodes[name].reload
   end
-  
+
   def print_tree(node, print_ids = false, depth = 0)
     print '  ' * depth
     print '- ' unless depth == 0
@@ -19,28 +19,28 @@ module Mongoid::Tree::TreeMacros
     print "\n"
     node.children.each { |c| print_tree(c, print_ids, depth + 1) }
   end
-  
-  private 
-  
+
+  private
+
   def create_tree(object)
     case object
       when String: return create_node(object)
       when Array: object.each { |tree| create_tree(tree) }
-      when Hash: 
+      when Hash:
         name, children = object.first
         node = create_node(name)
         children.each { |c| node.children << create_tree(c) }
         return node
     end
   end
-  
+
   def create_node(name)
     @nodes ||= HashWithIndifferentAccess.new
     @nodes[name] = Node.create(:name => name)
   end
-  
+
 end
 
 RSpec.configure do |config|
   config.include Mongoid::Tree::TreeMacros
-end
+end

data/spec/support/models/node.rb

@@ -1,7 +1,7 @@
 class Node
   include Mongoid::Document
   include Mongoid::Tree
-  
+
   field :name
 end
 

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: mongoid-tree
 version: !ruby/object:Gem::Version 
-  hash: 27
+  hash: 23
   prerelease: false
   segments: 
   - 0
-  - 1
+  - 2
   - 0
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors: 
 - Benedikt Deicke
@@ -15,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-07-26 00:00:00 +02:00
+date: 2010-07-27 00:00:00 +02:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency