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

data/lib/mongoid/identity.rb

@@ -1,47 +1,89 @@
 # encoding: utf-8
 module Mongoid #:nodoc:
   class Identity #:nodoc:
-    # Create the identity for the +Document+.
-    #
-    # The id will be set in either in the form of a Mongo
-    # +ObjectID+ or a composite key set up by defining a key on the document.
+
+    attr_reader :document
+
+    # Create the identity for the document. The id will be set in either in
+    # the form of a Mongo object id or a composite key set up by defining
+    # a key on the document. The _type will be set to the document's class
+    # name.
     #
-    # The _type will be set to the document's class name.
+    # @example Create the id and set the type.
+    #   identity.create
     def create
-      identify!; type!
+      identify and type
     end
 
     # Create the new identity generator - this will be expanded in the future
     # to support pk generators.
     #
-    # Options:
+    # @example
+    #   Identity.new(document)
+    #
+    # @param [ Document ] document The document to generate an id for.
     #
-    # document: The document to generate an id for.
+    # @return [ Identity ] The new identity object.
     def initialize(document)
       @document = document
     end
 
-    protected
-    # Return the proper id for the document.
+    private
+
+    # Return the proper id for the document. Will be an object id or its string
+    # representation depending on the configuration.
+    #
+    # @example Generate the id.
+    #   identity.generate_id
+    #
+    # @return [ Object ] The bson object id or its string equivalent.
     def generate_id
       id = BSON::ObjectId.new
-      @document.using_object_ids? ? id : id.to_s
+      document.using_object_ids? ? id : id.to_s
     end
 
-    # Set the id for the document.
-    def identify!
-      @document.id = compose.join(" ").identify if @document.primary_key
-      @document.id = generate_id if @document.id.blank?
+    # Sets the id on the document. Will either set a newly generated id or
+    # build the composite key.
+    #
+    # @example Set the id.
+    #   identity.identify
+    def identify
+      document.id = compose.join(" ").identify if document.primary_key
+      document.id = generate_id if document.id.blank?
     end
 
-    # Set the _type field on the @document.
-    def type!
-      @document._type = @document.class.name if @document.hereditary? || @document.class.descendants.any?
+    # Set the _type field on the document if the document is hereditary or in a
+    # polymorphic relation.
+    #
+    # @example Set the type.
+    #   identity.type
+    def type
+      document._type = document.class.name if typed?
     end
 
-    # Generates the composite key for a @document.ment.
+    # Generates the array of keys to build the id.
+    #
+    # @example Build the array for the keys.
+    #   identity.compose.
+    #
+    # @return [ Array<Object> ] The array of keys.
     def compose
-      @document.primary_key.collect { |key| @document.attributes[key] }.reject { |val| val.nil? }
+      document.primary_key.collect do |key|
+        document.attributes[key]
+      end.reject { |val| val.nil? }
+    end
+
+    # Determines if the document stores the type information. This is if it is
+    # in a hierarchy, has subclasses, or is in a polymorphic relation.
+    #
+    # @example Check if the document is typed.
+    #   identity.typed?
+    #
+    # @return [ true, false ] True if typed, false if not.
+    def typed?
+      document.hereditary? ||
+        document.class.descendants.any? ||
+        document.polymorphic?
     end
   end
 end

data/lib/mongoid/inspection.rb

@@ -0,0 +1,58 @@
+# encoding: utf-8
+module Mongoid #:nodoc
+  module Inspection #:nodoc
+
+    # Returns the class name plus its attributes. If using dynamic fields will
+    # include those as well.
+    #
+    # Example:
+    #
+    # <tt>person.inspect</tt>
+    #
+    # Returns:
+    #
+    # A nice pretty string to look at.
+    def inspect
+      inspection = []
+      inspection.concat(inspect_fields).concat(inspect_dynamic_fields)
+      "#<#{self.class.name} _id: #{id}, #{inspection * ', '}>"
+    end
+
+    private
+
+    # Get an array of inspected fields for the document.
+    #
+    # Example:
+    #
+    # <tt>inspect_fields</tt>
+    #
+    # Returns:
+    #
+    # An array of pretty printed field values.
+    def inspect_fields
+      fields.map do |name, field|
+        "#{name}: #{@attributes[name].inspect}"
+      end
+    end
+
+    # Get an array of inspected dynamic fields for the document.
+    #
+    # Example:
+    #
+    # <tt>inspect_dynamic_fields</tt>
+    #
+    # Returns:
+    #
+    # An array of pretty printed dynamic field values.
+    def inspect_dynamic_fields
+      if Mongoid.allow_dynamic_fields
+        keys = @attributes.keys - fields.keys - relations.keys - ["_id", "_type"]
+        return keys.map do |name|
+          "#{name}: #{@attributes[name].inspect}"
+        end
+      else
+        []
+      end
+    end
+  end
+end

