mongoid 0.8.10 → 0.9.0

data/VERSION

@@ -1 +1 @@
-0.8.10
+0.9.0

data/lib/mongoid.rb

@@ -73,7 +73,7 @@ module Mongoid
     end
   end
 
-  # Raised when invalid options are passed into an association.
+  # Raised when invalid options are passed into a constructor.
   class InvalidOptionsError < RuntimeError; end
 
   # Connect to the database name supplied. This should be run

data/lib/mongoid/criteria.rb

@@ -14,8 +14,29 @@ module Mongoid #:nodoc:
   #
   # <tt>criteria.execute</tt>
   class Criteria
-    attr_accessor :klass
-    attr_reader :selector, :options, :type
+    include Enumerable
+
+    attr_reader :klass, :options, :selector
+
+    # 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.
+    #
+    # Options:
+    #
+    # other: The other +Enumerable+ or +Criteria+ to compare to.
+    def ==(other)
+      case other
+      when Criteria
+        self.selector == other.selector && self.options == other.options
+      when Enumerable
+        execute
+        return (@collection == other)
+      else
+        return false
+      end
+    end
 
     AGGREGATE_REDUCE = "function(obj, prev) { prev.count++; }"
     # Aggregate the criteria. This will take the internally built selector and options
@@ -54,21 +75,32 @@ module Mongoid #:nodoc:
 
     # Get the count of matching documents in the database for the +Criteria+.
     #
-    # Options:
-    #
-    # klass: Optional class that the collection will be retrieved from.
-    #
     # Example:
     #
     # <tt>criteria.count</tt>
     #
     # Returns: <tt>Integer</tt>
-    def count(klass = nil)
+    def count
       return @count if @count
       @klass = klass if klass
       return @klass.collection.find(@selector, @options.dup).count
     end
 
+    # Iterate over each +Document+ in the results. This can take an optional
+    # block to pass to each argument in the results.
+    #
+    # Example:
+    #
+    # <tt>criteria.each { |doc| p doc }</tt>
+    def each
+      @collection ||= execute
+      if block_given?
+        @collection.each { |doc| yield doc }
+      else
+        @collection.each
+      end
+    end
+
     # 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".
@@ -89,32 +121,6 @@ module Mongoid #:nodoc:
       exclusions.each { |key, value| @selector[key] = { "$ne" => value } }; self
     end
 
-    # Execute the criteria. This will take the internally built selector and options
-    # and pass them on to the Ruby driver's +find()+ method on the collection. The
-    # collection itself will be retrieved from the class provided, and once the
-    # query has returned new documents of the type of class provided will be instantiated.
-    #
-    # If this is a +Criteria+ to only find the first object, this will return a
-    # single object of the type of class provided.
-    #
-    # If this is a +Criteria+ to find multiple results, will return an +Array+ of
-    # objects of the type of class provided.
-    def execute(klass = nil)
-      @klass = klass if klass
-      if type == :all
-        attributes = @klass.collection.find(@selector, @options.dup)
-        if attributes
-          @count = attributes.count
-          return attributes.collect { |doc| @klass.instantiate(doc) }
-        else
-          return []
-        end
-      else
-        attributes = @klass.collection.find_one(@selector, @options.dup)
-        return attributes ? @klass.instantiate(attributes) : nil
-      end
-    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.
     #
@@ -133,6 +139,16 @@ module Mongoid #:nodoc:
       self
     end
 
+    # Return the first result for the +Criteria+.
+    #
+    # Example:
+    #
+    # <tt>Criteria.select(:name).where(:name = "Chrissy").one</tt>
+    def one
+      attributes = @klass.collection.find_one(@selector, @options.dup)
+      attributes ? @klass.instantiate(attributes) : nil
+    end
+
     GROUP_REDUCE = "function(obj, prev) { prev.group.push(obj); }"
     # Groups the criteria. This will take the internally built selector and options
     # and pass them on to the Ruby driver's +group()+ method on the collection. The
@@ -196,8 +212,24 @@ module Mongoid #:nodoc:
     #
     # type: One of :all, :first:, or :last
     # klass: The class to execute on.
-    def initialize(type, klass = nil)
-      @selector, @options, @type, @klass = {}, {}, type, klass
+    def initialize(klass)
+      @selector, @options, @klass = {}, {}, klass
+    end
+
+    # Return the last result for the +Criteria+. Essentially does a find_one on
+    # the collection with the sorting reversed. If no sorting parameters have
+    # been provided it will default to ids.
+    #
+    # Example:
+    #
+    # <tt>Criteria.select(:name).where(:name = "Chrissy").last</tt>
+    def last
+      opts = @options.dup
+      sorting = opts[:sort]
+      sorting = [[:_id, :asc]] unless sorting
+      opts[:sort] = sorting.collect { |option| [ option[0], option[1].invert ] }
+      attributes = @klass.collection.find_one(@selector, opts)
+      attributes ? @klass.instantiate(attributes) : nil
     end
 
     # Adds a criterion to the +Criteria+ that specifies the maximum number of
@@ -217,6 +249,61 @@ module Mongoid #:nodoc:
       @options[:limit] = value; self
     end
 
