mongoid 2.0.2 → 2.1.0

data/lib/mongoid/logger.rb

@@ -1,16 +1,37 @@
-module Mongoid
+# encoding: utf-8
+module Mongoid #:nodoc:
+
+  # The Mongoid logger which wraps some other ruby compliant logger class.
   class Logger
 
     delegate :info, :debug, :error, :fatal, :unknown, :to => :logger, :allow_nil => true
 
+    # Emit a warning log message.
+    #
+    # @example Log a warning.
+    #   logger.warn("Danger")
+    #
+    # @param [ String ] message The warning message.
     def warn(message)
       logger.warn(message) if logger && logger.respond_to?(:warn)
     end
 
+    # Get the mongoid logger.
+    #
+    # @example Get the global logger.
+    #   logger.logger
+    #
+    # @return [ Logger ] The logger.
     def logger
       Mongoid.logger
     end
 
+    # Inspect the logger.
+    #
+    # @example Inspect the logger.
+    #   logger.inspect
+    #
+    # @return [ String ] The logger, inspected.
     def inspect
       "#<Mongoid::Logger:0x#{object_id.to_s(16)} @logger=#{logger.inspect}>"
     end

data/lib/mongoid/matchers/all.rb

@@ -1,8 +1,18 @@
 # encoding: utf-8
 module Mongoid #:nodoc:
   module Matchers #:nodoc:
+
+    # Checks that all values match.
     class All < Default
+
       # Return true if the attribute and first value in the hash are equal.
+      #
+      # @example Do the values match?
+      #   matcher.matches?({ :key => 10 })
+      #
+      # @param [ Hash ] value The values to check.
+      #
+      # @return [ true, false ] If the values match.
       def matches?(value)
         @attribute == value.values.first
       end

data/lib/mongoid/matchers/default.rb

@@ -32,7 +32,7 @@ module Mongoid #:nodoc:
       #
       # @since 1.0.0
       def matches?(value)
-        attribute.is_a?(Array) ? attribute.include?(value) : value === attribute
+        attribute.is_a?(Array) && !value.is_a?(Array) ? attribute.include?(value) : value === attribute
       end
 
       protected

data/lib/mongoid/matchers/exists.rb

@@ -1,10 +1,20 @@
 # encoding: utf-8
 module Mongoid #:nodoc:
   module Matchers #:nodoc:
+
+    # Checks for existance.
     class Exists < Default
+
       # Return true if the attribute exists and checking for existence or
       # return true if the attribute does not exist and checking for
       # non-existence.
+      #
+      # @example Does anything exist?
+      #   matcher.matches?({ :key => 10 })
+      #
+      # @param [ Hash ] value The values to check.
+      #
+      # @return [ true, false ] If a value exists.
       def matches?(value)
         @attribute.nil? != value.values.first
       end

data/lib/mongoid/matchers/gt.rb

@@ -1,8 +1,18 @@
 # encoding: utf-8
 module Mongoid #:nodoc:
   module Matchers #:nodoc:
+
+    # Performs Greater Than matching.
     class Gt < Default
+
       # Return true if the attribute is greater than the value.
+      #
+      # @example Do the values match?
+      #   matcher.matches?({ :key => 10 })
+      #
+      # @param [ Hash ] value The values to check.
+      #
+      # @return [ true, false ] If a value exists.
       def matches?(value)
         determine(value, :>)
       end

data/lib/mongoid/matchers/gte.rb

@@ -1,8 +1,18 @@
 # encoding: utf-8
 module Mongoid #:nodoc:
   module Matchers #:nodoc:
+
+    # Performs Greater than or equal to matching.
     class Gte < Default
+
       # Return true if the attribute is greater than or equal to the value.
+      #
+      # @example Do the values match?
+      #   matcher.matches?({ :key => 10 })
+      #
+      # @param [ Hash ] value The values to check.
+      #
+      # @return [ true, false ] If a value exists.
       def matches?(value)
         determine(value, :>=)
       end

data/lib/mongoid/matchers/in.rb

@@ -1,8 +1,18 @@
 # encoding: utf-8
 module Mongoid #:nodoc:
   module Matchers #:nodoc:
+
+    # Performs matching for any value in an array.
     class In < Default
+
       # Return true if the attribute is in the values.
+      #
+      # @example Do the values match?
+      #   matcher.matches?({ :key => 10 })
+      #
+      # @param [ Hash ] value The values to check.
+      #
+      # @return [ true, false ] If a value exists.
       def matches?(value)
         value.values.first.include?(@attribute)
       end

data/lib/mongoid/matchers/lt.rb

@@ -1,8 +1,18 @@
 # encoding: utf-8
 module Mongoid #:nodoc:
   module Matchers #:nodoc:
+
+    # Performs less than matching.
     class Lt < Default
+
       # Return true if the attribute is less than the value.
