mongoid-sleeping_king_studios 0.5.0 → 0.6.2

data/lib/mongoid/sleeping_king_studios/has_tree/cache_ancestry.rb

@@ -1,6 +1,7 @@
 # lib/mongoid/sleeping_king_studios/has_tree/cache_ancestry.rb
 
 require 'mongoid/sleeping_king_studios'
+require 'mongoid/sleeping_king_studios/concern'
 require 'mongoid/sleeping_king_studios/has_tree/errors'
 
 module Mongoid::SleepingKingStudios
@@ -21,6 +22,142 @@ module Mongoid::SleepingKingStudios
     # @since 0.5.0
     module CacheAncestry
       extend ActiveSupport::Concern
+      extend Mongoid::SleepingKingStudios::Concern
+
+      # @api private
+      # 
+      # Sets up the ancestry caching concern.
+      # 
+      # @param [Class] base The base class into which the concern is mixed in.
+      # @param [Hash] options The options for the relation.
+      # 
+      # @since 0.6.0
+      def self.apply base, metadata
+        name = :has_tree_cache_ancestry
+        validate_options name, metadata.properties
+
+        define_fields    base, metadata
+        define_accessors base, metadata
+        define_helpers   base, metadata
+      end # class method apply
+
+      # @api private
+      # 
+      # Overwrites the parent id setter to update the ancestor ids field,
+      # and defines the ancestors and descendents methods.
+      # 
+      # @param [Class] base The base class into which the concern is mixed in.
+      # @param [Metadata] metadata The metadata for the relation.
+      # 
+      # @since 0.6.0
+      def self.define_accessors base, metadata
+        parent_id_writer = base.instance_method metadata.parent_foreign_key_writer
+
+        base.re_define_method metadata.parent_foreign_key_writer do |value|
+          old_ancestor_ids = send(metadata.foreign_key).dup
+
+          parent_id_writer.bind(self).call value
+          new_ancestor_ids = send(metadata.parent_name) ?
+            send(metadata.parent_name).send(metadata.foreign_key) + [send(metadata.parent_name).id] :
+            []
+
+          descendents.each do |descendent|
+            ary = descendent.send(metadata.foreign_key).dup
+            ary[0..old_ancestor_ids.count] = new_ancestor_ids + [id]
+            descendent.update_attributes metadata.foreign_key => ary
+          end # each
+          
+          send :"#{metadata.foreign_key}=", new_ancestor_ids
+        end # method
+
+        base.send :define_method, metadata.relation_name do
+          begin
+            self.class.find(send(metadata.foreign_key))
+          rescue Mongoid::Errors::DocumentNotFound, Mongoid::Errors::InvalidFind
+            raise Mongoid::SleepingKingStudios::HasTree::Errors::MissingAncestor.new metadata.relation_name, send(metadata.foreign_key)
+          end # begin-rescue
+        end # method
+
+        base.send :define_method, :descendents do
+          criteria = self.class.all
+
+          send(metadata.foreign_key).each_with_index do |ancestor_id, index|
+            criteria = criteria.where(:"#{metadata.foreign_key}.#{index}" => ancestor_id)
+          end # each
+
+          criteria.where(:"#{metadata.foreign_key}.#{send(metadata.foreign_key).count}" => id)
+        end # method descendents
+      end # class method define_fields
+
+      # @api private
+      # 
+      # Defines the foreign key field on the base class.
+      # 
+      # @param [Class] base The base class into which the concern is mixed in.
+      # @param [Metadata] metadata The metadata for the relation.
+      # 
+      # @since 0.6.0
+      def self.define_fields base, metadata
+        base.send :field, metadata.foreign_key, :type => Array, :default => []
+      end # class method define_fields
+
+      # @api private
+      # 
+      # Defines the rebuild and validate ancestry helper methods.
+      # 
+      # @param [Class] base The base class into which the concern is mixed in.
+      # @param [Metadata] metadata The metadata for the relation.
+      # 
+      # @since 0.6.0
+      def self.define_helpers base, metadata
+        base.send :define_method, :rebuild_ancestry! do
+          begin
+            ary, object = [], self
+            while object.send(metadata.parent_name)
+              ary.unshift object.send(metadata.parent_name).id
+              object = object.send(metadata.parent_name)
+            end # while
+            self.send :"#{metadata.foreign_key}=", ary
+          rescue Mongoid::Errors::DocumentNotFound
+            raise Mongoid::SleepingKingStudios::HasTree::Errors::MissingAncestor.new "#{relation_name}", object.send(metadata.parent_foreign_key)
+          end # begin-rescue
+        end # method rebuild_ancestry!
+
+        base.send :define_method, :validate_ancestry! do
+          return if send(metadata.foreign_key).empty?
+
+          ancestors = []
+          send(metadata.foreign_key).each_with_index do |ancestor_id, index|
+            begin
+              ancestor = self.class.find(ancestor_id)
+              ancestors << ancestor
+
+              if index > 0 && ancestor.send(metadata.parent_foreign_key) != send(metadata.foreign_key)[index - 1]
+                # If the ancestor's parent is not the same as the previous
+                # ancestor.
+                raise Mongoid::SleepingKingStudios::HasTree::Errors::UnexpectedAncestor.new "#{metadata.relation_name}", ancestor.send(metadata.parent_foreign_key), send(metadata.foreign_key)[index - 1]
+              end # if
+            rescue Mongoid::Errors::InvalidFind, Mongoid::Errors::DocumentNotFound
+              # If the ancestor id is nil, or the ancestor does not exist.
+              raise Mongoid::SleepingKingStudios::HasTree::Errors::MissingAncestor.new "#{metadata.relation_name}", ancestor_id
+            end # begin-rescue
+          end # each with index
+        end # method validate_ancestry!
+      end # class method define_helpers
+
+      # Get the valid options allowed with this concern.
+      # 
+      # @return [ Array<Symbol> ] The valid options.
+      #
+      # @since 0.5.1
+      def self.valid_options
+        %i(
+          children_name # Internal; do not set directly.
+          foreign_key
+          parent_name   # Internal; do not set directly.
+          relation_name
+        ) # end Array
+      end # class method valid_options
 
       # @!attribute [r] ancestor_ids
       #   Stores the ids of the object's ancestors, starting from the root
