djsun-mongo_mapper 0.5.6.6 → 0.5.8.1

data/.gitignore

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

data/Rakefile

@@ -1,23 +1,24 @@
 require 'rubygems'
 require 'rake'
-
 require 'jeweler'
+require 'yard'
+require 'yard/rake/yardoc_task'
+
 Jeweler::Tasks.new do |gem|
   gem.name        = "djsun-mongo_mapper"
-  gem.summary     = %Q{Awesome gem for modeling your domain and storing it in mongo}
-  gem.description = %Q{Awesome gem for modeling your domain and storing it in mongo}
+  gem.summary     = %(Model your domain, store it in MongoDB)
   gem.email       = "nunemaker@gmail.com"
   gem.homepage    = "http://github.com/jnunemaker/mongomapper"
-  gem.authors     = ["John Nunemaker"]
+  gem.authors     = ["John Nunemaker", "David James"]
   
   gem.add_dependency('activesupport', '>= 2.3')
-  gem.add_dependency('mongo', '>= 0.15.1')
-  gem.add_dependency('jnunemaker-validatable', '>= 1.8.0')
+  gem.add_dependency('mongo', '>= 0.16')
+  gem.add_dependency('jnunemaker-validatable', '>= 1.8.1')
   
   gem.add_development_dependency('jnunemaker-matchy', '>= 0.4.0')
   gem.add_development_dependency('shoulda', '>= 2.10.2')
-  gem.add_development_dependency('timecop', '>= 0.3.1')
-  gem.add_development_dependency('mocha', '>= 0.9.4')
+  gem.add_development_dependency('timecop', '>= 0.3.2')
+  gem.add_development_dependency('mocha', '>= 0.9.8')
 end
 
 Jeweler::GemcutterTasks.new
@@ -48,3 +49,7 @@ end
 
 task :default  => :test
 task :test     => :check_dependencies
+
+YARD::Rake::YardocTask.new(:doc) do |t|
+  t.options = ["--legacy"]
+end

data/VERSION

@@ -1 +1 @@
-0.5.6.6
+0.5.8.1

data/djsun-mongo_mapper.gemspec

@@ -5,13 +5,12 @@
 
 Gem::Specification.new do |s|
   s.name = %q{djsun-mongo_mapper}
-  s.version = "0.5.6.6"
+  s.version = "0.5.8.1"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
-  s.authors = ["John Nunemaker"]
+  s.authors = ["John Nunemaker", "David James"]
   s.date = %q{2009-11-04}
   s.default_executable = %q{mmconsole}
