mongoid 2.4.9 → 3.0.0.rc

data/lib/mongoid/criterion/exclusion.rb

@@ -1,108 +0,0 @@
-# encoding: utf-8
-module Mongoid #:nodoc:
-  module Criterion #:nodoc:
-
-    # This module contains criteria behaviour for exclusion of values.
-    module Exclusion
-
-      # Adds a criterion to the +Criteria+ that specifies values that are not
-      # allowed to match any document in the database. The MongoDB
-      # conditional operator that will be used is "$ne".
-      #
-      # @example Match documents without these values.
-      #   criteria.excludes(:field => "value1")
-      #   criteria.excludes(:field1 => "value1", :field2 => "value1")
-      #
-      # @param [ Hash ] attributes: A +Hash+ where the key is the field
-      #   name and the value is a value that must not be equal to the
-      #   corresponding field value in the database.
-      #
-      # @return [ Criteria ] A newly cloned copy.
-      def excludes(attributes = {})
-        mongo_id = attributes.delete(:id)
-        attributes = attributes.merge(:_id => mongo_id) if mongo_id
-        update_selector(attributes, "$ne")
-      end
-
-      # Used when wanting to set the fields options directly using a hash
-      # instead of going through only or without.
-      #
-      # @example Set the limited fields.
-      #   criteria.fields(:field => 1)
-      #
-      # @param [ Hash ] attributes The field options.
-      #
-      # @return [ Criteria ] A newly cloned copy.
-      #
-      # @since 2.0.2
-      def fields(attributes = nil)
-        clone.tap { |crit| crit.options[:fields] = attributes || {} }
-      end
-
-      # Adds a criterion to the +Criteria+ that specifies values where none
-      # should match in order to return results. This is similar to an SQL
-      # "NOT IN" clause. The MongoDB conditional operator that will be
-      # used is "$nin".
-      #
-      # @example Match documents with values not in the provided.
-      #   criteria.not_in(:field => ["value1", "value2"])
-      #   criteria.not_in(:field1 => ["value1", "value2"], :field2 => ["value1"])
-      #
-      # @param [ Hash ] attributes A +Hash+ where the key is the field name
-      #   and the value is an +Array+ of values that none can match.
-      #
-      # @return [ Criteria ] A newly cloned copy.
-      def not_in(attributes)
-        update_selector(attributes, "$nin")
-      end
-
-      # Adds a criterion to the +Criteria+ that specifies the fields that will
-      # get returned from the Document. Used mainly for list views that do not
-      # require all fields to be present. This is similar to SQL "SELECT" values.
-      #
-      # @example Limit the fields to only the specified.
-      #   criteria.only(:field1, :field2, :field3)
-      #
-      # @note #only and #without cannot be used together.
-      #
-      # @param [ Array<Symbol> ] args A list of field names to limit to.
-      #
-      # @return [ Criteria ] A newly cloned copy.
-      def only(*args)
-        clone.tap do |crit|
-          if args.any?
-            crit.options[:fields] = {:_type => 1}
-            crit.field_list = args.flatten
-            crit.field_list.each do |f|
-              crit.options[:fields][f] = 1
-            end
-          end
-        end
-      end
-
-      # Adds a criterion to the +Criteria+ that specifies the fields that will
-      # not get returned by the document.
-      #
-      # @example Filter out specific fields.
-      #   criteria.without(:field2, :field2)
-      #
-      # @note #only and #without cannot be used together.
-      #
-      # @param [ Array<Symbol> args A list of fields to exclude.
-      #
-      # @return [ Criteria ] A newly cloned copy.
-      #
-      # @since 2.0.0
-      def without(*args)
-        clone.tap do |crit|
-          if args.any?
-            crit.options[:fields] = {}
-            args.flatten.each do |f|
-              crit.options[:fields][f] = 0
-            end
-          end
-        end
-      end
-    end
-  end
-end

data/lib/mongoid/criterion/inclusion.rb