+    # Merges another object into this +Criteria+. The other object may be a
+    # +Criteria+ or a +Hash+. This is used to combine multiple scopes together,
+    # where a chained scope situation may be desired.
+    #
+    # Options:
+    #
+    # other: The +Criteria+ or +Hash+ to merge with.
+    #
+    # Example:
+    #
+    # <tt>criteria.merge({ :conditions => { :title => "Sir" } })</tt>
+    def merge(other)
+      case other
+      when Hash
+        merge(self.class.translate(@klass, other))
+      else
+        @selector.update(other.selector)
+        @options.update(other.options)
+      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.
+    #
+    # Example:
+    #
+    #   class Person < Mongoid::Document
+    #     field :title
+    #     field :terms, :type => Boolean, :default => false
+    #
+    #     class << self
+    #       def knights
+    #         all(:conditions => { :title => "Sir" })
+    #       end
+    #
+    #       def accepted
+    #         all(:conditions => { :terms => true })
+    #       end
+    #     end
+    #   end
+    #
+    #   Person.accepted.knights #returns a merged criteria of the 2 scopes.
+    #
+    # Returns: <tt>Criteria</tt>
+    def method_missing(name, *args)
+      new_scope = @klass.send(name)
+      new_scope.merge(self)
+      new_scope
+    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".
@@ -272,17 +359,13 @@ module Mongoid #:nodoc:
 
     # Executes the +Criteria+ and paginates the results.
     #
-    # Options:
-    #
-    # klass: Optional class name to execute the criteria on.
-    #
     # Example:
     #
-    # <tt>criteria.paginate(Person)</tt>
-    def paginate(klass = nil)
-      results = execute(klass)
+    # <tt>criteria.paginate</tt>
+    def paginate
+      @collection ||= execute
       WillPaginate::Collection.create(page, per_page, count) do |pager|
-        pager.replace(results)
+        pager.replace(@collection)
       end
     end
 
@@ -340,16 +423,16 @@ module Mongoid #:nodoc:
     #
     # Example:
     #
-    # <tt>Criteria.translate("4ab2bc4b8ad548971900005c")</tt>
+    # <tt>Criteria.translate(Person, "4ab2bc4b8ad548971900005c")</tt>
     #
-    # <tt>Criteria.translate(:all, :conditions => { :field => "value"}, :limit => 20)</tt>
+    # <tt>Criteria.translate(Person, :conditions => { :field => "value"}, :limit => 20)</tt>
     #
     # Returns a new +Criteria+ object.
     def self.translate(*args)
-      type = args[0] || :all
+      klass = args[0]
       params = args[1] || {}
-      return new(:first).id(args[0]) unless type.is_a?(Symbol)
-      return new(type).where(params.delete(:conditions)).extras(params)
+      return new(klass).id(params).one if params.is_a?(String)
+      return new(klass).where(params.delete(:conditions) || {}).extras(params)
     end
 
     # Adds a criterion to the +Criteria+ that specifies values that must
@@ -372,6 +455,29 @@ module Mongoid #:nodoc:
     end
 
     protected
+    # Execute the criteria. This will take the internally built selector and options
+    # and pass them on to the Ruby driver's +find()+ method on the collection. The
+    # collection itself will be retrieved from the class provided, and once the
+    # query has returned new documents of the type of class provided will be instantiated.
+    #
+    # If this is a +Criteria+ to only find the first object, this will return a
+    # single object of the type of class provided.
+    #
+    # If this is a +Criteria+ to find multiple results, will return an +Array+ of
+    # objects of the type of class provided.
+    def execute
+      attributes = @klass.collection.find(@selector, @options.dup)
+      if attributes
+        @count = attributes.count
+        @collection = attributes.collect { |doc| @klass.instantiate(doc) }
+      else
+        @collection = []
+      end
+    end
+
+    # Filters the unused options out of the options +Hash+. Currently this
+    # takes into account the "page" and "per_page" options that would be passed
+    # in if using will_paginate.
     def filter_options
       page_num = @options.delete(:page)
       per_page_num = @options.delete(:per_page)

data/lib/mongoid/extensions/string/inflections.rb

@@ -2,9 +2,22 @@ module Mongoid #:nodoc:
   module Extensions #:nodoc:
     module String #:nodoc:
       module Inflections #:nodoc:
+
+        REVERSALS = {
+          "asc" => "desc",
+          "ascending" => "descending",
+          "desc" => "asc",
+          "descending" => "ascending"
+        }
+
+        def invert
+          REVERSALS[self]
+        end
+
         def singular?
           singularize == self
         end
+
         def plural?
           pluralize == self
         end

data/lib/mongoid/extensions/symbol/inflections.rb

@@ -2,12 +2,26 @@ module Mongoid #:nodoc:
   module Extensions #:nodoc:
     module Symbol #:nodoc:
       module Inflections #:nodoc:
+
+        REVERSALS = {
+          :asc => :desc,
+          :ascending => :descending,
+          :desc => :asc,
+          :descending => :ascending
+        }
+
+        def invert
+          REVERSALS[self]
+        end
+
         def singular?
           to_s.singular?
         end