@@ -31,120 +168,47 @@ module Mongoid::SleepingKingStudios
       # 
       #   @since 0.5.0
 
-      # Class methods added to the base class via #extend.
-      module ClassMethods
-        # @overload cache_ancestry()
-        #   Adds the :ancestry_id field, the #ancestors and #descendents
-        #   scopes, and redefines #parent_id= to update the :ancestry_id
-        #   field on the object and its descendents.
-        # 
-        #   Do not call this method directly; rather, add a
-        #   :cache_ancestry => true options to the call to ::has_tree.
-        def cache_ancestry **options
-          parent_name   = options[:children][:inverse_of]
-          children_name = options[:parent][:inverse_of]
-
-          field :ancestor_ids, :type => Array, :default => []
-
-          alias_method :"set_parent_id", :"#{parent_name}_id="
-          private :set_parent_id
-          re_define_method "#{parent_name}_id=" do |value|
-            old_ancestor_ids = ancestor_ids.dup
-
-            set_parent_id value
-            new_ancestor_ids = parent ? parent.ancestor_ids + [parent.id] : []
-
-            descendents.each do |descendent|
-              ary = descendent.ancestor_ids.dup
-              ary[0..old_ancestor_ids.count] = new_ancestor_ids + [id]
-              descendent.update_attributes :ancestor_ids => ary
-            end # each
-            
-            self.send :ancestor_ids=, new_ancestor_ids
-          end # method #{parent_name}_id=
-        end # class method cache_ancestry
-      end # module ClassMethods
-
-      # Returns an array of the current object's ancestors, from the root
-      # object to the current parent. If the object has no parent, returns an
-      # empty array. If an error is raised, consider calling #rebuild_ancestry!
-      # 
-      # @raise [Mongoid::SleepingKingStudios::HasTree::Errors::MissingAncestor]
-      #   If one or more of the ancestors is not found in the datastore (the id
-      #   is wrong, the object is not persisted, there is a nil value in
-      #   ancestor_ids, and so on).
-      # 
-      # @return [Array] The objects' ancestors
-      def ancestors
-        self.class.find(ancestor_ids)
-      rescue Mongoid::Errors::DocumentNotFound, Mongoid::Errors::InvalidFind
-        raise Mongoid::SleepingKingStudios::HasTree::Errors::MissingAncestor.new ancestor_ids
-      end # method ancestors
-
-      # Returns a scope for all of the descendents of the current object, i.e.
-      # all objects that have the current object as an ancestor.
-      # 
-      # @return [Mongoid::Criteria] The criteria for finding the descendents.
-      def descendents
-        criteria = self.class.all
-
-        ancestor_ids.each_with_index do |ancestor_id, index|
-          criteria = criteria.where(:"ancestor_ids.#{index}" => ancestor_id)
-        end # each
-
-        criteria.where(:"ancestor_ids.#{ancestor_ids.count}" => id)
-      end # scope descendents
-
-      # Travels up the tree using the #parent method and saves the ancestors to
-      # the :ancestor_ids field. This overwrites the value of :ancestor_ids on
-      # the current object, but not on any of its ancestors.
-      # 
-      # @raise [Mongoid::SleepingKingStudios::HasTree::Errors::MissingAncestor]
-      #   If the current object or an ancestor has an invalid #parent.
-      def rebuild_ancestry!
-        ary, object = [], self
-        while object.parent
-          ary.unshift object.parent.id
-          object = object.parent
-        end # while
-        self.send :ancestor_ids=, ary
-      rescue Mongoid::Errors::DocumentNotFound
-        raise Mongoid::SleepingKingStudios::HasTree::Errors::MissingAncestor.new object.parent_id
-      end # method rebuild_ancestry!
-
-      # Travels up the tree using the :ancestor_ids and ensures that each
-      # ancestor exists and is persisted to the database, and that the
-      # object's parent correctly matches the last value in its own
-      # :ancestor_ids field.
-      # 
-      # @raise [Mongoid::SleepingKingStudios::HasTree::Errors::MissingAncestor]
-      #   If any of the ancestors is not found in the datastore (the id is
-      #   wrong, the object is not persisted, there is a nil value in
-      #   ancestor_ids, and so on).
+      # @!method ancestors
+      #   Returns an array of the current object's ancestors, from the root
+      #   object to the current parent. If the object has no parent, returns an
+      #   empty array. If an error is raised, consider calling
+      #   #rebuild_ancestry!
+      # 
+      #   @raise [Mongoid::SleepingKingStudios::HasTree::Errors::MissingAncestor]
+      #     If one or more of the ancestors is not found in the datastore (the
+      #     id is wrong, the object is not persisted, there is a nil value in
+      #     ancestor_ids, and so on).
+      # 
+      #   @return [Array] The objects' ancestors
+
+      # @!method descendents
+      #   Returns a scope for all of the descendents of the current object,
+      #   i.e. all objects that have the current object as an ancestor.
+      # 
+      #   @return [Mongoid::Criteria] The criteria for finding the descendents.
+      
+      # @!method rebuild_ancestry!
+      #   Travels up the tree using the #parent method and saves the ancestors
+      #   to the :ancestor_ids field. This overwrites the value of
+      #   :ancestor_ids on the current object, but not on any of its ancestors.
+      # 
+      #   @raise [Mongoid::SleepingKingStudios::HasTree::Errors::MissingAncestor]
+      #     If the current object or an ancestor has an invalid #parent.
+
+      # @!method validate_ancestry!
+      #   Travels up the tree using the :ancestor_ids and ensures that each
+      #   ancestor exists and is persisted to the database, and that the
+      #   object's parent correctly matches the last value in its own
+      #   :ancestor_ids field.
+      # 
+      #   @raise [Mongoid::SleepingKingStudios::HasTree::Errors::MissingAncestor]
+      #     If any of the ancestors is not found in the datastore (the id is
+      #     wrong, the object is not persisted, there is a nil value in
+      #     ancestor_ids, and so on).
       #
