# encoding: utf-8
require 'mongoid/contexts/id_conversion'
module Mongoid #:nodoc:
module Criterion #:nodoc:
module Optional
include Mongoid::Contexts::IdConversion
# 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:
#
# criteria.cache
def cache
@options.merge!(:cache => true); self
end
# Will return true if the cache option has been set.
#
# Example:
#
# criteria.cached?
def cached?
@options[:cache] == true
end
# Flags the criteria to execute against a read-only slave in the pool
# instead of master.
#
# Example:
#
# criteria.enslave
def enslave
@options.merge!(:enslave => true); self
end
# Will return true if the criteria is enslaved.
#
# Example:
#
# criteria.enslaved?
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:
#
# criteria.extras(:limit => 20, :skip => 40)
#
# Returns: self
def extras(extras)
@options.merge!(extras); filter_options; self
end
# Adds a criterion to the +Criteria+ that specifies an id that must be matched.
#
# Options:
#
# object_id: A +String+ representation of a BSON::ObjectID
#
# Example:
#
# criteria.id("4ab2bc4b8ad548971900005c")
#
# Returns: self
def id(*args)
ids = strings_to_object_ids(args.flatten)
if ids.size > 1
self.in(:_id => ids)
else
@selector[:_id] = ids.first
self
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.
#
# Options:
#
# value: An +Integer+ specifying the max number of results. Defaults to 20.
#
# Example:
#
# criteria.limit(100)
#
# Returns: self
def limit(value = 20)
@options[:limit] = value; self
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]
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".
#
# Options:
#
# params: An +Array+ of [field, direction] sorting pairs.
#
# Example:
#
# criteria.order_by([[:field1, :asc], [:field2, :desc]])
#
# Returns: self
def order_by(params = [])
@options[:sort] = params; self
end
# 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.
#
# Options:
#
# value: An +Integer+ specifying the number of results to skip. Defaults to 0.
#
# Example:
#
# criteria.skip(20)
#
# Returns: self
def skip(value = 0)
@options[:skip] = value; self
end
end
end
end