candy 0.2.7 → 0.2.8

data/HISTORY.markdown

@@ -3,6 +3,14 @@ Candy History
 
 This document aims to provide only an overview.  Further, we've only really been tracking things since **v0.2**.  For obsessive detail, just check out the `git log`.
 
+v0.2.8 - 2010-05-13 (the "Holy crap, that was ten pomodoros" release)
+---------------------------------------------------------------------
+Major refactoring to fix a major bug: embedded documents weren't being loaded properly on document retrieval.  This resulted in a lot of code being moved around, and some regrettable circular connascence between Piece and Wrapper that I hope to address later.  Overall, though, it's simpler now.
+
+**API CHANGE:** The `.embed` class method has two new required parameters and is now used _only_ when you know the parent you want to embed something in.  To make a Candy piece that you don't want to be saved right away, use `.piece` instead.
+
+* Fixed Github issue #11
+
 v0.2.7 - 2010-05-05 (the "yes, you MAY put your peanut butter in my chocolate" release)
 --------------------------------------------------------------------------------------
 Found and fixed a convoluted bug that was preventing embedded Candy objects from being saved properly. (It was treating them as _non_-Candy objects, which makes the world a gray and boring place.) While I was at it, refactored some methods and chipped away at some complexity.

data/VERSION

@@ -1 +1 @@
-0.2.7
+0.2.8

data/candy.gemspec

@@ -5,11 +5,11 @@
 
 Gem::Specification.new do |s|
   s.name = %q{candy}
