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

data/lib/mongoid/criterion/creational.rb

@@ -0,0 +1,34 @@
+# encoding: utf-8
+module Mongoid #:nodoc:
+  module Criterion #:nodoc:
+
+    # This module defines criteria behavior for creating documents in the
+    # database for specified conditions.
+    module Creational
+
+      # Create a document in the database given the selector and return it.
+      # Complex criteria, such as $in and $or operations will get ignored.
+      #
+      # @example Create the document.
+      #   Person.where(:title => "Sir").create
+      #
+      # @example Create with selectors getting ignored.
+      #   Person.where(:age.gt => 5).create
+      #
+      # @return [ Document ] A newly created document.
+      #
+      # @since 2.0.0.rc.1
+      def create
+        klass.create(
+          selector.inject({}) do |hash, (key, value)|
+            hash.tap do |attrs|
+              unless key.to_s =~ /\$/ || value.is_a?(Hash)
+                attrs[key] = value
+              end
+            end
+          end
+        )
+      end
+    end
+  end
+end

data/lib/mongoid/criterion/destructive.rb

@@ -0,0 +1,37 @@
+# encoding: utf-8
+module Mongoid #:nodoc:
+  module Criterion #:nodoc:
+
+    # This module defines criteria behavior for deleting or destroying
+    # documents.
+    module Destructive
+
+      # Delete all documents in the database that match the criteria.
+      #
+      # @example Delete all matching documents.
+      #   Person.where(:title => "Sir").and(:age.gt => 5).delete_all
+      #
+      # @return [ Integer ] The number of documents deleted.
+      #
+      # @since 2.0.0.rc.1
+      def delete_all
+        context.delete_all
+      end
+      alias :delete :delete_all
+
+      # Destroy all documents in the database that match the criteria. Will run
+      # the destruction callbacks on each document as well.
+      #
+      # @example Destroy all matching documents.
+      #   Person.where(:title => "Sir").and(:age.gt => 5).destroy_all
+      #
+      # @return [ Integer ] The number of documents destroyed.
+      #
+      # @since 2.0.0.rc.1
+      def destroy_all
+        context.destroy_all
+      end
+      alias :destroy :destroy_all
+    end
+  end
+end

data/lib/mongoid/criterion/exclusion.rb

@@ -58,7 +58,9 @@ module Mongoid #:nodoc:
       #
       # Returns: <tt>self</tt>
       def only(*args)
-        @options[:fields] = args.flatten if args.any?; self
+        clone.tap do |crit|
+          crit.options[:fields] = args.flatten if args.any?
+        end
       end
     end
   end

data/lib/mongoid/criterion/inclusion.rb

@@ -2,23 +2,19 @@
 module Mongoid #:nodoc:
   module Criterion #:nodoc:
     module Inclusion
+
       # Adds a criterion to the +Criteria+ that specifies values that must all
       # be matched in order to return results. Similar to an "in" clause but the
       # underlying conditional logic is an "AND" and not an "OR". The MongoDB
       # conditional operator that will be used is "$all".
       #
-      # Options:
-      #
-      # attributes: A +Hash+ where the key is the field name and the value is an
-      # +Array+ of values that must all match.
-      #
-      # Example:
-      #
-      # <tt>criteria.all(:field => ["value1", "value2"])</tt>
+      # @example Adding the criterion.
+      #   criteria.all(:field => ["value1", "value2"])
+      #   criteria.all(:field1 => ["value1", "value2"], :field2 => ["value1"])
       #
-      # <tt>criteria.all(:field1 => ["value1", "value2"], :field2 => ["value1"])</tt>
+      # @param [ Hash ] attributes Name/value pairs that all must match.
       #
-      # Returns: <tt>self</tt>
+      # @return [ Criteria ] A new criteria with the added selector.
       def all(attributes = {})
         update_selector(attributes, "$all")
       end
@@ -30,15 +26,12 @@ module Mongoid #:nodoc:
       # similar to the Javascript object that is used when performing a find()
       # in the MongoDB console.
       #
-      # Options:
+      # @example Adding the criterion.
+      #   criteria.and(:field1 => "value1", :field2 => 15)
       #
-      # selectior: A +Hash+ that must match the attributes of the +Document+.
+      # @param [ Hash ] selectior Name/value pairs that all must match.
       #
