mongoid 0.8.7 → 0.8.8

data/VERSION

@@ -1 +1 @@
-0.8.7
+0.8.8

data/lib/mongoid/associations/has_many.rb

@@ -44,6 +44,17 @@ module Mongoid #:nodoc:
         object
       end
 
+      # Creates a new Document and adds it to the association collection. The
+      # document created will be of the same class as the others in the
+      # association, and the attributes will be passed into the constructor and
+      # the new object will then be saved.
+      #
+      # Returns the newly created object.
+      def create(attributes)
+        object = build(attributes)
+        object.save
+      end
+
       # Finds a document in this association.
       # If :all is passed, returns all the documents
       # If an id is passed, will return the document for that id.
@@ -60,9 +71,7 @@ module Mongoid #:nodoc:
       # This then delegated all methods to the array class since this is
       # essentially a proxy to an array itself.
       def initialize(document, options)
-        @parent = document
-        @association_name = options.name
-        @klass = options.klass
+        @parent, @association_name, @klass = document, options.name, options.klass
         attributes = document.attributes[@association_name]
         @documents = attributes ? attributes.collect do |attribute|
           child = @klass.instantiate(attribute)

data/lib/mongoid/associations/has_one.rb

@@ -5,7 +5,23 @@ module Mongoid #:nodoc:
 
       delegate :valid?, :to => :document
 
-      attr_accessor :klass
+      attr_accessor :klass, :parent, :association_name
+
+      # Build a new object for the association.
+      def build(attributes)
+        @document = @klass.instantiate(attributes)
+        @document.parentize(@parent, @association_name)
+        @document.notify
+        decorate!
+        self
+      end
+
+      # Create a new object for the association and save it.
+      def create(attributes)
+        build(attributes)
+        @document.save
+        self
+      end
 
       # Creates the new association by finding the attributes in 
       # the parent document with its name, and instantiating a 
@@ -14,7 +30,7 @@ module Mongoid #:nodoc:
       # All method calls on this object will then be delegated
       # to the internal document itself.
       def initialize(document, options)
-        @klass = options.klass
+        @klass, @parent, @association_name = options.klass, document, options.name
         attributes = document.attributes[options.name]
         @document = klass.instantiate(attributes || {})
         @document.parentize(document, options.name)

data/lib/mongoid/document.rb

@@ -113,7 +113,8 @@ module Mongoid #:nodoc:
 
     end
 
-    # Performs equality checking on the attributes.
+    # Performs equality checking on the attributes. For now we chack against
+    # all attributes excluding timestamps on the object.
     def ==(other)
       return false unless other.is_a?(Document)
       @attributes.except(:modified_at).except(:created_at) ==
@@ -146,8 +147,8 @@ module Mongoid #:nodoc:
       self.class.fields
     end
 
-    # Get the id associated with this object.
-    # This is in essence the primary key.
+    # Get the id associated with this object. This will pull the _id value out
+    # of the attributes +Hash+.
     def id
       @attributes[:_id]
     end
@@ -160,8 +161,20 @@ module Mongoid #:nodoc:
     alias :_id :id
     alias :_id= :id=
 
-    # Instantiate a new Document, setting the Document's attributes if given.
-    # If no attributes are provided, they will be initialized with an empty Hash.
+    # Instantiate a new +Document+, setting the Document's attributes if
+    # given. If no attributes are provided, they will be initialized with
+    # an empty +Hash+.
+    #
+    # If a primary key is defined, the document's id will be set to that key,
+    # otherwise it will be set to a fresh +Mongo::ObjectID+ string.
+    #
+    # Options:
+    #
+    # attrs: The attributes +Hash+ to set up the document with.
+    #
+    # Example:
+    #
+    # <tt>Person.new(:title => "Mr", :age => 30)</tt>
     def initialize(attrs = {})
       @attributes = {}.with_indifferent_access
       process(defaults.merge(attrs))
@@ -169,34 +182,72 @@ module Mongoid #:nodoc:
       generate_key
     end
 
+    # Returns the class name plus its attributes.
     def inspect
       "#{self.class.name} : #{@attributes.inspect}"
     end
 