-  s.description = %q{Awesome gem for modeling your domain and storing it in mongo}
   s.email = %q{nunemaker@gmail.com}
   s.executables = ["mmconsole"]
   s.extra_rdoc_files = [
@@ -53,7 +52,6 @@ Gem::Specification.new do |s|
      "lib/mongo_mapper/serializers/json_serializer.rb",
      "lib/mongo_mapper/support.rb",
      "lib/mongo_mapper/validations.rb",
-     "mongo_mapper.gemspec",
      "specs.watchr",
      "test/NOTE_ON_TESTING",
      "test/functional/associations/test_belongs_to_polymorphic_proxy.rb",
@@ -63,7 +61,6 @@ Gem::Specification.new do |s|
      "test/functional/associations/test_many_embedded_proxy.rb",
      "test/functional/associations/test_many_polymorphic_proxy.rb",
      "test/functional/associations/test_many_proxy.rb",
-     "test/functional/associations/test_namespace.rb",
      "test/functional/test_associations.rb",
      "test/functional/test_binary.rb",
      "test/functional/test_callbacks.rb",
@@ -76,7 +73,7 @@ Gem::Specification.new do |s|
      "test/functional/test_validations.rb",
      "test/models.rb",
      "test/support/custom_matchers.rb",
-     "test/support/test_timing.rb",
+     "test/support/timing.rb",
      "test/test_helper.rb",
      "test/unit/serializers/test_json_serializer.rb",
      "test/unit/test_association_base.rb",
@@ -98,7 +95,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{Awesome gem for modeling your domain and storing it in mongo}
+  s.summary = %q{Model your domain, store it in MongoDB}
   s.test_files = [
     "test/functional/associations/test_belongs_to_polymorphic_proxy.rb",
      "test/functional/associations/test_belongs_to_proxy.rb",
@@ -107,7 +104,6 @@ Gem::Specification.new do |s|
      "test/functional/associations/test_many_embedded_proxy.rb",
      "test/functional/associations/test_many_polymorphic_proxy.rb",
      "test/functional/associations/test_many_proxy.rb",
-     "test/functional/associations/test_namespace.rb",
      "test/functional/test_associations.rb",
      "test/functional/test_binary.rb",
      "test/functional/test_callbacks.rb",
@@ -120,7 +116,7 @@ Gem::Specification.new do |s|
      "test/functional/test_validations.rb",
      "test/models.rb",
      "test/support/custom_matchers.rb",
-     "test/support/test_timing.rb",
+     "test/support/timing.rb",
      "test/test_helper.rb",
      "test/unit/serializers/test_json_serializer.rb",
      "test/unit/test_association_base.rb",
@@ -145,29 +141,29 @@ Gem::Specification.new do |s|
 
     if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
       s.add_runtime_dependency(%q<activesupport>, [">= 2.3"])
-      s.add_runtime_dependency(%q<mongo>, [">= 0.15.1"])
-      s.add_runtime_dependency(%q<jnunemaker-validatable>, [">= 1.8.0"])
+      s.add_runtime_dependency(%q<mongo>, [">= 0.16"])
+      s.add_runtime_dependency(%q<jnunemaker-validatable>, [">= 1.8.1"])
       s.add_development_dependency(%q<jnunemaker-matchy>, [">= 0.4.0"])
       s.add_development_dependency(%q<shoulda>, [">= 2.10.2"])
-      s.add_development_dependency(%q<timecop>, [">= 0.3.1"])
-      s.add_development_dependency(%q<mocha>, [">= 0.9.4"])
+      s.add_development_dependency(%q<timecop>, [">= 0.3.2"])
+      s.add_development_dependency(%q<mocha>, [">= 0.9.8"])
     else
       s.add_dependency(%q<activesupport>, [">= 2.3"])
-      s.add_dependency(%q<mongo>, [">= 0.15.1"])
-      s.add_dependency(%q<jnunemaker-validatable>, [">= 1.8.0"])
+      s.add_dependency(%q<mongo>, [">= 0.16"])
+      s.add_dependency(%q<jnunemaker-validatable>, [">= 1.8.1"])
       s.add_dependency(%q<jnunemaker-matchy>, [">= 0.4.0"])
       s.add_dependency(%q<shoulda>, [">= 2.10.2"])
-      s.add_dependency(%q<timecop>, [">= 0.3.1"])
-      s.add_dependency(%q<mocha>, [">= 0.9.4"])
+      s.add_dependency(%q<timecop>, [">= 0.3.2"])
+      s.add_dependency(%q<mocha>, [">= 0.9.8"])
     end
   else
     s.add_dependency(%q<activesupport>, [">= 2.3"])
-    s.add_dependency(%q<mongo>, [">= 0.15.1"])
-    s.add_dependency(%q<jnunemaker-validatable>, [">= 1.8.0"])
+    s.add_dependency(%q<mongo>, [">= 0.16"])
+    s.add_dependency(%q<jnunemaker-validatable>, [">= 1.8.1"])
     s.add_dependency(%q<jnunemaker-matchy>, [">= 0.4.0"])
     s.add_dependency(%q<shoulda>, [">= 2.10.2"])
-    s.add_dependency(%q<timecop>, [">= 0.3.1"])
-    s.add_dependency(%q<mocha>, [">= 0.9.4"])
+    s.add_dependency(%q<timecop>, [">= 0.3.2"])
+    s.add_dependency(%q<mocha>, [">= 0.9.8"])
   end
 end
 

data/lib/mongo_mapper/associations/base.rb

@@ -1,41 +1,27 @@
-module ConstantHelper
-  def self.lookup(class_name, scope)
-    if class_name.is_a?(Class)
-      class_name
-    elsif namespaced?(class_name)
-      class_name.constantize
-    else
-      lookup_in_parent(class_name, scope)
-    end
-  end
-  
-  def self.namespaced?(class_name)
-    class_name.include?("::")
-  end
-  
-  def self.lookup_in_parent(class_name, scope)
-    parent = parent_scope(scope)
-    return nil unless parent.const_defined?(class_name)
-    parent.const_get(class_name)
-  end
-    
-  def self.parent_scope(scope)
-    chain = scope.to_s.split("::")[0 ... -1]
-    chain.reduce(Object) { |m, o| m.const_get(o) }
-  end
-  
-  def self.leaf(constant_name)
-    constant_name.split("::").last
-  end
-end
-
 module MongoMapper
   module Associations
+    # Base class for keeping track of associations.
+    #
+    # @private
     class Base
-      attr_reader :type, :name, :options
+      attr_reader :type, :name, :options, :finder_options
+
+      # Options that should not be considered MongoDB query options/criteria
+      AssociationOptions = [:as, :class, :class_name, :dependent, :extend, :foreign_key, :polymorphic]
+
+      def initialize(type, name, options={}, &extension)
+        @type, @name, @options, @finder_options = type, name, {}, {}
+        options.symbolize_keys!
 
-      def initialize(type, name, options = {})
-        @type, @name, @options = type, name, options
+        options[:extend] = modulized_extensions(extension, options[:extend])
+
+        options.each_pair do |key, value|
+          if AssociationOptions.include?(key)
+            @options[key] = value
+          else
+            @finder_options[key] = value
+          end
+        end
       end
 
       def class_name
@@ -49,9 +35,9 @@ module MongoMapper
           end
         end
       end
-      
+
       def klass
-        @klass ||= ConstantHelper.lookup(class_name, options[:scope])
+        @klass ||= options[:class] || class_name.constantize
       end
 
       def many?
@@ -109,6 +95,16 @@ module MongoMapper
           end
         end # end begin
       end # end proxy_class
+
+      private
+
+        # @param [Array<Module, Proc>] extensions a collection of Modules or 
+        #   Procs that extend the behaviour of this association.
+        def modulized_extensions(*extensions)
+          extensions.flatten.compact.map do |extension|
+            Proc === extension ? Module.new(&extension) : extension
+          end
+        end
     end
   end
 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

@@ -10,25 +10,30 @@ module MongoMapper
         options = args.extract_options!
         klass.find(*args << scoped_options(options))
       end
+      
+      def find!(*args)
+        options = args.extract_options!
+        klass.find!(*args << scoped_options(options))
+      end
 
       def paginate(options)
         klass.paginate(scoped_options(options))
       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(options={})
-        klass.count(options.merge(scoped_conditions))
+        klass.count(scoped_options(options))
       end
 
       def replace(docs)
@@ -56,6 +61,12 @@ module MongoMapper
         apply_scope(doc).save
         doc
       end
+      
+      def create!(attrs={})
+        doc = klass.new(attrs)
+        apply_scope(doc).save!
+        doc
+      end
 
       def destroy_all(options={})
         all(options).map(&:destroy)
@@ -89,13 +100,13 @@ module MongoMapper
         def scoped_conditions
           {self.foreign_key => @owner.id}
         end
-
+        
         def scoped_options(options)
-          options.merge(scoped_conditions)
+          @association.finder_options.merge(options).merge(scoped_conditions)
         end
 
         def find_target
-          find(:all)
+          all
         end
 
         def ensure_owner_saved
@@ -109,9 +120,7 @@ module MongoMapper
         end
 
         def foreign_key
-          @association.options[:foreign_key] || 
-            (ConstantHelper.leaf(@owner.class.name).
-              underscore.gsub("/", "_") + "_id")
+          @association.options[:foreign_key] || @owner.class.name.underscore.gsub("/", "_") + "_id"
         end
     end
   end

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_embedded_proxy.rb

@@ -5,34 +5,23 @@ module MongoMapper
         @_values = v.map { |e| e.kind_of?(EmbeddedDocument) ? e.attributes : e }
         reset
       end
-      
-      def build(opts={})
-        owner = @owner
-        child = @association.klass.new(opts)
-        assign_parent_reference(child)
-        child._root_document = owner
-        self << child
-        child
+
+      def build(attributes={})
+        doc = @association.klass.new(attributes)
+        assign_root_document(doc)
+        self << doc
+        doc
       end
-      
-      def find(opts)
-        case opts
-        when :all
-          self
-        when String
-          if load_target
-            child = @target.detect {|item| item.id == opts}
-            assign_parent_reference(child)
-            child
-          end
-        end
+
+      def find(id)
+        load_target
+        @target.detect { |item| item.id == id }
       end
 
       def <<(*docs)
         if load_target
-          root = @owner._root_document || @owner
           docs.each do |doc|
-            doc._root_document = root
+            assign_root_document(doc)
             @target << doc
           end
         end
@@ -40,28 +29,24 @@ module MongoMapper
       alias_method :push, :<<
       alias_method :concat, :<<
 
-      protected
+      private
         def find_target
           (@_values || []).map do |e|
             child = @association.klass.new(e)
-            assign_parent_reference(child)
+            assign_root_document(child)
             child
           end
         end
-        
-      private
-      
-        def assign_parent_reference(child)
-          return unless child && @owner
-          return if @owner.class.name.blank?
-          owner = @owner
-          child.class_eval do
-            define_method(owner.class.name.underscore) do
-              owner
-            end
+
+        def root_document
+          @owner._root_document || @owner
+        end
+
+        def assign_root_document(*docs)
+          docs.each do |doc|
+            doc._root_document = root_document
           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
 
@@ -32,7 +33,7 @@ module MongoMapper
       def replace(v)
         raise NotImplementedError
       end
-
+      
       def inspect
         load_target
         @target.inspect
@@ -42,7 +43,7 @@ module MongoMapper
         load_target
         @target.nil?
       end
-
+      
       protected
         def method_missing(method, *args)
           if load_target

data/lib/mongo_mapper/associations.rb

@@ -1,13 +1,121 @@
 module MongoMapper
   module Associations
     module ClassMethods
-      def belongs_to(association_id, options = {})
-        create_association(:belongs_to, association_id, options, self)
+      ##
+      # This macro allows you define a "belongs-to" relationship between one 
+      # document and some other document.
+      #
+      # == Requirements
+      #
+      # Usage of this macro requires that your document define a key that can 
+      # be used to store the ID of the target document that is the parent of 
+      # this document.
+      #
+      # == Conventions
+      # 
+      # The following is a list of the conventions used by MongoMapper in 
+      # defining a belongs-to relationship. Each can likely be overridden via 
+      # the +options+ parameter.
+      #
+      # * The name of your belongs-to association is the lowercase, singular 
+      #   name of the target class
+      # * A key with the name of your association exists with an "_id" suffix 
+      #   to store the ID of the target of this relationship
+      #
+      # @param [Symbol] association_id The name of this association
+      # @param [Hash] options Optional parameters that define the 
+      #   characteristics of this relationship. These are often used to 
+      #   override MongoMapper conventions.
+      # @option options [Boolean] :polymorphic (false) Set this option to 
+      #   <code>true</code> to define a relationship that can be between this 
+      #   document and any other type of document. Note that you *must* also 
+      #   have a key on your document to store the type of document in this 
+      #   relationship.
+      # @option options [String] :class_name If your relationship doesn't use 
+      #   the name of some class, you *must* use this option to indicate the 
+      #   target class for this relationship.
+      # @option options [Symbol] :foreign_key Use this option to specify a 
+      #   non-conventional key that stores the ID of the parent in this 
+      #   relationship
+      #
+      # @example Conventional, and simple, usage of <code>belongs_to</code>
+      #   class Novel
+      #     include MongoMapper::Document
+      #
+      #     key :author_id, String # our "foreign key"
+      #
+      #     belongs_to :author
+      #   end
+      #
+      # @example Using :foreign_key and :class_name
+      #   class Pet
+      #     include MongoMapper::Document
+      #
+      #     key :person_id, String
+      #
+      #     belongs_to :owner,
+      #       :foreign_key => :person_id,
+      #       :class_name  => "Person"
+      #   end
+      #
+      # @example Defining a polymorphic belongs-to relationship
+      #   class Vehicle
+      #     include MongoMapper::Document
+      #
+      #     key :owner_id,   String
+      #     key :owner_type, String
+      #
+      #     belongs_to :owner,
+      #       :polymorphic => true
+      #   end
+      #
+      # @example Non-standard polymorphic belongs-to relationship
+      #   class Vehicle
+      #     include MongoMapper::Document
+      #
+      #     key :person_id,   String
+      #     key :person_type, String
+      #
+      #     belongs_to :owner,
+      #       :polymorphic   => true,
+      #       :foreign_key   => "person_id",
+      #       :type_key_name => "person_type"
+      #   end
+      def belongs_to(association_id, options={}, &extension)
+        create_association(:belongs_to, association_id, options, &extension)
         self
       end
 
-      def many(association_id, options = {})
-        create_association(:many, association_id, options, self)
+      ##
+      # This macro allows you to define a "has-many" relationship between a 
+      # document, and numerous child documents.
+      #
+      # == Conventions
+      #
+      # The following is a list of the conventions used by MongoMapper in 
+      # defining this relationship. Each can likely be overridden via the 
+      # +options+ parameter.
+      #
+      # * The name of your association is the lowercase, *plural* name of the 
+      #   target class
+      # * Your target class must have a "foreign key" bearing the name of this 
+      #   class suffixed by "_id"
+      #
+      # @param [Symbol] association_id The name of this association
+      # @param [Hash] options Optional parameters that define the 
+      #   characteristics of this relationship. These are often used to 
+      #   override MongoMapper conventions.
+      # @option options [String] :class_name If your relationship doesn't use 
+      #   the name of some class, you *must* use this option to indicate the 
+      #   target class for this relationship.
+      # @option options [Symbol] :foreign_key Use this option to specify a 
+      #   non-conventional key that stores the ID of the parent in this 
+      #   relationship
+      # @option options [#to_s] :as Used when the target relationship is 
+      #   polymorphic (i.e. the +belongs_to+ has set <tt>:polymorphic</tt> to 
+      #   +true+). See examples for usage.
+      def many(association_id, options={}, &extension)
+        create_association(:many, association_id, options, &extension)
         self
       end
 
@@ -18,9 +126,8 @@ module MongoMapper
       end
 
       private
-        def create_association(type, name, options, scope)
-          options[:scope] = scope
-          association = Associations::Base.new(type, name, options)
+        def create_association(type, name, options, &extension)
+          association = Associations::Base.new(type, name, options, &extension)
           associations[association.name] = association
           define_association_methods(association)
           define_dependent_callback(association)
@@ -60,7 +167,6 @@ module MongoMapper
             end
           end
         end
-
     end
 
     module InstanceMethods

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