data/lib/mongoid/matchers.rb

@@ -12,9 +12,20 @@ require "mongoid/matchers/nin"
 require "mongoid/matchers/size"
 
 module Mongoid #:nodoc:
+
+  # This module contains all the behavior for ruby implementations of MongoDB
+  # selectors.
   module Matchers
+
     # Determines if this document has the attributes to match the supplied
     # MongoDB selector. Used for matching on embedded associations.
+    #
+    # @example Does the document match?
+    #   document.matches?(:title => { "$in" => [ "test" ] })
+    #
+    # @param [ Hash ] selector The MongoDB selector.
+    #
+    # @return [ true, false ] True if matches, false if not.
     def matches?(selector)
       selector.each_pair do |key, value|
         return false unless matcher(key, value).matches?(value)
@@ -22,8 +33,17 @@ module Mongoid #:nodoc:
     end
 
     protected
+
     # Get the matcher for the supplied key and value. Will determine the class
     # name from the key.
+    #
+    # @example Get the matcher.
+    #   document.matcher(:title, { "$in" => [ "test" ] })
+    #
+    # @param [ Symbol, String ] key The field name.
+    # @param [ Object, Hash ] The value or selector.
+    #
+    # @return [ Matcher ] The matcher.
     def matcher(key, value)
       if value.is_a?(Hash)
         name = "Mongoid::Matchers::#{value.keys.first.gsub("$", "").camelize}"

data/lib/mongoid/multi_database.rb

@@ -0,0 +1,11 @@
+module Mongoid::MultiDatabase
+  extend ActiveSupport::Concern
+
+  module ClassMethods
+
+    def database; @database end
+    def set_database(name)
+      @database = name.to_s
+    end
+  end
+end

data/lib/mongoid/nested_attributes.rb

@@ -0,0 +1,41 @@
+# encoding: utf-8
+module Mongoid #:nodoc:
+  module NestedAttributes
+    extend ActiveSupport::Concern
+
+    module ClassMethods
+
+      # Used when needing to update related models from a parent relation. Can
+      # be used on embedded or referenced relations.
+      #
+      # @example Defining nested attributes.
+      #
+      #   class Person
+      #     include Mongoid::Document
+      #
+      #     embeds_many :addresses
+      #     embeds_one :game
+      #     references_many :posts
+      #
+      #     accepts_nested_attributes_for :addresses, :game, :posts
+      #   end
+      #
+      # @param [ Array<Symbol>, Hash ] *args A list of relation names, followed
+      #   by a hash of options.
+      #
+      # @option *args [ true, false ] :allow_destroy Can deletion occur?
+      # @option *args [ Proc ] :reject_if Block to reject documents with.
+      # @option *args [ Integer ] :limit The max number to create.
+      # @option *args [ true, false ] :update_only Only update existing docs.
+      def accepts_nested_attributes_for(*args)
+        options = args.extract_options!
+        args.each do |name|
+          define_method("#{name}_attributes=") do |attrs|
+            relation = relations[name.to_s]
+            relation.nested_builder(attrs, options).build(self)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/mongoid/paranoia.rb

@@ -84,21 +84,20 @@ module Mongoid #:nodoc:
       # Returns:
       #
       # A +Criteria+ for deleted_at not existing.
-      def criteria
+      def criteria(embedded = false)
         super.where(:deleted_at.exists => false)
       end
-      
+
       # Find deleted documents
       #
       # Examples:
       #
       #   <tt>Person.deleted</tt>  # all deleted employees
       #   <tt>Company.first.employees.deleted</tt>  # works with a join
-      #   <tt>Person.deleted.find("4c188dea7b17235a2a000001").first</tt>  # retrieve by id a deleted person
+      #   <tt>Person.deleted.find("4c188dea7b17235a2a000001").first</tt>
       def deleted
         where(:deleted_at.exists => true)
       end
-      
     end
   end
 end

data/lib/mongoid/paths.rb

@@ -35,7 +35,7 @@ module Mongoid #:nodoc:
     # <tt>address.position</tt>
     def _position
       locator = _index ? (new_record? ? "" : ".#{_index}") : ""
