mongo_mapper-unstable 2009.12.30 → 2010.1.4

data/lib/mongo_mapper/document.rb

@@ -6,7 +6,6 @@ module MongoMapper
       model.class_eval do
         include EmbeddedDocument
         include InstanceMethods
-        include Observing
         include Callbacks
         include Dirty
         include RailsCompatibility::Document
@@ -19,6 +18,9 @@ module MongoMapper
         end unless respond_to?(:per_page)
       end
 
+      extra_extensions.each { |extension| model.extend(extension) }
+      extra_inclusions.each { |inclusion| model.send(:include, inclusion) }
+
       descendants << model
     end
 
@@ -26,6 +28,34 @@ module MongoMapper
       @descendants ||= Set.new
     end
 
+    def self.append_extensions(*extensions)
+      extra_extensions.concat extensions
+
+      # Add the extension to existing descendants
+      descendants.each do |model|
+        extensions.each { |extension| model.extend(extension) }
+      end
+    end
+
+    # @api private
+    def self.extra_extensions
+      @extra_extensions ||= []
+    end
+
+    def self.append_inclusions(*inclusions)
+      extra_inclusions.concat inclusions
+
+      # Add the inclusion to existing descendants
+      descendants.each do |model|
+        inclusions.each { |inclusion| model.send :include, inclusion }
+      end
+    end
+
+    # @api private
+    def self.extra_inclusions
+      @extra_inclusions ||= []
+    end
+    
     module ClassMethods
       def key(*args)
         key = super
@@ -43,18 +73,6 @@ module MongoMapper
         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
@@ -91,45 +109,21 @@ module MongoMapper
         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={})
         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={})
         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)
-        find_one(:_id => id)
+        find(id)
       end
 
       def count(options={})
@@ -140,52 +134,14 @@ module MongoMapper
         !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
 
-      # @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'})
-      #
-      # @example Updating multiple documents at once:
-      #   Person.update({'1' => {:foo => 'bar'}, '2' => {:baz => 'wick'}})
       def update(*args)
         if args.length == 1
           update_multiple(args[0])
@@ -195,10 +151,6 @@ 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)
         collection.remove(to_criteria(:_id => ids.flatten))
       end
@@ -207,27 +159,6 @@ module MongoMapper
         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
@@ -235,15 +166,58 @@ module MongoMapper
       def destroy_all(options={})
         all(options).each(&:destroy)
       end
+      
+      def increment(*args)
+        modifier_update('$inc', args)
+      end
+      
+      def decrement(*args)
+        criteria, keys = criteria_and_keys_from_args(args)
+        values, to_decrement = keys.values, {}
+        keys.keys.each_with_index { |k, i| to_decrement[k] = -values[i].abs }
+        collection.update(criteria, {'$inc' => to_decrement}, :multi => true)
+      end
+      
+      def set(*args)
+        modifier_update('$set', args)
+      end
+      
+      def push(*args)
+        modifier_update('$push', args)
+      end
+      
+      def push_all(*args)
+        modifier_update('$pushAll', args)
+      end
+      
+      def push_uniq(*args)
+        criteria, keys = criteria_and_keys_from_args(args)
+        keys.each { |key, value | criteria[key] = {'$ne' => value} }
+        collection.update(criteria, {'$push' => keys}, :multi => true)
+      end
+      
+      def pull(*args)
+        modifier_update('$pull', args)
+      end
+      
+      def pull_all(*args)
+        modifier_update('$pullAll', args)
+      end
+      
+      def modifier_update(modifier, args)
+        criteria, keys = criteria_and_keys_from_args(args)
+        modifiers = {modifier => keys}
+        collection.update(criteria, modifiers, :multi => true)
+      end
+      private :modifier_update
+      
+      def criteria_and_keys_from_args(args)
+        keys     = args.pop
+        criteria = args[0].is_a?(Hash) ? args[0] : {:id => args}
+        [to_criteria(criteria), keys]
+      end
+      private :criteria_and_keys_from_args
 
