mongo_mapper-unstable 2009.10.16 → 2009.10.31

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/Rakefile

@@ -1,89 +1,55 @@
 require 'rubygems'
 require 'rake'
-
-begin
-  require 'jeweler'
-  Jeweler::Tasks.new do |gem|
-    gem.name = "mongo_mapper"
-    gem.summary = %Q{Awesome gem for modeling your domain and storing it in mongo}
-    gem.email = "nunemaker@gmail.com"
-    gem.homepage = "http://github.com/jnunemaker/mongomapper"
-    gem.authors = ["John Nunemaker"]
-    gem.rubyforge_project = "mongomapper"
-    
-    gem.add_dependency('activesupport', '>= 2.3')
-    gem.add_dependency('mongo', '0.15.1')
-    gem.add_dependency('jnunemaker-validatable', '1.7.4')
-    
-    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')
-  end
+require 'jeweler'
+require 'yard'
+require 'yard/rake/yardoc_task'
+
+Jeweler::Tasks.new do |gem|
+  gem.name        = "mongo_mapper"
+  gem.summary     = %Q{Awesome gem for modeling your domain and storing it in mongo}
+  gem.email       = "nunemaker@gmail.com"
+  gem.homepage    = "http://github.com/jnunemaker/mongomapper"
+  gem.authors     = ["John Nunemaker"]
   
-  Jeweler::RubyforgeTasks.new do |rubyforge|
-    rubyforge.doc_task = "rdoc"
-  end
-rescue LoadError
-  puts "Jeweler (or a dependency) not available. Install it with: sudo gem install jeweler"
+  gem.add_dependency('activesupport', '>= 2.3')
+  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')
 end
 
+Jeweler::GemcutterTasks.new
+
 require 'rake/testtask'
 Rake::TestTask.new(:test) do |test|
-  test.libs << 'lib' << 'test'
+  test.libs << 'test'
+  test.ruby_opts << '-rubygems'
   test.pattern = 'test/**/test_*.rb'
   test.verbose = true
 end
 
 namespace :test do
   Rake::TestTask.new(:units) do |test|
-    test.libs << 'lib' << 'test'
+    test.libs << 'test'
+    test.ruby_opts << '-rubygems'
     test.pattern = 'test/unit/**/test_*.rb'
     test.verbose = true
   end
   
   Rake::TestTask.new(:functionals) do |test|
-    test.libs << 'lib' << 'test'
-    test.pattern = 'test/functional/**/test_*.rb'
-    test.verbose = true
-  end
-end
-
-begin
-  require 'rcov/rcovtask'
-  Rcov::RcovTask.new do |test|
     test.libs << 'test'
-    test.pattern = 'test/**/test_*.rb'
+    test.ruby_opts << '-rubygems'
+    test.pattern = 'test/functional/**/test_*.rb'
     test.verbose = true
   end
-rescue LoadError
-  task :rcov do
-    abort "RCov is not available. In order to run rcov, you must: sudo gem install spicycode-rcov"
-  end
 end
 
-begin
-  require 'cucumber/rake/task'
-  Cucumber::Rake::Task.new(:features)
-rescue LoadError
-  task :features do
-    abort "Cucumber is not available. In order to run features, you must: sudo gem install cucumber"
-  end
-end
+task :default  => :test
+task :test     => :check_dependencies
 
-task :default => :test
-
-require 'rake/rdoctask'
-Rake::RDocTask.new do |rdoc|
-  if File.exist?('VERSION.yml')
-    config = YAML.load(File.read('VERSION.yml'))
-    version = "#{config[:major]}.#{config[:minor]}.#{config[:patch]}"
-  else
-    version = ""
-  end
-
-  rdoc.rdoc_dir = 'rdoc'
-  rdoc.title = "MongoMapper #{version}"
-  rdoc.rdoc_files.include('README*')
-  rdoc.rdoc_files.include('lib/**/*.rb')
-end
+YARD::Rake::YardocTask.new(:doc) do |t|
+  t.options = ["--legacy"]
+end

data/VERSION

@@ -1 +1 @@
-2009.10.16
+2009.10.31

data/lib/mongo_mapper/associations/base.rb

@@ -1,10 +1,27 @@
 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
 
-      def initialize(type, name, options = {})
-        @type, @name, @options = type, name, 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!
+
+        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
@@ -20,7 +37,7 @@ module MongoMapper
       end
 
       def klass
-        @klass ||= class_name.constantize
+        @klass ||= options[:class] ? options[:class] : class_name.constantize
       end
 
       def many?
@@ -78,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

@@ -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)
@@ -56,21 +56,27 @@ module MongoMapper
         apply_scope(doc).save
         doc
       end
+      
+      def create!(attrs={})
+        doc = klass.new(attrs)
+        apply_scope(doc).save!
+        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(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 +95,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_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
 

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)
+      ##
+      # 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)
+      ##
+      # 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,8 +126,8 @@ module MongoMapper
       end
 
       private
-        def create_association(type, name, options)
-          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)
@@ -41,8 +149,6 @@ module MongoMapper
           if association.options[:dependent]
             if association.many?
               define_dependent_callback_for_many(association)
-            elsif association.belongs_to?
-              define_dependent_callback_for_belongs_to(association)
             end
           end
         end
@@ -61,15 +167,6 @@ module MongoMapper
             end
           end
         end
-
-        def define_dependent_callback_for_belongs_to(association)
-          after_destroy do |doc|
-            case association.options[:dependent]
-            when :destroy
-              doc.get_proxy(association).destroy
-            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