mongoid 2.0.2 → 2.1.0

data/lib/mongoid/criteria.rb

@@ -13,18 +13,15 @@ module Mongoid #:nodoc:
 
   # The +Criteria+ class is the core object needed in Mongoid to retrieve
   # objects from the database. It is a DSL that essentially sets up the
-  # selector and options arguments that get passed on to a <tt>Mongo::Collection</tt>
+  # selector and options arguments that get passed on to a Mongo::Collection
   # in the Ruby driver. Each method on the +Criteria+ returns self to they
   # can be chained in order to create a readable criterion to be executed
   # against the database.
   #
-  # Example setup:
-  #
-  # <tt>criteria = Criteria.new</tt>
-  #
-  # <tt>criteria.only(:field).where(:field => "value").skip(20).limit(20)</tt>
-  #
-  # <tt>criteria.execute</tt>
+  # @example Create and execute a criteria.
+  #   criteria = Criteria.new
+  #   criteria.only(:field).where(:field => "value").skip(20).limit(20)
+  #   criteria.execute
   class Criteria
     include Enumerable
     include Criterion::Builder
@@ -45,6 +42,7 @@ module Mongoid #:nodoc:
       :field_list
 
     delegate \
+      :add_to_set,
       :aggregate,
       :avg,
       :blank?,
@@ -62,6 +60,7 @@ module Mongoid #:nodoc:
       :max,
       :min,
       :one,
+      :pull,
       :shift,
       :sum,
       :update,
@@ -69,12 +68,22 @@ module Mongoid #:nodoc:
 
     # Concatinate the criteria with another enumerable. If the other is a
     # +Criteria+ then it needs to get the collection from it.
+    #
+    # @example Concat 2 criteria.
+    #   criteria + criteria
+    #
+    # @param [ Criteria ] other The other criteria.
     def +(other)
       entries + comparable(other)
     end
 
     # Returns the difference between the criteria and another enumerable. If
     # the other is a +Criteria+ then it needs to get the collection from it.
+    #
+    # @example Get the difference of 2 criteria.
+    #   criteria - criteria
+    #
+    # @param [ Criteria ] other The other criteria.
     def -(other)
       entries - comparable(other)
     end
@@ -82,11 +91,11 @@ module Mongoid #:nodoc:
     # Returns true if the supplied +Enumerable+ or +Criteria+ is equal to the results
     # of this +Criteria+ or the criteria itself.
     #
-    # This will force a database load when called if an enumerable is passed.
+    # @note This will force a database load when called if an enumerable is passed.
     #
-    # Options:
+    # @param [ Object ] other The other +Enumerable+ or +Criteria+ to compare to.
     #
-    # other: The other +Enumerable+ or +Criteria+ to compare to.
+    # @return [ true, false ] If the objects are equal.
     def ==(other)
       case other
       when Criteria
@@ -102,6 +111,11 @@ module Mongoid #:nodoc:
     #
     # This will return an Enumerable context if the class is embedded,
     # otherwise it will return a Mongo context for root classes.
+    #
+    # @example Get the appropriate context.
+    #   criteria.context
+    #
+    # @return [ Mongo, Enumerable ] The appropriate context.
     def context
       @context ||= Contexts.context_for(self, embedded)
     end
@@ -109,18 +123,20 @@ module Mongoid #:nodoc:
     # Iterate over each +Document+ in the results. This can take an optional
     # block to pass to each argument in the results.
     #
-    # Example:
+    # @example Iterate over the criteria results.
+    #   criteria.each { |doc| p doc }
     #
-    # <tt>criteria.each { |doc| p doc }</tt>
+    # @return [ Criteria ] The criteria itself.
     def each(&block)
       tap { context.iterate(&block) }
     end
 
-    # Return true if the criteria has some Document or not
+    # Return true if the criteria has some Document or not.
     #
-    # Example:
+    # @example Are there any documents for the criteria?
+    #   criteria.exists?
     #
-    # <tt>criteria.exists?</tt>
+    # @return [ true, false ] If documents match.
     def exists?
       context.count > 0
     end
