mongoid 0.3.4 → 0.4.0

data/README.textile

@@ -3,26 +3,19 @@
 <h3>About Mongoid</h3>
 
 <p>
-  Mongoid is an ODM (Object-Document-Mapper) framework for MongoDB in Ruby. Mongoid differs from other
-  mapping frameworks in that it constrains the models into behaving in a manner appropriate for a
-  document database. That is to say there are no relationships between documents in the underlying datastore.
-  If a relationship is set up in the Model the child models are automatically embedded within the parent document
-  in the database. The concept of a foreign key relationship to another Document does not exist, as that is
-  design and thinking for a relational database, not a document database. Mongoloid does however provide
-  all the ActiveRecord style functionality you need, with the difference that it stores all associations
-  within the parent document.
+  Mongoid is an ODM (Object-Document-Mapper) framework for MongoDB in Ruby.
 </p>
 
 <h3>Project Tracking</h3>
 
 <a href="http://www.pivotaltracker.com/projects/27482">Mongoid on Pivotal Tracker</a>
 <a href="http://groups.google.com/group/mongoid">Mongoid Google Group</a>
-<a href="http://ci.hshrckt.com:4891/">Mongoid on CI Joe</a>
+<a href="http://mongoid.org:4444/">Mongoid on CI Joe</a>
 
 <h3>Compatibility</h3>
 
 <p>
-  Mongoid is developed against Ruby 1.8.6, 1.8.7, 1.9.1
+  Mongoid is developed against Ruby 1.8.6, 1.8.7, 1.9.1, 1.9.2
 </p>
 
 <h2>Mongoid in Action</h2>
@@ -55,6 +48,7 @@ Example of a simple domain model:
     fields \
       :first_name,
       :last_name
+    has_timestamps
   end
 </pre>
 
@@ -85,15 +79,15 @@ Update a Document:
 Search for a Document in the database:
 
 <pre>
-  Person.find(:all, :title => "Esquire")
+  Person.find(:all, :conditions => {:title => "Esquire"})
 
-  Person.find(:first, :title => "Esquire")
+  Person.find(:first, :conditions => {:title => "Esquire"})
 </pre>
 
 Paginate Document search results:
 
 <pre>
-  Person.paginate(:title => "Esquire", :page => 1, :per_page => 20)
+  Person.paginate(:conditions => {:title => "Esquire"}, :page => 1, :per_page => 20)
 </pre>
 
 Validations:

data/Rakefile

@@ -8,7 +8,7 @@ begin
   require "jeweler"
   Jeweler::Tasks.new do |gem|
     gem.name = "mongoid"
-    gem.summary = %Q{Mongoid}
+    gem.summary = "ODM framework for MongoDB"
     gem.email = "durran@gmail.com"
     gem.homepage = "http://github.com/durran/mongoid"
     gem.authors = ["Durran Jordan"]
@@ -37,13 +37,13 @@ end
 
 Rake::RDocTask.new do |rdoc|
   if File.exist?("VERSION.yml")
-    config = YAML.load(File.read("VERSION.yml"))
+    config = File.read("VERSION")
     version = "#{config[:major]}.#{config[:minor]}.#{config[:patch]}"
   else
     version = ""
   end
   rdoc.rdoc_dir = "rdoc"
-  rdoc.title = "my_emma #{version}"
+  rdoc.title = "mongoid #{version}"
   rdoc.rdoc_files.include("README*")
   rdoc.rdoc_files.include("lib/**/*.rb")
 end

data/VERSION

@@ -1 +1 @@
-0.3.4
+0.4.0

data/lib/mongoid/criteria.rb

@@ -1,85 +1,265 @@
 module Mongoid #:nodoc:
-  class Criteria #:nodoc:
+  # The +Criteria+ class is the core object needed in Mongoid to retrieve
+  # objects from the database. It is a DSL that essentially sets up the
+  # selector and options arguments that get passed on to a <tt>Mongo::Collection</tt>
+  # in the Ruby driver. Each method on the +Criteria+ returns self to they
+  # can be chained in order to create a readable criterion to be executed
+  # against the database.
+  #
+  # Example setup:
+  #
+  # <tt>criteria = Criteria.new</tt>
+  #
+  # <tt>criteria.select(:field => "value").only(:field).skip(20).limit(20)</tt>
+  #
+  # <tt>criteria.execute</tt>
+  class Criteria
     attr_reader :selector, :options, :type
 
-    # Supply a hash of arrays for field values that must match every single
-    # element in the array.
+    # 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:
+    #
+    # selections: 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>
+    #
+    # <tt>criteria.all(:field1 => ["value1", "value2"], :field2 => ["value1"])</tt>
+    #
+    # Returns: <tt>self</tt>
     def all(selections = {})
       selections.each { |key, value| @selector[key] = { "$all" => value } }; self
     end
 
