mongoid-tree-rational 0.1.0

data/lib/mongoid/tree.rb

@@ -0,0 +1,443 @@
+module Mongoid
+  ##
+  # = 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
+  #
+  # === 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 <tt>before_destroy</tt> 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:
+  #
+  #   class Node
+  #     include Mongoid::Document
+  #     include Mongoid::Tree
+  #
+  #     before_destroy :nullify_children
+  #   end
+  #
+  # === 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
+
+    autoload :Ordering, 'mongoid/tree/ordering'
+    autoload :Traversal, 'mongoid/tree/traversal'
+    autoload :RationalNumbering, 'mongoid/tree/rational_numbering'
+
+    included do
+      has_many :children, :class_name => self.name, :foreign_key => :parent_id, :inverse_of => :parent, :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 => 1
+
+      set_callback :save, :after, :rearrange_children, :if => :rearrange_children?
+      set_callback :validation, :before do
+        run_callbacks(:rearrange) { rearrange }
+      end
+
+      validate :position_in_tree
+
+      define_model_callbacks :rearrange, :only => [:before, :after]
+
+      class_eval "def base_class; ::#{self.name}; end"
+    end
+
+    ##
+    # 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
+        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
+
+    end
+
+    ##
+    # @!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]
+
+    ##
+    # @!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.
+    #
+    #   @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.
+    #
+    #   @note Generated by Mongoid
+    #
+    #   @return [Mongoid::Document] The document's parent document
+
+    ##
+    # @!method parent=(document)
+    #   Sets this documents parent document.
+    #
+    #   @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.
+    #
+    #   @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 `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?
+        base_class.find(parent_ids.first)
+      else
+        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
+      if parent_ids.any?
+        base_class.and({
+          '$or' => parent_ids.map { |id| { :_id => id } }
+        })
+      else
+        base_class.where(:_id.in => [])
+      end
+    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 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
+        c.save
+      end
+    end
+
+    ##
+    # Moves all children to this document's parent
+    #
+    # @return [undefined]
+    def move_children_to_parent
+      children.each do |c|
+        c.parent = self.parent
+        c.save
+      end
+    end
+
+    ##
+    # 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]
+      else
+        self.parent_ids = []
+      end
+      rearrange_children! if self.parent_ids_changed?
+    end
+
+    def rearrange_children
+      @rearrange_children = false
+      self.children.each { |c| c.save }
+    end
+
+    def position_in_tree
+      errors.add(:parent_id, :invalid) if self.parent_ids.include?(self.id)
+    end
+  end
+end

data/lib/mongoid/tree/ordering.rb