@@ -141,15 +157,12 @@ module Mongoid #:nodoc:
 
     # Merges the supplied argument hash into a single criteria
     #
-    # Options:
+    # @example Fuse the criteria and the object.
+    #   criteria.fuse(:where => { :field => "value"}, :limit => 20)
     #
-    # criteria_conditions: Hash of criteria keys, and parameter values
+    # @param [ Hash ] criteria_conditions Criteria keys and values.
     #
-    # Example:
-    #
-    # <tt>criteria.fuse(:where => { :field => "value"}, :limit => 20)</tt>
-    #
-    # Returns <tt>self</tt>
+    # @return [ Criteria ] self.
     def fuse(criteria_conditions = {})
       criteria_conditions.inject(self) do |criteria, (key, value)|
         criteria.send(key, value)
@@ -159,10 +172,11 @@ module Mongoid #:nodoc:
     # Create the new +Criteria+ object. This will initialize the selector
     # and options hashes, as well as the type of criteria.
     #
-    # Options:
+    # @example Instantiate a new criteria.
+    #   Criteria.new(Model, true)
     #
-    # type: One of :all, :first:, or :last
-    # klass: The class to execute on.
+    # @param [ Class ] klass The model the criteria is for.
+    # @param [ true, false ] embedded Is the criteria for embedded docs.
     def initialize(klass, embedded = false)
       @selector = Criterion::Selector.new(klass)
       @options, @klass, @documents, @embedded = {}, klass, [], embedded
@@ -172,13 +186,15 @@ module Mongoid #:nodoc:
     # +Criteria+ or a +Hash+. This is used to combine multiple scopes together,
     # where a chained scope situation may be desired.
     #
-    # Options:
+    # @example Merge the criteria with a conditions hash.
+    #   criteria.merge({ :conditions => { :title => "Sir" } })
     #
-    # other: The +Criteria+ or +Hash+ to merge with.
+    # @example Merge the criteria with another criteria.
+    #   criteri.merge(other_criteria)
     #
-    # Example:
+    # @param [ Criteria, Hash ] other The other criterion to merge with.
     #
-    # <tt>criteria.merge({ :conditions => { :title => "Sir" } })</tt>
+    # @return [ Criteria ] A cloned self.
     def merge(other)
       clone.tap do |crit|
         if other.is_a?(Criteria)
@@ -193,36 +209,15 @@ module Mongoid #:nodoc:
       end
     end
 
-    # Used for chaining +Criteria+ scopes together in the for of class methods
-    # on the +Document+ the criteria is for.
-    #
-    # Options:
-    #
-    # name: The name of the class method on the +Document+ to chain.
-    # args: The arguments passed to the method.
-    # block: Optional block to pass
-    #
-    # Returns: <tt>Criteria</tt>
-    def method_missing(name, *args, &block)
-      if @klass.respond_to?(name)
-        @klass.send(:with_scope, self) do
-          @klass.send(name, *args, &block)
-        end
-      else
-        return entries.send(name, *args)
-      end
-    end
-
     # Returns true if criteria responds to the given method.
     #
-    # Options:
-    #
-    # name: The name of the class method on the +Document+.
-    # include_private: The arguments passed to the method.
+    # @example Does the criteria respond to the method?
+    #   crtiteria.respond_to?(:each)
     #
-    # Example:
+    # @param [ Symbol ] name The name of the class method on the +Document+.
+    # @param [ true, false ] include_private Whether to include privates.
     #
-    # <tt>criteria.respond_to?(:batch_update)</tt>
+    # @return [ true, false ] If the criteria responds to the method.
     def respond_to?(name, include_private = false)
       # don't include klass private methods because method_missing won't call them
       super || @klass.respond_to?(name) || entries.respond_to?(name, include_private)
@@ -230,6 +225,11 @@ module Mongoid #:nodoc:
 
     # Returns the selector and options as a +Hash+ that would be passed to a
     # scope for use with named scopes.
+    #
+    # @example Get the criteria as a scoped hash.
+    #   criteria.scoped
+    #
+    # @return [ Hash ] The criteria as a scoped hash.
     def scoped
       scope_options = @options.dup
       sorting = scope_options.delete(:sort)
