candy 0.1.0 → 0.2.1

data/lib/candy/crunch.rb

@@ -2,47 +2,83 @@ require 'mongo'
 require 'etc'  # To get the current username for database default
 
 module Candy
+  # Our option accessors live here so that someone could include just the
+  # 'candy/crunch' module and make it standalone.
+  
+  # Overrides the host and resets the connection, db, and collection.
+  def self.host=(val)
+    @connection = nil
+    @host = val
+  end
+  
+  # Overrides the port and resets the connection, db, and collection.
+  def self.port=(val)
+    @connection = nil
+    @port = val
+  end
+  
+  # Overrides the options hash and resets the connection, db, and collection.
+  def self.connection_options=(val)
+    @connection = nil
+    @connection_options = val
+  end
+  
+  # Passed to the default connection.  If not set, Mongo's default of localhost will be used.
+  def self.host
+    @host
+  end
+  
+  # Passed to the default connection.  If not set, Mongo's default of 27017 will be used.
+  def self.port
+    @port
+  end
+  
+  # A hash passed to the default connection.  See the Mongo::Connection documentation for valid options.
+  def self.connection_options
+    @connection_options ||= {}
+  end
+  
+  # First clears any collection and database we're talking to, then accepts a connection you provide.
+  # You're responsible for your own host, port and options if you use this.
+  def self.connection=(val)
+    self.db = nil
+    @connection = val
+  end
+  
+  # Returns the connection you gave, or creates a default connection to the default host and port.
+  def self.connection
+    @connection ||= Mongo::Connection.new(host, port, connection_options)
+  end
+  
+  # Accepts a database you provide. You can provide a Mongo::DB object or a string with the database
+  # name. If you provide a Mongo::DB object, the default connection is not used, and the :strict flag
+  # should be false or default collection lookup will fail.
+  def self.db=(val)
+    case val
+    when Mongo::DB
+      @db = val
+    when String
+      @db = Mongo::DB.new(val, connection)
+    when nil
+      @db = nil
+    else 
+      raise ConnectionError, "The db attribute needs a Mongo::DB object or a name string."
+    end
+  end
+  
+  # Returns the database you gave, or creates a default database named for your username (or 'candy' if it
+  # can't find a username).
+  def self.db
+    @db ||= Mongo::DB.new(Etc.getlogin || 'candy', connection, :strict => false)
+  end
   
   # All of the hard crunchy bits that connect us to a collection within a Mongo database.
   module Crunch
     module ClassMethods
-      
-      # Passed to the default connection.  It uses the $MONGO_HOST global if that's set and you don't override it.
-      def host
-        @host ||= $MONGO_HOST
-      end
-
-      # Passed to the default connection.  It uses the $MONGO_PORT global if that's set and you don't override it.
-      def port
-        @port ||= $MONGO_PORT
-      end
-      
-      # A hash passed to the default connection. It uses the $MONGO_OPTIONS global if that's set and you don't override it.
-      def options
-        @options ||= ($MONGO_OPTIONS || {})
-      end
-      
-      # Overrides the host and resets the connection, db, and collection.
-      def host=(val)
-        @connection = nil
-        @host = val
-      end
-      
-      # Overrides the port and resets the connection, db, and collection.
-      def port=(val)
-        @connection = nil
-        @port = val
-      end
-
-      # Overrides the options hash and resets the connection, db, and collection.
-      def options=(val)
-        @connection = nil
-        @options = val
-      end
-      
-      # Returns the connection you gave, or creates a default connection to the default host and port.
+            
+      # Returns the connection you gave, or uses the application-level Candy collection.
       def connection
-        @connection ||= Mongo::Connection.new(host, port, options)
+        @connection ||= Candy.connection
       end
        
       # First clears any collection and database we're talking to, then accepts a connection you provide.
@@ -69,10 +105,9 @@ module Candy
         end
       end
       
-      # Returns the database you gave, or creates a default database named for your username (or 'candy' if it
-      # can't find a username).
+      # Returns the database you gave, or uses the application-level Candy database.
       def db
-        @db ||= Mongo::DB.new($MONGO_DB || Etc.getlogin || 'candy', connection, :strict => false)
+        @db ||= Candy.db
       end
       
       # Accepts either a Mongo::Collection object or a string with the collection name.  If you provide a 
@@ -82,7 +117,7 @@ module Candy
         when Mongo::Collection
           @collection = val
         when String
-          @collection = db.create_collection(val)
+          @collection = db.collection(val)
         when nil
           @collection = nil
         else