+      #
+      # @example Do the values match?
+      #   matcher.matches?({ :key => 10 })
+      #
+      # @param [ Hash ] value The values to check.
+      #
+      # @return [ true, false ] If a value exists.
       def matches?(value)
         determine(value, :<)
       end

data/lib/mongoid/matchers/lte.rb

@@ -1,8 +1,18 @@
 # encoding: utf-8
 module Mongoid #:nodoc:
   module Matchers #:nodoc:
+
+    # Performs less than or equal to matching.
     class Lte < Default
+
       # Return true if the attribute is less than or equal to the value.
+      #
+      # @example Do the values match?
+      #   matcher.matches?({ :key => 10 })
+      #
+      # @param [ Hash ] value The values to check.
+      #
+      # @return [ true, false ] If a value exists.
       def matches?(value)
         determine(value, :<=)
       end

data/lib/mongoid/matchers/ne.rb

@@ -1,8 +1,18 @@
 # encoding: utf-8
 module Mongoid #:nodoc:
   module Matchers #:nodoc:
+
+    # Performs non-equivalency checks.
     class Ne < Default
+
       # Return true if the attribute and first value are not equal.
+      #
+      # @example Do the values match?
+      #   matcher.matches?({ :key => 10 })
+      #
+      # @param [ Hash ] value The values to check.
+      #
+      # @return [ true, false ] If a value exists.
       def matches?(value)
         @attribute != value.values.first
       end

data/lib/mongoid/matchers/nin.rb

@@ -1,8 +1,18 @@
 # encoding: utf-8
 module Mongoid #:nodoc:
   module Matchers #:nodoc:
+
+    # Performs not in checking.
     class Nin < Default
+
       # Return true if the attribute is not in the value list.
+      #
+      # @example Do the values match?
+      #   matcher.matches?({ :key => 10 })
+      #
+      # @param [ Hash ] value The values to check.
+      #
+      # @return [ true, false ] If a value exists.
       def matches?(value)
         !value.values.first.include?(@attribute)
       end

data/lib/mongoid/matchers/or.rb

@@ -17,11 +17,14 @@ module Mongoid #:nodoc:
       # @since 2.0.0.rc.7
       def matches?(conditions)
         conditions.each do |condition|
-          key = condition.keys.first
-          value = condition.values.first
-          if Strategies.matcher(document, key, value).matches?(value)
-            return true
+          res = true
+          condition.keys.each do |k|
+            key = k
+            value = condition[k]
+            res &&= Strategies.matcher(document, key, value).matches?(value)
+            break unless res
           end
+          return res if res
         end
         return false
       end

data/lib/mongoid/matchers/size.rb

@@ -1,8 +1,18 @@
 # encoding: utf-8
 module Mongoid #:nodoc:
   module Matchers #:nodoc:
+
+    # Performs size checking.
     class Size < Default
+
       # Return true if the attribute size is equal to the first value.
+      #
+      # @example Do the values match?
+      #   matcher.matches?({ :key => 10 })
+      #
+      # @param [ Hash ] value The values to check.
+      #
+      # @return [ true, false ] If a value exists.
       def matches?(value)
         @attribute.size == value.values.first
       end

data/lib/mongoid/multi_database.rb

@@ -1,11 +1,31 @@
-module Mongoid::MultiDatabase
-  extend ActiveSupport::Concern
+# encoding: utf-8
+module Mongoid #:nodoc:
 
-  module ClassMethods
+  # Adds multiple database support to documents.
+  module MultiDatabase
+    extend ActiveSupport::Concern
 
-    def database; @database end
-    def set_database(name)
-      @database = name.to_s
+    module ClassMethods #:nodoc:
+
+      # Gets the database from the class.
+      #
+      # @example Get the database.
+      #   Model.database
+      #
+      # @return [ Mongo::DB ] The database.
+      def database; @database end
+
+      # Set the database name.
+      #
+      # @example Set the database name.
+      #   Model.set_database(:testing)
+      #
+      # @param [ Symbol ] name The database name.
+      #
+      # @return [ String ] The database name.
+      def set_database(name)
+        @database = name.to_s
+      end
     end
   end
 end

data/lib/mongoid/multi_parameter_attributes.rb

@@ -1,14 +1,19 @@
 # encoding: utf-8
 module Mongoid #:nodoc:
 
+  # Adds Rails' multi-parameter attribute support to Mongoid.
+  #
   # @todo: Durran: This module needs an overhaul.
   module MultiParameterAttributes
-    module Errors
-      # Raised when an error occurred while doing a mass assignment to an attribute through the
-      # <tt>attributes=</tt> method. The exception has an +attribute+ property that is the name of the
-      # offending attribute.
+
+    module Errors #:nodoc:
+
+      # Raised when an error occurred while doing a mass assignment to an
+      # attribute through the <tt>attributes=</tt> method. The exception
+      # has an +attribute+ property that is the name of the offending attribute.
       class AttributeAssignmentError < Mongoid::Errors::MongoidError
         attr_reader :exception, :attribute