-    # Return the +Document+ primary key.
+    # Return the +Document+ primary key. This will only exist if a key has been
+    # set up on the +Document+ and will return an array of fields.
+    #
+    # Example:
+    #
+    #   class Person < Mongoid::Document
+    #     field :first_name
+    #     field :last_name
+    #     key :first_name, :last_name
+    #   end
+    #
+    # <tt>person.primary_key #[:first_name, :last_name]</tt>
     def primary_key
       self.class.primary_key
     end
 
-    # Returns true is the Document has not been persisted to the database, false if it has.
+    # Returns true is the +Document+ has not been persisted to the database,
+    # false if it has. This is determined by the instance variable @new_record
+    # and NOT if the object has an id.
     def new_record?
       @new_record == true
     end
 
-    # Notify observers that this Document has changed.
+    # Set the changed state of the +Document+ then notify observers that it has changed.
+    #
+    # Example:
+    #
+    # <tt>person.notify</tt>
     def notify
       changed(true)
       notify_observers(self)
     end
 
-    # Sets the parent object
+    # Sets up a child/parent association. This is used for newly created
+    # objects so they can be properly added to the graph and have the parent
+    # observers set up properly.
+    #
+    # Options:
+    #
+    # abject: The parent object that needs to be set for the child.
+    # association_name: The name of the association for the child.
+    #
+    # Example:
+    #
+    # <tt>address.parentize(person, :addresses)</tt>
     def parentize(object, association_name)
       self.parent = object
       self.association_name = association_name
       add_observer(object)
     end
 
-    # Read from the attributes hash.
+    # Read a value from the +Document+ attributes. If the value does not exist
+    # it will return nil.
+    #
+    # Options:
+    #
+    # name: The name of the attribute to get.
+    #
+    # Example:
+    #
+    # <tt>person.read_attribute(:title)</tt>
     def read_attribute(name)
       fields[name].get(@attributes[name])
     end
@@ -206,26 +257,55 @@ module Mongoid #:nodoc:
       @attributes = collection.find_one(:_id => id).with_indifferent_access
     end
 
-    # Return the root +Document+ in the object graph.
+    # Return the root +Document+ in the object graph. If the current +Document+
+    # is the root object in the graph it will return self.
     def root
       object = self
       while (object.parent) do object = object.parent; end
       object || self
     end
 
-    # Returns the id of the Document
+    # Returns the id of the Document, used in Rails compatibility.
     def to_param
-      id.to_s
+      id
     end
 
-    # Update the document based on notify from child
+    # Observe a notify call from a child +Document+. This will either update
+    # existing attributes on the +Document+ or clear them out for the child if
+    # the clear boolean is provided.
+    #
+    # Options:
+    #
+    # child: The child +Document+ that sent the notification.
+    # clear: Will clear out the child's attributes if set to true.
+    #
+    # Example:
+    #
+    # <tt>person.notify_observers(self)</tt> will cause this method to execute.
+    #
+    # This will also cause the observing +Document+ to notify it's parent if
+    # there is any.
     def update(child, clear = false)
       @attributes.insert(child.association_name, child.attributes) unless clear
       @attributes.delete(child.association_name) if clear
       notify
     end
 
-    # Write to the attributes hash.
+    # Write a single attribute to the +Document+ attribute +Hash+. This will
+    # also fire the before and after update callbacks, and perform any
+    # necessary typecasting.
+    #
+    # Options:
+    #
+    # name: The name of the attribute to update.
+    # value: The value to set for the attribute.
+    #
+    # Example:
+    #
+    # <tt>person.write_attribute(:title, "Mr.")</tt>
+    #
+    # This will also cause the observing +Document+ to notify it's parent if
+    # there is any.
     def write_attribute(name, value)
       run_callbacks(:before_update)
       @attributes[name] = fields[name].set(value)
@@ -233,14 +313,26 @@ module Mongoid #:nodoc:
       notify
     end
 
-    # Writes all the attributes of this Document, and delegate up to
-    # the parent.
+    # Writes the supplied attributes +Hash+ to the +Document+. This will only
+    # overwrite existing attributes if they are present in the new +Hash+, all
+    # others will be preserved.
+    #
+    # Options:
+    #
+    # attrs: The +Hash+ of new attributes to set on the +Document+
+    #
+    # Example:
+    #
+    # <tt>person.write_attributes(:title => "Mr.")</tt>
+    #
+    # This will also cause the observing +Document+ to notify it's parent if
+    # there is any.
     def write_attributes(attrs)
       process(attrs)
       notify
     end
 