-      # Example:
-      #
-      # <tt>criteria.and(:field1 => "value1", :field2 => 15)</tt>
-      #
-      # Returns: <tt>self</tt>
+      # @return [ Criteria ] A new criteria with the added selector.
       def and(selector = nil)
         where(selector)
       end
@@ -48,39 +41,48 @@ module Mongoid #:nodoc:
       # is similar to a SQL OR. This is named #any_of and aliased "or" for
       # readability.
       #
-      # Options:
-      #
-      # selector: Multiple +Hash+ expressions that any can match.
+      # @example Adding the criterion.
+      #   criteria.any_of({ :field1 => "value" }, { :field2 => "value2" })
       #
-      # Example:
+      # @param [ Array<Hash> ] args A list of name/value pairs any can match.
       #
-      # <tt>criteria.any_of({ :field1 => "value" }, { :field2 => "value2" })</tt>
-      #
-      # Returns: <tt>self</tt>
+      # @return [ Criteria ] A new criteria with the added selector.
       def any_of(*args)
-        criterion = @selector["$or"] || []
-        expanded = args.collect(&:expand_complex_criteria)
-        @selector["$or"] = criterion.concat(expanded)
-        self
+        clone.tap do |crit|
+          criterion = @selector["$or"] || []
+          expanded = args.collect(&:expand_complex_criteria)
+          crit.selector["$or"] = criterion.concat(expanded)
+        end
       end
       alias :or :any_of
 
-      # Adds a criterion to the +Criteria+ that specifies values where any can
-      # be matched in order to return results. This is similar to an SQL "IN"
-      # clause. The MongoDB conditional operator that will be used is "$in".
+      # Using the existing criteria, find a document by a single id, multiple
+      # ids, or using a conditions hash.
       #
-      # Options:
+      # @example Find a single document by id.
+      #   Person.where(:title => "Sir").find(id)
       #
-      # attributes: A +Hash+ where the key is the field name and the value is an
-      # +Array+ of values that any can match.
+      # @example Find multiple documents by ids.
+      #   Person.where(:title => "Sir").find([ id_one, id_two ])
       #
-      # Example:
+      # @return [ Document, Array<Document> ] The matching document(s).
       #
-      # <tt>criteria.in(:field => ["value1", "value2"])</tt>
+      # @since 2.0.0.rc.1
+      def find(*args)
+        id_criteria(*args)
+      end
+
+      # Adds a criterion to the +Criteria+ that specifies values where any can
+      # be matched in order to return results. This is similar to an SQL "IN"
+      # clause. The MongoDB conditional operator that will be used is "$in".
+      #
+      # @example Adding the criterion.
+      #   criteria.in(:field => ["value1", "value2"])
+      #   criteria.in(:field1 => ["value1", "value2"], :field2 => ["value1"])
       #
-      # <tt>criteria.in(:field1 => ["value1", "value2"], :field2 => ["value1"])</tt>
+      # @param [ Hash ] attributes Name/value pairs any can match.
       #
-      # Returns: <tt>self</tt>
+      # @return [ Criteria ] A new criteria with the added selector.
       def in(attributes = {})
         update_selector(attributes, "$in")
       end
@@ -89,16 +91,12 @@ module Mongoid #:nodoc:
       # Adds a criterion to the +Criteria+ that specifies values to do
       # geospacial searches by. The field must be indexed with the "2d" option.
       #
-      # Options:
-      #
-      # attributes: A +Hash+ where the keys are the field names and the values are
-      # +Arrays+ of [latitude, longitude] pairs.
+      # @example Adding the criterion.
+      #   criteria.near(:field1 => [30, -44])
       #
-      # Example:
+      # @param [ Hash ] attributes The fields with lat/long values.
       #
-      # <tt>criteria.near(:field1 => [30, -44])</tt>
-      #
-      # Returns: <tt>self</tt>
+      # @return [ Criteria ] A new criteria with the added selector.
       def near(attributes = {})
         update_selector(attributes, "$near")
       end
@@ -109,30 +107,27 @@ module Mongoid #:nodoc:
       # similar to the Javascript object that is used when performing a find()
       # in the MongoDB console.
       #