-  s.version = "0.2.7"
+  s.version = "0.2.8"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Stephen Eley"]
-  s.date = %q{2010-05-05}
+  s.date = %q{2010-05-13}
   s.description = %q{Candy provides simple, transparent object persistence for the MongoDB database.  Classes that 
 include Candy modules save all properties to Mongo automatically, can be recursively embedded,
 and can retrieve records with chainable open-ended class methods, eliminating the need for 

data/lib/candy/array.rb

@@ -10,23 +10,23 @@ module Candy
     include Crunch
     include Embeddable
     
-    # Included for purposes of 'embeddable' compatibility, but does nothing except pass its 
-    # parameters to the new object.  Since you can't save an array on its own anyway, there's
-    # no need to flag it as "don't save."
-    def self.embed(*args, &block)
-      self.new(*args, &block)
+    # Creates the object with parent and attribute values set properly on the object and any children.
+    def self.embed(parent, attribute, *args)
+      this = self.new(*args)
+      this.candy_adopt(parent, attribute)
     end
     
     # Sets the initial array state.
-    def initialize(*args, &block)
-      @__candy = args
+    def initialize(*args)
+      @__candy = from_candy(args)
+      super()
     end
     
     # Set a value at a specified index in our array.  Note that this operation _does not_ confirm that the 
     # array in Mongo still matches our current state.  If concurrent updates have happened, you might end up
     # overwriting something other than what you thought.
     def []=(index, val)
-      property = candy_coat(@__candy_parent_key, val)
+      property = candy_coat(nil, val)  # There are no attribute names on array inheritance
       @__candy_parent.set embedded(index => property)
       self.candy[index] = property
     end
@@ -47,8 +47,8 @@ module Candy
     # Pops the front off the MongoDB array and returns it, then resyncs the array.
     # (Thus supporting real-time concurrency for queue-like behavior.)
     def shift(n=1)
-      doc = @__candy_parent.findAndModify({"_id" => @__candy_parent.id}, {'$pop' => {@__candy_parent_key => -1}})
-      @__candy = doc['value'][@__candy_parent_key.to_s]
+      doc = @__candy_parent.collection.find_and_modify query: {"_id" => @__candy_parent.id}, update: {'$pop' => {@__candy_parent_key => -1}}, new: false
+      @__candy = doc[@__candy_parent_key.to_s]
       @__candy.shift
     end
     
@@ -59,6 +59,11 @@ module Candy
     alias_method :to_candy, :candy
     alias_method :to_ary, :candy
     
+    # Unwraps all elements of the array, telling them who their parent is.  The attribute doesn't matter because arrays don't have them.
+    def from_candy(array)
+      array.map {|element| Wrapper.unwrap(element, self)}
+    end
+    
     # Array equality.
     def ==(val)
       self.to_ary == val
@@ -70,5 +75,11 @@ module Candy
     end
     alias_method :size, :length
 
+    protected
+    
+    # Sets the array.  Primarily used by the .embed class method.
+    def candy=(val)
+      @__candy = val
+    end
   end
 end

data/lib/candy/embeddable.rb

@@ -3,11 +3,13 @@ module Candy
   # Shared methods to create associations between top-level objects and embedded objects (hashes, 
   # arrays, or Candy::Pieces).
   module Embeddable
+        
     # Tells an embedded object about its parent.  When its own state changes, it can use this
     # information to write home and update the parent.
     def candy_adopt(parent, attribute)
       @__candy_parent = parent
       @__candy_parent_key = attribute
+      self
     end
     
   private
@@ -20,16 +22,18 @@ module Candy
   
     # Convert hashes and arrays to CandyHashes and CandyArrays, and set the parent key for any Candy pieces.
     def candy_coat(key, value)
-      piece = case value
-        when CandyHash then value
-        when Hash then CandyHash.embed(value)
-        when CandyArray then value
-        when Array then CandyArray.embed(*value)   # Explode our array into separate arguments
+      case value
+      when Hash then CandyHash.embed(self, key, value)
+      when Array then CandyArray.embed(self, key, *value)   # Explode our array into separate arguments
+      when CandyHash then value.candy_adopt(self, key)
+      when CandyArray then value.candy_adopt(self, key)
+      else
+        if value.respond_to?(:candy_adopt)
+          value.candy_adopt(self, key)
         else
           value
         end
-      piece.candy_adopt(self, key) if piece.respond_to?(:candy_adopt)
-      piece
+      end
     end
   
   end

data/lib/candy/piece.rb

@@ -33,13 +33,32 @@ module Candy
         collection.update search_keys, fields, :upsert => true
       end
       
+
+      # Deep magic!  Finds and returns a single object by the named attribute.
+      def method_missing(name, *args, &block)
+        if args.size == 1 or args.size == 2     # If we don't have a value, or have more than
+          search = {name => args.shift}         # just a simple options hash, this must not be for us.
+          search.merge!(args.shift) if args[0]  # We might have other conditions
+          first(search)
+        else
+          super
+        end
+      end
+
+      # Creates the object with parent and attribute values set properly on the object and any children.
+      def embed(parent, attribute, *args)
+        this = self.piece(*args)
+        this.candy_adopt(parent, attribute)
+      end
+      
+      
       # Makes a new object with a given state that is _not_ immediately saved, but is 
       # held in memory instead.  The principal use for this is to embed it in other 
       # documents.  Except for the unsaved state, this functions identically to 'new'
       # and will pass all its arguments to the initializer.  (Note that you can still 
       # embed documents that _have_ been saved--but then you'll have the data in two
       # places.)
-      def embed(*args, &block)
+      def piece(*args)
         if args[-1].is_a?(Hash)
           args[-1].merge!(EMBED_KEY => true)
         else
@@ -47,17 +66,7 @@ module Candy
         end
         self.new(*args)
       end
-
-      # Deep magic!  Finds and returns a single object by the named attribute.
-      def method_missing(name, *args, &block)
-        if args.size == 1 or args.size == 2     # If we don't have a value, or have more than
-          search = {name => args.shift}         # just a simple options hash, this must not be for us.
-          search.merge!(args.shift) if args[0]  # We might have other conditions
-          first(search)
-        else
-          super
-        end
-      end
+      
       
     private
       # Creates a method in the same namespace as the included class that points to
@@ -72,16 +81,15 @@ module Candy
     include Embeddable
     
     
-    # Our initializer checks the LAST argument passed to it, and pops it off the chain if it's a hash.
-    # If the hash contains an '_id' field we assume we're being constructed from a MongoDB document; 
-    # otherwise we assume we're a new document and insert ourselves into the database.
+    # Our initializer expects the last argument to be a hash of values. If the hash contains an '_id' 
+    # field we assume we're being constructed from a MongoDB document and we unwrap the remaining
+    # values; otherwise we assume we're a new document and set any values in the hash as if they
+    # were assigned. Any other arguments are not our business and will be passed down the chain.
     def initialize(*args, &block)
       if args[-1].is_a?(Hash)
         data = args.pop
-        if @__candy_id = data.delete('_id')  # We're an existing document
-          @__candy = self.from_candy(Wrapper.unwrap(data))
-        elsif data.delete(EMBED_KEY)  # We're being embedded: take any data, but don't save to Mongo
-          @__candy = data
+        if data.delete(EMBED_KEY) or @__candy_id = data.delete('_id')  # We're an embedded or existing document
+          @__candy = self.from_candy(data)
         else
           data.each {|key, value| send("#{key}=", value)}  # Assign all the data we're given
         end
@@ -96,7 +104,7 @@ module Candy
     
     # Pull our document from the database if we know our ID.
     def retrieve_document
-      Wrapper.unwrap(collection.find_one({'_id' => id})) if id
+      from_candy(collection.find_one({'_id' => id})) if id
     end
     
     
@@ -169,11 +177,15 @@ module Candy
       candy.merge(CLASS_KEY => self.class.name)
     end
     
-    # A hoook for specific object classes to set their internal state using the hash passed in by
-    # MongoDB.  If you override this method, delete any hash keys you need for your own purposes
-    # and then call 'super' on the remainder.
+    # Unwraps the values passed to us from MongoDB, setting parent attributes on any embedded Candy
+    # objects.
     def from_candy(hash) 
-      hash
+      unwrapped = {}
+      hash.each do |key, value|
+        field = Wrapper.unwrap_key(key)
+        unwrapped[field] = Wrapper.unwrap(value, self, field)
+      end
+      unwrapped
     end
     
     

data/lib/candy/wrapper.rb

@@ -52,24 +52,28 @@ module Candy
       array.map {|element| wrap(element)}
     end
     
-    # Takes a hash and returns it with values wrapped. Keys are converted to strings, and 
-    # wrapped with single quotes if they were already strings.  (So that we can easily tell
-    # hash keys from string keys later on.)
+    # Takes a hash and returns it with values wrapped. Symbol keys are reversibly converted to strings.
     def self.wrap_hash(hash)
       wrapped = {}
       hash.each do |key, value|  
-        case key
-        when Symbol
-          wrapped[key.to_s] = wrap(value)
-        when String
-          wrapped["'#{key}'"] = wrap(value)
-        else
-          wrapped[wrap(key)] = wrap(value)
-        end
+        wrapped[wrap_key(key)] = wrap(value)
       end
       wrapped
     end
     
+    # Lightly wraps hash keys, converting symbols to strings and wrapping strings in single quotes.
+    # Thus, we can recover symbols when we _unwrap_ them later.  Other key types will raise an exception.
+    def self.wrap_key(key)
+      case key
+      when String
+        "'#{key}'"
+      when Symbol
+        key.to_s
+      else
+        raise TypeError, "Candy field names must be strings or symbols. You gave us #{key.class}: #{key}"
+      end
+    end
+    
     # Returns a nested hash containing the class and instance variables of the object.  It's not the
     # deepest we could ever go (it doesn't handle singleton methods, etc.) but it's a start.
     def self.wrap_object(object)
@@ -84,43 +88,53 @@ module Candy
       {"__object_" => wrapped}
     end
     
-    # Undoes any complicated magic from the Wrapper.wrap method.  Almost everything falls through
-    # untouched except for symbol strings and hashed objects.
-    def self.unwrap(thing)
+    # Undoes any magic from the Wrapper.wrap method.  Almost everything falls through
+    # untouched except for arrays and hashes. The 'parent' and 'attribute' parameters
+    # are for recursively setting the parent properties of embedded Candy objects.
+    def self.unwrap(thing, parent=nil, attribute=nil)
       case thing
       when Hash
-        if thing["__object_"]
+        if thing.has_key?("__object_")
           unwrap_object(thing)
         else
-          unwrap_hash(thing)
+          unwrap_hash(thing, parent, attribute)
         end
       when Array
-        CandyArray.embed(*thing.map {|element| unwrap(element)})
-      # when /^__:(.+)/
-      #   $1.to_sym
+        if parent   # We only want to create CandyArrays inside Candy pieces
+          CandyArray.embed(parent, attribute, *thing)
+        else
+          thing.collect {|element| unwrap(element)}
+        end
       else
         thing
       end
     end
     
-    # Traverses the hash, unwrapping values and converting keys back to symbols.  Returns 
-    # the results as a CandyHash object.
-    def self.unwrap_hash(hash)
-      unwrapped = {}
-      hash.each do |key, value|
-        case key
-        when /^'(.+)'$/
-          unwrapped[$1] = unwrap(value)
-        when String
-          unwrapped[key.to_sym] = unwrap(value)
-        else
-          unwrapped[unwrap(key)] = unwrap(value)
-        end
+    
+    # Returns the hash as a Candy::Piece if a class name is embedded, or a CandyHash object otherwise.
+    # The 'parent' and 'attribute' parameters should be set by the caller if this is an embedded
+    # Candy object.
+    def self.unwrap_hash(hash, parent=nil, attribute=nil)
+      if class_name = hash.delete(CLASS_KEY.to_s)
+        klass = qualified_const_get(class_name)
+      else
+        klass = CandyHash
       end
-      if klass = unwrapped.delete(CLASS_KEY)
-        qualified_const_get(klass).embed(unwrapped)
+      
+      if parent
+        klass.embed(parent, attribute, hash)
+      else
+        klass.piece(hash)
+      end
+    end
+    
+    # The inverse of Wrapper.wrap_key -- removes single-quoting from strings and converts other strings 
+    # to symbols.
+    def self.unwrap_key(key)
+      if key =~ /^'(.*)'$/
+        $1
       else
-        CandyHash.embed(unwrapped)
+        key.to_sym
       end
     end
     

data/spec/candy/array_spec.rb

@@ -42,6 +42,14 @@ describe Candy::CandyArray do
       that = Zagnut(@this.id)
       that.bits[3][2][:foo][0].should == :bar
     end
+    
+    # Github issue #11
+    it "can be updated after load" do
+      that = Zagnut(@this.id)
+      that.bits << 'schadenfreude'
+      @this.refresh
+      @this.bits[3].should == 'schadenfreude'
+    end
 
     after(:each) do
       Zagnut.collection.remove

data/spec/candy/piece_spec.rb

@@ -235,7 +235,7 @@ describe Candy::Piece do
       end
       
       it "cascades deeply" do
-        @this.inner.inner = Zagnut.embed(beauty: 'recursive!')
+        @this.inner.inner = Zagnut.piece(beauty: 'recursive!')
         that = Zagnut(@this.id)
         that.inner.inner.beauty.should == 'recursive!'
       end

data/spec/candy/wrapper_spec.rb

@@ -166,10 +166,16 @@ module Candy
         obj.rocket[1].should be_an(Object)
       end
       
+      it "doesn't turn arrays into CandyArrays inside non-Candy objects" do
+        obj = Wrapper.unwrap(@wrapped)
+        obj.rocket.should_not be_a(CandyArray)
+      end
+      
       it "traverses a hash and unwraps whatever it needs to" do
         hash = {"foo" => :bar, "'missile'" => @wrapped}
         unwrapped = Wrapper.unwrap(hash)
         unwrapped[:foo].should == :bar
+        puts unwrapped
         unwrapped["missile"].should be_a(Missile)
       end
     
@@ -182,9 +188,31 @@ module Candy
         unwrapped[3].should be_nil
         unwrapped[4].should == "hi"
       end
+      
   
     end
-    
 
+    describe "key names" do
+      it "can wrap symbols" do
+        Wrapper.wrap_key(:foo).should == 'foo'
+      end
+      
+      it "can wrap strings" do
+        Wrapper.wrap_key('foo').should == "'foo'"
+      end
+      
+      it "refuses to wrap complicated objects" do
+        lambda{Wrapper.wrap_key(Object.new)}.should raise_error(TypeError, /Object/)
+      end
+      
+      it "can unwrap symbols" do
+        Wrapper.unwrap_key('foo').should == :foo
+      end
+      
+      it "can unwrap strings" do
+        Wrapper.unwrap_key("'foo'").should == 'foo'
+      end
+    end
+    
   end
 end

metadata

@@ -5,8 +5,8 @@ version: !ruby/object:Gem::Version
   segments: 
   - 0
   - 2
-  - 7
-  version: 0.2.7
+  - 8
+  version: 0.2.8
 platform: ruby
 authors: 
 - Stephen Eley
@@ -14,7 +14,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-05-05 00:00:00 -04:00
+date: 2010-05-13 00:00:00 -04:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency