mongoid-tree 0.1.0

data/.rspec

@@ -0,0 +1,2 @@
+--color
+--format documentation

data/Gemfile

@@ -0,0 +1,5 @@
+source :rubygems
+
+gemspec
+
+gem 'bson_ext', '>= 1.0.4'

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2010 Benedikt Deicke
+
+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,44 @@
+= mongoid-tree
+
+A tree structure for Mongoid documents using the materialized path pattern
+
+== Requirements
+
+* mongoid (>= 2.0.0.beta9)
+
+== Install
+
+To install mongoid_tree, simply add it to your Gemfile:
+
+  gem "mongoid-tree"
+
+In order to get the latest development version of 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
+
+== Usage
+
+Read the API documentation at http://benedikt.github.com/mongoid-tree and take a look at the Mongoid::Tree module
+
+  require 'mongoid/tree'
+
+  class Node
+    include Mongoid::Document
+    include Mongoid::Tree
+  end
+
+== Known issues
+
+See http://github.com/benedikt/mongoid-tree/issues
+
+== Repository
+
+See http://github.com/benedikt/mongoid-tree and feel free to fork it!
+
+== Copyright
+
+Copyright (c) 2010 Benedikt Deicke. See LICENSE for details.

data/Rakefile

@@ -0,0 +1,26 @@
+require 'rspec/core/rake_task'
+require 'hanna/rdoctask'
+
+spec = Gem::Specification.load("mongoid-tree.gemspec")
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec
+
+Rake::RDocTask.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
+
+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

data/lib/mongoid/tree.rb

@@ -0,0 +1,157 @@
+require 'mongoid/tree/traversal'
+
+module Mongoid # :nodoc:
+  ##
+  # = Mongoid::Tree
+  #
+  # 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 
+  #
+  # Each document references many children. You can access them using the <tt>#children</tt> method.
+  #
+  #   node = Node.create
+  #   node.children.create
+  #   node.children.count # => 1
+  #
+  # Every document references one parent (unless it's a root document).
+  #
+  #   node = Node.create
+  #   node.parent # => nil
+  #   node.children.create
+  #   node.children.first.parent # => node
+  # 
+  module Tree
+    extend ActiveSupport::Concern
+
+    include Traversal
+  
+    included do
+      reference_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?
+    end
+    
+    ##
+    # :method: children
+    # Returns a list of the document's children. It's a <tt>reference_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_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)? 
+    def root?
+      parent_id.nil?
+    end
+    
+    ##
+    # Is this document a leaf node (has no children)?
+    def leaf?
+      children.empty?
+    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 })
+    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 
+    
+    ##
+    # Returns this document's descendants
+    def descendants
+      self.class.find(:conditions => { :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 })
+    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

data/lib/mongoid/tree/traversal.rb

@@ -0,0 +1,85 @@
+module Mongoid # :nodoc:
+  module Tree
+    ##
+    # = Mongoid::Tree::Traversal
+    #
+    # Mongoid::Tree provides a #traverse method to walk through the tree.
+    # It supports these traversal methods:
+    #
+    # * depth_first
+    # * breadth_first
+    #
+    # == Depth First Traversal
+    #
+    # See http://en.wikipedia.org/wiki/Depth-first_search for a proper description.
+    # 
+    # Given a tree like: 
+    #
+    #   node1:
+    #    - node2:
+    #      - node3
+    #    - node4:
+    #      - node5
+    #      - node6
+    #    - node7
+    #
+    # Traversing the tree using depth first traversal would visit each node in this order:
+    #
+    #   node1, node2, node3, node4, node5, node6, node7
+    #
+    # == Breadth First Traversal
+    #
+    # See http://en.wikipedia.org/wiki/Breadth-first_search for a proper description.
+    #
+    # Given a tree like:
+    #
+    #   node1:
+    #     - node2:
+    #       - node5
+    #     - node3:
+    #       - node6
+    #       - node7
+    #     - node4
+    #
+    # Traversing the tree using breadth first traversal would visit each node in this order:
+    #
+    #   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.
+      #
+      # See Mongoid::Tree::Traversal for available traversal methods.
+      #
+      # Example:
+      #
+      #   results = []
+      #   root.traverse(:depth_first) do |node|
+      #     results << node
+      #   end
+      def traverse(type = :depth_first, &block)
+        raise "No block given" unless block_given?
+        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
+          node = queue.shift
+          block.call(node)
+          queue += node.children
+        end
+      end
+      
+    end
+  end
+end

data/spec/mongoid/tree/traversal_spec.rb

@@ -0,0 +1,92 @@
+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:
+          - node2:
+            - node3
+          - node4:
+            - node5
+            - 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:
+          - node2:
+            - node5
+          - node3:
+            - node6
+            - 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

data/spec/mongoid/tree_spec.rb

@@ -0,0 +1,178 @@
+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
+    a.association.should == Mongoid::Associations::ReferencesMany
+    a.options.class_name.should == 'Node'
+    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
+    a.association.should == Mongoid::Associations::ReferencedIn
+    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:
+          - child:
+            - subchild:
+              - subsubchild
+        - other_root:
+          - 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
+      ENDTREE
+    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
+      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
+      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
+        node(:subchild).ancestors.to_a.should == [node(:root), node(:child)]
+      end
+    
+      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
+        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
+        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
+        node(:root).descendants_and_self.to_a.should =~ [node(:root), node(:child), node(:other_child), node(:subchild)]
+      end
+      
+      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
+      end
+    end
+
+    describe '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
+        node(:child).siblings_and_self.to_a.should == [node(:child), node(:other_child)]
+      end
+    end
+    
+  end
+  
+end

data/spec/spec_helper.rb

@@ -0,0 +1,21 @@
+require 'rubygems'
+require 'bundler/setup'
+
+require 'mongoid'
+require 'mongoid/tree'
+
+require 'rspec'
+
+Mongoid.configure do |config|
+  config.master = Mongo::Connection.new.db('mongoid_tree_test')
+  config.allow_dynamic_fields = false
+end
+
+Dir["#{File.dirname(__FILE__)}/support/**/*.rb"].each { |f| require f }
+
+RSpec.configure do |config|
+  config.mock_with :rspec
+  config.after :each do
+    Mongoid.master.collections.reject { |c| c.name =~ /^system\./ }.each(&:drop)
+  end
+end

data/spec/support/macros/tree_macros.rb

@@ -0,0 +1,46 @@
+require 'yaml'
+
+module Mongoid::Tree::TreeMacros
+  
+  def setup_tree(tree)
+    create_tree(YAML.load(tree))
+  end
+  
+  def node(name) 
+    @nodes[name].reload
+  end
+  
+  def print_tree(node, print_ids = false, depth = 0)
+    print '  ' * depth
+    print '- ' unless depth == 0
+    print node.name
+    print " (#{node.id})" if print_ids
+    print ':' if node.children.any?
+    print "\n"
+    node.children.each { |c| print_tree(c, print_ids, depth + 1) }
+  end
+  
+  private 
+  
+  def create_tree(object)
+    case object
+      when String: return create_node(object)
+      when Array: object.each { |tree| create_tree(tree) }
+      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

data/spec/support/models/node.rb

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

metadata

@@ -0,0 +1,148 @@
+--- !ruby/object:Gem::Specification 
+name: mongoid-tree
+version: !ruby/object:Gem::Version 
+  hash: 27
+  prerelease: false
+  segments: 
+  - 0
+  - 1
+  - 0
+  version: 0.1.0
+platform: ruby
+authors: 
+- Benedikt Deicke
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-07-26 00:00:00 +02:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: mongoid
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: -1848230043
+        segments: 
+        - 2
+        - 0
+        - 0
+        - beta9
+        version: 2.0.0.beta9
+  type: :runtime
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: rspec
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 62196423
+        segments: 
+        - 2
+        - 0
+        - 0
+        - beta
+        - 18
+        version: 2.0.0.beta.18
+  type: :development
+  version_requirements: *id002
+- !ruby/object:Gem::Dependency 
+  name: autotest
+  prerelease: false
+  requirement: &id003 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 55
+        segments: 
+        - 4
+        - 3
+        - 2
+        version: 4.3.2
+  type: :development
+  version_requirements: *id003
+- !ruby/object:Gem::Dependency 
+  name: hanna
+  prerelease: false
+  requirement: &id004 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        - 1
+        - 12
+        version: 0.1.12
+  type: :development
+  version_requirements: *id004
+description: A tree structure for Mongoid documents using the materialized path pattern
+email: 
+- benedikt@synatic.net
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README.rdoc
+- LICENSE
+files: 
+- lib/mongoid/tree/traversal.rb
+- lib/mongoid/tree.rb
+- spec/mongoid/tree/traversal_spec.rb
+- spec/mongoid/tree_spec.rb
+- spec/spec_helper.rb
+- spec/support/macros/tree_macros.rb
+- spec/support/models/node.rb
+- LICENSE
+- README.rdoc
+- Rakefile
+- Gemfile
+- .rspec
+has_rdoc: true
+homepage: http://github.com/benedikt/mongoid-tree
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --main
+- README.rdoc
+- --charset=UTF-8
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.7
+signing_key: 
+specification_version: 3
+summary: A tree structure for Mongoid documents
+test_files: []
+