@@ -0,0 +1,236 @@
+module Mongoid
+  module Tree
+    ##
+    # = Mongoid::Tree::Ordering
+    #
+    # Mongoid::Tree doesn't order the tree by default. To enable ordering of children
+    # include both Mongoid::Tree and Mongoid::Tree::Ordering into your document.
+    #
+    # == Utility methods
+    #
+    # This module adds methods to get related siblings depending on their position:
+    #
+    #    node.lower_siblings
+    #    node.higher_siblings
+    #    node.first_sibling_in_list
+    #    node.last_sibling_in_list
+    #
+    # There are several methods to move nodes around in the list:
+    #
+    #    node.move_up
+    #    node.move_down
+    #    node.move_to_top
+    #    node.move_to_bottom
+    #    node.move_above(other)
+    #    node.move_below(other)
+    #
+    # Additionally there are some methods to check aspects of the document
+    # in the list of children:
+    #
+    #    node.at_top?
+    #    node.at_bottom?
+    module Ordering
+      extend ActiveSupport::Concern
+
+      included do
+        field :position, :type => Integer
+
+        default_scope asc(:position)
+
+        before_save :assign_default_position, :if => :assign_default_position?
+        before_save :reposition_former_siblings, :if => :sibling_reposition_required?
+        after_destroy :move_lower_siblings_up
+      end
+
+      ##
+      # Returns a chainable criteria for this document's ancestors
+      #
+      # @return [Mongoid::Criteria] Mongoid criteria to retrieve the document's ancestors
+      def ancestors
+        base_class.unscoped { super }
+      end
+
+      ##
+      # Returns siblings below the current document.
+      # Siblings with a position greater than this document's position.
+      #
+      # @return [Mongoid::Criteria] Mongoid criteria to retrieve the document's lower siblings
+      def lower_siblings
+        self.siblings.where(:position.gt => self.position)
+      end
+
+      ##
+      # Returns siblings above the current document.
+      # Siblings with a position lower than this document's position.
+      #
+      # @return [Mongoid::Criteria] Mongoid criteria to retrieve the document's higher siblings
+      def higher_siblings
+        self.siblings.where(:position.lt => self.position)
+      end
+
+      ##
+      # Returns siblings between the current document and the other document
+      # Siblings with a position between this document's position and the other document's position.
+      #
+      # @return [Mongoid::Criteria] Mongoid criteria to retrieve the documents between this and the other document
+      def siblings_between(other)
+        range = [self.position, other.position].sort
+        self.siblings.where(:position.gt => range.first, :position.lt => range.last)
+      end
+
+      ##
+      # Returns the lowest sibling (could be self)
+      #
+      # @return [Mongoid::Document] The lowest sibling
+      def last_sibling_in_list
+        siblings_and_self.last
+      end
+
+      ##
+      # Returns the highest sibling (could be self)
+      #
+      # @return [Mongoid::Document] The highest sibling
+      def first_sibling_in_list
+        siblings_and_self.first
+      end
+
+      ##
+      # Is this the highest sibling?
+      #
+      # @return [Boolean] Whether the document is the highest sibling
+      def at_top?
+        higher_siblings.empty?
+      end
+
+      ##
+      # Is this the lowest sibling?
+      #
+      # @return [Boolean] Whether the document is the lowest sibling
+      def at_bottom?
+        lower_siblings.empty?
+      end
+
+      ##
+      # Move this node above all its siblings
+      #
+      # @return [undefined]
+      def move_to_top
+        return true if at_top?
+        move_above(first_sibling_in_list)
+      end
+
+      ##
+      # Move this node below all its siblings
+      #
+      # @return [undefined]
+      def move_to_bottom
+        return true if at_bottom?
+        move_below(last_sibling_in_list)
+      end
+
+      ##
+      # Move this node one position up
+      #
+      # @return [undefined]
+      def move_up
+        switch_with_sibling_at_offset(-1) unless at_top?
+      end
+
+      ##
+      # Move this node one position down
+      #
+      # @return [undefined]
+      def move_down
+        switch_with_sibling_at_offset(1) unless at_bottom?
+      end
+
+      ##
+      # Move this node above the specified node
+      #
+      # This method changes the node's parent if nescessary.
+      #
+      # @param [Mongoid::Tree] other document to move this document above
+      #
+      # @return [undefined]
+      def move_above(other)
+        ensure_to_be_sibling_of(other)
+
+        if position > other.position
+          new_position = other.position
+          self.siblings_between(other).inc(:position, 1)
+          other.inc(:position, 1)
+        else
+          new_position = other.position - 1
+          self.siblings_between(other).inc(:position, -1)
+        end
+
+        self.position = new_position
+        save!
+      end
+
+      ##
+      # Move this node below the specified node
+      #
+      # This method changes the node's parent if nescessary.
+      #
+      # @param [Mongoid::Tree] other document to move this document below
+      #
+      # @return [undefined]
+      def move_below(other)
+        ensure_to_be_sibling_of(other)
+
+        if position > other.position
+          new_position = other.position + 1
+          self.siblings_between(other).inc(:position, 1)
+        else
+          new_position = other.position
+          self.siblings_between(other).inc(:position, -1)
+          other.inc(:position, -1)
+        end
+
+        self.position = new_position
+        save!
+      end
+
+    private
+
+      def switch_with_sibling_at_offset(offset)
+        siblings.where(:position => self.position + offset).first.inc(:position, -offset)
+        inc(:position, offset)
+      end
+
+      def ensure_to_be_sibling_of(other)
+        return if sibling_of?(other)
+        self.parent_id = other.parent_id
+        save!
+      end
+
+      def move_lower_siblings_up
+        lower_siblings.inc(:position, -1)
+      end
+
+      def reposition_former_siblings
+        former_siblings = base_class.where(:parent_id => attribute_was('parent_id')).
+                                     and(:position.gt => (attribute_was('position') || 0)).
+                                     excludes(:id => self.id)
+        former_siblings.inc(:position,  -1)
+      end
+
+      def sibling_reposition_required?
+        parent_id_changed? && persisted?
+      end
+
+      def assign_default_position
+        self.position = if self.siblings.where(:position.ne => nil).any?
+          self.last_sibling_in_list.position + 1
+        else
+          0
+        end
+      end
+
+      def assign_default_position?
+        self.position.nil? || self.parent_id_changed?
+      end
+    end
+  end
+end