+
         def plural?
           to_s.plural?
         end
+
       end
     end
   end

data/lib/mongoid/finders.rb

@@ -8,7 +8,7 @@ module Mongoid #:nodoc:
     #
     # <tt>Person.all(:conditions => { :attribute => "value" })</tt>
     def all(*args)
-      find(:all, *args)
+      find(*args)
     end
 
     # Returns a count of matching records in the database based on the
@@ -16,7 +16,16 @@ module Mongoid #:nodoc:
     #
     # <tt>Person.count(:first, :conditions => { :attribute => "value" })</tt>
     def count(*args)
-      Criteria.translate(*args).count(self)
+      Criteria.translate(self, *args).count
+    end
+
+    # Helper to initialize a new +Criteria+ object for this class.
+    #
+    # Example:
+    #
+    # <tt>Person.criteria</tt>
+    def criteria
+      Criteria.new(self)
     end
 
     # Find a +Document+ in several different ways.
@@ -33,7 +42,14 @@ module Mongoid #:nodoc:
     #
     # <tt>Person.find(Mongo::ObjectID.new.to_s)</tt>
     def find(*args)
-      Criteria.translate(*args).execute(self)
+      type = args.delete_at(0) if args[0].is_a?(Symbol)
+      criteria = Criteria.translate(self, *args)
+      case type
+      when :first then return criteria.one
+      when :last then return criteria.last
+      else
+        return criteria
+      end
     end
 
     # Find the first +Document+ given the conditions.
@@ -44,7 +60,7 @@ module Mongoid #:nodoc:
     #
     # <tt>Person.first(:conditions => { :attribute => "value" })</tt>
     def first(*args)
-      find(:first, *args)
+      find(*args).one
     end
 
     # Find the last +Document+ given the conditions.
@@ -55,8 +71,7 @@ module Mongoid #:nodoc:
     #
     # <tt>Person.last(:conditions => { :attribute => "value" })</tt>
     def last(*args)
-      return find(:last, :conditions => {}, :sort => [[:_id, :desc]]) if args.empty?
-      return find(:last, *args) unless args.empty?
+      find(*args).last
     end
 
     # Will execute a +Criteria+ based on the +DynamicFinder+ that gets
@@ -73,7 +88,7 @@ module Mongoid #:nodoc:
     def method_missing(name, *args)
       dyna = DynamicFinder.new(name, *args)
       finder, conditions = dyna.finder, dyna.conditions
-      results = Criteria.translate(finder, :conditions => conditions).execute(self)
+      results = find(finder, :conditions => conditions)
       results ? results : dyna.create(self)
     end
 
@@ -91,7 +106,7 @@ module Mongoid #:nodoc:
     #
     # Returns paginated array of docs.
     def paginate(params = {})
-      Criteria.translate(:all, params).paginate(self)
+      Criteria.translate(self, params).paginate
     end
 
     # Entry point for creating a new criteria from a Document. This will
@@ -108,7 +123,7 @@ module Mongoid #:nodoc:
     #
     # Returns: <tt>Criteria</tt>
     def select(*args)
-      Criteria.new(:all, self).select(*args)
+      Criteria.new(self).select(*args)
     end
 
   end

data/mongoid.gemspec

@@ -5,11 +5,11 @@
 
 Gem::Specification.new do |s|
   s.name = %q{mongoid}
-  s.version = "0.8.10"
+  s.version = "0.9.0"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Durran Jordan"]
-  s.date = %q{2009-11-27}
+  s.date = %q{2009-11-28}
   s.email = %q{durran@gmail.com}
   s.extra_rdoc_files = [
     "README.textile"

data/spec/integration/mongoid/document_spec.rb

@@ -64,6 +64,23 @@ describe Mongoid::Document do
     end
   end
 
+  context "chaining criteria scopes" do
+
+    before do
+      @one = Person.create(:title => "Mr", :age => 55, :terms => true)
+      @two = Person.create(:title => "Sir", :age => 55, :terms => true)
+      @three = Person.create(:title => "Sir", :age => 35, :terms => true)
+      @four = Person.create(:title => "Sir", :age => 55, :terms => false)
+    end
+
+    it "finds by the merged criteria" do
+      people = Person.old.accepted.knight
+      people.count.should == 1
+      people.first.should == @two
+    end
+
+  end
+
   context "using dynamic finders" do
 
     before do
@@ -113,7 +130,7 @@ describe Mongoid::Document do
 
       it "returns an array of documents based on the selector provided" do
         documents = Person.find(:all, :conditions => { :title => "Test"})
-        documents[0].title.should == "Test"
+        documents.first.title.should == "Test"
       end
 
     end
@@ -181,8 +198,7 @@ describe Mongoid::Document do
     end
 
     it "returns a proper count" do
-      @criteria = Mongoid::Criteria.translate(:all, { :per_page => 20, :page => 1 })
-      @criteria.execute(Person)
+      @criteria = Mongoid::Criteria.translate(Person, { :per_page => 20, :page => 1 })
       @criteria.count.should == 30
     end