-      embedded? ? "#{_parent._position}#{"." unless _parent._position.blank?}#{@association_name}#{locator}" : ""
+      embedded? ? "#{_parent._position}#{"." unless _parent._position.blank?}#{metadata.name.to_s}#{locator}" : ""
     end
 
     # Get the removal modifier for the document. Will be nil on root

data/lib/mongoid/persistence.rb

@@ -8,116 +8,121 @@ require "mongoid/persistence/remove_embedded"
 require "mongoid/persistence/update"
 
 module Mongoid #:nodoc:
+
   # The persistence module is a mixin to provide database accessor methods for
   # the document. These correspond to the appropriate accessors on a
-  # +Mongo::Collection+ and retain the same DSL.
-  #
-  # Examples:
+  # mongo collection and retain the same DSL.
   #
-  # <tt>document.insert</tt>
-  # <tt>document.update</tt>
-  # <tt>document.upsert</tt>
+  # @example Sample persistence operations.
+  #   document.insert
+  #   document.update
+  #   document.upsert
   module Persistence
     extend ActiveSupport::Concern
 
-    # Remove the +Document+ from the datbase with callbacks.
+    # Remove the document from the datbase with callbacks.
+    #
+    # @example Destroy a document.
+    #   document.destroy
     #
-    # Example:
+    # @param [ Hash ] options Options to pass to destroy.
     #
-    # <tt>document.destroy</tt>
+    # @return [ true, false ] True if successful, false if not.
     def destroy(options = {})
-      run_callbacks(:destroy) { _remove(options) }
+      run_callbacks(:destroy) { remove(options) }
     end
 
-    # Insert a new +Document+ into the database. Will return the document
+    # Insert a new document into the database. Will return the document
     # itself whether or not the save was successful.
     #
-    # Example:
+    # @example Insert a document.
+    #   document.insert
     #
-    # <tt>document.insert</tt>
+    # @param [ Hash ] options Options to pass to insert.
+    #
+    # @return [ Document ] The persisted document.
     def insert(options = {})
       Insert.new(self, options).persist
     end
 
-    # Remove the +Document+ from the datbase.
+    # Remove the document from the datbase.
     #
-    # Example:
+    # @example Remove the document.
+    #   document.remove
     #
-    # <tt>document._remove</tt>
+    # @param [ Hash ] options Options to pass to remove.
     #
-    # TODO: Will get rid of other #remove once observable pattern killed.
-    def _remove(options = {})
+    # @return [ TrueClass ] True.
+    def remove(options = {})
       if Remove.new(self, options).persist
         self.destroyed = true
-        cascading_remove!
+        cascade!
       end; true
     end
-
-    alias :delete :_remove
+    alias :delete :remove
 
     # Save the document - will perform an insert if the document is new, and
-    # update if not. If a validation error occurs a
-    # Mongoid::Errors::Validations error will get raised.
-    #
-    # Example:
+    # update if not. If a validation error occurs an error will get raised.
     #
-    # <tt>document.save!</tt>
+    # @example Save the document.
+    #   document.save!
     #
-    # Returns:
+    # @param [ Hash ] options Options to pass to the save.
     #
-    # +true+ if validation passed, will raise error otherwise.
+    # @return [ true, false ] True if validation passed.
     def save!(options = {})
       self.class.fail_validate!(self) unless upsert; true
     end
 
-    # Update the +Document+ in the datbase.
+    # Update the document in the datbase.
     #
-    # Example:
+    # @example Update an existing document.
+    #   document.update
     #
-    # <tt>document.update</tt>
+    # @param [ Hash ] options Options to pass to update.
+    #
+    # @return [ true, false ] True if succeeded, false if not.
     def update(options = {})
       Update.new(self, options).persist
     end
 
-    # Update the +Document+ attributes in the datbase.
-    #
-    # Example:
+    # Update the document attributes in the datbase.
     #
-    # <tt>document.update_attributes(:title => "Sir")</tt>
+    # @example Update the document's attributes
+    #   document.update_attributes(:title => "Sir")
     #
-    # Returns:
+    # @param [ Hash ] attributes The attributes to update.
     #
-    # +true+ if validation passed, +false+ if not.
+    # @return [ true, false ] True if validation passed, false if not.
     def update_attributes(attributes = {})
       write_attributes(attributes); update
     end
 
-    # Update the +Document+ attributes in the datbase.
-    #
-    # Example:
+    # Update the document attributes in the database and raise an error if
+    # validation failed.
     #
-    # <tt>document.update_attributes(:title => "Sir")</tt>
+    # @example Update the document's attributes.
+    #   document.update_attributes(:title => "Sir")
     #