-      # @raise [Mongoid::SleepingKingStudios::HasTree::Errors::UnexpectedAncestor]
-      #   If there is a mismatch between an object's #parent and the last value
-      #   in the object's :ancestor_ids field.
-      def validate_ancestry!
-        return if ancestor_ids.empty?
-
-        ancestors = []
-        ancestor_ids.each_with_index do |ancestor_id, index|
-          begin
-            ancestor = self.class.find(ancestor_id)
-            ancestors << ancestor
-
-            if index > 0 && ancestor.parent_id != ancestor_ids[index - 1]
-              # If the ancestor's parent is not the same as the previous
-              # ancestor.
-              raise Mongoid::SleepingKingStudios::HasTree::Errors::UnexpectedAncestor.new ancestor.parent_id, ancestor_ids[index - 1]
-            end # if
-          rescue Mongoid::Errors::InvalidFind, Mongoid::Errors::DocumentNotFound
-            # If the ancestor id is nil, or the ancestor does not exist.
-            raise Mongoid::SleepingKingStudios::HasTree::Errors::MissingAncestor.new ancestor_id
-          end # begin-rescue
-        end # each
-      end # method validate_ancestry!
+      #   @raise [Mongoid::SleepingKingStudios::HasTree::Errors::UnexpectedAncestor]
+      #     If there is a mismatch between an object's #parent and the last
+      #     value in the object's :ancestor_ids field.
     end # module
   end # module
 end # module

data/lib/mongoid/sleeping_king_studios/has_tree/cache_ancestry/metadata.rb