@@ -303,6 +303,13 @@ module Mongoid #:nodoc:
 
     # Return the entries of the other criteria or the object. Used for
     # comparing criteria or an enumerable.
+    #
+    # @example Get the comparable version.
+    #   criteria.comparable(other)
+    #
+    # @param [ Criteria ] other Another criteria.
+    #
+    # @return [ Array ] The array to compare with.
     def comparable(other)
       other.is_a?(Criteria) ? other.entries : other
     end
@@ -310,36 +317,46 @@ module Mongoid #:nodoc:
     # Clone or dup the current +Criteria+. This will return a new criteria with
     # the selector, options, klass, embedded options, etc intact.
     #
-    # Example:
-    #
-    # <tt>criteria.clone</tt>
-    # <tt>criteria.dup</tt>
+    # @example Clone a criteria.
+    #   criteria.clone
     #
-    # Options:
+    # @example Dup a criteria.
+    #   criteria.dup
     #
-    # other: The criteria getting cloned.
+    # @param [ Criteria ] other The criteria getting cloned.
     #
-    # Returns:
-    #
-    # A new identical criteria
+    # @return [ nil ] nil.
     def initialize_copy(other)
       @selector = other.selector.dup
       @options = other.options.dup
       @context = nil
     end
 
+    # Used for chaining +Criteria+ scopes together in the for of class methods
+    # on the +Document+ the criteria is for.
+    def method_missing(name, *args, &block)
+      if @klass.respond_to?(name)
+        @klass.send(:with_scope, self) do
+          @klass.send(name, *args, &block)
+        end
+      else
+        return entries.send(name, *args)
+      end
+    end
+
     # Update the selector setting the operator on the value for each key in the
     # supplied attributes +Hash+.
     #
-    # Example:
-    #
-    # <tt>criteria.update_selector({ :field => "value" }, "$in")</tt>
+    # @example Update the selector.
+    #   criteria.update_selector({ :field => "value" }, "$in")
     #
+    # @param [ Hash, Array ] attributes The values to convert and apply.
+    # @param [ String ] operator The MongoDB operator.
     # @param [ Symbol ] combine The operator to use when combining sets.
     def update_selector(attributes, operator, combine = :+)
       clone.tap do |crit|
         converted = BSON::ObjectId.convert(klass, attributes || {})
-        converted.each do |key, value|
+        converted.each_pair do |key, value|
           unless crit.selector[key]
             crit.selector[key] = { operator => value }
           else

data/lib/mongoid/criterion/complex.rb

@@ -1,30 +1,57 @@
 # encoding: utf-8
 module Mongoid #:nodoc:
   module Criterion #:nodoc:
+
     # Complex criterion are used when performing operations on symbols to get
     # get a shorthand syntax for where clauses.
     #
-    # Example:
-    #
-    # <tt>{ :field => { "$lt" => "value" } }</tt>
-    # becomes:
-    # <tt> { :field.lt => "value }</tt>
+    # @example Conversion of a simple to complex criterion.
+    #   { :field => { "$lt" => "value" } }
+    #   becomes:
+    #   { :field.lt => "value }
     class Complex
       attr_accessor :key, :operator
 
       # Create the new complex criterion.
+      #
+      # @example Instantiate a new complex criterion.
+      #   Complex.new(:key => :field, :operator => "$gt")
+      #
+      # @param [ Hash ] opts The options to convert.
       def initialize(opts = {})
         @key, @operator = opts[:key], opts[:operator]
       end
 
+      # Get the criterion as a hash.
+      #
+      # @example Get the criterion as a hash.
+      #   criterion.hash
+      #
+      # @return [ Hash ] The keys and operators.
       def hash
         [@key, @operator].hash
       end
 
+      # Is the criterion equal to the other?
+      #
+      # @example Check equality.
+      #   criterion.eql?(other)
+      #
+      # @param [ Complex ] other The other complex criterion.
+      #
+      # @return [ true, false ] If they are equal.
       def eql?(other)
         self == (other)
       end
 
