mongoid 2.0.0.beta.20 → 2.0.0.rc.1

data/lib/mongoid/relations/referenced/one.rb

@@ -0,0 +1,204 @@
+# encoding: utf-8
+module Mongoid # :nodoc:
+  module Relations #:nodoc:
+    module Referenced #:nodoc:
+
+      # This class defines the behaviour for all relations that are a
+      # one-to-one between documents in different collections.
+      class One < Relations::One
+
+        # Binds the base object to the inverse of the relation. This is so we
+        # are referenced to the actual objects themselves and dont hit the
+        # database twice when setting the relations up.
+        #
+        # This is called after first creating the relation, or if a new object
+        # is set on the relation.
+        #
+        # @example Bind the relation.
+        #   person.game.bind(:continue => false)
+        #
+        # @param [ Hash ] options The options to bind with.
+        #
+        # @option options [ true, false ] :building Are we in build mode?
+        # @option options [ true, false ] :continue Continue binding the
+        #   inverse?
+        #
+        # @since 2.0.0.rc.1
+        def bind(options = {})
+          binding.bind(options)
+          target.save if base.persisted? && !options[:building]
+        end
+
+        # Instantiate a new references_one relation. Will set the foreign key
+        # and the base on the inverse object.
+        #
+        # @example Create the new relation.
+        #   Referenced::One.new(base, target, metadata)
+        #
+        # @param [ Document ] base The document this relation hangs off of.
+        # @param [ Document ] target The target (child) of the relation.
+        # @param [ Metadata ] metadata The relation's metadata.
+        def initialize(base, target, metadata)
+          init(base, target, metadata)
+        end
+
+        # Removes the association between the base document and the target
+        # document by deleting the foreign key and the reference, orphaning
+        # the target document in the process.
+        #
+        # @example Nullify the relation.
+        #   person.game.nullify
+        #
+        # @since 2.0.0.rc.1
+        def nullify
+          target.send(metadata.foreign_key_setter, nil)
+          target.send(:remove_instance_variable, "@#{metadata.inverse(target)}")
+          base.send(:remove_instance_variable, "@#{metadata.name}")
+          target.save
+        end
+
+        # Unbinds the base object to the inverse of the relation. This occurs
+        # when setting a side of the relation to nil.
+        #
+        # Will delete the object if necessary.
+        #
+        # @example Unbind the relation.
+        #   person.game.unbind(name, :continue => true)
+        #
+        # @param [ Document ] old_target The previous target of the relation.
+        # @param [ Hash ] options The options to bind with.
+        #
+        # @option options [ true, false ] :building Are we in build mode?
+        # @option options [ true, false ] :continue Continue binding the
+        #   inverse?
+        #
+        # @since 2.0.0.rc.1
+        def unbind(old_target, options = {})
+          binding(old_target).unbind(options)
+          old_target.delete if base.persisted? && !old_target.destroyed?
+        end
+
+        private
+
+        # Instantiate the binding associated with this relation.
+        #
+        # @example Get the binding.
+        #   relation.binding([ address ])
+        #
+        # @param [ Document ] new_target The new target of the relation.
+        #
+        # @return [ Binding ] The binding object.
+        def binding(new_target = nil)
+          Bindings::Referenced::One.new(base, new_target || target, metadata)
+        end
+
+        class << self
+
+          # Return the builder that is responsible for generating the documents
+          # that will be used by this relation.
+          #
+          # @example Get the builder.
+          #   Referenced::One.builder(meta, object)
+          #
+          # @param [ Metadata ] meta The metadata of the relation.
+          # @param [ Document, Hash ] object A document or attributes to build
+          #   with.
+          #
+          # @return [ Builder ] A new builder object.
+          #
+          # @since 2.0.0.rc.1
+          def builder(meta, object)
+            Builders::Referenced::One.new(meta, object)
+          end
+
+          # Returns true if the relation is an embedded one. In this case
+          # always false.
+          #
+          # @example Is this relation embedded?
+          #   Referenced::One.embedded?
+          #
+          # @return [ false ] Always false.
+          #
+          # @since 2.0.0.rc.1
+          def embedded?
+            false
+          end
+
+          # Get the default value for the foreign key.
+          #
+          # @example Get the default.
+          #   Referenced::One.foreign_key_default
+          #
+          # @return [ nil ] Always nil.
+          #
+          # @since 2.0.0.rc.1
+          def foreign_key_default
+            nil
+          end
+
+          # Returns the suffix of the foreign key field, either "_id" or "_ids".
+          #
+          # @example Get the suffix for the foreign key.
+          #   Referenced::One.foreign_key_suffix
+          #
+          # @return [ String ] "_id"
+          #
+          # @since 2.0.0.rc.1
+          def foreign_key_suffix
+            "_id"
+          end
+
+          # Returns the macro for this relation. Used mostly as a helper in
+          # reflection.
+          #
+          # @example Get the macro.
+          #   Referenced::One.macro
+          #
+          # @return [ Symbol ] :references_one.
+          def macro
+            :references_one
+          end
+
+          # Return the nested builder that is responsible for generating the documents
+          # that will be used by this relation.
+          #
+          # @example Get the nested builder.
+          #   Referenced::One.builder(attributes, options)
+          #
+          # @param [ Metadata ] metadata The relation metadata.
+          # @param [ Hash ] attributes The attributes to build with.
+          # @param [ Hash ] options The options for the builder.
+          #
+          # @option options [ true, false ] :allow_destroy Can documents be
+          #   deleted?
+          # @option options [ Integer ] :limit Max number of documents to
+          #   create at once.
+          # @option options [ Proc, Symbol ] :reject_if If documents match this
+          #   option then they are ignored.
+          # @option options [ true, false ] :update_only Only existing documents
+          #   can be modified.
+          #
+          # @return [ NestedBuilder ] A newly instantiated nested builder object.
+          #
+          # @since 2.0.0.rc.1
+          def nested_builder(metadata, attributes, options)
+            Builders::NestedAttributes::One.new(metadata, attributes, options)
+          end
+
+          # Tells the caller if this relation is one that stores the foreign
+          # key on its own objects.
+          #
+          # @example Does this relation store a foreign key?
+          #   Referenced::One.stores_foreign_key?
+          #
+          # @return [ false ] Always false.
+          #
+          # @since 2.0.0.rc.1
+          def stores_foreign_key?
+            false
+          end
+        end
+      end
+    end
+  end
+end