@@ -92,7 +127,7 @@ module Candy
       
       # Returns the collection you gave, or creates a default collection named for the current class.
       def collection
-        @collection ||= db.create_collection(name)
+        @collection ||= db.collection(name)
       end
       
       # Creates an index on the specified property, with an optional direction specified as either :asc or :desc.
@@ -109,13 +144,19 @@ module Candy
       end
     end
     
-    module InstanceMethods
-      
+    # We're implementing FindAndModify on Mongo 1.4 until the Ruby driver gets around to being updated...
+    def findAndModify(query, update, sort={})
+      command = OrderedHash[
+        findandmodify: self.collection.name,
+        query: query,
+        update: update,
+        sort: sort
+      ]
+      result = self.class.db.command(command)
     end
     
     def self.included(receiver)
       receiver.extend         ClassMethods
-      receiver.send :include, InstanceMethods
     end
   end
 end

data/lib/candy/embeddable.rb

@@ -0,0 +1,34 @@
+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 whom it belongs to and what attribute it's associated with.  When
+    # its own state changes, it can use this information to update the parent.
+    def adopt(parent, attribute)
+      @__candy_parent = parent
+      @__candy_parent_key = attribute
+    end
+    
+  private
+    # If we're an attribute of another object, set our field names accordingly.
+    def embedded(fields)
+      new_fields = {}
+      fields.each{|k,v| new_fields["#{@__candy_parent_key}.#{k}".to_sym] = v}
+      new_fields
+    end
+  
+    # Convert hashes and arrays to CandyHashes and CandyArrays.
+    def embeddify(value)
+      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
+      else
+        value
+      end
+    end
+  
+  end
+end

data/lib/candy/factory.rb

@@ -0,0 +1,30 @@
+require 'candy/qualified_const_get'
+module Candy
+  
+  # Utility methods that can generate new methods or classes for some of Candy's magic. 
+  module Factory
+
+    # Creates a method with the same name as a provided class, in the same namespace as
+    # that class, which delegates to a given class method of that class.  (Whew.  Make sense?)
+    def self.magic_method(klass, method, params='')
+      ns = namespace(klass)
+      my_name = klass.name.sub(ns, '').to_sym
+      parent = (ns == '' ? Object : qualified_const_get(ns))
+      unless parent.method_defined?(my_name)
+        parent.class_eval <<-CLASS
+          def #{my_name}(#{params})
+            #{klass}.#{method}(#{params.gsub(/\s?=(.+?),/,',')})
+          end
+        CLASS
+      end
+    end
+      
+  private
+    # Retrieves the 'BlahModule::BleeModule::' part of a class name, so that we
+    # can put other things in the same namespace.
+    def self.namespace(receiver)
+      receiver.name[/^.*::/] || '' # Hooray for greedy matching
+    end
+  end
+end
+    

data/lib/candy/hash.rb

@@ -0,0 +1,30 @@
+require 'candy/piece'
+
+module Candy
+  
+  # A subclass of Hash that behaves like a Candy::Piece.  This class has two major uses:
+  #
+  # * It's a convenient starting point if you just want to store a bunch of data in Mongo
+  #   and don't need to implement any business logic in your own classes; and
+  # * It's the default when you embed hashed data in another Candy::Piece and don't
+  #   supply another object class. Because it doesn't need to store a classname, using
+  #   it means less metadata in your collections.
+  #
+  # If you don't tell them otherwise, top-level CandyHash objects store themselves in
+  # the 'candy' collection.  You can change that at any time by setting a different
+  # collection at the class or object level.
+  class CandyHash < Hash
+    include Crunch
+    include Piece
+    
+    self.collection = 'candy'
+    
+  
+    # Overrides the default behavior in Candy::Piece so that we DO NOT add our
+    # class name to the saved values.
+    def to_mongo
+      candy
+    end
+          
+  end
+end

data/lib/candy/piece.rb

