djsun-mongo_mapper 0.5.6.6 → 0.5.8.1

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,18 +32,30 @@ 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
-      
-      def find(*args)
+
+      # @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
           when :first then first(options)
@@ -61,6 +73,12 @@ module MongoMapper
             end
         end
       end
+      
+      def find(*args)
+        find!(*args)
+      rescue DocumentNotFound
+        nil
+      end
 
       def paginate(options)
         per_page      = options.delete(:per_page) || self.per_page
@@ -73,15 +91,39 @@ 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
@@ -98,18 +140,51 @@ 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
 
-      # 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)
         if args.length == 1
@@ -120,6 +195,10 @@ 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
@@ -128,6 +207,27 @@ 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
@@ -136,6 +236,14 @@ module MongoMapper
         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
@@ -145,49 +253,73 @@ module MongoMapper
         @connection
       end
 
-      def database(name=nil)
-        if name.nil?
-          @database ||= MongoMapper.database
+      # 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
         else
-          @database = connection.db(name)
+          connection.db(database_name)
         end
-        @database
       end
-      
+
       # Changes the collection name from the default to whatever you want
-      def set_collection_name(name=nil)
-        @collection = nil
+      #
+      # @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.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)
+        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)
@@ -200,7 +332,7 @@ module MongoMapper
         def create_indexes_for(key)
           ensure_index key.name if key.options[:index]
         end
-        
+
         def initialize_each(*docs)
           instances = []
           docs = [{}] if docs.blank?
@@ -211,7 +343,7 @@ module MongoMapper
           end
           instances.size == 1 ? instances[0] : instances
         end
-        
+
         def initialize_doc(doc)
           begin
             klass = doc['_type'].present? ? doc['_type'].constantize : self
@@ -220,38 +352,38 @@ module MongoMapper
             new(doc)
           end
         end
-        
+
         def find_every(options)
           criteria, options = to_finder_options(options)
           collection.find(criteria, options).to_a.map do |doc|
             initialize_doc(doc)
           end
         end
-        
+
         def find_some(ids, options={})
           ids       = ids.flatten.compact.uniq
           documents = find_every(options.merge(:_id => ids))
-          
+
           if ids.size == documents.size
             documents
           else
             raise DocumentNotFound, "Couldn't find all of the ids (#{ids.to_sentence}). Found #{documents.size}, but was expecting #{ids.size}"
           end
         end
-        
+
         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| 
+          order.split(',').map do |order_segment|
             if order_segment =~ /\sasc/i
               order_segment.sub /\sasc/i, ' desc'
             elsif order_segment =~ /\sdesc/i
@@ -281,17 +413,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
@@ -314,6 +446,10 @@ module MongoMapper
         freeze
       end
 
+      def reload
+        self.class.find(id)
+      end
+
     private
       def create_or_update
         result = new? ? create : update
@@ -324,7 +460,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)
@@ -345,7 +481,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

data/lib/mongo_mapper/dynamic_finder.rb

@@ -14,7 +14,7 @@ module MongoMapper
     end
 
     protected
-      def match        
+      def match
         case method.to_s
           when /^find_(all_by|by)_([_a-zA-Z]\w*)$/
             @finder = :all if $1 == 'all_by'

data/lib/mongo_mapper/embedded_document.rb

@@ -241,7 +241,7 @@ module MongoMapper
         
         _keys.each_pair do |name, key|
           value = key.set(read_attribute(key.name))
-          attrs[name] = value
+          attrs[name] = value unless value.nil?
         end
         
         embedded_associations.each do |association|
@@ -269,13 +269,7 @@ module MongoMapper
       end
 
       def ==(other)
-        return false unless other.is_a?(EmbeddedDocument)
-        ignore = { '_id' => nil }
-        attributes.merge(ignore) == other.attributes.merge(ignore)
-      end
-      
-      def eql?(other)
-        other.is_a?(self.class) && (self == other)
+        other.is_a?(self.class) && id == other.id
       end
 
       def id
@@ -337,11 +331,13 @@ module MongoMapper
         end
 
         def read_attribute(name)
-          key = _keys[name]
-          raise KeyNotFound, "Could not find key: #{name.inspect}" unless key
-          value = key.get(instance_variable_get("@#{name}"))
-          instance_variable_set "@#{name}", value if !frozen?
-          value
+          if key = _keys[name]
+            value = key.get(instance_variable_get("@#{name}"))
+            instance_variable_set "@#{name}", value if !frozen?
+            value
+          else
+            raise KeyNotFound, "Could not find key: #{name.inspect}"
+          end
         end
 
         def read_attribute_before_typecast(name)

data/lib/mongo_mapper/finder_options.rb

@@ -1,15 +1,35 @@
 module MongoMapper
+  # Controls the parsing and handling of options used by finders.
+  #
+  # == 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.
+  #
+  # @private
+  class FinderOperator
+    def initialize(field, operator)
+      @field, @operator = field, operator
+    end
+    
+    def to_criteria(value)
+      {@field => {@operator => value}}
+    end
+  end
+  
   class FinderOptions
     OptionKeys = [:fields, :select, :skip, :offset, :limit, :sort, :order]
-    
-    attr_reader :model, :options
-    
+
     def initialize(model, options)
-      raise ArgumentError, "FinderOptions must be a hash" unless options.is_a?(Hash)
+      raise ArgumentError, "Options must be a hash" unless options.is_a?(Hash)
       options.symbolize_keys!
       