data/lib/mongoid/relations/reflections.rb

@@ -0,0 +1,45 @@
+# encoding: utf-8
+module Mongoid # :nodoc:
+  module Relations #:nodoc:
+
+    # The reflections module provides convenience methods that can retrieve
+    # useful information about associations.
+    module Reflections
+      extend ActiveSupport::Concern
+
+      included do
+
+        delegate \
+          :reflect_on_association,
+          :reflect_on_all_associations, :to => "self.class"
+      end
+
+      module ClassMethods #:nodoc
+
+        # Returns the relation metadata for the supplied name.
+        #
+        # @example Find relation metadata by name.
+        #   Person.reflect_on_association(:addresses)
+        #
+        # @param [ String, Symbol ] name The name of the relation to find.
+        #
+        # @return [ Metadata ] The matching relation metadata.
+        def reflect_on_association(name)
+          relations[name.to_s]
+        end
+
+        # Returns all relation metadata for the supplied macros.
+        #
+        # @example Find multiple relation metadata by macro.
+        #   Person.reflect_on_all_associations(:embeds_many)
+        #
+        # @param [ Array<String, Symbol> ] *macros The relation macros.
+        #
+        # @return [ Array<Metadata> ] The matching relation metadata.
+        def reflect_on_all_associations(*macros)
+          relations.values.select { |meta| macros.include?(meta.macro) }
+        end
+      end
+    end
+  end
+end

data/lib/mongoid/safe.rb

@@ -1,10 +1,20 @@
 # encoding: utf-8
 module Mongoid #:nodoc:
-  module Safe #:nodoc:
+
+  # Contains behaviour for determining if Mongoid is in safe mode.
+  module Safe
+
     # Determine based on configuration if we are persisting in safe mode or
     # not.
     #
     # The query option will always override the global configuration.
+    #
+    # @example Are we in safe mode?
+    #   document.safe_mode?(:safe => true)
+    #
+    # @param [ Hash ] options Persistence options.
+    #
+    # @return [ true, false ] True if in safe mode, false if not.
     def safe_mode?(options)
       safe = options[:safe]
       safe.nil? ? Mongoid.persist_in_safe_mode : safe

data/lib/mongoid/safety.rb

@@ -9,14 +9,20 @@ module Mongoid #:nodoc:
 
     # Execute the following class-level persistence operation in safe mode.
     #
-    # Example:
+    # @example Upsert in safe mode.
+    #   person.safely.upsert
     #
-    # <tt>person.safely.upsert</tt>
-    # <tt>person.safely(:w => 2, :fsync => true).destroy</tt>
+    # @example Destroy in safe mode with w and fsync options.
+    #   person.safely(:w => 2, :fsync => true).destroy
     #
-    # Returns:
+    # @param [ Hash ] options The safe mode options.
     #
-    # A +Proxy+ to the +Document+.
+    # @option options [ Integer ] :w The number of nodes to write to.
+    # @option options [ Integer ] :wtimeout Time to wait for return from all
+    #   nodes.
+    # @option options [ true, false ] :fsync Should a fsync occur.
+    #
+    # @return [ Proxy ] The safety proxy.
     def safely(safety = true)
       Proxy.new(self, safety)
     end
