mongoid-braxton 2.0.2

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(attrs = {})
+        klass.create(
+          selector.inject(attrs) 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/exclusion.rb

@@ -0,0 +1,108 @@
+# 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

@@ -0,0 +1,198 @@
+# 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 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(&: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 execute_or_raise(args, crit)
+        else
+          crit
+        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".
+      #
+      # @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
+
+      # 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
+
+          selector.each_pair do |key, value|
+            if crit.selector.has_key?(key) && crit.selector[key].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
+          end
+        end
+      end
+
+      private
+
+      # 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, criteria)
+        (args[0].is_a?(Array) ? criteria.entries : criteria.one).tap do |result|
+          if Mongoid.raise_not_found_error && !args.flatten.blank?
+            raise Errors::DocumentNotFound.new(klass, args) if result._vacant?
+          end
+        end
+      end
+    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" <<
+        "  class:    #{klass},\n" <<
+        "  embedded: #{embedded}>\n"
+      end
+    end
+  end
+end

data/lib/mongoid/criterion/optional.rb

@@ -0,0 +1,193 @@
+# 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:
+      #
+      # <tt>criteria.ascending(:title, :dob)</tt>
+      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 ] }
+        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:
+      #
+      # <tt>criteria.cache</tt>
+      def cache
+        clone.tap { |crit| crit.options.merge!(:cache => true) }
+      end
+
+      # Will return true if the cache option has been set.
+      #
+      # Example:
+      #
+      # <tt>criteria.cached?</tt>
+      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:
+      #
+      # <tt>criteria.descending(:title, :dob)</tt>
+      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 ] }
+        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.
+      #
+      # Options:
+      #
+      # extras: A +Hash+ that gets set to the driver options.
+      #
+      # Example:
+      #
+      # <tt>criteria.extras(:limit => 20, :skip => 40)</tt>
+      #
+      # Returns: <tt>self</tt>
+      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.
+      #
+      # Options:
+      #
+      # object_id: A single id or an array of ids in +String+ or <tt>BSON::ObjectId</tt> format
+      #
+      # Example:
+      #
+      # <tt>criteria.for_ids("4ab2bc4b8ad548971900005c")</tt>
+      # <tt>criteria.for_ids(["4ab2bc4b8ad548971900005c", "4c454e7ebf4b98032d000001"])</tt>
+      #
+      # Returns: <tt>self</tt>
+      def for_ids(*ids)
+        ids.flatten!
+        if ids.size > 1
+          any_in(
+            :_id => ::BSON::ObjectId.convert(klass, ids)
+          )
+        else
+          clone.tap do |crit|
+            crit.selector[:_id] =
+              ::BSON::ObjectId.convert(klass, ids.first)
+          end
+        end
+      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>
+      # to handle paginated results.
+      #
+      # Options:
+      #
+      # value: An +Integer+ specifying the max number of results. Defaults to 20.
+      #
+      # Example:
+      #
+      # <tt>criteria.limit(100)</tt>
+      #
+      # Returns: <tt>self</tt>
+      def limit(value = 20)
+        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]
+      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:
+      #
+      # <tt>criteria.order_by([[:field1, :asc], [:field2, :desc]])</tt>
+      #
+      # Returns: <tt>self</tt>
+      def order_by(*args)
+        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
+        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
+      # <tt>limit()</tt> 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:
+      #
+      # <tt>criteria.skip(20)</tt>
+      #
+      # Returns: <tt>self</tt>
+      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
+      #
+      # Example:
+      #
+      # <tt>criteria.type('Browser')</tt>
+      # <tt>criteria.type(['Firefox', 'Browser'])</tt>
+      #
+      # Returns: <tt>self</tt>
+      def type(types)
+        types = [types] unless types.is_a?(Array)
+        any_in(:_type => types)
+      end
+
+    end
+  end
+end