humanoid 1.2.7

data/lib/humanoid/criterion/optional.rb

@@ -0,0 +1,128 @@
+# encoding: utf-8
+module Humanoid #:nodoc:
+  module Criterion #:nodoc:
+    module Optional
+      # Tells the criteria that the cursor that gets returned needs to be
+      # cached. This is so multiple iterations don't hit the database multiple
+      # times, however this is not advisable when working with large data sets
+      # as the entire results will get stored in memory.
+      #
+      # Example:
+      #
+      # <tt>criteria.cache</tt>
+      def cache
+        @options.merge!(:cache => true); self
+      end
+
+      # Will return true if the cache option has been set.
+      #
+      # Example:
+      #
+      # <tt>criteria.cached?</tt>
+      def cached?
+        @cached ||= @options.delete(:cache)
+        @cached == true
+      end
+
+      # Flags the criteria to execute against a read-only slave in the pool
+      # instead of master.
+      #
+      # Example:
+      #
+      # <tt>criteria.enslave</tt>
+      def enslave
+        @options.merge!(:enslave => true); self
+      end
+
+      # Adds a criterion to the +Criteria+ that specifies additional options
+      # to be passed to the Ruby driver, in the exact format for the driver.
+      #
+      # Options:
+      #
+      # extras: A +Hash+ that gets set to the driver options.
+      #
+      # Example:
+      #
+      # <tt>criteria.extras(:limit => 20, :skip => 40)</tt>
+      #
+      # Returns: <tt>self</tt>
+      def extras(extras)
+        @options.merge!(extras); filter_options; self
+      end
+
+      # Adds a criterion to the +Criteria+ that specifies an id that must be matched.
+      #
+      # Options:
+      #
+      # object_id: A +String+ representation of a <tt>Mongo::ObjectID</tt>
+      #
+      # Example:
+      #
+      # <tt>criteria.id("4ab2bc4b8ad548971900005c")</tt>
+      #
+      # Returns: <tt>self</tt>
+      def id(*args)
+        (args.flatten.size > 1) ? self.in(:_id => args.flatten) : (@selector[:_id] = args.first)
+        self
+      end
+
+      # Adds a criterion to the +Criteria+ that specifies the maximum number of
+      # results to return. This is mostly used in conjunction with <tt>skip()</tt>
+      # to handle paginated results.
+      #
+      # Options:
+      #
+      # value: An +Integer+ specifying the max number of results. Defaults to 20.
+      #
+      # Example:
+      #
+      # <tt>criteria.limit(100)</tt>
+      #
+      # Returns: <tt>self</tt>
+      def limit(value = 20)
+        @options[:limit] = value; self
+      end
+
+      # Returns the offset option. If a per_page option is in the list then it
+      # will replace it with a skip parameter and return the same value. Defaults
+      # to 20 if nothing was provided.
+      def offset(*args)
+        args.size > 0 ? skip(args.first) : @options[:skip]
+      end
+
+      # Adds a criterion to the +Criteria+ that specifies the sort order of
+      # the returned documents in the database. Similar to a SQL "ORDER BY".
+      #
+      # Options:
+      #
+      # params: An +Array+ of [field, direction] sorting pairs.
+      #
+      # Example:
+      #
+      # <tt>criteria.order_by([[:field1, :asc], [:field2, :desc]])</tt>
+      #
+      # Returns: <tt>self</tt>
+      def order_by(params = [])
+        @options[:sort] = params; self
+      end
+
+      # Adds a criterion to the +Criteria+ that specifies how many results to skip
+      # when returning Documents. This is mostly used in conjunction with
+      # <tt>limit()</tt> to handle paginated results, and is similar to the
+      # traditional "offset" parameter.
+      #
+      # Options:
+      #
+      # value: An +Integer+ specifying the number of results to skip. Defaults to 0.
+      #
+      # Example:
+      #
+      # <tt>criteria.skip(20)</tt>
+      #
+      # Returns: <tt>self</tt>
+      def skip(value = 0)
+        @options[:skip] = value; self
+      end
+    end
+  end
+end

data/lib/humanoid/cursor.rb

