mongoid 2.0.2 → 2.1.0

data/lib/mongoid/errors/document_not_found.rb

@@ -6,9 +6,8 @@ module Mongoid #:nodoc
     # does not exist. If multiple ids were passed then it will display all of
     # those.
     #
-    # Example:
-    #
-    # <tt>DocumentNotFound.new(Person, ["1", "2"])</tt>
+    # @example Create the error.
+    #   DocumentNotFound.new(Person, ["1", "2"])
     class DocumentNotFound < MongoidError
 
       attr_reader :klass, :identifiers
@@ -20,7 +19,7 @@ module Mongoid #:nodoc
         super(
           translate(
             "document_not_found",
-            { :klass => klass.name, :identifiers => @identifiers }
+            { :klass => klass.name, :identifiers => identifiers }
           )
         )
       end

data/lib/mongoid/errors/invalid_collection.rb

@@ -5,9 +5,8 @@ module Mongoid #:nodoc
     # This error is raised when trying to access a Mongo::Collection from an
     # embedded document.
     #
-    # Example:
-    #
-    # <tt>InvalidCollection.new(Address)</tt>
+    # @example Create the error.
+    #   InvalidCollection.new(Address)
     class InvalidCollection < MongoidError
       def initialize(klass)
         super(

data/lib/mongoid/errors/invalid_database.rb

@@ -6,9 +6,8 @@ module Mongoid #:nodoc
     # by attempting to set an object on the db that is not a +Mongo::DB+, or
     # not setting anything at all.
     #
-    # Example:
-    #
-    # <tt>InvalidDatabase.new("Not a DB")</tt>
+    # @example Create the error.
+    #   InvalidDatabase.new("Not a DB")
     class InvalidDatabase < MongoidError
       def initialize(database)
         super(

data/lib/mongoid/errors/invalid_field.rb

@@ -5,9 +5,8 @@ module Mongoid #:nodoc
     # This error is raised when trying to create a field that conflicts with
     # a Mongoid internal attribute or method.
     #
-    # Example:
-    #
-    # <tt>InvalidField.new('collection')</tt>
+    # @example Create the error.
+    #   InvalidField.new('collection')
     class InvalidField < MongoidError
       def initialize(name)
         super(

data/lib/mongoid/errors/invalid_options.rb

@@ -2,14 +2,26 @@
 module Mongoid #:nodoc
   module Errors #:nodoc
 
-    # Raised when invalid options are passed into a constructor or method.
-    #
-    # Example:
-    #
-    # <tt>InvalidOptions.new</tt>
+    # Raised when invalid options are passed to a relation macro.
     class InvalidOptions < MongoidError
-      def initialize(key, options)
-        super(translate(key, options))
+
+      # Instantiate the options error.
+      #
+      # @example Create the error.
+      #   InvalidOptions.new(:name, :polymorphic, [ :as ])
+      #
+      # @param [ Symbol ] name The name of the relation.
+      # @param [ Symbol ] invalid The invalid option.
+      # @param [ Array<Symbol> ] valid The allowed options.
+      #
+      # @since 2.1.0
+      def initialize(name, invalid, valid)
+        super(
+          translate(
+            "invalid_options",
+            { :name => name, :invalid => invalid, :valid => valid.join(', ') }
+          )
+        )
       end
     end
   end

data/lib/mongoid/errors/invalid_type.rb

@@ -5,9 +5,8 @@ module Mongoid #:nodoc
     # Raised when trying to get or set a value for a defined field, where the
     # type of the object does not match the defined field type.
     #
-    # Example:
-    #
-    # <tt>InvalidType.new(Array, "Not an Array")</tt>
+    # @example Create the error.
+    #   InvalidType.new(Array, "Not an Array")
     class InvalidType < MongoidError
       def initialize(klass, value)
         super(

data/lib/mongoid/errors/mongoid_error.rb

@@ -11,14 +11,13 @@ module Mongoid #:nodoc
       # Given the key of the specific error and the options hash, translate the
       # message.
       #
-      # Options:
+      # @example Translate the message.
+      #   error.translate("errors", :key => value)
       #
-      # key: The key of the error in the locales.
-      # options: The objects to pass to create the message.
+      # @param [ String ] key The key of the error in the locales.
+      # @param [ Hash ] options The objects to pass to create the message.
       #
-      # Returns:
-      #
-      # A localized error message string.
+      # @return [ String ] A localized error message string.
       def translate(key, options)
         ::I18n.translate("#{BASE_KEY}.#{key}", options)
       end

data/lib/mongoid/errors/too_many_nested_attribute_records.rb

@@ -4,9 +4,8 @@ module Mongoid #:nodoc
     # This error is raised when trying to create set nested records above the
     # specified :limit
     #
-    # Example:
-    #
-    #<tt>TooManyNestedAttributeRecords.new('association', limit)
+    # @example Create the error.
+    #   TooManyNestedAttributeRecords.new('association', limit)
     class TooManyNestedAttributeRecords < MongoidError
       def initialize(association, limit)
         super(

data/lib/mongoid/errors/unsupported_version.rb

@@ -4,9 +4,8 @@ module Mongoid #:nodoc
 
     # Raised when the database version is not supported by Mongoid.
     #
-    # Example:
-    #
-    # <tt>UnsupportedVersion.new(Mongo::ServerVersion.new("1.3.1"))</tt>
+    # @example Create the error.
+    #   UnsupportedVersion.new(Mongo::ServerVersion.new("1.3.1"))
     class UnsupportedVersion < MongoidError
       def initialize(version)
         super(

data/lib/mongoid/errors/validations.rb

@@ -5,9 +5,8 @@ module Mongoid #:nodoc
     # Raised when a persistence method ending in ! fails validation. The message
     # will contain the full error messages from the +Document+ in question.
     #
-    # Example:
-    #
-    # <tt>Validations.new(person.errors)</tt>
+    # @example Create the error.
+    #   Validations.new(person.errors)
     class Validations < MongoidError
       attr_reader :document
       def initialize(document)

data/lib/mongoid/extensions.rb

@@ -1,80 +1,33 @@
 # encoding: utf-8
-require "mongoid/extensions/time_conversions"
-require "mongoid/extensions/array/conversions"
-require "mongoid/extensions/array/parentization"
-require "mongoid/extensions/set/conversions"
-require "mongoid/extensions/big_decimal/conversions"
-require "mongoid/extensions/binary/conversions"
-require "mongoid/extensions/boolean/conversions"
-require "mongoid/extensions/date/conversions"
-require "mongoid/extensions/datetime/conversions"
+require "mongoid/extensions/array/deletion"
 require "mongoid/extensions/false_class/equality"
-require "mongoid/extensions/float/conversions"
-require "mongoid/extensions/hash/conversions"
 require "mongoid/extensions/hash/criteria_helpers"
 require "mongoid/extensions/hash/scoping"
-require "mongoid/extensions/integer/conversions"
 require "mongoid/extensions/nil/collectionization"
 require "mongoid/extensions/object/checks"
-require "mongoid/extensions/object/conversions"
 require "mongoid/extensions/object/reflections"
 require "mongoid/extensions/object/yoda"
 require "mongoid/extensions/proc/scoping"
-require "mongoid/extensions/range/conversions"
 require "mongoid/extensions/string/conversions"
 require "mongoid/extensions/string/inflections"
 require "mongoid/extensions/symbol/inflections"
-require "mongoid/extensions/symbol/conversions"
 require "mongoid/extensions/true_class/equality"
 require "mongoid/extensions/object_id/conversions"
 
 class Array #:nodoc
-  include Mongoid::Extensions::Array::Conversions
-  include Mongoid::Extensions::Array::Parentization
+  include Mongoid::Extensions::Array::Deletion
 end
 
-class Set #:nodoc
-  include Mongoid::Extensions::Set::Conversions
-end
-
-class BigDecimal #:nodoc
-  extend Mongoid::Extensions::BigDecimal::Conversions
-end
-
-class Binary #:nodoc
-  extend Mongoid::Extensions::Binary::Conversions
-end
-
-class Boolean #:nodoc
-  include Mongoid::Extensions::Boolean::Conversions
-end
-
-class DateTime #:nodoc
-  extend Mongoid::Extensions::TimeConversions
-  extend Mongoid::Extensions::DateTime::Conversions
-end
-
-class Date #:nodoc
-  extend Mongoid::Extensions::TimeConversions
-  extend Mongoid::Extensions::Date::Conversions
-end
+class Binary; end #:nodoc:
+class Boolean; end #:nodoc:
 
 class FalseClass #:nodoc
   include Mongoid::Extensions::FalseClass::Equality
 end
 
-class Float #:nodoc
-  extend Mongoid::Extensions::Float::Conversions
-end
-
 class Hash #:nodoc
   include Mongoid::Extensions::Hash::CriteriaHelpers
   include Mongoid::Extensions::Hash::Scoping
-  include Mongoid::Extensions::Hash::Conversions
-end
-
-class Integer #:nodoc
-  extend Mongoid::Extensions::Integer::Conversions
 end
 
 class NilClass #:nodoc
@@ -83,7 +36,6 @@ end
 
 class Object #:nodoc:
   include Mongoid::Extensions::Object::Checks
-  include Mongoid::Extensions::Object::Conversions
   include Mongoid::Extensions::Object::Reflections
   include Mongoid::Extensions::Object::Yoda
 end
@@ -92,23 +44,14 @@ class Proc #:nodoc:
   include Mongoid::Extensions::Proc::Scoping
 end
 
-class Range
-  include Mongoid::Extensions::Range::Conversions
-end
-
 class String #:nodoc
-  include Mongoid::Extensions::String::Inflections
   include Mongoid::Extensions::String::Conversions
+  include Mongoid::Extensions::String::Inflections
 end
 
 class Symbol #:nodoc
   remove_method :size if instance_methods.include? :size # temporal fix for ruby 1.9
   include Mongoid::Extensions::Symbol::Inflections
-  include Mongoid::Extensions::Symbol::Conversions
-end
-
-class Time #:nodoc
-  extend Mongoid::Extensions::TimeConversions
 end
 
 class TrueClass #:nodoc
@@ -120,4 +63,7 @@ class BSON::ObjectId #:nodoc
   def as_json(options = nil)
     to_s
   end
+  def to_xml(options = nil)
+    ActiveSupport::XmlMini.to_tag(options[:root], self.to_s, options)
+  end
 end

data/lib/mongoid/extensions/array/deletion.rb

@@ -0,0 +1,29 @@
+# encoding: utf-8
+module Mongoid #:nodoc:
+  module Extensions #:nodoc:
+    module Array #:nodoc:
+
+      # This module contains deletion helpers for arrays.
+      module Deletion
+
+        # Delete the first object in the array that is equal to the supplied
+        # object and return it. This is much faster than performing a standard
+        # delete for large arrays ince it attempt to delete multiple in the
+        # other.
+        #
+        # @example Delete the first object.
+        #   [ "1", "2", "1" ].delete_one("1")
+        #
+        # @param [ Object ] object The object to delete.
+        #
+        # @return [ Object ] The deleted object.
+        #
+        # @since 2.1.0
+        def delete_one(object)
+          position = index(object)
+          position ? delete_at(position) : nil
+        end
+      end
+    end
+  end
+end

data/lib/mongoid/extensions/false_class/equality.rb

@@ -2,7 +2,20 @@
 module Mongoid #:nodoc:
   module Extensions #:nodoc:
     module FalseClass #:nodoc:
-      module Equality #:nodoc:
+
+      # Adds equality hooks for false values.
+      module Equality
+
+        # Is the passed value a boolean?
+        #
+        # @example Is the value a boolean type?
+        #   false.is_a?(Boolean)
+        #
+        # @param [ Class ] other The class to check.
+        #
+        # @return [ true, false ] If the other is a boolean.
+        #
+        # @since 1.0.0
         def is_a?(other)
           return true if other.name == "Boolean"
           super(other)

data/lib/mongoid/extensions/hash/criteria_helpers.rb

@@ -2,19 +2,30 @@
 module Mongoid #:nodoc:
   module Extensions #:nodoc:
     module Hash #:nodoc:
-      module CriteriaHelpers #:nodoc:
+
+      # Expands complex criterion into mongodb selectors.
+      module CriteriaHelpers
+
+        # Expand the complex criteria into a MongoDB compliant selector hash.
+        #
+        # @example Convert the criterion.
+        #   {}.expand_complex_criteria
+        #
+        # @return [ Hash ] The mongo selector.
+        #
+        # @since 1.0.0
         def expand_complex_criteria
-          hsh = {}
-          each_pair do |k,v|
-            case k
-            when Mongoid::Criterion::Complex
-              hsh[k.key] ||= {}
-              hsh[k.key].merge!({"$#{k.operator}" => v})
-            else
-              hsh[k] = v
+          {}.tap do |hsh|
+            each_pair do |k,v|
+              case k
+              when Mongoid::Criterion::Complex
+                hsh[k.key] ||= {}
+                hsh[k.key].merge!({"$#{k.operator}" => v})
+              else
+                hsh[k] = v
+              end
             end
           end
-          hsh
         end
       end
     end

data/lib/mongoid/extensions/hash/scoping.rb

@@ -2,7 +2,20 @@
 module Mongoid #:nodoc:
   module Extensions #:nodoc:
     module Hash #:nodoc:
-      module Scoping #:nodoc:
+
+      # Adds functionality for criteria scoping/merging.
+      module Scoping
+
+        # Get the hash scoped for criteria merges.
+        #
+        # @example Get the hash.
+        #   { :field => "value" }.scoped
+        #
+        # @param [ Array ] args The arguments (ignored).
+        #
+        # @return [ Hash ] The hash unmodified.
+        #
+        # @since 1.0.0
         def scoped(*args)
           self
         end

data/lib/mongoid/extensions/nil/collectionization.rb

@@ -2,7 +2,18 @@
 module Mongoid #:nodoc:
   module Extensions #:nodoc:
     module Nil #:nodoc:
-      module Collectionization #:nodoc:
+
+      # This module safeguards collection access on anonymous classes.
+      module Collectionization
+
+        # Get the name of a nil collection.
+        #
+        # @example Get the nil name.
+        #   nil.collectionize
+        #
+        # @return [ String ] A blank string.
+        #
+        # @since 1.0.0
         def collectionize
           to_s.collectionize
         end

data/lib/mongoid/extensions/object/reflections.rb

@@ -2,14 +2,45 @@
 module Mongoid #:nodoc:
   module Extensions #:nodoc:
     module Object #:nodoc:
-      module Reflections #:nodoc:
+
+      # This module contains reflection convenience methods.
+      module Reflections
         extend ActiveSupport::Concern
 
+        # Get the value for an instance variable or nil if it doesn't exist.
+        #
+        # @example Get the value for an instance var.
+        #   document.ivar("person")
+        #
+        # @param [ String ] name The name of the variable.
+        #
+        # @return [ Object, nil ] The value or nil.
+        #
+        # @since 2.0.0.rc.1
         def ivar(name)
           if instance_variable_defined?("@#{name}")
             return instance_variable_get("@#{name}")
+          else
+            false
+          end
+        end
+
+        # Remove the instance variable for the provided name.
+        #
+        # @example Remove the instance variable
+        #   document.remove_ivar("person")
+        #
+        # @param [ String ] name The name of the variable.
+        #
+        # @return [ true, false ] If the variable was defined.
+        #
+        # @since 2.1.0
+        def remove_ivar(name)
+          if instance_variable_defined?("@#{name}")
+            return remove_instance_variable("@#{name}")
+          else
+            false
           end
-          nil
         end
       end
     end