-    private
+    protected
     def generate_key
       if primary_key
         values = primary_key.collect { |key| @attributes[key] }

data/mongoid.gemspec

@@ -5,7 +5,7 @@
 
 Gem::Specification.new do |s|
   s.name = %q{mongoid}
-  s.version = "0.8.7"
+  s.version = "0.8.8"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Durran Jordan"]

data/spec/integration/mongoid/document_spec.rb

@@ -35,6 +35,33 @@ describe Mongoid::Document do
       person.attributes[:title].should == "Test"
     end
 
+    context "when creating a has many" do
+
+      before do
+        @person = Person.new(:title => "Esquire")
+        @person.addresses.create(:street => "Nan Jing Dong Lu", :city => "Shanghai")
+      end
+
+      it "should create and save the entire graph" do
+        person = Person.find(@person.id)
+        person.addresses.first.street.should == "Nan Jing Dong Lu"
+      end
+
+    end
+
+    context "when creating a has one" do
+
+      before do
+        @person = Person.new(:title => "Esquire")
+        @person.name.create(:first_name => "Jorge")
+      end
+
+      it "should create and save the entire graph" do
+        person = Person.find(@person.id)
+        person.name.first_name.should == "Jorge"
+      end
+
+    end
   end
 
   describe "#find" do

data/spec/unit/mongoid/associations/has_many_spec.rb

@@ -9,25 +9,6 @@ describe Mongoid::Associations::HasMany do
     @document = stub(:attributes => @attributes, :add_observer => true, :update => true)
   end
 
-  describe "#update" do
-
-    before do
-      @address = Address.new(:street => "Madison Ave")
-      @person = Person.new(:title => "Sir")
-      Mongoid::Associations::HasMany.update([@address], @person, Mongoid::Associations::Options.new(:name => :addresses))
-    end
-
-    it "parentizes the child document" do
-      @address.parent.should == @person
-    end
-
-    it "sets the attributes of the child on the parent" do
-      @person.attributes[:addresses].should ==
-        [{ "_id" => "madison-ave", "street" => "Madison Ave" }]
-    end
-
-  end
-
   describe "#[]" do
 
     before do
@@ -56,7 +37,10 @@ describe Mongoid::Associations::HasMany do
   describe "#<<" do
 
     before do
-      @association = Mongoid::Associations::HasMany.new(@document, Mongoid::Associations::Options.new(:name => :addresses))
+      @association = Mongoid::Associations::HasMany.new(
+        @document,
+        Mongoid::Associations::Options.new(:name => :addresses)
+      )
       @address = Address.new
     end
 
@@ -74,22 +58,50 @@ describe Mongoid::Associations::HasMany do
 
   end
 
-  describe "#concat" do
+  describe "#build" do
 
     before do
-      @association = Mongoid::Associations::HasMany.new(@document, Mongoid::Associations::Options.new(:name => :addresses))
-      @address = Address.new
+      @association = Mongoid::Associations::HasMany.new(
+        @document,
+        Mongoid::Associations::Options.new(:name => :addresses)
+      )
     end
 
-    it "adds the parent document before appending to the array" do
-      @association.concat [@address]
+    it "adds a new document to the array with the suppied parameters" do
+      @association.build({ :street => "Street 1" })
       @association.length.should == 3
-      @address.parent.should == @document
+      @association[2].should be_a_kind_of(Address)
+      @association[2].street.should == "Street 1"
+    end
+
+    it "returns the newly built object in the association" do
+      address = @association.build({ :street => "Yet Another" })
+      address.should be_a_kind_of(Address)
+      address.street.should == "Yet Another"
     end
 
   end
 
-  describe "#push" do
+  describe "#create" do
+
+    before do
+      @association = Mongoid::Associations::HasMany.new(
+        @document,
+        Mongoid::Associations::Options.new(:name => :addresses)
+      )
+      @address = Address.new(:street => "Yet Another")
+    end
+
+    it "builds and saves a new object" do
+      Mongoid::Commands::Create.expects(:execute).returns(@address)
+      address = @association.create({ :street => "Yet Another" })
+      address.should be_a_kind_of(Address)
+      address.street.should == "Yet Another"
+    end
+
+  end
+
+  describe "#concat" do
 
     before do
       @association = Mongoid::Associations::HasMany.new(@document, Mongoid::Associations::Options.new(:name => :addresses))