+      # Is the criterion equal to the other?
+      #
+      # @example Check equality.
+      #   criterion == other
+      #
+      # @param [ Complex ] other The other complex criterion.
+      #
+      # @return [ true, false ] If they are equal.
       def ==(other)
         return false unless other.is_a?(self.class)
         self.key == other.key && self.operator == other.operator

data/lib/mongoid/criterion/inclusion.rb

@@ -67,7 +67,7 @@ module Mongoid #:nodoc:
         clone.tap do |crit|
           criterion = @selector["$or"] || []
           converted = BSON::ObjectId.convert(klass, args.flatten)
-          expanded = converted.collect(&:expand_complex_criteria)
+          expanded = converted.collect { |hash| hash.expand_complex_criteria }
           crit.selector["$or"] = criterion.concat(expanded)
         end
       end
@@ -159,7 +159,9 @@ module Mongoid #:nodoc:
           end
 
           selector.each_pair do |key, value|
-            if crit.selector.has_key?(key) && crit.selector[key].respond_to?(:merge!)
+            if crit.selector.has_key?(key) &&
+              crit.selector[key].respond_to?(:merge!) &&
+              value.respond_to?(:merge!)
               crit.selector[key] =
                 crit.selector[key].merge!(value) do |key, old, new|
                   key == '$in' ? old & new : new

data/lib/mongoid/criterion/optional.rb

@@ -6,13 +6,17 @@ module Mongoid #:nodoc:
       # Adds fields to be sorted in ascending order. Will add them in the order
       # they were passed into the method.
       #
-      # Example:
+      # @example Sort in ascending order.
+      #   criteria.ascending(:title, :dob)
+      #   criteria.asc(:title, :dob)
       #
-      # <tt>criteria.ascending(:title, :dob)</tt>
+      # @param [ Array<Symbol> ] fields The fields to sort on.
+      #
+      # @return [ Criteria ] The cloned criteria.
       def ascending(*fields)
         clone.tap do |crit|
           crit.options[:sort] = [] unless options[:sort] || fields.first.nil?
-          fields.flatten.each { |field| crit.options[:sort] << [ field, :asc ] }
+          fields.flatten.each { |field| merge_options(crit.options[:sort], [ field, :asc ]) }
         end
       end
       alias :asc :ascending
@@ -22,18 +26,20 @@ module Mongoid #:nodoc:
       # times, however this is not advisable when working with large data sets
       # as the entire results will get stored in memory.
       #
-      # Example:
+      # @example Flag the criteria as cached.
+      #   criteria.cache
       #
-      # <tt>criteria.cache</tt>
+      # @return [ Criteria ] The cloned criteria.
       def cache
         clone.tap { |crit| crit.options.merge!(:cache => true) }
       end
 
       # Will return true if the cache option has been set.
       #
-      # Example:
+      # @example Is the criteria cached?
+      #   criteria.cached?
       #
-      # <tt>criteria.cached?</tt>
+      # @return [ true, false ] If the criteria is flagged as cached.
       def cached?
         options[:cache] == true
       end
@@ -41,48 +47,30 @@ module Mongoid #:nodoc:
       # Adds fields to be sorted in descending order. Will add them in the order
       # they were passed into the method.
       #
-      # Example:
+      # @example Sort the criteria in descending order.
+      #   criteria.descending(:title, :dob)
+      #   criteria.desc(:title, :dob)
+      #
+      # @param [ Array<Symbol> ] fields The fields to sort on.
       #
-      # <tt>criteria.descending(:title, :dob)</tt>
+      # @return [ Criteria ] The cloned criteria.
       def descending(*fields)
         clone.tap do |crit|
           crit.options[:sort] = [] unless options[:sort] || fields.first.nil?
-          fields.flatten.each { |field| crit.options[:sort] << [ field, :desc ] }
+          fields.flatten.each { |field| merge_options(crit.options[:sort], [ field, :desc ]) }
         end
       end
       alias :desc :descending
 