-    # Excludes the parameters passed using $ne in the selector.
+    # 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".
+    #
+    # Options:
+    #
+    # excludes: 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.
+    #
+    # Example:
+    #
+    # <tt>criteria.excludes(:field => "value1")</tt>
+    #
+    # <tt>criteria.excludes(:field1 => "value1", :field2 => "value1")</tt>
+    #
+    # Returns: <tt>self</tt>
     def excludes(exclusions = {})
       exclusions.each { |key, value| @selector[key] = { "$ne" => value } }; self
     end
 
-    # Execute the criteria, which will retrieve the results from
-    # the collection.
-    def execute(collection, klass)
-      return klass.new(collection.find_one(@selector, @options)) if type == :first
-      return collection.find(@selector, @options).collect { |doc| klass.new(doc) }
+    # 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)
+      return klass.new(klass.collection.find_one(@selector, @options)) if type == :first
+      return klass.collection.find(@selector, @options).collect { |doc| klass.new(doc) }
     end
 
-    # Defines criteria for matching any of the supplied parameters, similar to
-    # a SQL in statement.
+    # 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".
+    #
+    # Options:
+    #
+    # inclusions: A +Hash+ where the key is the field name and the value is an
+    # +Array+ of values that any can match.
+    #
+    # Example:
+    #
+    # <tt>criteria.in(:field => ["value1", "value2"])</tt>
+    #
+    # <tt>criteria.in(:field1 => ["value1", "value2"], :field2 => ["value1"])</tt>
+    #
+    # Returns: <tt>self</tt>
     def in(inclusions = {})
       inclusions.each { |key, value| @selector[key] = { "$in" => value } }; self
     end
 
-    # Adds an _id criteria to the selector.
+    # Adds a criterion to the +Criteria+ that specifies an id that must be matched.
+    #
+    # Options:
+    #
+    # object_id: A +String+ representation of a <tt>Mongo::ObjectID</tt>
+    #
+    # Example:
+    #
+    # <tt>criteria.id("4ab2bc4b8ad548971900005c")</tt>
+    #
+    # Returns: <tt>self</tt>
     def id(object_id)
       @selector[:_id] = Mongo::ObjectID.from_string(object_id); self
     end
 
-    # Create the new Criteria object. Does not take any params, just
-    # initializes the selector and options hashes that will be 
-    # eventually passed to the driver.
+    # Create the new +Criteria+ object. This will initialize the selector
+    # and options hashes, as well as the type of criteria.
+    #
+    # Options:
+    #
+    # type: One of :all, :first:, or :last
     def initialize(type)
       @selector, @options, @type = {}, {}, type
     end
 
-    # Limits the number of results returned by the query, usually used in
-    # conjunction with skip() for pagination.
+    # 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)
       @options[:limit] = value; self
     end
 
-    # The conditions that must prove true on each record in the
-    # database in order for them to be a part of the result set.
-    # This is a hash that maps to a selector in the driver.
+    # 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.
+    #
+    # Options:
+    #
+    # selectior: A +Hash+ that must match the attributes of the +Document+.
+    #
+    # Example:
+    #
+    # <tt>criteria.select(:field1 => "value1", :field2 => 15)</tt>
+    #
+    # Returns: <tt>self</tt>
     def select(selector = {})
       @selector = selector; self
     end
 
-    # Defines a clause that the criteria should ignore.
+    # 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".
+    #
+    # Options:
+    #
+    # exclusions: A +Hash+ where the key is the field name and the value is an
+    # +Array+ of values that none can match.
+    #
+    # Example:
+    #
+    # <tt>criteria.not_in(:field => ["value1", "value2"])</tt>
+    #
+    # <tt>criteria.not_in(:field1 => ["value1", "value2"], :field2 => ["value1"])</tt>
+    #
+    # Returns: <tt>self</tt>
     def not_in(exclusions)
       exclusions.each { |key, value| @selector[key] = { "$nin" => value } }; self
     end
 
-    # Define extras for the criteria.
+    # 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)
       @options = extras; self
     end
 
-    # Specifies how to sort this Criteria. Current valid params
-    # are: { :field => 1 } or { :field => -1 }
+    # 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: A +Hash+ where the key is the field name and the value is an
+    # integer specifying the direction: 1 for ascending, -1 for descending.
+    #
+    # Example:
+    #
+    # <tt>criteria.order_by(:field1 => 1, :field2 => -1)</tt>
+    #
+    # Returns: <tt>self</tt>
     def order_by(params = {})
       @options[:sort] = params; self
     end
 
-    # Specify what fields to be returned from the database.
-    # Similar to a SQL select field1, field2, field3
+    # 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.
+    #
+    # Options:
+    #
+    # params: A list of field names to retrict the returned fields to.
+    #
+    # Example:
+    #
+    # <tt>criteria.only(:field1, :field2, :field3)</tt>
+    #
+    # Returns: <tt>self</tt>
     def only(*args)
       @options[:fields] = args.flatten; self
     end
 
-    # Skips the supplied number of records, as offset behaves in traditional
-    # pagination.
+    # 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)
       @options[:skip] = value; self
     end
 