-    # Returns:
+    # @param [ Hash ] attributes The attributes to update.
     #
-    # +true+ if validation passed, raises an error if not
+    # @return [ true, false ] True if validation passed.
     def update_attributes!(attributes = {})
       write_attributes(attributes)
-      result = update
-      self.class.fail_validate!(self) unless result
-      result
+      update.tap do |result|
+        self.class.fail_validate!(self) unless result
+      end
     end
 
     # Upsert the document - will perform an insert if the document is new, and
     # update if not.
     #
-    # Example:
-    #
-    # <tt>document.upsert</tt>
+    # @example Upsert the document.
+    #   document.upsert
     #
-    # Returns:
+    # @param [ Hash ] options Options to pass to the upsert.
     #
-    # A +Boolean+ for updates.
+    # @return [ true, false ] True is success, false if not.
     def upsert(options = {})
       if new_record?
         insert(options).persisted?
@@ -125,53 +130,35 @@ module Mongoid #:nodoc:
         update(options)
       end
     end
-
-    # Save is aliased so that users familiar with active record can have some
-    # semblance of a familiar API.
-    #
-    # Example:
-    #
-    # <tt>document.save</tt>
     alias :save :upsert
 
-    protected
-
-    # Perform all cascading deletes or destroys.
-    def cascading_remove!
-      cascades.each do |name, option|
-        association = send(name)
-        if association
-          documents = association.target.to_a
-          documents.each { |doc| doc.send(option) }
-        end
-      end
-    end
-
     module ClassMethods #:nodoc:
 
-      # Create a new +Document+. This will instantiate a new document and
+      # 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:
+      # @example Create a new document.
+      #   Person.create(:title => "Mr")
       #
-      # <tt>Person.create(:title => "Mr")</tt>
+      # @param [ Hash ] attributes The attributes to create with.
       #
-      # Returns: the +Document+.
+      # @return [ Document ] The newly created document.
       def create(attributes = {})
-        new(attributes).tap(&:insert)
+        new(attributes).tap(&:save)
       end
 
-      # Create a new +Document+. This will instantiate a new document and
+      # 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 Create a new document.
+      #   Person.create!(:title => "Mr")
       #
-      # <tt>Person.create!(:title => "Mr")</tt>
+      # @param [ Hash ] attributes The attributes to create with.
       #
-      # Returns: the +Document+.
+      # @return [ Document ] The newly created document.
       def create!(attributes = {})
         document = new(attributes)
         fail_validate!(document) if document.insert.errors.any?
@@ -182,12 +169,15 @@ module Mongoid #:nodoc:
       # are passed, the entire collection will be dropped for performance
       # benefits. Does not fire any callbacks.
       #
-      # Example:
+      # @example Delete matching documents from the collection.
+      #   Person.delete_all(:conditions => { :title => "Sir" })
+      #
+      # @example Delete all documents from the collection.
+      #   Person.delete_all
       #
-      # <tt>Person.delete_all(:conditions => { :title => "Sir" })</tt>
-      # <tt>Person.delete_all</tt>
+      # @param [ Hash ] conditions Optional conditions to delete by.
       #
-      # Returns: true or raises an error.
+      # @return [ Integer ] The number of documents deleted.
       def delete_all(conditions = {})
         RemoveAll.new(
           self,
@@ -200,19 +190,28 @@ module Mongoid #:nodoc:
       # are passed, the entire collection will be dropped for performance
       # benefits. Fires the destroy callbacks if conditions were passed.
       #
-      # Example:
+      # @example Destroy matching documents from the collection.
+      #   Person.destroy_all(:conditions => { :title => "Sir" })
+      #
+      # @example Destroy all documents from the collection.
+      #   Person.destroy_all
       #
-      # <tt>Person.destroy_all(:conditions => { :title => "Sir" })</tt>
-      # <tt>Person.destroy_all</tt>
+      # @param [ Hash ] conditions Optional conditions to destroy by.
       #
-      # Returns: true or raises an error.
+      # @return [ Integer ] The number of documents destroyed.
       def destroy_all(conditions = {})
         documents = all(conditions)
-        count = documents.count
-        documents.each { |doc| doc.destroy }; count
+        documents.count.tap do
+          documents.each { |doc| doc.destroy }
+        end
       end
 
       # Raise an error if validation failed.
+      #
+      # @example Raise the validation error.
+      #   Person.fail_validate!(person)
+      #
+      # @param [ Document ] document The document to fail.
       def fail_validate!(document)
         raise Errors::Validations.new(document)
       end