-      # Flags the criteria to execute against a read-only slave in the pool
-      # instead of master.
-      #
-      # Example:
-      #
-      # <tt>criteria.enslave</tt>
-      def enslave
-        clone.tap { |crit| crit.options.merge!(:enslave => true) }
-      end
-
-      # Will return true if the criteria is enslaved.
-      #
-      # Example:
-      #
-      # <tt>criteria.enslaved?</tt>
-      def enslaved?
-        options[:enslave] == true
-      end
-
       # Adds a criterion to the +Criteria+ that specifies additional options
       # to be passed to the Ruby driver, in the exact format for the driver.
       #
-      # Options:
-      #
-      # extras: A +Hash+ that gets set to the driver options.
+      # @example Add extra params to the criteria.
+      #   criteria.extras(:limit => 20, :skip => 40)
       #
-      # Example:
+      # @param [ Hash ] extras The extra driver options.
       #
-      # <tt>criteria.extras(:limit => 20, :skip => 40)</tt>
-      #
-      # Returns: <tt>self</tt>
+      # @return [ Criteria ] The cloned criteria.
       def extras(extras)
         clone.tap do |crit|
           crit.options.merge!(extras)
@@ -91,16 +79,15 @@ module Mongoid #:nodoc:
 
       # Adds a criterion to the +Criteria+ that specifies an id that must be matched.
       #
-      # Options:
-      #
-      # object_id: A single id or an array of ids in +String+ or <tt>BSON::ObjectId</tt> format
+      # @example Add a single id criteria.
+      #   criteria.for_ids("4ab2bc4b8ad548971900005c")
       #
-      # Example:
+      # @example Add multiple id criteria.
+      #   criteria.for_ids(["4ab2bc4b8ad548971900005c", "4c454e7ebf4b98032d000001"])
       #
-      # <tt>criteria.for_ids("4ab2bc4b8ad548971900005c")</tt>
-      # <tt>criteria.for_ids(["4ab2bc4b8ad548971900005c", "4c454e7ebf4b98032d000001"])</tt>
+      # @param [ Array ] ids: A single id or an array of ids.
       #
-      # Returns: <tt>self</tt>
+      # @return [ Criteria ] The cloned criteria.
       def for_ids(*ids)
         ids.flatten!
         if ids.size > 1
@@ -116,18 +103,15 @@ module Mongoid #:nodoc:
       end
 
       # Adds a criterion to the +Criteria+ that specifies the maximum number of
-      # results to return. This is mostly used in conjunction with <tt>skip()</tt>
+      # results to return. This is mostly used in conjunction with skip()
       # to handle paginated results.
       #
-      # Options:
-      #
-      # value: An +Integer+ specifying the max number of results. Defaults to 20.
+      # @example Limit the result set size.
+      #   criteria.limit(100)
       #
-      # Example:
+      # @param [ Integer ] value The max number of results.
       #
-      # <tt>criteria.limit(100)</tt>
-      #
-      # Returns: <tt>self</tt>
+      # @return [ Criteria ] The cloned criteria.
       def limit(value = 20)
         clone.tap { |crit| crit.options[:limit] = value }
       end
@@ -135,6 +119,11 @@ module Mongoid #:nodoc:
       # Returns the offset option. If a per_page option is in the list then it
       # will replace it with a skip parameter and return the same value. Defaults
       # to 20 if nothing was provided.
+      #
+      # @example Get the offset.
+      #   criteria.offset(10)
+      #
+      # @return [ Integer ] The number of documents to skip.
       def offset(*args)
         args.size > 0 ? skip(args.first) : options[:skip]
       end
@@ -142,30 +131,25 @@ module Mongoid #:nodoc:
       # Adds a criterion to the +Criteria+ that specifies the sort order of
       # the returned documents in the database. Similar to a SQL "ORDER BY".
       #
-      # Options:
-      #
-      # params: An +Array+ of [field, direction] sorting pairs.
-      #
-      # Example:
+      # @example Order by specific fields.
+      #   criteria.order_by([[:field1, :asc], [:field2, :desc]])
       #
-      # <tt>criteria.order_by([[:field1, :asc], [:field2, :desc]])</tt>
+      # @param [ Array ] params: An +Array+ of [field, direction] sorting pairs.
       #
-      # Returns: <tt>self</tt>
+      # @return [ Criteria ] The cloned criteria.
       def order_by(*args)
         clone.tap do |crit|