@@ -0,0 +1,82 @@
+# encoding: utf-8
+module Humanoid #:nodoc
+  class Cursor
+    include Enumerable
+    # Operations on the Mongo::Cursor object that will not get overriden by the
+    # Humanoid::Cursor are defined here.
+    OPERATIONS = [
+      :admin,
+      :close,
+      :closed?,
+      :count,
+      :explain,
+      :fields,
+      :full_collection_name,
+      :hint,
+      :limit,
+      :order,
+      :query_options_hash,
+      :query_opts,
+      :selector,
+      :skip,
+      :snapshot,
+      :sort,
+      :timeout
+    ]
+
+    attr_reader :collection
+
+    # The operations above will all delegate to the proxied Mongo::Cursor.
+    #
+    # Example:
+    #
+    # <tt>cursor.close</tt>
+    OPERATIONS.each do |name|
+      define_method(name) { |*args| @cursor.send(name, *args) }
+    end
+
+    # Iterate over each document in the cursor and yield to it.
+    #
+    # Example:
+    #
+    # <tt>cursor.each { |doc| p doc.title }</tt>
+    def each
+      @cursor.each do |document|
+        yield Humanoid::Factory.build(@klass, document)
+      end
+    end
+
+    # Create the new +Humanoid::Cursor+.
+    #
+    # Options:
+    #
+    # collection: The Humanoid::Collection instance.
+    # cursor: The Mongo::Cursor to be proxied.
+    #
+    # Example:
+    #
+    # <tt>Humanoid::Cursor.new(Person, cursor)</tt>
+    def initialize(klass, collection, cursor)
+      @klass, @collection, @cursor = klass, collection, cursor
+    end
+
+    # Return the next document in the cursor. Will instantiate a new Humanoid
+    # document with the attributes.
+    #
+    # Example:
+    #
+    # <tt>cursor.next_document</tt>
+    def next_document
+      Humanoid::Factory.build(@klass, @cursor.next_document)
+    end
+
+    # Returns an array of all the documents in the cursor.
+    #
+    # Example:
+    #
+    # <tt>cursor.to_a</tt>
+    def to_a
+      @cursor.to_a.collect { |attrs| Humanoid::Factory.build(@klass, attrs) }
+    end
+  end
+end

data/lib/humanoid/document.rb