@@ -25,14 +31,20 @@ module Mongoid #:nodoc:
 
       # Execute the following class-level persistence operation in safe mode.
       #
-      # Example:
+      # @example Create in safe mode.
+      #   Person.safely.create(:name => "John")
+      #
+      # @example Delete all in safe mode with options.
+      #   Person.safely(:w => 2, :fsync => true).delete_all
       #
-      # <tt>Person.safely.create(:name => "John")</tt>
-      # <tt>Person.safely(:w => 2, :fsync => true).delete_all</tt>
+      # @param [ Hash ] options The safe mode options.
       #
-      # Returns:
+      # @option options [ Integer ] :w The number of nodes to write to.
+      # @option options [ Integer ] :wtimeout Time to wait for return from all
+      #   nodes.
+      # @option options [ true, false ] :fsync Should a fsync occur.
       #
-      # A +Proxy+ to the +Document+ class.
+      # @return [ Proxy ] The safety proxy.
       def safely(safety = true)
         Proxy.new(self, safety)
       end
@@ -50,132 +62,145 @@ module Mongoid #:nodoc:
 
       attr_reader :target, :safety_options
 
-      # Create the new +Proxy+.
+      # Create a new +Document+. This will instantiate a new document and
+      # insert it in a single call. Will always return the document
+      # whether save passed or not.
       #
-      # Options:
+      # @example Safely create a document.
+      #   Person.safely.create(:title => "Mr")
       #
-      # target: Either the class or the instance.
-      # safety_options: true or a hash of options
-      def initialize(target, safety_options)
-        @target = target
-        @safety_options = safety_options
+      # @param [ Hash ] attributes The attributes to create with.
+      #
+      # @return [ Document ] The new document.
+      def create(attributes = {})
+        target.new(attributes).tap { |doc| doc.insert(:safe => safety_options) }
       end
 
-      # We will use method missing to proxy calls to the target.
+      # Create a new +Document+. This will instantiate a new document and
+      # insert it in a single call. Will always return the document
+      # whether save passed or not, and if validation fails an error will be
+      # raise.
       #
-      # Example:
+      # @example Safely create a document.
+      #   Person.safely.create!(:title => "Mr")
       #
-      # <tt>person.safely.save</tt>
-      def method_missing(*args)
-        name = args[0]
-        attributes = args[1] || {}
-        @target.send(name, attributes.merge(:safe => safety_options))
-      end
-
-      # Increment the field by the provided value, else if it doesn't exists set
-      # it to that value.
+      # @param [ Hash ] attributes The attributes to create with.
       #
-      # Options:
+      # @raise [ Errors::Validations ] If validation failed.
       #
-      # field: The field to increment.
-      # value: The value to increment by.
-      # options: Options to pass through to the driver.
-      def inc(field, value, options = {})
-        @target.inc(field, value, :safe => safety_options)
+      # @return [ Document ] If validation passed.
+      def create!(attributes = {})
+        target.new(attributes).tap do |document|
+          fail_validate!(document) if document.insert(:safe => safety_options).errors.any?
+        end
       end
 
-      # Update the +Document+ attributes in the datbase.
+      # Delete all documents given the supplied conditions. If no conditions
+      # are passed, the entire collection will be dropped for performance
+      # benefits. Does not fire any callbacks.
       #
-      # Example:
+      # @example Delete all documents.
+      #   Person.safely.delete_all
       #
-      # <tt>document.update_attributes(:title => "Sir")</tt>
+      # @example Conditionally delete all documents.
+      #   Person.safely.delete_all(:conditions => { :title => "Sir" })
       #
-      # Returns:
+      # @param [ Hash ] conditions The conditions to delete with.
       #
-      # +true+ if validation passed, +false+ if not.
-      def update_attributes(attributes = {})
-        @target.write_attributes(attributes)
-        @target.update(:safe => safety_options)
+      # @return [ Integer ] The number of documents deleted.
+      def delete_all(conditions = {})
+        Mongoid::Persistence::RemoveAll.new(
+          target,
+          { :validate => false, :safe => safety_options },
+          conditions[:conditions] || {}
+        ).persist
       end
 
-      # Update the +Document+ attributes in the datbase.
+      # destroy all documents given the supplied conditions. If no conditions
+      # are passed, the entire collection will be dropped for performance
+      # benefits. Fires the destroy callbacks if conditions were passed.
       #
-      # Example:
+      # @example destroy all documents.
+      #   Person.safely.destroy_all
       #
-      # <tt>document.update_attributes(:title => "Sir")</tt>
+      # @example Conditionally destroy all documents.
+      #   Person.safely.destroy_all(:conditions => { :title => "Sir" })
       #