+
         def initialize(message, exception, attribute)
           @exception = exception
           @attribute = attribute
@@ -16,17 +21,32 @@ module Mongoid #:nodoc:
         end
       end
 
-      # Raised when there are multiple errors while doing a mass assignment through the +attributes+
-      # method. The exception has an +errors+ property that contains an array of AttributeAssignmentError
-      # objects, each corresponding to the error while assigning to an attribute.
+      # Raised when there are multiple errors while doing a mass assignment
+      # through the +attributes+ method. The exception has an +errors+
+      # property that contains an array of AttributeAssignmentError
+      # objects, each corresponding to the error while assigning to an
+      # attribute.
       class MultiparameterAssignmentErrors < Mongoid::Errors::MongoidError
         attr_reader :errors
+
         def initialize(errors)
           @errors = errors
         end
       end
     end
 
+    # Process the provided attributes casting them to their proper values if a
+    # field exists for them on the document. This will be limited to only the
+    # attributes provided in the suppied +Hash+ so that no extra nil values get
+    # put into the document's attributes.
+    #
+    # @example Process the attributes.
+    #   person.process(:title => "sir", :age => 40)
+    #
+    # @param [ Hash ] attrs The attributes to set.
+    # @param [ Boolean ] guard_protected_attributes False to skip mass assignment protection.
+    #
+    # @since 2.0.0.rc.7
     def process(attrs = nil, guard_protected_attributes = true)
       if attrs
         errors = []
@@ -45,15 +65,20 @@ module Mongoid #:nodoc:
         multi_parameter_attributes.each_pair do |key, values|
           begin
             values = (values.keys.min..values.keys.max).map { |i| values[i] }
-            klass = self.class.fields[key].try(:type)
-            attributes[key] = instantiate_object(klass, values)
+            field = self.class.fields[key]
+            attributes[key] = instantiate_object(field, values)
           rescue => e
-            errors << Errors::AttributeAssignmentError.new("error on assignment #{values.inspect} to #{key}", e, key)
+            errors << Errors::AttributeAssignmentError.new(
+              "error on assignment #{values.inspect} to #{key}", e, key
+            )
           end
         end
 
         unless errors.empty?
-          raise Errors::MultiparameterAssignmentErrors.new(errors), "#{errors.size} error(s) on assignment of multiparameter attributes"
+          raise(
+            Errors::MultiparameterAssignmentErrors.new(errors),
+            "#{errors.size} error(s) on assignment of multiparameter attributes"
+          )
         end
 
         super attributes, guard_protected_attributes
@@ -62,21 +87,19 @@ module Mongoid #:nodoc:
       end
     end
 
-  protected
+    protected
 
-    def instantiate_object(klass, values_with_empty_parameters)
+    def instantiate_object(field, values_with_empty_parameters)
       return nil if values_with_empty_parameters.all? { |v| v.nil? }
-
       values = values_with_empty_parameters.collect { |v| v.nil? ? 1 : v }
-
+      klass = field.type
       if klass == DateTime || klass == Date || klass == Time
-        klass.send(:convert_to_time, values)
+        field.serialize(values)
       elsif klass
         klass.new *values
       else
         values
       end
     end
-
   end
 end

data/lib/mongoid/named_scope.rb

@@ -85,8 +85,7 @@ module Mongoid #:nodoc:
       #
       # @since 1.0.0
       def scope_stack
-        scope_stack_for = Thread.current[:mongoid_scope_stack] ||= {}
-        scope_stack_for[object_id] ||= []
+        Threaded.scope_stack[object_id] ||= []
       end
 
       # Get a criteria object for the class, ignoring default scoping.

data/lib/mongoid/nested_attributes.rb

@@ -1,5 +1,7 @@
 # encoding: utf-8
 module Mongoid #:nodoc:
+
+  # Mongoid's implementation of Rails' nested attributes.
   module NestedAttributes
     extend ActiveSupport::Concern
 
@@ -10,7 +12,8 @@ module Mongoid #:nodoc:
       delegate :nested_attributes, :to => "self.class"
     end
 
-    module ClassMethods
+    module ClassMethods #:nodoc:
+
       REJECT_ALL_BLANK_PROC = proc { |attributes| attributes.all? { |_, value| value.blank? } }
 
       # Used when needing to update related models from a parent relation. Can

data/lib/mongoid/observer.rb

@@ -1,7 +1,110 @@
 # encoding: utf-8
 module Mongoid #:nodoc:
 