-    # Translate the supplied arguments into a criteria object.
+    # Translate the supplied arguments into a +Criteria+ object. 
+    # 
+    # If the passed in args is a single +String+, then it will 
+    # construct an id +Criteria+ from it.
+    #
+    # If the passed in args are a type and a hash, then it will construct
+    # the +Criteria+ with the proper selector, options, and type.
+    #
+    # Options:
+    #
+    # args: either a +String+ or a +Symbol+, +Hash combination.
+    #
+    # Example:
+    #
+    # <tt>Criteria.translate("4ab2bc4b8ad548971900005c")</tt>
+    #
+    # <tt>Criteria.translate(:all, :conditions => { :field => "value"}, :limit => 20)</tt>
+    #
+    # Returns a new +Criteria+ object.
     def self.translate(*args)
       type, params = args[0], args[1] || {}
       return new(:first).id(type.to_s) if type.is_a?(String)

data/lib/mongoid/document.rb

@@ -16,7 +16,6 @@ module Mongoid #:nodoc:
 
     class << self
 
-      # Create an association to a parent Document.
       # Get an aggregate count for the supplied group of fields and the
       # selector that is provided.
       def aggregate(fields, params = {})
@@ -61,7 +60,7 @@ module Mongoid #:nodoc:
       # Model.find(:first, :attribute => "value")
       # Model.find(:all, :attribute => "value")
       def find(*args)
-        Criteria.translate(*args).execute(collection, self)
+        Criteria.translate(*args).execute(self)
       end
 
       # Find a single Document given the passed selector, which is a Hash of attributes that

data/mongoid.gemspec

@@ -5,11 +5,11 @@
 
 Gem::Specification.new do |s|
   s.name = %q{mongoid}
-  s.version = "0.3.4"
+  s.version = "0.4.0"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Durran Jordan"]
-  s.date = %q{2009-10-09}
+  s.date = %q{2009-10-10}
   s.email = %q{durran@gmail.com}
   s.extra_rdoc_files = [
     "README.textile"
@@ -51,7 +51,7 @@ Gem::Specification.new do |s|
   s.rdoc_options = ["--charset=UTF-8"]
   s.require_paths = ["lib"]
   s.rubygems_version = %q{1.3.5}
-  s.summary = %q{Mongoid}
+  s.summary = %q{ODM framework for MongoDB}
   s.test_files = [
     "spec/integration/mongoid/document_spec.rb",
      "spec/spec_helper.rb",

data/spec/unit/mongoid/criteria_spec.rb

@@ -39,8 +39,9 @@ describe Mongoid::Criteria do
       it "calls find on the collection with the selector and options" do
         criteria = Mongoid::Criteria.new(:first)
         collection = mock
+        Person.expects(:collection).returns(collection)
         collection.expects(:find_one).with(@criteria.selector, @criteria.options).returns({})
-        criteria.execute(collection, Person).should be_a_kind_of(Person)
+        criteria.execute(Person).should be_a_kind_of(Person)
       end
 
     end
@@ -50,8 +51,9 @@ describe Mongoid::Criteria do
       it "calls find on the collection with the selector and options" do
         criteria = Mongoid::Criteria.new(:all)
         collection = mock
+        Person.expects(:collection).returns(collection)
         collection.expects(:find).with(@criteria.selector, @criteria.options).returns([])
-        criteria.execute(collection, Person).should == []
+        criteria.execute(Person).should == []
       end
 
     end

data/spec/unit/mongoid/document_spec.rb

@@ -137,7 +137,7 @@ describe Mongoid::Document do
 
       it "delegates to criteria" do
         Mongoid::Criteria.expects(:translate).with(@id.to_s).returns(@criteria)
-        @criteria.expects(:execute).with(@collection, Person).returns(@attributes)
+        @criteria.expects(:execute).with(Person).returns(@attributes)
         Person.find(@id.to_s)
       end
 
@@ -147,7 +147,7 @@ describe Mongoid::Document do
 
       it "delegates to criteria" do
         Mongoid::Criteria.expects(:translate).with(:first, :conditions => { :test => "Test" }).returns(@criteria)
-        @criteria.expects(:execute).with(@collection, Person).returns(@attributes)
+        @criteria.expects(:execute).with(Person).returns(@attributes)
         Person.find(:first, :conditions => { :test => "Test" })
       end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: mongoid
 version: !ruby/object:Gem::Version 
-  version: 0.3.4
+  version: 0.4.0
 platform: ruby
 authors: 
 - Durran Jordan
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-10-09 00:00:00 -04:00
+date: 2009-10-10 00:00:00 -04:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -119,7 +119,7 @@ rubyforge_project:
 rubygems_version: 1.3.5
 signing_key: 
 specification_version: 3
-summary: Mongoid
+summary: ODM framework for MongoDB
 test_files: 
 - spec/integration/mongoid/document_spec.rb
 - spec/spec_helper.rb