-      # Returns:
+      # @param [ Hash ] conditions The conditions to destroy with.
       #
-      # +true+ if validation passed, raises an error if not
-      def update_attributes!(attributes = {})
-        @target.write_attributes(attributes)
-        result = update(:safe => safety_options)
-        @target.class.fail_validate!(self) unless result
-        result
+      # @return [ Integer ] The number of documents destroyd.
+      def destroy_all(conditions = {})
+        documents = target.all(conditions)
+        documents.count.tap do |count|
+          documents.each { |doc| doc.destroy(:safe => safety_options) }
+        end
       end
 
-      # Create a new +Document+. This will instantiate a new document and
-      # insert it in a single call. Will always return the document
-      # whether save passed or not.
-      #
-      # Example:
+      # Increment the field by the provided value, else if it doesn't exists set
+      # it to that value.
       #
-      # <tt>Person.create(:title => "Mr")</tt>
+      # @example Safely increment a field.
+      #   person.safely.inc(:age, 1)
       #
-      # Returns: the +Document+.
-      def create(attributes = {})
-        @target.new(attributes).tap { |doc| doc.insert(:safe => safety_options) }
+      # @param [ Symbol, String ] field The field to increment.
+      # @param [ Integer ] value The value to increment by.
+      # @param [ Hash ] options Options to pass through to the driver.
+      def inc(field, value, options = {})
+        target.inc(field, value, :safe => safety_options)
       end
 
-      # Create a new +Document+. This will instantiate a new document and
-      # insert it in a single call. Will always return the document
-      # whether save passed or not, and if validation fails an error will be
-      # raise.
+      # Create the new +Proxy+.
+      #
+      # @example Create the proxy.
+      #   Proxy.new(document, :w => 3)
       #
-      # Example:
+      # @param [ Document, Class ] target Either the class or the instance.
+      # @param [ true, Hash ] safety_options The options.
+      def initialize(target, safety_options)
+        @target = target
+        @safety_options = safety_options
+      end
+
+      # We will use method missing to proxy calls to the target.
       #
-      # <tt>Person.create!(:title => "Mr")</tt>
+      # @example Save safely.
+      #   person.safely.save
       #
-      # Returns: the +Document+.
-      def create!(attributes = {})
-        document = @target.new(attributes)
-        fail_validate!(document) if document.insert(:safe => safety_options).errors.any?
-        document
+      # @param [ Array ] *args The arguments to pass on.
+      def method_missing(*args)
+        name = args[0]
+        attributes = args[1] || {}
+        target.send(name, attributes.merge(:safe => safety_options))
       end
 
-      # Delete all documents given the supplied conditions. If no conditions
-      # are passed, the entire collection will be dropped for performance
-      # benefits. Does not fire any callbacks.
+      # Update the +Document+ attributes in the datbase.
       #
-      # Example:
+      # @example Safely update attributes.
+      #   person.safely.update_attributes(:title => "Sir")
       #
-      # <tt>Person.delete_all(:conditions => { :title => "Sir" })</tt>
-      # <tt>Person.delete_all</tt>
+      # @param [ Hash ] attributes The attributes to update.
       #
-      # Returns: true or raises an error.
-      def delete_all(conditions = {})
-        Mongoid::Persistence::RemoveAll.new(
-          @target,
-          { :validate => false, :safe => safety_options },
-          conditions[:conditions] || {}
-        ).persist
+      # @return [ true, false ] Whether the document was saved.
+      def update_attributes(attributes = {})
+        target.write_attributes(attributes)
+        target.update(:safe => safety_options)
       end
 
-      # Delete all documents given the supplied conditions. If no conditions
-      # are passed, the entire collection will be dropped for performance
-      # benefits. Fires the destroy callbacks if conditions were passed.
+      # Update the +Document+ attributes in the datbase.
       #
-      # Example:
+      # @example Safely update attributes.
+      #   person.safely.update_attributes(:title => "Sir")
       #
-      # <tt>Person.destroy_all(:conditions => { :title => "Sir" })</tt>
-      # <tt>Person.destroy_all</tt>
+      # @param [ Hash ] attributes The attributes to update.
       #
-      # Returns: true or raises an error.
-      def destroy_all(conditions = {})
-        documents = @target.all(conditions)
-        count = documents.count
-        documents.each { |doc| doc.destroy(:safe => safety_options) }
-        count
+      # @raise [ Errors::Validations ] If validation failed.
+      #
+      # @return [ true ] If the document was saved.
+      def update_attributes!(attributes = {})
+        target.write_attributes(attributes)
+        update(:safe => safety_options).tap do |result|
+          target.class.fail_validate!(self) unless result
+        end
       end
     end
   end