+          arguments = args.size == 1 ? args.first : args
           crit.options[:sort] = [] unless options[:sort] || args.first.nil?
-          arguments = args.first
-          case arguments
-          when Hash
-            arguments.each do |field, direction|
-              crit.options[:sort] << [ field, direction ]
-            end
-          when Array
-            crit.options[:sort].concat(arguments)
-          when Complex
-            args.flatten.each do |complex|
-              crit.options[:sort] << [ complex.key, complex.operator.to_sym ]
+          if arguments.is_a?(Array)
+            #[:name, :asc]
+            if arguments.size == 2 && (arguments.first.is_a?(Symbol) || arguments.first.is_a?(String))
+              build_order_options(arguments, crit)
+            else
+              arguments.each { |argument| build_order_options(argument, crit) }
             end
+          else
+            build_order_options(arguments, crit)
           end
         end
       end
@@ -173,40 +157,81 @@ module Mongoid #:nodoc:
 
       # Adds a criterion to the +Criteria+ that specifies how many results to skip
       # when returning Documents. This is mostly used in conjunction with
-      # <tt>limit()</tt> to handle paginated results, and is similar to the
+      # limit() to handle paginated results, and is similar to the
       # traditional "offset" parameter.
       #
-      # Options:
-      #
-      # value: An +Integer+ specifying the number of results to skip. Defaults to 0.
+      # @example Skip a specified number of documents.
+      #   criteria.skip(20)
       #
-      # Example:
+      # @param [ Integer ] value The number of results to skip.
       #
-      # <tt>criteria.skip(20)</tt>
-      #
-      # Returns: <tt>self</tt>
+      # @return [ Criteria ] The cloned criteria.
       def skip(value = 0)
         clone.tap { |crit| crit.options[:skip] = value }
       end
 
       # Adds a criterion to the +Criteria+ that specifies a type or an Array of
-      # type that must be matched.
-      #
-      # Options:
-      #
-      # types : An +Array+ of types of a +String+ representing the Type of you search
+      # types that must be matched.
       #
-      # Example:
+      # @example Match only specific models.
+      #   criteria.type('Browser')
+      #   criteria.type(['Firefox', 'Browser'])
       #
-      # <tt>criteria.type('Browser')</tt>
-      # <tt>criteria.type(['Firefox', 'Browser'])</tt>
+      # @param [ Array<String> ] types The types to match against.
       #
-      # Returns: <tt>self</tt>
+      # @return [ Criteria ] The cloned criteria.
       def type(types)
         types = [types] unless types.is_a?(Array)
         any_in(:_type => types)
       end
 
+      private
+
+      # Build ordering options from given arguments on given criteria
+      #
+      # @example build order options
+      #   criteria.build_order_options(:name.asc, criteria)
+      #
+      #
+      # @param [ <Hash>, <Array>, <Complex> ] argument to build criteria from
+      # @param [ Criterion ] criterion to change
+      def build_order_options(arguments, crit)
+        case arguments
+        when Hash
+          if arguments.size > 1
+            raise ArgumentError, "Please don't use hash to define multiple orders " +
+                "due to the fact that hash doesn't have order this may cause unpredictable results"
+          end
+          arguments.each_pair do |field, direction|
+            merge_options(crit.options[:sort], [ field, direction ])
+          end
+        when Array
+          merge_options(crit.options[:sort],arguments)
+        when Complex
+          merge_options(crit.options[:sort], [ arguments.key, arguments.operator.to_sym ])
+        end
+      end
+
+      # Merge options for order_by criterion
+      # Allow only one order direction for same field
+      #
+      # @example Merge ordering options
+      #   criteria.merge_options([[:title, :asc], [:created_at, :asc]], [:title, :desc])
+      #
+      #
+      # @param [ Array<Array> ] Existing options
+      # @param [ Array ] New option for merge.
+      #
+      # @since 2.1.0
+      def merge_options(options, new_option)
+        old_option = options.assoc(new_option.first)
+
+        if old_option
+          options[options.index(old_option)] = new_option.flatten
+        else
+          options << new_option.flatten
+        end
+      end
     end
   end
 end