-  # Mongoid observers hook into the lifecycle of documents.
+  # Observer classes respond to life cycle callbacks to implement trigger-like
+  # behavior outside the original class. This is a great way to reduce the
+  # clutter that normally comes when the model class is burdened with
+  # functionality that doesn't pertain to the core responsibility of the
+  # class. Mongoid's observers work similar to ActiveRecord's. Example:
+  #
+  #   class CommentObserver < Mongoid::Observer
+  #     def after_save(comment)
+  #       Notifications.comment(
+  #         "admin@do.com", "New comment was posted", comment
+  #       ).deliver
+  #     end
+  #   end
+  #
+  # This Observer sends an email when a Comment#save is finished.
+  #
+  #   class ContactObserver < Mongoid::Observer
+  #     def after_create(contact)
+  #       contact.logger.info('New contact added!')
+  #     end
+  #
+  #     def after_destroy(contact)
+  #       contact.logger.warn("Contact with an id of #{contact.id} was destroyed!")
+  #     end
+  #   end
+  #
+  # This Observer uses logger to log when specific callbacks are triggered.
+  #
+  # == Observing a class that can't be inferred
+  #
+  # Observers will by default be mapped to the class with which they share a
+  # name. So CommentObserver will be tied to observing Comment,
+  # ProductManagerObserver to ProductManager, and so on. If you want to
+  # name your observer differently than the class you're interested in
+  # observing, you can use the Observer.observe class method which takes
+  # either the concrete class (Product) or a symbol for that class (:product):
+  #
+  #   class AuditObserver < Mongoid::Observer
+  #     observe :account
+  #
+  #     def after_update(account)
+  #       AuditTrail.new(account, "UPDATED")
+  #     end
+  #   end
+  #
+  # If the audit observer needs to watch more than one kind of object,
+  # this can be specified with multiple arguments:
+  #
+  #   class AuditObserver < Mongoid::Observer
+  #     observe :account, :balance
+  #
+  #     def after_update(record)
+  #       AuditTrail.new(record, "UPDATED")
+  #     end
+  #   end
+  #
+  # The AuditObserver will now act on both updates to Account and Balance
+  # by treating them both as records.
+  #
+  # == Available callback methods
+  #
+  # * after_initialize
+  # * before_validation
+  # * after_validation
+  # * before_create
+  # * around_create
+  # * after_create
+  # * before_update
+  # * around_update
+  # * after_update
+  # * before_save
+  # * around_save
+  # * after_save
+  # * before_destroy
+  # * around_destroy
+  # * after_destroy
+  #
+  # == Storing Observers in Rails
+  #
+  # If you're using Mongoid within Rails, observer classes are usually stored
+  # in +app/models+ with the naming convention of +app/models/audit_observer.rb+.
+  #
+  # == Configuration
+  #
+  # In order to activate an observer, list it in the +config.mongoid.observers+
+  # configuration setting in your +config/application.rb+ file.
+  #
+  #   config.mongoid.observers = :comment_observer, :signup_observer
+  #
+  # Observers will not be invoked unless you define them in your
+  # application configuration.
+  #
+  # == Loading
+  #
+  # Observers register themselves with the model class that they observe,
+  # since it is the class that notifies them of events when they occur.
+  # As a side-effect, when an observer is loaded, its corresponding model
+  # class is loaded.
+  #
+  # Observers are loaded after the application initializers, so that
+  # observed models can make use of extensions. If by any chance you are
+  # using observed models in the initialization, you can
+  # still load their observers by calling +ModelObserver.instance+ before.
+  # Observers are singletons and that call instantiates and registers them.
   class Observer < ActiveModel::Observer
 
     # Instantiate the new observer. Will add all child observers as well.
@@ -9,7 +112,7 @@ module Mongoid #:nodoc:
     # @example Instantiate the observer.
     #   Mongoid::Observer.new
     #
-    # @since 2.0.0
+    # @since 2.0.0.rc.8
     def initialize
       super and observed_descendants.each { |klass| add_observer!(klass) }
     end
@@ -23,7 +126,7 @@ module Mongoid #:nodoc:
     #
     # @return [ Array<Class> ] The children.
     #
-    # @since 2.0.0
+    # @since 2.0.0.rc.8
     def observed_descendants
       observed_classes.sum([]) { |klass| klass.descendants }
     end
@@ -35,7 +138,7 @@ module Mongoid #:nodoc:
     #
     # @param [ Class ] klass The child observer to add.
     #
-    # @since 2.0.0
+    # @since 2.0.0.rc.8
     def add_observer!(klass)
       super and define_callbacks(klass)
     end
@@ -47,7 +150,7 @@ module Mongoid #:nodoc:
     #
     # @param [ Class ] klass The model to define them on.
     #
-    # @since 2.0.0
+    # @since 2.0.0.rc.8
     def define_callbacks(klass)
       tap do |observer|
         observer_name = observer.class.name.underscore.gsub('/', '__')