mongo_mapper 0.5.6 → 0.5.7

data/.gitignore

@@ -5,4 +5,6 @@ rdoc
 pkg
 *~
 *.gem
-tmp
+tmp
+.yardoc
+doc/*

data/README.rdoc

@@ -35,7 +35,10 @@ You can also just declare the source:
 
 == Documentation
 
+Documentation is lacking right now because if you can't look through the code right now and feel comfortable, this is probably too young for you to use. Wait til it stabilizes a bit more.
+
 http://rdoc.info/projects/jnunemaker/mongomapper
+http://groups.google.com/group/mongomapper
 
 == More Info
 

data/VERSION

@@ -1 +1 @@
-0.5.6
+0.5.7

data/lib/mongo_mapper.rb

@@ -3,8 +3,17 @@ require 'mongo'
 require 'validatable'
 
 module MongoMapper
-  DocumentNotFound  = Class.new(StandardError)
-  DocumentNotValid  = Class.new(StandardError) do
+  # generic MM error
+  class MongoMapperError < StandardError; end
+  
+  # raised when key expected to exist but not found
+  class KeyNotFound < MongoMapperError; end
+  
+  # raised when document expected but not found
+  class DocumentNotFound < MongoMapperError; end
+  
+  # raised when document not valid and using !
+  class DocumentNotValid < MongoMapperError
     def initialize(document)
       @document = document
       super("Validation failed: #{@document.errors.full_messages.join(", ")}")
@@ -54,13 +63,12 @@ module MongoMapper
   module Finders
     def dynamic_find(finder, args)
       attributes = {}
-      find_options = args.extract_options!.deep_merge(:conditions => attributes)
-
       finder.attributes.each_with_index do |attr, index|
         attributes[attr] = args[index]
       end
-
-      result = find(finder.finder, find_options)
+      
+      options = args.extract_options!.merge(attributes)
+      result  = find(finder.finder, options)
 
       if result.nil?
         if finder.bang

data/lib/mongo_mapper/associations.rb

@@ -1,13 +1,13 @@
 module MongoMapper
   module Associations
     module ClassMethods
-      def belongs_to(association_id, options = {})
+      def belongs_to(association_id, options={})
         create_association(:belongs_to, association_id, options)
         self
       end
 
-      def many(association_id, options = {})
-        create_association(:many, association_id, options)
+      def many(association_id, options = {}, &block)
+        create_association(:many, association_id, options, &block)
         self
       end
 
@@ -18,13 +18,20 @@ module MongoMapper
       end
 
       private
-        def create_association(type, name, options)
+        def create_association(type, name, options, &extension)
+          options[:extend] = modulized_extensions(extension, options[:extend])
           association = Associations::Base.new(type, name, options)
           associations[association.name] = association
           define_association_methods(association)
           define_dependent_callback(association)
           association
         end
+        
+        def modulized_extensions(*extensions)
+          extensions.flatten.compact.map do |extension|
+            Proc === extension ? Module.new(&extension) : extension
+          end
+        end
 
         def define_association_methods(association)
           define_method(association.name) do
@@ -59,7 +66,6 @@ module MongoMapper
             end
           end
         end
-
     end
 
     module InstanceMethods

data/lib/mongo_mapper/associations/base.rb

@@ -1,10 +1,22 @@
 module MongoMapper
   module Associations
     class Base
-      attr_reader :type, :name, :options
-
-      def initialize(type, name, options = {})
-        @type, @name, @options = type, name, options
+      attr_reader :type, :name, :options, :finder_options
+      
+      # Options that should not be considered MongoDB query options/criteria
+      AssociationOptions = [:as, :class_name, :dependent, :extend, :foreign_key, :polymorphic]
+      
+      def initialize(type, name, options={})
+        @type, @name = type, name
+        @options, @finder_options = {}, {}
+        
+        options.each_pair do |key, value|
+          if AssociationOptions.include?(key)
+            @options[key] = value
+          else
+            @finder_options[key] = value
+          end
+        end
       end
 
       def class_name
@@ -26,7 +38,7 @@ module MongoMapper
       def many?
         @many_type ||= @type == :many
       end
-
+      
       def belongs_to?
         @belongs_to_type ||= @type == :belongs_to
       end

data/lib/mongo_mapper/associations/many_documents_as_proxy.rb

@@ -8,10 +8,8 @@ module MongoMapper
 
         def apply_scope(doc)
           ensure_owner_saved
-
           doc.send("#{as_type_name}=", @owner.class.name)
           doc.send("#{as_id_name}=", @owner.id)
-
           doc
         end
 

data/lib/mongo_mapper/associations/many_documents_proxy.rb

@@ -4,7 +4,7 @@ module MongoMapper
       delegate :klass, :to => :@association
       delegate :collection, :to => :klass
       
-      include MongoMapper::Finders
+      include ::MongoMapper::Finders
       
       def find(*args)
         options = args.extract_options!
@@ -16,19 +16,19 @@ module MongoMapper
       end
 
       def all(options={})
-        find(:all, scoped_options(options))
+        klass.all(scoped_options(options))
       end
 
       def first(options={})
-        find(:first, scoped_options(options))
+        klass.first(scoped_options(options))
       end
 
       def last(options={})
-        find(:last, scoped_options(options))
+        klass.last(scoped_options(options))
       end
 
-      def count(conditions={})
-        klass.count(conditions.deep_merge(scoped_conditions))
+      def count(options={})
+        klass.count(scoped_options(options))
       end
 
       def replace(docs)
@@ -57,20 +57,20 @@ module MongoMapper
         doc
       end
 
-      def destroy_all(conditions={})
-        all(:conditions => conditions).map(&:destroy)
+      def destroy_all(options={})
+        all(options).map(&:destroy)
         reset
       end
 
-      def delete_all(conditions={})
-        klass.delete_all(conditions.deep_merge(scoped_conditions))
+      def delete_all(options={})
+        klass.delete_all(options.merge(scoped_conditions))
         reset
       end
       
       def nullify
-        criteria = FinderOptions.to_mongo_criteria(klass, scoped_conditions)
+        criteria = FinderOptions.new(klass, scoped_conditions).criteria
         all(criteria).each do |doc|
-          doc.update_attributes self.foreign_key => nil
+          doc.update_attributes(self.foreign_key => nil)
         end
         reset
       end
@@ -89,13 +89,13 @@ module MongoMapper
         def scoped_conditions
           {self.foreign_key => @owner.id}
         end
-
+        
         def scoped_options(options)
-          options.deep_merge({:conditions => scoped_conditions})
+          @association.finder_options.merge(options).merge(scoped_conditions)
         end
 
         def find_target
-          find(:all)
+          all
         end
 
         def ensure_owner_saved

data/lib/mongo_mapper/associations/many_embedded_polymorphic_proxy.rb

@@ -1,6 +1,6 @@
 module MongoMapper
   module Associations
-    class ManyEmbeddedPolymorphicProxy < Proxy      
+    class ManyEmbeddedPolymorphicProxy < Proxy
       def replace(v)
         @_values = v.map do |doc_or_hash|
           if doc_or_hash.kind_of?(EmbeddedDocument)
@@ -30,4 +30,4 @@ module MongoMapper
         end
     end
   end
-end
+end

data/lib/mongo_mapper/associations/many_polymorphic_proxy.rb

@@ -1,6 +1,6 @@
 module MongoMapper
   module Associations
-    class ManyPolymorphicProxy < ManyDocumentsProxy      
+    class ManyPolymorphicProxy < ManyDocumentsProxy
       private
         def apply_scope(doc)
           doc.send("#{@association.type_key_name}=", doc.class.name)

data/lib/mongo_mapper/associations/proxy.rb

@@ -6,6 +6,7 @@ module MongoMapper
       def initialize(owner, association)
         @owner = owner
         @association = association
+        @association.options[:extend].each { |ext| proxy_extend(ext) }
         reset
       end
 

data/lib/mongo_mapper/callbacks.rb

@@ -1,4 +1,17 @@
 module MongoMapper
+  # This module is mixed into the Document module to provide call-backs before 
+  # and after the following events:
+  #
+  # * save
+  # * create
+  # * update
+  # * validation
+  # ** every validation
+  # ** validation when created
+  # ** validation when updated
+  # * destruction
+  #
+  # @see ActiveSupport::Callbacks
   module Callbacks
     def self.included(model) #:nodoc:
       model.class_eval do
@@ -42,6 +55,11 @@ module MongoMapper
       return result
     end
 
+    # Here we override the +destroy+ method to allow for the +before_destroy+ 
+    # and +after_destroy+ call-backs. Note that the +destroy+ call is aborted 
+    # if the +before_destroy+ call-back returns +false+.
+    #
+    # @return the result of calling +destroy+ on the document
     def destroy #:nodoc:
       return false if callback(:before_destroy) == false
       result = super

data/lib/mongo_mapper/document.rb

@@ -13,12 +13,12 @@ module MongoMapper
         extend Validations::Macros
         extend ClassMethods
         extend Finders
-        
+
         def self.per_page
           25
         end unless respond_to?(:per_page)
       end
-      
+
       descendants << model
     end
 
@@ -32,17 +32,29 @@ module MongoMapper
         create_indexes_for(key)
         key
       end
-      
+
       def ensure_index(name_or_array, options={})
         keys_to_index = if name_or_array.is_a?(Array)
           name_or_array.map { |pair| [pair[0], pair[1]] }
         else
           name_or_array
         end
-        
+
         MongoMapper.ensure_index(self, keys_to_index, options)
       end
-      
+
+      # @overload find(:first, options)
+      #   @see Document.first
+      #
+      # @overload find(:last, options)
+      #   @see Document.last
+      #
+      # @overload find(:all, options)
+      #   @see Document.all
+      #
+      # @overload find(ids, options)
+      #
+      # @raise DocumentNotFound raised when no ID or arguments are provided
       def find(*args)
         options = args.extract_options!
         case args.first
@@ -55,7 +67,7 @@ module MongoMapper
               when 0
                 raise DocumentNotFound, "Couldn't find without an ID"
               when 1
-                find_one(args[0], options)
+                find_one!(options.merge({:_id => args[0]}))
               else
                 find_some(args, options)
             end
@@ -63,68 +75,113 @@ module MongoMapper
       end
 
       def paginate(options)
-        per_page      = options.delete(:per_page) ||  self.per_page
+        per_page      = options.delete(:per_page) || self.per_page
         page          = options.delete(:page)
-        total_entries = count(options[:conditions] || {})
-        collection    = Pagination::PaginationProxy.new(total_entries, page, per_page)
+        total_entries = count(options)
+        pagination    = Pagination::PaginationProxy.new(total_entries, page, per_page)
 
-        options[:limit] = collection.limit
-        options[:skip]  = collection.skip
-
-        collection.subject = find_every(options)
-        collection
+        options.merge!(:limit => pagination.limit, :skip => pagination.skip)
+        pagination.subject = find_every(options)
+        pagination
       end
 
+      # @param [Hash] options any conditions understood by 
+      #   FinderOptions.to_mongo_criteria
+      #
+      # @return the first document in the ordered collection as described by 
+      #   +options+
+      #
+      # @see FinderOptions
       def first(options={})
-        options.merge!(:limit => 1)
-        find_every(options)[0]
+        find_one(options)
       end
 
+      # @param [Hash] options any conditions understood by 
+      #   FinderOptions.to_mongo_criteria
+      # @option [String] :order this *mandatory* option describes how to 
+      #   identify the ordering of the documents in your collection. Note that 
+      #   the *last* document in this collection will be selected.
+      #
+      # @return the last document in the ordered collection as described by 
+      #   +options+
+      #
+      # @raise Exception when no <tt>:order</tt> option has been defined
       def last(options={})
-        if options[:order].blank?
-          raise ':order option must be provided when using last'
-        end
-        
-        options.merge!(:limit => 1)
-        options[:order] = invert_order_clause(options[:order])
-        find_every(options)[0]
+        raise ':order option must be provided when using last' if options[:order].blank?
+        find_one(options.merge(:order => invert_order_clause(options[:order])))
       end
 
+      # @param [Hash] options any conditions understood by 
+      #   FinderOptions.to_mongo_criteria
+      #
+      # @return [Array] all documents in your collection that match the 
+      #   provided conditions
+      #
+      # @see FinderOptions
       def all(options={})
         find_every(options)
       end
 
       def find_by_id(id)
-        criteria = FinderOptions.to_mongo_criteria(self, :_id => id)
-        if doc = collection.find_one(criteria)
-          new(doc)
-        end
+        find_one(:_id => id)
       end
 
-      def count(conditions={})
-        collection.find(FinderOptions.to_mongo_criteria(self, conditions)).count
+      def count(options={})
+        collection.find(to_criteria(options)).count
       end
 
-      def exists?(conditions={})
-        !count(conditions).zero?
+      def exists?(options={})
+        !count(options).zero?
       end
 
+      # @overload create(doc_attributes)
+      #   Create a single new document
+      #   @param [Hash] doc_attributes key/value pairs to create a new 
+      #     document
+      #
+      # @overload create(docs_attributes)
+      #   Create many new documents
+      #   @param [Array<Hash>] provide many Hashes of key/value pairs to create 
+      #     multiple documents
+      #
+      # @example Creating a single document
+      #   MyModel.create({ :foo => "bar" })
+      #
+      # @example Creating multiple documents
+      #   MyModel.create([{ :foo => "bar" }, { :foo => "baz" })
+      #
+      # @return [Boolean] when a document is successfully created, +true+ will 
+      #   be returned. If a document fails to create, +false+ will be returned.
       def create(*docs)
         initialize_each(*docs) { |doc| doc.save }
       end
 
+      # @see Document.create
+      #
+      # @raise [DocumentNotValid] raised if a document fails to create
       def create!(*docs)
         initialize_each(*docs) { |doc| doc.save! }
       end
 
-      # For updating single document
+      # @overload update(id, attributes)
+      #   Update a single document
+      #   @param id the ID of the document you wish to update
+      #   @param [Hash] attributes the key to update on the document with a new 
+      #     value
+      #
+      # @overload update(ids_and_attributes)
+      #   Update multiple documents
+      #   @param [Hash] ids_and_attributes each key is the ID of some document 
+      #     you wish to update. The value each key points toward are those 
+      #     applied to the target document
+      #
+      # @example Updating single document
       #   Person.update(1, {:foo => 'bar'})
       #
-      # For updating multiple documents at once:
+      # @example Updating multiple documents at once:
       #   Person.update({'1' => {:foo => 'bar'}, '2' => {:baz => 'wick'}})
       def update(*args)
-        updating_multiple = args.length == 1
-        if updating_multiple
+        if args.length == 1
           update_multiple(args[0])
         else
           id, attributes = args
@@ -132,24 +189,55 @@ module MongoMapper
         end
       end
 
+      # Removes ("deletes") one or many documents from the collection. Note 
+      # that this will bypass any +destroy+ hooks defined by your class.
+      #
+      # @param [Array] ids the ID or IDs of the records you wish to delete
       def delete(*ids)
-        criteria = FinderOptions.to_mongo_criteria(self, :_id => ids.flatten)
-        collection.remove(criteria)
+        collection.remove(to_criteria(:_id => ids.flatten))
       end
 
-      def delete_all(conditions={})
-        criteria = FinderOptions.to_mongo_criteria(self, conditions)
-        collection.remove(criteria)
+      def delete_all(options={})
+        collection.remove(to_criteria(options))
       end
 
+      # Iterates over each document found by the provided IDs and calls their 
+      # +destroy+ method. This has the advantage of processing your document's 
+      # +destroy+ call-backs.
+      #
+      # @overload destroy(id)
+      #   Destroy a single document by ID
+      #   @param id the ID of the document to destroy
+      #
+      # @overload destroy(ids)
+      #   Destroy many documents by their IDs
+      #   @param [Array] the IDs of each document you wish to destroy
+      #
+      # @example Destroying a single document
+      #   Person.destroy("34")
+      #
+      # @example Destroying multiple documents
+      #   Person.destroy("34", "45", ..., "54")
+      #
+      #   # OR...
+      #
+      #   Person.destroy(["34", "45", ..., "54"])
       def destroy(*ids)
         find_some(ids.flatten).each(&:destroy)
       end
 
-      def destroy_all(conditions={})
-        all(conditions).each(&:destroy)
+      def destroy_all(options={})
+        all(options).each(&:destroy)
       end
 
+      # @overload connection()
+      #   @return [Mongo::Connection] the connection used by your document class
+      #
+      # @overload connection(mongo_connection)
+      #   @param [Mongo::Connection] mongo_connection a new connection for your 
+      #     document class to use
+      #   @return [Mongo::Connection] a new Mongo::Connection for yoru document 
+      #     class
       def connection(mongo_connection=nil)
         if mongo_connection.nil?
           @connection ||= MongoMapper.connection
@@ -159,6 +247,12 @@ module MongoMapper
         @connection
       end
 
+      # @overload database()
+      #   @return [Mongo] the database object used by your document class
+      #
+      # @overload database(name)
+      #   @param [String] name the name of an existing, or new, Mongo database
+      #   @return [Mongo] a Mongo database object for the specified database
       def database(name=nil)
         if name.nil?
           @database ||= MongoMapper.database
@@ -167,42 +261,49 @@ module MongoMapper
         end
         @database
       end
-      
+
       # Changes the collection name from the default to whatever you want
+      #
+      # @param [#to_s] name the new collection name to use. Defaults to +nil+
       def set_collection_name(name=nil)
         @collection = nil
         @collection_name = name
       end
-      
+
       # Returns the collection name, if not set, defaults to class name tableized
+      #
+      # @return [String] the collection name, if not set, defaults to class 
+      #   name tableized
       def collection_name
-        @collection_name ||= self.to_s.demodulize.tableize
+        @collection_name ||= self.to_s.tableize.gsub(/\//, '.')
       end
 
-      # Returns the mongo ruby driver collection object
+      # @return the Mongo Ruby driver +collection+ object
       def collection
         @collection ||= database.collection(collection_name)
       end
       
+      # Defines a +created_at+ and +updated_at+ attribute (with a +Time+ 
+      # value) on your document. These attributes are updated by an 
+      # injected +update_timestamps+ +before_save+ hook.
       def timestamps!
         key :created_at, Time
         key :updated_at, Time
-        
         class_eval { before_save :update_timestamps }
       end
-      
+
       def single_collection_inherited?
         keys.has_key?('_type') && single_collection_inherited_superclass?
       end
-      
+
       def single_collection_inherited_superclass?
         superclass.respond_to?(:keys) && superclass.keys.has_key?('_type')
       end
-            
+
       protected
         def method_missing(method, *args)
           finder = DynamicFinder.new(method)
-          
+
           if finder.found?
             meta_def(finder.method) { |*args| dynamic_find(finder, args) }
             send(finder.method, *args)
@@ -212,50 +313,41 @@ module MongoMapper
         end
 
       private
-        # Initializes each document and yields each initialized document
+        def create_indexes_for(key)
+          ensure_index key.name if key.options[:index]
+        end
+
         def initialize_each(*docs)
           instances = []
           docs = [{}] if docs.blank?
           docs.flatten.each do |attrs|
-            doc = new(attrs)
+            doc = initialize_doc(attrs)
             yield(doc)
             instances << doc
           end
           instances.size == 1 ? instances[0] : instances
         end
 
-        def create_indexes_for(key)
-          ensure_index key.name if key.options[:index]
+        def initialize_doc(doc)
+          begin
+            klass = doc['_type'].present? ? doc['_type'].constantize : self
+            klass.new(doc)
+          rescue NameError
+            new(doc)
+          end
         end
-        
+
         def find_every(options)
-          criteria, options = FinderOptions.new(self, options).to_a
+          criteria, options = to_finder_options(options)
           collection.find(criteria, options).to_a.map do |doc|
-            begin
-              klass = doc['_type'].present? ? doc['_type'].constantize : self
-              klass.new(doc)
-            rescue NameError
-              new(doc)
-            end
+            initialize_doc(doc)
           end
         end
 
-        def invert_order_clause(order)
-          order.split(',').map do |order_segment| 
-            if order_segment =~ /\sasc/i
-              order_segment.sub /\sasc/i, ' desc'
-            elsif order_segment =~ /\sdesc/i
-              order_segment.sub /\sdesc/i, ' asc'
-            else
-              "#{order_segment.strip} desc"
-            end
-          end.join(',')
-        end
-
         def find_some(ids, options={})
-          ids = ids.flatten.compact.uniq
-          documents = find_every(options.deep_merge(:conditions => {'_id' => ids}))
-          
+          ids       = ids.flatten.compact.uniq
+          documents = find_every(options.merge(:_id => ids))
+
           if ids.size == documents.size
             documents
           else
@@ -263,14 +355,29 @@ module MongoMapper
           end
         end
 
-        def find_one(id, options={})
-          if doc = find_every(options.deep_merge(:conditions => {:_id => id})).first
-            doc
-          else
-            raise DocumentNotFound, "Document with id of #{id} does not exist in collection named #{collection.name}"
+        def find_one(options={})
+          criteria, options = to_finder_options(options)
+          if doc = collection.find_one(criteria, options)
+            initialize_doc(doc)
           end
         end
 
+        def find_one!(options={})
+          find_one(options) || raise(DocumentNotFound, "Document match #{options.inspect} does not exist in #{collection.name} collection")
+        end
+
+        def invert_order_clause(order)
+          order.split(',').map do |order_segment|
+            if order_segment =~ /\sasc/i
+              order_segment.sub /\sasc/i, ' desc'
+            elsif order_segment =~ /\sdesc/i
+              order_segment.sub /\sdesc/i, ' asc'
+            else
+              "#{order_segment.strip} desc"
+            end
+          end.join(',')
+        end
+
         def update_single(id, attrs)
           if id.blank? || attrs.blank? || !attrs.is_a?(Hash)
             raise ArgumentError, "Updating a single document requires an id and a hash of attributes"
@@ -290,9 +397,17 @@ module MongoMapper
           docs.each_pair { |id, attrs| instances << update(id, attrs) }
           instances
         end
+
+        def to_criteria(options={})
+          FinderOptions.new(self, options).criteria
+        end
+
+        def to_finder_options(options={})
+          FinderOptions.new(self, options).to_a
+        end
     end
 
-    module InstanceMethods      
+    module InstanceMethods
       def collection
         self.class.collection
       end
@@ -311,12 +426,14 @@ module MongoMapper
 
       def destroy
         return false if frozen?
-
-        criteria = FinderOptions.to_mongo_criteria(self.class, :_id => id)
-        collection.remove(criteria) unless new?
+        self.class.delete(id) unless new?
         freeze
       end
 
+      def reload
+        self.class.find(id)
+      end
+
     private
       def create_or_update
         result = new? ? create : update
@@ -327,7 +444,7 @@ module MongoMapper
         assign_id
         save_to_collection
       end
-      
+
       def assign_id
         if read_attribute(:_id).blank?
           write_attribute(:_id, Mongo::ObjectID.new.to_s)
@@ -348,7 +465,7 @@ module MongoMapper
         write_attribute('created_at', now) if new?
         write_attribute('updated_at', now)
       end
-      
+
       def clear_custom_id_flag
         @using_custom_id = nil
       end