-      # @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
@@ -253,24 +227,14 @@ module MongoMapper
         @connection
       end
 
-      # Changes the database name from the default to whatever you want
-      #
-      # @param [#to_s] name the new database name to use.
       def set_database_name(name)
         @database_name = name
       end
       
-      # Returns the database name
-      #
-      # @return [String] the database name
       def database_name
         @database_name
       end
 
-      # Returns the database the document should use. Defaults to
-      #   MongoMapper.database if other database is not set.
-      #
-      # @return [Mongo::DB] the mongo database instance
       def database
         if database_name.nil?
           MongoMapper.database
@@ -279,35 +243,31 @@ module MongoMapper
         end
       end
 
-      # Changes the collection name from the default to whatever you want
-      #
-      # @param [#to_s] name the new collection name to use.
       def set_collection_name(name)
         @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.tableize.gsub(/\//, '.')
       end
 
-      # @return the Mongo Ruby driver +collection+ object
       def 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 userstamps!
+        key :creator_id, ObjectId
+        key :updater_id, ObjectId
+        belongs_to :creator, :class_name => 'User'
+        belongs_to :updater, :class_name => 'User'
+      end
+
       def single_collection_inherited?
         keys.has_key?('_type') && single_collection_inherited_superclass?
       end
@@ -406,13 +366,23 @@ module MongoMapper
       def collection
         self.class.collection
       end
+      
+      def database
+        self.class.database
+      end
 
       def new?
         read_attribute('_id').blank? || using_custom_id?
       end
 
-      def save(perform_validations=true)
-        !perform_validations || valid? ? create_or_update : false
+      def save(options={})
+        if options === false
+          ActiveSupport::Deprecation.warn "save with true/false is deprecated. You should now use :validate => true/false."
+          options = {:validate => false}
+        end
+        options.reverse_merge!(:validate => true)
+        perform_validations = options.delete(:validate)
+        !perform_validations || valid? ? create_or_update(options) : false
       end
 
       def save!
@@ -420,9 +390,11 @@ module MongoMapper
       end
 
       def destroy
-        return false if frozen?
-        self.class.delete(_id) unless new?
-        freeze
+        self.class.delete(id) unless new?
+      end
+      
+      def delete
+        self.class.delete(id) unless new?
       end
 
       def reload
@@ -433,14 +405,14 @@ module MongoMapper
       end
 
     private
-      def create_or_update
-        result = new? ? create : update
+      def create_or_update(options={})
+        result = new? ? create(options) : update(options)
         result != false
       end
 
-      def create
+      def create(options={})
         assign_id
-        save_to_collection
+        save_to_collection(options)
       end
 
       def assign_id
@@ -449,13 +421,14 @@ module MongoMapper
         end
       end
 
-      def update
-        save_to_collection
+      def update(options={})
+        save_to_collection(options)
       end
 
-      def save_to_collection
+      def save_to_collection(options={})
         clear_custom_id_flag
-        collection.save(to_mongo)
+        safe = options.delete(:safe) || false
+        collection.save(to_mongo, :safe => safe)
       end
 
       def update_timestamps

data/lib/mongo_mapper/embedded_document.rb

@@ -281,7 +281,7 @@ module MongoMapper
       end
 
       def id
-        read_attribute(:_id)
+        self[:_id]
       end
 
       def id=(value)
@@ -291,7 +291,7 @@ module MongoMapper
           @using_custom_id = true
         end
         
-        write_attribute :_id, value
+        self[:_id] = value
       end
 
       def using_custom_id?
@@ -305,16 +305,12 @@ module MongoMapper
         "#<#{self.class} #{attributes_as_nice_string}>"
       end
 
-      def save
-        if _root_document
-          _root_document.save
-        end
+      def save(options={})
+        _root_document.try(:save, options)
       end
       
-      def save!
-        if _root_document
-          _root_document.save!
-        end
+      def save!(options={})
+        _root_document.try(:save!, options)
       end
 
       def update_attributes(attrs={})
@@ -355,7 +351,7 @@ module MongoMapper
         def read_attribute(name)
           if key = _keys[name]
             value = key.get(instance_variable_get("@#{name}"))
-            instance_variable_set "@#{name}", value if !frozen?
+            instance_variable_set "@#{name}", value
             value
           else
             raise KeyNotFound, "Could not find key: #{name.inspect}"

data/lib/mongo_mapper/finder_options.rb

@@ -1,25 +1,20 @@
 module MongoMapper
-  # Controls the parsing and handling of options used by finders.
-  #
-  # == Important Note
-  #
+  # = Important Note
   # This class is private to MongoMapper and should not be considered part of 
-  # MongoMapper's public API. Some documentation herein, however, may prove 
-  # useful for understanding how MongoMapper handles the parsing of finder 
-  # conditions and options.
+  # MongoMapper's public API.
   #
   class FinderOptions
     OptionKeys = [:fields, :select, :skip, :offset, :limit, :sort, :order]
-    
+
     def self.normalized_field(field)
       field.to_s == 'id' ? :_id : field
     end
-    
+
     def self.normalized_order_direction(direction)
       direction ||= 'ASC'
       direction.upcase == 'ASC' ? 1 : -1
     end
-    
+
     def initialize(model, options)
       raise ArgumentError, "Options must be a hash" unless options.is_a?(Hash)
       options = options.symbolize_keys
@@ -38,15 +33,11 @@ module MongoMapper
 
       add_sci_scope
     end
-    
-    # @return [Hash] Mongo compatible criteria options
-    #
-    # @see FinderOptions#to_mongo_criteria
+
     def criteria
       to_mongo_criteria(@conditions)
     end
-    
-    # @return [Hash] Mongo compatible options
+
     def options
       fields = @options.delete(:fields) || @options.delete(:select)
       skip   = @options.delete(:skip)   || @options.delete(:offset) || 0
@@ -55,8 +46,7 @@ module MongoMapper
 
       {:fields => to_mongo_fields(fields), :skip => skip.to_i, :limit => limit.to_i, :sort => sort}
     end
-    
-    # @return [Array<Hash>] Mongo criteria and options enclosed in an Array
+
     def to_a
       [criteria, options]
     end
@@ -82,6 +72,8 @@ module MongoMapper
               criteria[field] = operator?(field) ? value : {'$in' => value}
             when Hash
               criteria[field] = to_mongo_criteria(value, field)
+            when Time
+              criteria[field] = value.utc
             else            
               criteria[field] = value
           end
@@ -104,10 +96,10 @@ module MongoMapper
       def to_mongo_fields(fields)
         return if fields.blank?
 
-        if fields.is_a?(String)
-          fields.split(',').map { |field| field.strip }
-        else
+        if fields.respond_to?(:flatten, :compact)
           fields.flatten.compact
+        else
+          fields.split(',').map { |field| field.strip }
         end
       end
 

data/lib/mongo_mapper/mongo_mapper.rb

@@ -0,0 +1,125 @@
+# if Gem is defined i'll assume you are using rubygems and lock specific versions
+# call me crazy but a plain old require will just get the latest version you have installed
+# so i want to make sure that if you are using gems you do in fact have the correct versions
+# if there is a better way to do this, please enlighten me!
+if self.class.const_defined?(:Gem)
+  gem 'activesupport', '>= 2.3'
+  gem 'mongo', '0.18.2'
+  gem 'jnunemaker-validatable', '1.8.1'
+end
+
+require 'active_support'
+require 'mongo'
+require 'validatable'
+
+module MongoMapper
+  # 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)
+      super("Validation failed: #{document.errors.full_messages.join(", ")}")
+    end
+  end
+  
+  # @api public
+  def self.connection
+    @@connection ||= Mongo::Connection.new
+  end
+  
+  # @api public
+  def self.connection=(new_connection)
+    @@connection = new_connection
+  end
+  
+  # @api public
+  def self.logger
+    connection.logger
+  end
+  
+  # @api public
+  def self.database=(name)
+    @@database = nil
+    @@database_name = name
+  end
+  
+  # @api public
+  def self.database
+    if @@database_name.blank?
+      raise 'You forgot to set the default database name: MongoMapper.database = "foobar"'
+    end
+    
+    @@database ||= MongoMapper.connection.db(@@database_name)
+  end
+  
+  # @api private
+  def self.ensured_indexes
+    @@ensured_indexes ||= []
+  end
+  
+  # @api private
+  def self.ensured_indexes=(value)
+    @@ensured_indexes = value
+  end
+  
+  # @api private
+  def self.ensure_index(klass, keys, options={})
+    ensured_indexes << {:klass => klass, :keys => keys, :options => options}
+  end
+  
+  # @api public
+  def self.ensure_indexes!
+    ensured_indexes.each do |index|
+      unique = index[:options].delete(:unique)
+      index[:klass].collection.create_index(index[:keys], unique)
+    end
+  end
+  
+  # @api private
+  def self.use_time_zone?
+    Time.respond_to?(:zone) && Time.zone ? true : false
+  end
+  
+  # @api private
+  def self.time_class
+    use_time_zone? ? Time.zone : Time
+  end
+  
+  # @api private
+  def self.normalize_object_id(value)
+    value.is_a?(String) ? Mongo::ObjectID.from_string(value) : value
+  end
+end
+
+require 'mongo_mapper/support'
+require 'mongo_mapper/callbacks'
+require 'mongo_mapper/finder_options'
+require 'mongo_mapper/dirty'
+require 'mongo_mapper/dynamic_finder'
+require 'mongo_mapper/key'
+require 'mongo_mapper/pagination'
+require 'mongo_mapper/serialization'
+require 'mongo_mapper/validations'
+require 'mongo_mapper/rails_compatibility/document'
+require 'mongo_mapper/rails_compatibility/embedded_document'
+require 'mongo_mapper/embedded_document'
+require 'mongo_mapper/document'
+require 'mongo_mapper/associations'
+require 'mongo_mapper/associations/base'
+require 'mongo_mapper/associations/proxy'
+require 'mongo_mapper/associations/collection'
+require 'mongo_mapper/associations/many_documents_proxy'
+require 'mongo_mapper/associations/belongs_to_proxy'
+require 'mongo_mapper/associations/belongs_to_polymorphic_proxy'
+require 'mongo_mapper/associations/many_polymorphic_proxy'
+require 'mongo_mapper/associations/many_embedded_proxy'
+require 'mongo_mapper/associations/many_embedded_polymorphic_proxy'
+require 'mongo_mapper/associations/many_documents_as_proxy'
+require 'mongo_mapper/associations/one_proxy'

data/lib/mongo_mapper/pagination.rb

@@ -1,7 +1,7 @@
 module MongoMapper
   module Pagination
     class PaginationProxy
-      instance_methods.each { |m| undef_method m unless m =~ /(^__|^nil\?$|proxy_|^object_id$)/ }
+      instance_methods.each { |m| undef_method m unless m =~ /(^__|^nil\?$|^send$|proxy_|^object_id$)/ }
       
       attr_accessor :subject
       attr_reader :total_entries, :per_page, :current_page
@@ -33,7 +33,18 @@ module MongoMapper
         (current_page - 1) * per_page
       end
       alias offset skip # for will paginate support
+
+      def send(method, *args, &block)
+        if respond_to?(method)
+          super
+        else
+          subject.send(method, *args, &block)
+        end
+      end
       
+      def ===(other)
+        other === subject
+      end
       
       def method_missing(name, *args, &block)
         @subject.send(name, *args, &block)