-      # Options:
-      #
-      # selector: A +Hash+ that must match the attributes of the +Document+.
-      #
-      # Example:
+      # @example Adding the criterion.
+      #   criteria.where(:field1 => "value1", :field2 => 15)
       #
-      # <tt>criteria.where(:field1 => "value1", :field2 => 15)</tt>
+      # @param [ Hash ] selector Name/value pairs where all must match.
       #
-      # Returns: <tt>self</tt>
+      # @return [ Criteria ] A new criteria with the added selector.
       def where(selector = nil)
-        selector = case selector
-          when String then {"$where" => selector}
-          else selector ? selector.expand_complex_criteria : {}
-        end
+        clone.tap do |crit|
+          selector = case selector
+            when String then {"$where" => selector}
+            else selector ? selector.expand_complex_criteria : {}
+          end
 
-        selector.each_pair do |key, value|
-          if @selector.has_key?(key) && @selector[key].respond_to?(:merge!)
-            @selector[key].merge!(value)
-          else
-            @selector[key] = value
+          selector.each_pair do |key, value|
+            if crit.selector.has_key?(key) && crit.selector[key].respond_to?(:merge!)
+              crit.selector[key].merge!(value)
+            else
+              crit.selector[key] = value
+            end
           end
         end
-
-        self
       end
     end
   end

data/lib/mongoid/criterion/inspection.rb

@@ -0,0 +1,22 @@
+# encoding: utf-8
+module Mongoid #:nodoc:
+  module Criterion #:nodoc:
+    module Inspection #:nodoc:
+
+      # Get a pretty string representation of the criteria, including the
+      # selector, options, matching count and documents for inspection.
+      #
+      # @example Inspect the criteria.
+      #   criteria.inspect
+      #
+      # @return [ String ] The inspection string.
+      def inspect
+        "#<Mongoid::Criteria\n" <<
+        "  selector: #{selector.inspect},\n" <<
+        "  options:  #{options.inspect},\n" <<
+        "  count:    #{count.inspect},\n" <<
+        "  matching: #{entries.inspect}>\n"
+      end
+    end
+  end
+end

data/lib/mongoid/criterion/optional.rb

@@ -3,16 +3,6 @@ module Mongoid #:nodoc:
   module Criterion #:nodoc:
     module Optional
 
-      def using_default_sort?
-        @use_default_sort = true if @use_default_sort.nil? # TODO: move initialization elsewhere
-        return @use_default_sort
-      end
-
-      def remove_default_sort
-        @options[:sort] = nil if using_default_sort?
-        @use_default_sort = false
-      end
-
       # Adds fields to be sorted in ascending order. Will add them in the order
       # they were passed into the method.
       #
@@ -20,13 +10,11 @@ module Mongoid #:nodoc:
       #
       # <tt>criteria.ascending(:title, :dob)</tt>
       def ascending(*fields)
-        remove_default_sort
-
-        @options[:sort] = [] unless @options[:sort] || fields.first.nil?
-        fields.flatten.each { |field| @options[:sort] << [ field, :asc ] }
-        self
+        clone.tap do |crit|
+          crit.options[:sort] = [] unless options[:sort] || fields.first.nil?
+          fields.flatten.each { |field| crit.options[:sort] << [ field, :asc ] }
+        end
       end
-
       alias :asc :ascending
 
       # Tells the criteria that the cursor that gets returned needs to be
@@ -38,7 +26,7 @@ module Mongoid #:nodoc:
       #
       # <tt>criteria.cache</tt>
       def cache
-        @options.merge!(:cache => true); self
+        clone.tap { |crit| crit.options.merge!(:cache => true) }
       end
 
       # Will return true if the cache option has been set.
@@ -47,7 +35,7 @@ module Mongoid #:nodoc:
       #
       # <tt>criteria.cached?</tt>
       def cached?
-        @options[:cache] == true
+        options[:cache] == true
       end
 
       # Adds fields to be sorted in descending order. Will add them in the order
@@ -57,13 +45,11 @@ module Mongoid #:nodoc:
       #
       # <tt>criteria.descending(:title, :dob)</tt>
       def descending(*fields)