@@ -0,0 +1,82 @@
+# lib/mongoid/sleeping_king_studios/has_tree/cache_ancestry/metadata.rb
+
+require 'mongoid/sleeping_king_studios/concern/metadata'
+
+module Mongoid::SleepingKingStudios
+  module HasTree
+    module CacheAncestry
+      # Stores information about a HasTree::CacheAncestry concern.
+      class Metadata < Mongoid::SleepingKingStudios::Concern::Metadata
+        # The name of the children relation for the tree.
+        # 
+        # @return [Symbol] The relation name.
+        def children_name
+          self[:children_name] || :children
+        end # method parent_name
+
+        # @return [Boolean] True if a custom children relation name is set;
+        #   otherwise false.
+        def children_name?
+          !!self[:children_name]
+        end # method children_name?
+
+        # The name of the field used to store ancestor references. If no
+        # foreign key is set, uses the relation name and the field name to
+        # generate a key.
+        # 
+        # @return [Symbol] The field name.
+        def foreign_key
+          self[:foreign_key] || :"#{relation_name.to_s.singularize}_ids"
+        end # method foreign_key
+
+        # The name of the field used to store the tree's parent relation.
+        # 
+        # @return [Symbol] The method name.
+        def parent_foreign_key
+          :"#{parent_name}_id"
+        end # method parent_foreign_key
+
+        # The writer for the tree's parent relation id.
+        # 
+        # @return [Symbol] The method name.
+        def parent_foreign_key_writer
+          :"#{parent_name}_id="
+        end # method parent_foreign_key_writer
+
+        # The name of the parent relation for the tree.
+        # 
+        # @return [Symbol] The relation name.
+        def parent_name
+          self[:parent_name] || :parent
+        end # method parent_name
+
+        # @return [Boolean] True if a custom children relation name is set;
+        #   otherwise false.
+        def parent_name?
+          !!self[:parent_name]
+        end # method parent_name?
+
+        # The writer for the tree's parent relation.
+        # 
+        # @return [Symbol] The method name.
+        def parent_writer
+          :"#{parent_name}="
+        end # method parent_name
+
+        # The name of the tree's ancestors method. If no relation name is set,
+        # defaults to :ancestors.
+        # 
+        # @return [Symbol] The relation name.
+        def relation_name
+          fetch(:relation_name, :ancestors)
+        end # method relation_name
+
+        # @return [Boolean] True if a custom relation name is set; otherwise
+        #   false.
+        def relation_name?
+          !!self[:relation_name]
+        end # method relation_name?
+      end # class
+    end # module
+  end # module
+end # module

data/lib/mongoid/sleeping_king_studios/has_tree/children/metadata.rb

@@ -0,0 +1,40 @@
+# lib/mongoid/sleeping_king_studios/has_tree/children/metadata.rb
+
+require 'mongoid/sleeping_king_studios/concern/metadata'
+
+module Mongoid::SleepingKingStudios
+  module HasTree
+    module Children
+      # Stores information about a HasTree concern's children relation.
+      class Metadata < Mongoid::SleepingKingStudios::Concern::Metadata
+        # The name of the tree's parent relation. If no relation name is set,
+        # defaults to :parent.
+        # 
+        # @return [Symbol] The relation name.
+        def inverse_of
+          fetch(:inverse_of, :parent)
+        end # method inverse_of
+
+        # @return [Boolean] True if a custom inverse relation name is set;
+        #   otherwise false.
+        def inverse_of?
+          !!self[:inverse_of]
+        end # method inverse_of?
+
+        # The name of the tree's children relation. If no relation name is set,
+        # defaults to :children.
+        # 
+        # @return [Symbol] The relation name.
+        def relation_name
+          fetch(:relation_name, :children)
+        end # method relation_name
+
+        # @return [Boolean] True if a custom relation name is set; otherwise
+        #   false.
+        def relation_name?
+          !!self[:relation_name]
+        end # method relation_name?
+      end # class
+    end # module
+  end # module
+end # module

data/lib/mongoid/sleeping_king_studios/has_tree/errors.rb

@@ -6,17 +6,18 @@ module Mongoid::SleepingKingStudios
   module HasTree
     module Errors
       class MissingAncestor < Mongoid::SleepingKingStudios::Error
-        def initialize ancestor_id
+        def initialize relation_name, ancestor_id
           message = Array === ancestor_id ?
-            'ancestors with ids' :
-            'ancestor with id'
+            "#{relation_name.to_s.pluralize} with ids" :
+            "#{relation_name.to_s.singularize} with id"
           super "unable to find #{message} #{ancestor_id.inspect}"
         end # constructor
       end # class
 
       class UnexpectedAncestor < Mongoid::SleepingKingStudios::Error
-        def initialize expected_id, received_id
-          super "expected ancestor with id #{expected_id.inspect}, but received id #{received_id.inspect}"
+        def initialize relation_name, expected_id, received_id
+          message = "expected #{relation_name.to_s.singularize} with id"
+          super "#{message} #{expected_id.inspect}, but received id #{received_id.inspect}"
         end # constructor
       end # class
     end # module Errors