@@ -1,290 +0,0 @@
-# encoding: utf-8
-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".
-      #
-      # @example Adding the criterion.
-      #   criteria.all(:field => ["value1", "value2"])
-      #   criteria.all(:field1 => ["value1", "value2"], :field2 => ["value1"])
-      #
-      # @param [ Hash ] attributes Name/value pairs that all must match.
-      #
-      # @return [ Criteria ] A new criteria with the added selector.
-      def all(attributes = {})
-        update_selector(attributes, "$all")
-      end
-      alias :all_in :all
-
-      # Adds a criterion to the criteria that specifies multiple expressions
-      # that *all* must match. This uses MongoDB's $and operator under the
-      # covers.
-      #
-      # @example Match all provided expressions.
-      #   criteria.all_of(:name => value, :age.gt => 18)
-      #
-      # @param [ Array<Hash> ] Multiple hash expressions.
-      #
-      # @return [ Criteria ] The criteria object.
-      #
-      # @since 2.3.0
-      def all_of(*args)
-        clone.tap do |crit|
-          unless args.empty?
-            criterion = @selector["$and"] || []
-            converted = BSON::ObjectId.convert(klass, args.flatten)
-            expanded = converted.collect { |hash| hash.expand_complex_criteria }
-            crit.selector["$and"] = criterion.concat(expanded)
-          end
-        end
-      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".
-      # Any previously matching "$in" arrays will be unioned with new
-      # arguments.
-      #
-      # @example Adding the criterion.
-      #   criteria.in(:field => ["value1"]).also_in(:field => ["value2"])
-      #
-      # @param [ Hash ] attributes Name/value pairs any can match.
-      #
-      # @return [ Criteria ] A new criteria with the added selector.
-      def also_in(attributes = {})
-        update_selector(attributes, "$in")
-      end
-
-      # Adds a criterion to the +Criteria+ that specifies values that must
-      # be matched in order to return results. This is similar to a SQL "WHERE"
-      # clause. This is the actual selector that will be provided to MongoDB,
-      # similar to the Javascript object that is used when performing a find()
-      # in the MongoDB console.
-      #
-      # @example Adding the criterion.
-      #   criteria.and(:field1 => "value1", :field2 => 15)
-      #
-      # @param [ Hash ] selectior Name/value pairs that all must match.
-      #
-      # @return [ Criteria ] A new criteria with the added selector.
-      def and(selector = nil)
-        where(selector)
-      end
-
-      # Adds a criterion to the +Criteria+ that specifies a set of expressions
-      # to match if any of them return true. This is a $or query in MongoDB and
-      # is similar to a SQL OR. This is named #any_of and aliased "or" for
-      # readability.
-      #
-      # @example Adding the criterion.
-      #   criteria.any_of({ :field1 => "value" }, { :field2 => "value2" })
-      #
-      # @param [ Array<Hash> ] args A list of name/value pairs any can match.
-      #
-      # @return [ Criteria ] A new criteria with the added selector.
-      def any_of(*args)
-        clone.tap do |crit|
-          criterion = @selector["$or"] || []
-          converted = BSON::ObjectId.convert(klass, args.flatten)
-          expanded = converted.collect { |hash| hash.expand_complex_criteria }
-          crit.selector["$or"] = criterion.concat(expanded)
-        end
-      end
-      alias :or :any_of
-
-      # Find the matchind document in the criteria, either based on id or
-      # conditions.
-      #
-      # @todo Durran: DRY up duplicated code in a few places.
-      #
-      # @example Find by an id.
-      #   criteria.find(BSON::ObjectId.new)
-      #
-      # @example Find by multiple ids.
-      #   criteria.find([ BSON::ObjectId.new, BSON::ObjectId.new ])
-      #
-      # @example Conditionally find all matching documents.
-      #   criteria.find(:all, :conditions => { :title => "Sir" })
-      #
-      # @example Conditionally find the first document.
-      #   criteria.find(:first, :conditions => { :title => "Sir" })
-      #
-      # @example Conditionally find the last document.
-      #   criteria.find(:last, :conditions => { :title => "Sir" })
-      #
-      # @param [ Symbol, BSON::ObjectId, Array<BSON::ObjectId> ] arg The
-      #   argument to search with.
-      # @param [ Hash ] options The options to search with.
-      #
-      # @return [ Document, Criteria ] The matching document(s).
-      def find(*args)
-        type, crit = search(*args)
-        case type
-        when :first then crit.one
-        when :last then crit.last
-        when :ids then crit.execute_or_raise(args)
-        else
-          crit
-        end
-      end
-
-      # Execute the criteria or raise an error if no documents found.
-      #
-      # @example Execute or raise
-      #   criteria.execute_or_raise(id, criteria)
-      #
-      # @param [ Object ] args The arguments passed.
-      # @param [ Criteria ] criteria The criteria to execute.
-      #
-      # @raise [ Errors::DocumentNotFound ] If nothing returned.
-      #
-      # @return [ Document, Array<Document> ] The document(s).
-      #
-      # @since 2.0.0
-      def execute_or_raise(args)
-        (args[0].is_a?(Array) ? entries : from_map_or_db).tap do |result|
-          if Mongoid.raise_not_found_error && !args.flatten.blank?
-            raise Errors::DocumentNotFound.new(klass, args) if result._vacant?
-          end
-        end
-      end
-
-      # Get the document from the identity map, and if not found hit the
-      # database.
-      #
-      # @example Get the document from the map or criteria.
-      #   criteria.from_map_or_db(criteria)
-      #
-      # @param [ Criteria ] The cloned criteria.
-      #
-      # @return [ Document ] The found document.
-      #
-      # @since 2.2.1
-      def from_map_or_db
-        doc = IdentityMap.get(klass, extract_id || selector)
-        doc && doc.matches?(selector) ? doc : first
-      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"])
-      #
-      # @param [ Hash ] attributes Name/value pairs any can match.
-      #
-      # @return [ Criteria ] A new criteria with the added selector.
-      def in(attributes = {})
-        update_selector(attributes, "$in", :&)
-      end
-      alias :any_in :in
-
-      # Eager loads all the provided relations. Will load all the documents
-      # into the identity map who's ids match based on the extra query for the
-      # ids.
-      #
-      # @note This will only work if Mongoid's identity map is enabled. To do
-      #   so set identity_map_enabled: true in your mongoid.yml
-      #
-      # @note This will work for embedded relations that reference another
-      #   collection via belongs_to as well.
-      #
-      # @note Eager loading brings all the documents into memory, so there is a
-      #   sweet spot on the performance gains. Internal benchmarks show that
-      #   eager loading becomes slower around 100k documents, but this will
-      #   naturally depend on the specific application.
-      #
-      # @example Eager load the provided relations.
-      #   Person.includes(:posts, :game)
-      #
-      # @param [ Array<Symbol> ] relations The names of the relations to eager
-      #   load.
-      #
-      # @return [ Criteria ] The cloned criteria.
-      #
-      # @since 2.2.0
-      def includes(*relations)
-        relations.flatten.each do |name|
-          inclusions.push(klass.reflect_on_association(name))
-        end
-        clone
-      end
-
-      # Get a list of criteria that are to be executed for eager loading.
-      #
-      # @example Get the eager loading inclusions.
-      #   Person.includes(:game).inclusions
-      #
-      # @return [ Array<Metadata> ] The inclusions.
-      #
-      # @since 2.2.0
-      def inclusions
-        @inclusions ||= []
-      end
-
-      # Adds a criterion to the +Criteria+ that specifies values to do
-      # geospacial searches by. The field must be indexed with the "2d" option.
-      #
-      # @example Adding the criterion.
-      #   criteria.near(:field1 => [30, -44])
-      #
-      # @param [ Hash ] attributes The fields with lat/long values.
-      #
-      # @return [ Criteria ] A new criteria with the added selector.
-      def near(attributes = {})
-        update_selector(attributes, "$near")
-      end
-
-      # Adds a criterion to the +Criteria+ that specifies values that must
-      # be matched in order to return results. This is similar to a SQL "WHERE"
-      # clause. This is the actual selector that will be provided to MongoDB,
-      # similar to the Javascript object that is used when performing a find()
-      # in the MongoDB console.
-      #
-      # @example Adding the criterion.
-      #   criteria.where(:field1 => "value1", :field2 => 15)
-      #
-      # @param [ Hash ] selector Name/value pairs where all must match.
-      #
-      # @return [ Criteria ] A new criteria with the added selector.
-      def where(selector = nil)
-        clone.tap do |crit|
-          selector = case selector
-            when String then {"$where" => selector}
-            else
-              BSON::ObjectId.convert(klass, selector || {}, false).expand_complex_criteria
-          end
-
-          # @todo: Durran: 3.0.0: refactor the merging into separate strategies
-          # to clean this funkiness up.
-          selector.each_pair do |key, value|
-            if crit.selector.has_key?(key)
-              if key.mongoid_id?
-                if crit.selector.has_key?("$and")
-                  crit.selector["$and"] << { key => value }
-                elsif crit.selector[key] != value
-                  crit.selector["$and"] = [{ key => crit.selector.delete(key) }, { key => value }]
-                end
-              elsif 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
-                  end
-              else
-                crit.selector[key] = value
-              end
-            else
-              crit.selector[key] = value
-            end
-          end
-        end
-      end
-    end
-  end
-end