-        remove_default_sort
-
-        @options[:sort] = [] unless @options[:sort] || fields.first.nil?
-        fields.flatten.each { |field| @options[:sort] << [ field, :desc ] }
-        self
+        clone.tap do |crit|
+          crit.options[:sort] = [] unless options[:sort] || fields.first.nil?
+          fields.flatten.each { |field| crit.options[:sort] << [ field, :desc ] }
+        end
       end
-
       alias :desc :descending
 
       # Flags the criteria to execute against a read-only slave in the pool
@@ -73,7 +59,7 @@ module Mongoid #:nodoc:
       #
       # <tt>criteria.enslave</tt>
       def enslave
-        @options.merge!(:enslave => true); self
+        clone.tap { |crit| crit.options.merge!(:enslave => true) }
       end
 
       # Will return true if the criteria is enslaved.
@@ -82,7 +68,7 @@ module Mongoid #:nodoc:
       #
       # <tt>criteria.enslaved?</tt>
       def enslaved?
-        @options[:enslave] == true
+        options[:enslave] == true
       end
 
       # Adds a criterion to the +Criteria+ that specifies additional options
@@ -98,7 +84,10 @@ module Mongoid #:nodoc:
       #
       # Returns: <tt>self</tt>
       def extras(extras)
-        @options.merge!(extras); filter_options; self
+        clone.tap do |crit|
+          crit.options.merge!(extras)
+          crit.filter_options
+        end
       end
 
       # Adds a criterion to the +Criteria+ that specifies an id that must be matched.
@@ -116,14 +105,15 @@ module Mongoid #:nodoc:
       def id(*ids)
         ids.flatten!
         if ids.size > 1
-          self.in(
-            :_id => ::BSON::ObjectId.cast!(@klass, ids, @klass.primary_key.nil?)
+          any_in(
+            :_id => ::BSON::ObjectId.cast!(klass, ids, klass.primary_key.nil?)
           )
         else
-          @selector[:_id] =
-            ::BSON::ObjectId.cast!(@klass, ids.first, @klass.primary_key.nil?)
+          clone.tap do |crit|
+            crit.selector[:_id] =
+              ::BSON::ObjectId.cast!(klass, ids.first, klass.primary_key.nil?)
+          end
         end
-        self
       end
 
       # Adds a criterion to the +Criteria+ that specifies the maximum number of
@@ -140,14 +130,14 @@ module Mongoid #:nodoc:
       #
       # Returns: <tt>self</tt>
       def limit(value = 20)
-        @options[:limit] = value; self
+        clone.tap { |crit| crit.options[:limit] = value }
       end
 
       # 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.
       def offset(*args)
-        args.size > 0 ? skip(args.first) : @options[:skip]
+        args.size > 0 ? skip(args.first) : options[:skip]
       end
 
       # Adds a criterion to the +Criteria+ that specifies the sort order of
@@ -163,26 +153,24 @@ module Mongoid #:nodoc:
       #
       # Returns: <tt>self</tt>
       def order_by(*args)
-        remove_default_sort
-        set_order_by(*args)
-      end
-
-      def set_order_by(*args)
-        @options[:sort] = [] unless @options[:sort] || args.first.nil?
-        arguments = args.first
-        case arguments
-        when Hash
-          arguments.each do |field, direction|
-            @options[:sort] << [ field, direction ]
+        clone.tap do |crit|
+          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 ]
+            end
           end
-        when Array
-          @options[:sort].concat(arguments)
-        when Complex
-          args.flatten.each do |complex|
-            @options[:sort] << [ complex.key, complex.operator.to_sym ]
-          end
-        end; self
+        end
       end
+      alias :order :order_by
 
       # Adds a criterion to the +Criteria+ that specifies how many results to skip
       # when returning Documents. This is mostly used in conjunction with
@@ -199,7 +187,7 @@ module Mongoid #:nodoc:
       #
       # Returns: <tt>self</tt>
       def skip(value = 0)
-        @options[:skip] = value; self
+        clone.tap { |crit| crit.options[:skip] = value }
       end
 
       # Adds a criterion to the +Criteria+ that specifies a type or an Array of
@@ -217,7 +205,7 @@ module Mongoid #:nodoc:
       # Returns: <tt>self</tt>
       def type(types)
         types = [types] unless types.is_a?(Array)
-        self.in(:_type => types)
+        any_in(:_type => types)
       end
 
     end