@@ -0,0 +1,210 @@
+require 'candy/array'
+require 'candy/crunch'
+require 'candy/embeddable'
+require 'candy/factory'
+require 'candy/hash'
+
+module Candy
+  
+  # Handles autopersistence and single-object retrieval for an arbitrary Ruby class.
+  # For retrieving many objects, include Candy::Collection somewhere else or use
+  # the magic Candy() factory.
+  module Piece
+    
+    module ClassMethods
+      include Crunch::ClassMethods
+      
+      # Retrieves a single object from Mongo by its search attributes, or nil if it can't be found.
+      def first(conditions={})
+        conditions = {'_id' => conditions} unless conditions.is_a?(Hash)
+        if record = collection.find_one(conditions)
+          self.new(record)
+        end
+      end
+      
+      # Performs an 'upsert' into the collection.  The first parameter is a field name or array of fields
+      # which act as our "key" fields -- if a document in the system matches the values from the hash,
+      # it'll be updated.  Otherwise, an insert will occur.  The second parameter tells us what to set or
+      # insert.
+      def update(key_or_keys, fields)
+        search_keys = {}
+        Array(key_or_keys).each do |key|
+          search_keys[key] = Wrapper.wrap(fields[key])
+        end
+        collection.update search_keys, fields, :upsert => true
+      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)
+        if args[-1].is_a?(Hash)
+          args[-1].merge!(EMBED_KEY => true)
+        else
+          args.push({EMBED_KEY => true})
+        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
+      # 'first', for easier semantics.
+      def self.extended(receiver)
+        Factory.magic_method(receiver, 'first', 'conditions={}')
+      end  
+    end
+    
+    # HERE STARTETH THE MODULE PROPER.  (The above are the class methods.)
+    include Crunch
+    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.
+    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_mongo(Wrapper.unwrap(data))
+        elsif data.delete(EMBED_KEY)  # We're being embedded: take any data, but don't save to Mongo
+          @__candy = data
+        else
+          set data   # Insert the data we're given
+        end
+      end
+      super
+    end
+    
+    # Shortcut to the document ID.
+    def id
+      @__candy_id
+    end
+    
+    # Pull our document from the database if we know our ID.
+    def retrieve_document
+      Wrapper.unwrap(collection.find_one({'_id' => id})) if id
+    end
+    
+    
+    # Returns the hash of memoized values.
+    def candy
+      @__candy ||= retrieve_document || {}
+    end
+    
+    # Objects are equal if they point to the same MongoDB record (unless both have IDs of nil, in which case 
+    # they're never equal.)
+    def ==(subject)
+      return false if id.nil?
+      return false unless subject.respond_to?(:id)
+      self.id == subject.id 
+    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
+        self[$1.to_sym] = args[0]
+      elsif name =~ /(.*)\?$/  # We're asking
+        (self[$1.to_sym] ? true : false)
+      else
+        self[name]
+      end
+    end
+
+    # Hash-like getter. If we don't have a value yet, we pull from the database looking for one.
+    # Fields pulled from the database are keyed as symbols in the hash.
+    def [](key)
+      candy[key] 
+    end
+    
+    # Hash-like setter.  Updates the object's internal state, and writes to the database if the state
+    # has changed.  Keys should be passed in as symbols for best consistency with the database.
+    def []=(key, value)
+      property = embeddify(value)
+      candy[key] = property
+      if property.respond_to?(:to_mongo)
+        property.adopt(self, key)
+        set key => property.to_mongo
+      else
+        set key => property
+      end
+    end
+    
+    # Clears memoized data so that the next read pulls from the database.
+    def refresh
+      @__candy = nil
+      self
+    end
+    
+    # The MongoDB collection object that everything saves to.  Defaults to the class's
+    # collection, which in turn defaults to the classname.
+    def collection
+      @__candy_collection ||= self.class.collection
+    end
+    
+    # This is normally set at the class level (with a default of the classname) but you
+    # can override it on a per-object basis if you need to.
+    def collection=(val)
+      @__candy_collection = val
+    end
+    
+    # Convenience method for debugging.  Shows the class, the Mongo ID, and the saved state hash.
+    def to_s
+      "#{self.class.name} (#{id})#{candy.inspect}"
+    end
+    
+    
+    # Converts the object into a hash for MongoDB storage.  Keep in mind that wrapping happens _after_
+    # this stage, so it's best to use symbols for keys and leave internal arrays and hashes alone.
+    def to_mongo
+      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.
+    def from_mongo(hash) 
+      hash
+    end
+    
+    
+    # Given a hash of property/value pairs, sets those values in Mongo using the atomic $set if
+    # we have a document ID.  Otherwise inserts them and sets the object's ID. 
+    def set(fields)
+      operate :set, fields
+    end
+    
+    # A generic updater that performs the atomic operation specified on a value nested arbitrarily deeply.
+    # 
+    def operate(operator, fields)
+      if @__candy_parent
+        @__candy_parent.operate operator, embedded(fields)
+      else
+        @__candy_id = collection.insert({}) unless id   # Ensure we have something to update
+        collection.update({'_id' => id}, {"$#{operator}" => Wrapper.wrap(fields)})
+      end
+    end
+  
+  private
+        
+    
+    def self.included(receiver)
+      receiver.extend ClassMethods
+    end
+  end
+end