data/lib/mongoid/criterion/optional.rb

@@ -1,259 +0,0 @@
-# encoding: utf-8
-module Mongoid #:nodoc:
-  module Criterion #:nodoc:
-    module Optional
-
-      # Adds fields to be sorted in ascending order. Will add them in the order
-      # they were passed into the method.
-      #
-      # @example Sort in ascending order.
-      #   criteria.ascending(:title, :dob)
-      #   criteria.asc(:title, :dob)
-      #
-      # @param [ Array<Symbol> ] fields The fields to sort on.
-      #
-      # @return [ Criteria ] The cloned criteria.
-      def ascending(*fields)
-        clone.tap do |crit|
-          setup_sort_options(crit.options) unless fields.first.nil?
-          fields.flatten.each { |field| merge_options(crit.options[:sort], [ localize(field), :asc ]) }
-        end
-      end
-      alias :asc :ascending
-
-      # Tells the criteria that the cursor that gets returned needs to be
-      # cached. This is so multiple iterations don't hit the database multiple
-      # times, however this is not advisable when working with large data sets
-      # as the entire results will get stored in memory.
-      #
-      # @example Flag the criteria as cached.
-      #   criteria.cache
-      #
-      # @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 Is the criteria cached?
-      #   criteria.cached?
-      #
-      # @return [ true, false ] If the criteria is flagged as cached.
-      def cached?
-        options[:cache] == true
-      end
-
-      # Adds fields to be sorted in descending order. Will add them in the order
-      # they were passed into the method.
-      #
-      # @example Sort the criteria in descending order.
-      #   criteria.descending(:title, :dob)
-      #   criteria.desc(:title, :dob)
-      #
-      # @param [ Array<Symbol> ] fields The fields to sort on.
-      #
-      # @return [ Criteria ] The cloned criteria.
-      def descending(*fields)
-        clone.tap do |crit|
-          setup_sort_options(crit.options) unless fields.first.nil?
-          fields.flatten.each { |field| merge_options(crit.options[:sort], [ localize(field), :desc ]) }
-        end
-      end
-      alias :desc :descending
-
-      # Adds a criterion to the +Criteria+ that specifies additional options
-      # to be passed to the Ruby driver, in the exact format for the driver.
-      #
-      # @example Add extra params to the criteria.
-      #   criteria.extras(:limit => 20, :skip => 40)
-      #
-      # @param [ Hash ] extras The extra driver options.
-      #
-      # @return [ Criteria ] The cloned criteria.
-      def extras(extras)
-        clone.tap do |crit|
-          crit.options.merge!(extras)
-        end
-      end
-
-      # Adds a criterion to the +Criteria+ that specifies an id that must be matched.
-      #
-      # @example Add a single id criteria.
-      #   criteria.for_ids("4ab2bc4b8ad548971900005c")
-      #
-      # @example Add multiple id criteria.
-      #   criteria.for_ids(["4ab2bc4b8ad548971900005c", "4c454e7ebf4b98032d000001"])
-      #
-      # @param [ Array ] ids: A single id or an array of ids.
-      #
-      # @return [ Criteria ] The cloned criteria.
-      def for_ids(*ids)
-        field = klass.fields["_id"]
-        ids.flatten!
-        if ids.size > 1
-          any_in(:_id => ids.map{ |id| field.serialize(id) })
-        else
-          where(:_id => field.serialize(ids.first))
-        end
-      end
-
-      # Adds a criterion to the +Criteria+ that specifies the maximum number of
-      # results to return. This is mostly used in conjunction with skip()
-      # to handle paginated results.
-      #
-      # @example Limit the result set size.
-      #   criteria.limit(100)
-      #
-      # @param [ Integer ] value The max number of results.
-      #
-      # @return [ Criteria ] The cloned criteria.
-      def limit(value = 20)
-        clone.tap { |crit| crit.options[:limit] = value.to_i }
-      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.
-      #
-      # @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
-
-      # Adds a criterion to the +Criteria+ that specifies the sort order of
-      # the returned documents in the database. Similar to a SQL "ORDER BY".
-      #
-      # @example Order by specific fields.
-      #   criteria.order_by([[:field1, :asc], [:field2, :desc]])
-      #
-      # @param [ Array ] params: An +Array+ of [field, direction] sorting pairs.
-      #
-      # @return [ Criteria ] The cloned criteria.
-      def order_by(*args)
-        clone.tap do |crit|
-          arguments = args.size == 1 ? args.first : args
-          setup_sort_options(crit.options) unless args.first.nil?
-          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
-      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
-      # limit() to handle paginated results, and is similar to the
-      # traditional "offset" parameter.
-      #
-      # @example Skip a specified number of documents.
-      #   criteria.skip(20)
-      #
-      # @param [ Integer ] value The number of results to skip.
-      #
-      # @return [ Criteria ] The cloned criteria.
-      def skip(value = 0)
-        clone.tap { |crit| crit.options[:skip] = value.to_i }
-      end
-
-      # Adds a criterion to the +Criteria+ that specifies a type or an Array of
-      # types that must be matched.
-      #
-      # @example Match only specific models.
-      #   criteria.type('Browser')
-      #   criteria.type(['Firefox', 'Browser'])
-      #
-      # @param [ Array<String> ] types The types to match against.
-      #
-      # @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], [ localize(field), direction ])
-          end
-        when Array
-          merge_options(crit.options[:sort], arguments.map{ |field| localize(field) })
-        when Complex
-          merge_options(crit.options[:sort], [ localize(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
-
-      # Initialize the sort options
-      # Set options[:sort] to an empty array if it does not exist, or dup it if
-      # it already has been defined
-      #
-      # @example criteria.setup_sort_options(crit.options)
-      #
-      # @param [ Array<Array> ] Existing options
-      #
-      # @since 2.4.0
-      def setup_sort_options(options)
-        options[:sort] = options[:sort] ? options[:sort].dup : []
-      end
-
-      # Check if field is localized and return localized version if it is.
-      #
-      # @example localize
-      #   criteria.localize(:description)
-      #
-      # @param [ <Symbol> ] field to localize
-      def localize(field)
-        if klass.fields[field.to_s].try(:localized?)
-          field = "#{field}.#{::I18n.locale}".to_sym
-        end
-        field
-      end
-    end
-  end
-end