-      @model, @options, @conditions = model, {}, options.delete(:conditions) || {}
-      
+      @model      = model
+      @options    = {}
+      @conditions = options.delete(:conditions) || {}
+
       options.each_pair do |key, value|
         if OptionKeys.include?(key)
           @options[key] = value
@@ -17,37 +37,50 @@ module MongoMapper
           @conditions[key] = value
         end
       end
+
+      add_sci_scope
     end
     
+    # @return [Hash] Mongo compatible criteria options
+    #
+    # @see FinderOptions#to_mongo_criteria
     def criteria
-      to_mongo_criteria(model, @conditions)
+      to_mongo_criteria(@conditions)
     end
     
+    # @return [Hash] Mongo compatible options
     def options
-      to_mongo_options(model, @options)
+      options = @options.dup
+
+      fields = options.delete(:fields) || options.delete(:select)
+      skip   = options.delete(:skip)   || options.delete(:offset) || 0
+      limit  = options.delete(:limit)  || 0
+      sort   = options.delete(:sort)   || convert_order_to_sort(options.delete(:order))
+
+      {: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
-    
+
     private
-      def to_mongo_criteria(model, conditions, parent_key=nil)
+      def to_mongo_criteria(conditions, parent_key=nil)
         criteria = {}
-        add_sci_scope(model, criteria)
 
         conditions.each_pair do |field, value|
-          field = field_normalized(field)
+          field = normalized_field(field)
+          if field.is_a?(FinderOperator)
+            criteria.merge!(field.to_criteria(value))
+            next
+          end
           case value
             when Array
-              operator_present = field.to_s =~ /^\$/            
-              criteria[field] = if operator_present
-                                  value
-                                else
-                                  {'$in' => value}
-                                end
+              operator_present = field.to_s =~ /^\$/
+              criteria[field] = operator?(field) ? value : {'$in' => value}
             when Hash
-              criteria[field] = to_mongo_criteria(model, value, field)
+              criteria[field] = to_mongo_criteria(value, field)
             else            
               criteria[field] = value
           end
@@ -55,48 +88,38 @@ module MongoMapper
 
         criteria
       end
-      
-      def field_normalized(field)
-        if field.to_s == 'id'
-          :_id
-        else
-          field
-        end
+
+      def operator?(field)
+        field.to_s =~ /^\$/
+      end
+
+      def normalized_field(field)
+        field.to_s == 'id' ? :_id : field
       end
 
       # adds _type single collection inheritance scope for models that need it
-      def add_sci_scope(model, criteria)
-        if model.single_collection_inherited?
-          criteria[:_type] = model.to_s
+      def add_sci_scope
+        if @model.single_collection_inherited?
+          @conditions[:_type] = @model.to_s
         end
       end
 
-      def to_mongo_options(model, options)
-        options = options.dup
-        {
-          :fields => to_mongo_fields(options.delete(:fields) || options.delete(:select)),
-          :skip   => (options.delete(:skip) || options.delete(:offset) || 0).to_i,
-          :limit  => (options.delete(:limit) || 0).to_i,
-          :sort   => options.delete(:sort) || to_mongo_sort(options.delete(:order))
-        }
-      end
-      
       def to_mongo_fields(fields)
         return if fields.blank?
-      
+
         if fields.is_a?(String)
           fields.split(',').map { |field| field.strip }
         else
           fields.flatten.compact
         end
       end
-    
-      def to_mongo_sort(sort)
+
+      def convert_order_to_sort(sort)
         return if sort.blank?
         pieces = sort.split(',')
         pieces.map { |s| to_mongo_sort_piece(s) }
       end
-    
+
       def to_mongo_sort_piece(str)
         field, direction = str.strip.split(' ')
         direction ||= 'ASC'
@@ -104,4 +127,4 @@ module MongoMapper
         [field, direction]
       end
   end
-end
+end

data/lib/mongo_mapper/pagination.rb

@@ -30,6 +30,8 @@ module MongoMapper
       def skip
         (current_page - 1) * per_page
       end
+      alias offset skip # for will paginate support
+      
       
       def method_missing(name, *args, &block)
         @subject.send(name, *args, &block)

data/lib/mongo_mapper/serialization.rb

@@ -5,7 +5,7 @@ module MongoMapper #:nodoc:
     class Serializer #:nodoc:
       attr_reader :options
 
-      def initialize(record, options = {})
+      def initialize(record, options={})
         @record, @options = record, options.dup
       end
 

data/lib/mongo_mapper/serializers/json_serializer.rb

@@ -49,7 +49,7 @@ module MongoMapper #:nodoc:
     #   # => {"id": 1, "name": "Konata Izumi", "age": 16,
     #         "created_at": "2006/08/01", "awesome": true,
     #         "permalink": "1-konata-izumi"}
-    def to_json(options = {})
+    def to_json(options={})
       apply_to_json_defaults(options)
       
       if include_root_in_json

data/lib/mongo_mapper/support.rb

@@ -1,4 +1,5 @@
 class BasicObject #:nodoc:
+  alias_method :proxy_extend, :extend
   instance_methods.each { |m| undef_method m unless m =~ /(^__|^nil\?$|^send$|^methods$|instance_eval|proxy_|^object_id$)/ }
 end unless defined?(BasicObject)
 
@@ -129,6 +130,14 @@ class String
   end
 end
 
+class Symbol
+  %w{gt lt gte lte ne in nin mod size where exists}.each do |operator|
+    define_method operator do
+      MongoMapper::FinderOperator.new(self, "$#{operator}")
+    end
+  end
+end
+
 class Time
   def self.to_mongo(value)
     if value.nil? || value == ''