@@ -97,30 +109,24 @@ describe Mongoid::Associations::HasMany do
     end
 
     it "adds the parent document before appending to the array" do
-      @association.push @address
+      @association.concat [@address]
       @association.length.should == 3
       @address.parent.should == @document
     end
 
   end
 
-  describe "#build" do
+  describe "#push" do
 
     before do
       @association = Mongoid::Associations::HasMany.new(@document, Mongoid::Associations::Options.new(:name => :addresses))
+      @address = Address.new
     end
 
-    it "adds a new document to the array with the suppied parameters" do
-      @association.build({ :street => "Street 1" })
+    it "adds the parent document before appending to the array" do
+      @association.push @address
       @association.length.should == 3
-      @association[2].should be_a_kind_of(Address)
-      @association[2].street.should == "Street 1"
-    end
-
-    it "returns the newly built object in the association" do
-      address = @association.build({ :street => "Yet Another" })
-      address.should be_a_kind_of(Address)
-      address.street.should == "Yet Another"
+      @address.parent.should == @document
     end
 
   end
@@ -217,4 +223,23 @@ describe Mongoid::Associations::HasMany do
 
   end
 
+  describe "#update" do
+
+    before do
+      @address = Address.new(:street => "Madison Ave")
+      @person = Person.new(:title => "Sir")
+      Mongoid::Associations::HasMany.update([@address], @person, Mongoid::Associations::Options.new(:name => :addresses))
+    end
+
+    it "parentizes the child document" do
+      @address.parent.should == @person
+    end
+
+    it "sets the attributes of the child on the parent" do
+      @person.attributes[:addresses].should ==
+        [{ "_id" => "madison-ave", "street" => "Madison Ave" }]
+    end
+
+  end
+
 end

data/spec/unit/mongoid/associations/has_one_spec.rb

@@ -7,25 +7,44 @@ describe Mongoid::Associations::HasOne do
     @document = stub(:attributes => @attributes, :update => true)
   end
 
-  describe "#update" do
+  describe "#build" do
 
-    before do
-      @name = Name.new(:first_name => "Donald")
-      @person = Person.new(:title => "Sir")
-      Mongoid::Associations::HasOne.update(
-        @name,
-        @person,
-        Mongoid::Associations::Options.new(:name => :name)
-      )
-    end
+    context "when attributes provided" do
+
+      before do
+        @association = Mongoid::Associations::HasOne.new(
+          @document,
+          Mongoid::Associations::Options.new(:name => :mixed_drink)
+        )
+      end
+
+      it "replaces the existing has_one" do
+        drink = @association.build({ :name => "Sapphire and Tonic" })
+        drink.name.should == "Sapphire and Tonic"
+      end
 
-    it "parentizes the child document" do
-      @name.parent.should == @person
     end
 
-    it "sets the attributes of the child on the parent" do
-      @person.attributes[:name].should ==
-        { "_id" => "donald", "first_name" => "Donald" }
+  end
+
+  describe "#create" do
+
+    context "when attributes provided" do
+
+      before do
+        @association = Mongoid::Associations::HasOne.new(
+          @document,
+          Mongoid::Associations::Options.new(:name => :mixed_drink)
+        )
+        @drink = MixedDrink.new(:name => "Sapphire and Tonic")
+      end
+
+      it "replaces and saves the existing has_one" do
+        Mongoid::Commands::Create.expects(:execute).returns(@drink)
+        drink = @association.create({ :name => "Sapphire and Tonic" })
+        drink.name.should == "Sapphire and Tonic"
+      end
+
     end
 
   end
@@ -58,4 +77,27 @@ describe Mongoid::Associations::HasOne do
 
   end
 
+  describe "#update" do
+
+    before do
+      @name = Name.new(:first_name => "Donald")
+      @person = Person.new(:title => "Sir")
+      Mongoid::Associations::HasOne.update(
+        @name,
+        @person,
+        Mongoid::Associations::Options.new(:name => :name)
+      )
+    end
+
+    it "parentizes the child document" do
+      @name.parent.should == @person
+    end
+
+    it "sets the attributes of the child on the parent" do
+      @person.attributes[:name].should ==
+        { "_id" => "donald", "first_name" => "Donald" }
+    end
+
+  end
+
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: mongoid
 version: !ruby/object:Gem::Version 
-  version: 0.8.7
+  version: 0.8.8
 platform: ruby
 authors: 
 - Durran Jordan