@@ -0,0 +1,300 @@
+# encoding: utf-8
+module Humanoid #:nodoc:
+  module Document
+    def self.included(base)
+      base.class_eval do
+        include Components
+        include InstanceMethods
+        extend ClassMethods
+
+        cattr_accessor :_collection, :collection_name, :embedded, :primary_key, :hereditary
+
+        self.embedded = false
+        self.hereditary = false
+        self.collection_name = self.name.collectionize
+
+        attr_accessor :association_name, :_parent
+        attr_reader :new_record
+
+        delegate :collection, :db, :embedded, :primary_key, :to => "self.class"
+      end
+    end
+
+    module ClassMethods
+      # Return the database associated with this class.
+      def db
+        collection.db
+      end
+
+      # Returns the collection associated with this +Document+. If the
+      # document is embedded, there will be no collection associated
+      # with it.
+      #
+      # Returns: <tt>Mongo::Collection</tt>
+      def collection
+        raise Errors::InvalidCollection.new(self) if embedded
+        self._collection ||= Humanoid::Collection.new(self, self.collection_name)
+        add_indexes; self._collection
+      end
+
+      # Perform default behavior but mark the hierarchy as being hereditary.
+      def inherited(subclass)
+        super(subclass)
+        self.hereditary = true
+      end
+
+      # Returns a human readable version of the class.
+      #
+      # Example:
+      #
+      # <tt>MixedDrink.human_name # returns "Mixed Drink"</tt>
+      def human_name
+        name.labelize
+      end
+
+      # Instantiate a new object, only when loaded from the database or when
+      # the attributes have already been typecast.
+      #
+      # Example:
+      #
+      # <tt>Person.instantiate(:title => "Sir", :age => 30)</tt>
+      def instantiate(attrs = nil, allocating = false)
+        attributes = attrs || {}
+        if attributes["_id"] || allocating
+          document = allocate
+          document.instance_variable_set(:@attributes, attributes)
+          return document
+        else
+          return new(attrs)
+        end
+      end
+
+      # Defines the field that will be used for the id of this +Document+. This
+      # set the id of this +Document+ before save to a parameterized version of
+      # the field that was supplied. This is good for use for readable URLS in
+      # web applications.
+      #
+      # Example:
+      #
+      #   class Person
+      #     include Humanoid::Document
+      #     field :first_name
+      #     field :last_name
+      #     key :first_name, :last_name
+      #   end
+      def key(*fields)
+        self.primary_key = fields
+        before_save :identify
+      end
+
+      # Macro for setting the collection name to store in.
+      #
+      # Example:
+      #
+      # <tt>Person.store_in :populdation</tt>
+      def store_in(name)
+        self.collection_name = name.to_s
+        self._collection = Humanoid::Collection.new(self, name.to_s)
+      end
+
+      # Returns all types to query for when using this class as the base.
+      def _types
+        @_type ||= (self.subclasses + [ self.name ])
+      end
+
+    end
+
+    module InstanceMethods
+      # 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) ==
+          other.attributes.except(:modified_at).except(:created_at)
+      end
+
+      # Delegates to ==
+      def eql?(comparison_object)
+        self == (comparison_object)
+      end
+
+      # Delegates to id in order to allow two records of the same type and id to work with something like:
+      #   [ Person.find(1), Person.find(2), Person.find(3) ] & [ Person.find(1), Person.find(4) ] # => [ Person.find(1) ]
+      def hash
+        id.hash
+      end
+
+      # Introduces a child object into the +Document+ object graph. This will
+      # set up the relationships between the parent and child and update the
+      # attributes of the parent +Document+.
+      #
+      # Options:
+      #
+      # parent: The +Document+ to assimilate with.
+      # options: The association +Options+ for the child.
+      #
+      # Example:
+      #
+      # <tt>name.assimilate(person, options)</tt>
+      def assimilate(parent, options)
+        parentize(parent, options.name); notify; self
+      end
+
+      # Return the attributes hash with indifferent access.
+      def attributes
+        @attributes.with_indifferent_access
+      end
+
+      # Clone the current +Document+. This will return all attributes with the
+      # exception of the document's id and versions.
+      def clone
+        self.class.instantiate(@attributes.except("_id").except("versions").dup, true)
+      end
+
+      # Generate an id for this +Document+.
+      def identify
+        Identity.create(self)
+      end
+
+      # 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.
+      def initialize(attrs = nil)
+        @attributes = {}
+        process(attrs)
+        @attributes = attributes_with_defaults(@attributes)
+        @new_record = true if id.nil?
+        document = yield self if block_given?
+        identify
+      end
+
+      # Returns the class name plus its attributes.
+      def inspect
+        attrs = fields.map { |name, field| "#{name}: #{@attributes[name].inspect}" } * ", "
+        "#<#{self.class.name} _id: #{id}, #{attrs}>"
+      end
+
+      # Returns true is the +Document+ has not been persisted to the database,
+      # false if it has. This is determined by the variable @new_record
+      # and NOT if the object has an id.
+      def new_record?
+        @new_record == true
+      end
+
+      # Sets the new_record boolean - used after document is saved.
+      def new_record=(saved)
+        @new_record = saved
+      end
+
+      # 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 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.to_s
+        add_observer(object)
+      end
+
+      # Return the attributes hash.
+      def raw_attributes
+        @attributes
+      end
+
+      # Reloads the +Document+ attributes from the database.
+      def reload
+        @attributes = collection.find_one(:_id => id)
+        self
+      end
+
+      # Remove a child document from this parent +Document+. Will reset the
+      # memoized association and notify the parent of the change.
+      def remove(child)
+        name = child.association_name
+        reset(name) { @attributes.remove(name, child.raw_attributes) }
+        notify
+      end
+
+      # 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
+
+      # Return an array with this +Document+ only in it.
+      def to_a
+        [ self ]
+      end
+
+      # Return this document as a JSON string. Nothing special is required here
+      # since Humanoid bubbles up all the child associations to the parent
+      # attribute +Hash+ using observers throughout the +Document+ lifecycle.
+      #
+      # Example:
+      #
+      # <tt>person.to_json</tt>
+      def to_json(options = nil)
+        attributes.to_json(options)
+      end
+
+      # Returns the id of the Document, used in Rails compatibility.
+      def to_param
+        id
+      end
+
+      # 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.
+      #
+      # This will also cause the observing +Document+ to notify it's parent if
+      # there is any.
+      def update(child, clear = false)
+        name = child.association_name
+        attrs = child.instance_variable_get(:@attributes)
+        clear ? @attributes.delete(name) : @attributes.insert(name, attrs)
+        notify
+      end
+
+      protected
+      # apply default values to attributes - calling procs as required
+      def attributes_with_defaults(attributes = {})
+        default_values = defaults.merge(attributes)
+        default_values.each_pair do |key, val|
+          default_values[key] = val.call if val.respond_to?(:call)
+        end
+      end
+    end
+  end
+end