candy 0.1.0 → 0.2.1

data/Rakefile

@@ -5,22 +5,20 @@ begin
   require 'jeweler'
   Jeweler::Tasks.new do |gem|
     gem.name = "candy"
-    gem.summary = %Q{The simplest MongoDB ORM}
+    gem.summary = %Q{Transparent persistence for MongoDB}
     gem.description = <<DESCRIPTION
-Candy is a lightweight ORM for the MongoDB database. If MongoMapper is Rails, Candy is Sinatra. 
-It provides a module you mix into any class, enabling the class to connect to Mongo on its own
-and push its objects into a collection. Candied objects act like OpenStructs, allowing attributes
-to be defined and updated in Mongo immediately without having to be declared in the class. 
-Mongo's atomic operators are used whenever possible, and a smart serializer (Candy::Wrapper) 
-converts almost any object for assignment to any attribute.
+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 
+method calls like 'save' and 'find.'
 DESCRIPTION
 
     gem.email = "sfeley@gmail.com"
     gem.homepage = "http://github.com/SFEley/candy"
     gem.authors = ["Stephen Eley"]
-    gem.add_dependency "mongo", ">= 0.18"
+    gem.add_dependency "mongo", ">= 0.19.1"
     gem.add_development_dependency "rspec", ">= 1.2.9"
-    gem.add_development_dependency "yard", ">= 0"
+    # gem.add_development_dependency "yard", ">= 0"
     gem.add_development_dependency "mocha", ">= 0.9.8"
     # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
   end

data/VERSION

@@ -1 +1 @@
-0.1.0
+0.2.1

data/candy.gemspec

@@ -5,53 +5,70 @@
 
 Gem::Specification.new do |s|
   s.name = %q{candy}
-  s.version = "0.1.0"
+  s.version = "0.2.1"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Stephen Eley"]
-  s.date = %q{2010-02-16}
-  s.description = %q{Candy is a lightweight ORM for the MongoDB database. If MongoMapper is Rails, Candy is Sinatra. 
-It provides a module you mix into any class, enabling the class to connect to Mongo on its own
-and push its objects into a collection. Candied objects act like OpenStructs, allowing attributes
-to be defined and updated in Mongo immediately without having to be declared in the class. 
-Mongo's atomic operators are used whenever possible, and a smart serializer (Candy::Wrapper) 
-converts almost any object for assignment to any attribute.
+  s.date = %q{2010-04-05}
+  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 
+method calls like 'save' and 'find.'
 }
   s.email = %q{sfeley@gmail.com}
   s.extra_rdoc_files = [
-    "LICENSE",
+    "LICENSE.markdown",
      "README.markdown"
   ]
   s.files = [
     ".document",
      ".gitignore",
-     "LICENSE",
+     "HISTORY.markdown",
+     "LICENSE.markdown",
      "README.markdown",
      "Rakefile",
      "VERSION",
      "candy.gemspec",
      "lib/candy.rb",
+     "lib/candy/array.rb",
+     "lib/candy/collection.rb",
      "lib/candy/crunch.rb",
+     "lib/candy/embeddable.rb",
      "lib/candy/exceptions.rb",
+     "lib/candy/factory.rb",
+     "lib/candy/hash.rb",
+     "lib/candy/piece.rb",
      "lib/candy/qualified_const_get.rb",
      "lib/candy/wrapper.rb",
+     "spec/candy/array_spec.rb",
+     "spec/candy/collection_spec.rb",
      "spec/candy/crunch_spec.rb",
+     "spec/candy/hash_spec.rb",
+     "spec/candy/piece_spec.rb",
      "spec/candy/wrapper_spec.rb",
      "spec/candy_spec.rb",
      "spec/spec.opts",
      "spec/spec.watchr",
-     "spec/spec_helper.rb"
+     "spec/spec_helper.rb",
+     "spec/support/kitkat_fixture.rb",
+     "spec/support/zagnuts_fixture.rb"
   ]
   s.homepage = %q{http://github.com/SFEley/candy}
   s.rdoc_options = ["--charset=UTF-8"]
   s.require_paths = ["lib"]
-  s.rubygems_version = %q{1.3.5}
-  s.summary = %q{The simplest MongoDB ORM}
+  s.rubygems_version = %q{1.3.6}
+  s.summary = %q{Transparent persistence for MongoDB}
   s.test_files = [
-    "spec/candy/crunch_spec.rb",
+    "spec/candy/array_spec.rb",
+     "spec/candy/collection_spec.rb",
+     "spec/candy/crunch_spec.rb",
+     "spec/candy/hash_spec.rb",
+     "spec/candy/piece_spec.rb",
      "spec/candy/wrapper_spec.rb",
      "spec/candy_spec.rb",
-     "spec/spec_helper.rb"
+     "spec/spec_helper.rb",
+     "spec/support/kitkat_fixture.rb",
+     "spec/support/zagnuts_fixture.rb"
   ]
 
   if s.respond_to? :specification_version then
@@ -59,20 +76,17 @@ converts almost any object for assignment to any attribute.
     s.specification_version = 3
 
     if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
-      s.add_runtime_dependency(%q<mongo>, [">= 0.18"])
+      s.add_runtime_dependency(%q<mongo>, [">= 0.19.1"])
       s.add_development_dependency(%q<rspec>, [">= 1.2.9"])
-      s.add_development_dependency(%q<yard>, [">= 0"])
       s.add_development_dependency(%q<mocha>, [">= 0.9.8"])
     else
-      s.add_dependency(%q<mongo>, [">= 0.18"])
+      s.add_dependency(%q<mongo>, [">= 0.19.1"])
       s.add_dependency(%q<rspec>, [">= 1.2.9"])
-      s.add_dependency(%q<yard>, [">= 0"])
       s.add_dependency(%q<mocha>, [">= 0.9.8"])
     end
   else
-    s.add_dependency(%q<mongo>, [">= 0.18"])
+    s.add_dependency(%q<mongo>, [">= 0.19.1"])
     s.add_dependency(%q<rspec>, [">= 1.2.9"])
-    s.add_dependency(%q<yard>, [">= 0"])
     s.add_dependency(%q<mocha>, [">= 0.9.8"])
   end
 end

data/lib/candy.rb

@@ -1,140 +1,13 @@
-require 'candy/exceptions'
-require 'candy/crunch'
-require 'candy/wrapper'
+# encoding: utf-8
 
-# Mix me into your classes and Mongo will like them!
-module Candy
-  
-  module ClassMethods
-    include Crunch::ClassMethods
-    
-    attr_reader :stamp_create, :stamp_update
-    
-    # Retrieves an object from Mongo by its ID and returns it.  Returns nil if the ID isn't found in Mongo.
-    def find(id)
-      if collection.find_one(id)
-        self.new({:_candy => id})
-      end
-    end
-    
-    # Retrieves a single object from Mongo by its search attributes, or nil if it can't be found.
-    def first(conditions={})
-      options = extract_options(conditions)
-      if record = collection.find_one(conditions, options)
-        find(record["_id"])
-      else
-        nil
-      end
-    end
-    
-    # Retrieves all objects matching the search attributes as an Enumerator (even if it's an empty one).
-    # The option fields from Mongo::Collection#find can be passed as well, and will be extracted from the 
-    # condition set if they're found.
-    def all(conditions={})
-      options = extract_options(conditions)
-      cursor = collection.find(conditions, options)
-      Enumerator.new do |yielder|
-        while record = cursor.next_document do
-          yielder.yield find(record["_id"])
-        end
-      end  
-    end
-    
-    # Configures objects to set `created_at` and `updated_at` properties at the appropriate times.
-    # Pass `:create` or `:update` to limit it to just one or the other.  Defaults to both.
-    def timestamp(*args)
-      args = [:create, :update] if args.empty?
-      @stamp_create = args.include?(:create)
-      @stamp_update = args.include?(:update)
-    end
-    
-  private
-    # Returns a hash of options matching those enabled in Mongo::Collection#find, if any of them exist
-    # in the set of search conditions.
-    def extract_options(conditions)
-      options = {:fields => []}
-      [:fields, :skip, :limit, :sort, :hint, :snapshot, :timeout].each do |option|
-        options[option] = conditions.delete(option) if conditions[option]
-      end
-      options
-    end
-    
-  end
-  
-  module InstanceMethods
-    include Crunch::InstanceMethods
-    
-    # We push ourselves into the DB before going on with our day.
-    def initialize(*args, &block)
-      @__candy = check_for_candy(args) || 
-        self.class.collection.insert(self.class.stamp_create ? {:created_at => Time.now.utc} : {})
-      super
-    end
+# Make me one with everything...
+Dir[File.join(File.dirname(__FILE__), 'candy', '*.rb')].each {|f| require f}
 
-    # Shortcut to the document ID.
-    def id
-      @__candy
-    end
-    
-    # Candy's magic ingredient. Assigning to any unknown attribute will push that value into the Mongo collection.
-    # Retrieving any unknown attribute will return that value from this record in the Mongo collection.
-    def method_missing(name, *args, &block)
-      if name =~ /(.*)=$/  # We're assigning
-        set $1, Wrapper.wrap(args[0])
-      else
-        Wrapper.unwrap(self.class.collection.find_one(@__candy, :fields => [name.to_s])[name.to_s])
-      end
-    end
-    
-    # Given either a property/value pair or a hash (which can contain several property/value pairs), sets those
-    # values in Mongo using the atomic $set. The first form is functionally equivalent to simply using the
-    # magic assignment operator; i.e., `me.set(:foo, 'bar')` is the same as `me.foo = bar`.
-    def set(*args)
-      if args.length > 1  # This is the property/value form
-        hash = {args[0] => args[1]}
-      else
-        hash = args[0]
-      end
-      hash.merge!(:updated_at => Time.now.utc) if self.class.stamp_update
-      update '$set' => hash
-    end
-    
-    # Given a Candy array property, appends a value or values to the end of that array using the atomic $push.  
-    # (Note that we don't actually check the property to make sure it's an array and $push is valid. If it isn't, 
-    # this operation will silently fail.)
-    def push(property, *values)
-      values.each do |value|
-        update '$push' => {property => Wrapper.wrap(value)}
-      end
-    end
-    
-    # Given a Candy integer property, increments it by the given value (which defaults to 1) using the atomic $inc.
-    # (Note that we don't actually check the property to make sure it's an integer and $inc is valid. If it isn't, 
-    # this operation will silently fail.)
-    def inc(property, increment=1)
-      update '$inc' => {property => increment}
-    end
-  private
-  
-    # Returns the secret decoder ring buried in the arguments to "new"
-    def check_for_candy(args)
-      if (candidate = args.pop).is_a?(Hash) and candidate[:_candy]
-        candidate[:_candy]
-      else # This must not be for us, so put it back  
-        args.push candidate if candidate
-        nil
-      end
-    end
-    
-    # Updates the Mongo document with the given element or elements.
-    def update(element)
-      self.class.collection.update({"_id" => @__candy}, element)
-    end
-    
-  end
-  
-  def self.included(receiver)
-    receiver.extend         ClassMethods
-    receiver.send :include, InstanceMethods
-  end
-end
+# Special keys for Candy metadata in the Mongo store. We try to keep these to a minimum, 
+# and we're using moderately obscure Unicode symbols to reduce the odds of collisions.
+# If by some strange happenstance you might have single-character keys in your Mongo 
+# collections that use the 'CIRCLED LATIN SMALL LETTER' Unicode set, you may need to
+# change these constants.  Just be consistent about it if you want to use embedded
+# documents in Candy.
+CLASS_KEY = 'ⓒ'.to_sym
+EMBED_KEY = 'ⓔ'.to_sym

data/lib/candy/array.rb

@@ -0,0 +1,74 @@
+require 'candy/crunch'
+require 'candy/embeddable'
+
+module Candy
+  
+  # An array-like object that saves itself to a parent Candy::Piece object.  MongoDB's atomic
+  # array operators are used extensively to perform concurrency-friendly updates of individual
+  # array elements without rewriting the whole array.
+  class CandyArray
+    include Crunch
+    include Embeddable
+    
+    # Included for purposes of 'embeddable' compatbility, 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)
+    end
+    
+    # Sets the initial array state.
+    def initialize(*args, &block)
+      @__candy = args
+    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 = embeddify(val)
+      @__candy_parent.set embedded(index => property)
+      self.candy[index] = property
+    end
+    
+    # Retrieves the value from our internal array.
+    def [](index)
+      candy[index]
+    end
+    
+    # Appends a value to our array.  
+    def <<(val)
+      property = embeddify(val)
+      @__candy_parent.operate :push, @__candy_parent_key => property
+      self.candy << property
+    end
+    alias_method :push, :<<
+    
+    # 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]
+      @__candy.shift
+    end
+    
+    # Returns the array of memoized values.
+    def candy
+      @__candy ||= []
+    end
+    alias_method :to_mongo, :candy
+    alias_method :to_ary, :candy
+    
+    # Array equality.
+    def ==(val)
+      self.to_ary == val
+    end
+    
+    # Array length.
+    def length
+      self.to_ary.length
+    end
+    alias_method :size, :length
+
+  end
+end

data/lib/candy/collection.rb

@@ -0,0 +1,151 @@
+require 'candy/crunch'
+require 'candy/hash'
+
+module Candy
+  
+  # Handles Mongo queries for cursors upon a particular Mongo collection.  
+  module Collection
+    FIND_OPTIONS = [:fields, :skip, :limit, :sort, :hint, :snapshot, :timeout]
+    UP_SORTS = [Mongo::ASCENDING, 'ascending', 'asc', :ascending, :asc, 1, :up]
+    DOWN_SORTS = [Mongo::DESCENDING, 'descending', 'desc', :descending, :desc, -1, :down]
+    
+    include Enumerable
+
+    module ClassMethods
+      include Crunch::ClassMethods
+      
+      attr_reader :_candy_piece
+      
+      # Sets the collection that all queries run against, qualified by
+      # the namespace of the current class.  (I.e., if this class is 
+      # BigModule::LittleModule::People, `collects :person` will look for
+      # a collection named "BigModule::LittleModule::Person".) You can also 
+      # specify a class that includes Candy::Piece that will be instantiated
+      # for all found records. Otherwise the collection name is used as a 
+      # default, and CandyHash is a fallback.
+      def collects(collection, piece = nil)
+        collectible = namespace + camelcase(collection)
+        piecemeal = (piece ? namespace + camelcase(piece) : collectible)
+        self.collection = collectible
+        @_candy_piece = Kernel.qualified_const_get(piecemeal) || CandyHash
+      end
+      
+      def all(options={})
+        self.new(options)
+      end
+      
+      def method_missing(name, *args, &block)
+        coll = self.new
+        coll.send(name, *args, &block)
+      end  
+    private
+      # Retrieves the 'BlahModule::BleeModule::' part of the class name, so that we
+      # can put other things in the same namespace.
+      def namespace
+        name[/^.*::/] || '' # Hooray for greedy matching
+      end
+
+      # Modified from ActiveSupport (http://rubyonrails.org)
+      def camelcase(stringy)
+        stringy.to_s.gsub(/(?:^|_)(.)/) {$1.upcase}
+      end
+      
+      # Creates a method in the same namespace as the included class that points to
+      # 'all', for easier semantics.
+      def self.extended(receiver)
+        Factory.magic_method(receiver, 'all', 'conditions={}')
+      end
+      
+    end  # Here endeth the ClassMethods module
+   
+    def initialize(*args, &block)
+      conditions = args.pop || {}
+      super
+      @_candy_query = {}
+      if conditions.is_a?(Hash)
+        @_candy_options = {:fields => '_id'}.merge(extract_options(conditions))
+        @_candy_query.merge!(conditions)
+      else
+        @_candy_options = {:fields => '_id'}
+      end
+      refresh_cursor
+    end
+    
+    def method_missing(name, *args, &block)
+      if @_candy_cursor.respond_to?(name)
+        @_candy_cursor.send(name, *args, &block)
+      elsif FIND_OPTIONS.include?(name)
+        @_candy_options[name] = args.shift
+        refresh_cursor
+        self
+      else
+        @_candy_query[name] = args.shift
+        @_candy_query.merge!(args) if args.is_a?(Hash)
+        refresh_cursor
+        self
+      end
+    end
+      
+    
+    # Makes our collection enumerable.  This relies heavily on Mongo::Cursor methods --
+    # we only reimplement it so that the objects we return can be Candy objects.
+    def each
+      while this = @_candy_cursor.next_document
+        yield self.class._candy_piece.new(this)
+      end
+    end
+    
+    # Get our next document as a Candy object, if there is one.
+    def next
+      if this = @_candy_cursor.next_document
+        self.class._candy_piece.new(this)
+      end
+    end
+    
+    # Determines the sort order for this collection, with somewhat simpler semantics than
+    # the MongoDB options.  Each value is either a field name (which defaults to ascending sort)
+    # or a direction (which modifies the field name immediately prior) or a two-element array of
+    # same.  Direction can be :up or :down in addition to Mongo's accepted values of :ascending, 
+    # 'asc', 1, etc.  
+    #
+    # As an added bonus, sorts can also be chained.  If you call #sort more than once then all
+    # sorts will be applied in the order in which you called them.
+    def sort(*fields)
+      @_candy_sort ||= []
+      temp_sort = []
+      until fields.flatten.empty?
+        this = fields.pop  # We're going backwards so that we can test for modifiers
+        if UP_SORTS.include?(this)
+          temp_sort.unshift [fields.pop, Mongo::ASCENDING]
+        elsif DOWN_SORTS.include?(this)
+          temp_sort.unshift [fields.pop, Mongo::DESCENDING]
+        else
+          temp_sort.unshift [this, Mongo::ASCENDING]
+        end
+      end
+      @_candy_sort += temp_sort
+      @_candy_cursor.sort(@_candy_sort)
+      self
+    end
+          
+          
+  private
+      
+    def refresh_cursor
+      @_candy_cursor = self.class.collection.find(@_candy_query, @_candy_options)
+    end
+    
+    def extract_options(hash)
+      options = {}
+      (FIND_OPTIONS & hash.keys).each do |key|
+        options[key] = hash.delete(key)
+      end
+      options
+    end
+    
+    def self.included(receiver)
+      receiver.extend         ClassMethods
+    end
+  end
+end
+