humanoid 1.2.7

data/lib/humanoid/associations.rb

@@ -0,0 +1,258 @@
+# encoding: utf-8
+require "humanoid/associations/proxy"
+require "humanoid/associations/belongs_to"
+require "humanoid/associations/belongs_to_related"
+require "humanoid/associations/has_many"
+require "humanoid/associations/has_many_related"
+require "humanoid/associations/has_one"
+require "humanoid/associations/has_one_related"
+
+module Humanoid # :nodoc:
+  module Associations #:nodoc:
+    def self.included(base)
+      base.class_eval do
+        # Associations need to inherit down the chain.
+        class_inheritable_accessor :associations
+        self.associations = {}
+
+        include InstanceMethods
+        extend ClassMethods
+      end
+    end
+
+    module InstanceMethods
+      # Returns the associations for the +Document+.
+      def associations
+        self.class.associations
+      end
+
+      # Updates all the one-to-many relational associations for the name.
+      def update_associations(name)
+        send(name).each { |doc| doc.save }
+      end
+
+      # Update the one-to-one relational association for the name.
+      def update_association(name)
+        association = send(name)
+        association.save unless association.nil?
+      end
+    end
+
+    module ClassMethods
+      # Adds the association back to the parent document. This macro is
+      # necessary to set the references from the child back to the parent
+      # document. If a child does not define this association calling
+      # persistence methods on the child object will cause a save to fail.
+      #
+      # Options:
+      #
+      # name: A +Symbol+ that matches the name of the parent class.
+      #
+      # Example:
+      #
+      #   class Person
+      #     include Humanoid::Document
+      #     has_many :addresses
+      #   end
+      #
+      #   class Address
+      #     include Humanoid::Document
+      #     belongs_to :person, :inverse_of => :addresses
+      #   end
+      def belongs_to(name, options = {}, &block)
+        unless options.has_key?(:inverse_of)
+          raise Errors::InvalidOptions.new("Options for belongs_to association must include :inverse_of")
+        end
+        self.embedded = true
+        add_association(
+          Associations::BelongsTo,
+          Associations::Options.new(
+            options.merge(:name => name, :extend => block)
+          )
+        )
+      end
+
+      # Adds a relational association from the child Document to a Document in
+      # another database or collection.
+      #
+      # Options:
+      #
+      # name: A +Symbol+ that is the related class name.
+      #
+      # Example:
+      #
+      #   class Game
+      #     include Humanoid::Document
+      #     belongs_to_related :person
+      #   end
+      #
+      def belongs_to_related(name, options = {}, &block)
+        field "#{name.to_s}_id"
+        index "#{name.to_s}_id" unless self.embedded
+        add_association(
+          Associations::BelongsToRelated,
+          Associations::Options.new(
+            options.merge(:name => name, :extend => block)
+          )
+        )
+      end
+
+      # Adds the association from a parent document to its children. The name
+      # of the association needs to be a pluralized form of the child class
+      # name.
+      #
+      # Options:
+      #
+      # name: A +Symbol+ that is the plural child class name.
+      #
+      # Example:
+      #
+      #   class Person
+      #     include Humanoid::Document
+      #     has_many :addresses
+      #   end
+      #
+      #   class Address
+      #     include Humanoid::Document
+      #     belongs_to :person, :inverse_of => :addresses
+      #   end
+      def has_many(name, options = {}, &block)
+        add_association(
+          Associations::HasMany,
+          Associations::Options.new(
+            options.merge(:name => name, :extend => block)
+          )
+        )
+      end
+
+      # Adds a relational association from the Document to many Documents in
+      # another database or collection.
+      #
+      # Options:
+      #
+      # name: A +Symbol+ that is the related class name pluralized.
+      #
+      # Example:
+      #
+      #   class Person
+      #     include Humanoid::Document
+      #     has_many_related :posts
+      #   end
+      #
+      def has_many_related(name, options = {}, &block)
+        add_association(
+          Associations::HasManyRelated,
+          Associations::Options.new(
+            options.merge(:name => name, :parent_key => self.name.foreign_key, :extend => block)
+          )
+        )
+        before_save do |document|
+          document.update_associations(name)
+        end
+      end
+
+      # Adds the association from a parent document to its child. The name
+      # of the association needs to be a singular form of the child class
+      # name.
+      #
+      # Options:
+      #
+      # name: A +Symbol+ that is the plural child class name.
+      #
+      # Example:
+      #
+      #   class Person
+      #     include Humanoid::Document
+      #     has_many :addresses
+      #   end
+      #
+      #   class Address
+      #     include Humanoid::Document
+      #     belongs_to :person
+      #   end
+      def has_one(name, options = {}, &block)
+        opts = Associations::Options.new(
+          options.merge(:name => name, :extend => block)
+        )
+        type = Associations::HasOne
+        add_association(type, opts)
+        add_builder(type, opts)
+        add_creator(type, opts)
+      end
+
+      # Adds a relational association from the Document to one Document in
+      # another database or collection.
+      #
+      # Options:
+      #
+      # name: A +Symbol+ that is the related class name pluralized.
+      #
+      # Example:
+      #
+      #   class Person
+      #     include Humanoid::Document
+      #     has_one_related :game
+      #   end
+      def has_one_related(name, options = {}, &block)
+        add_association(
+          Associations::HasOneRelated,
+          Associations::Options.new(
+            options.merge(:name => name, :parent_key => self.name.foreign_key, :extend => block)
+          )
+        )
+        before_save do |document|
+          document.update_association(name)
+        end
+      end
+
+      # Returns the macro associated with the supplied association name. This
+      # will return has_one, has_many, belongs_to or nil.
+      #
+      # Options:
+      #
+      # name: The association name.
+      #
+      # Example:
+      #
+      # <tt>Person.reflect_on_association(:addresses)</tt>
+      def reflect_on_association(name)
+        association = associations[name.to_s]
+        association ? association.macro : nil
+      end
+
+      protected
+      # Adds the association to the associations hash with the type as the key,
+      # then adds the accessors for the association. The defined setters and
+      # getters for the associations will perform the necessary memoization.
+      def add_association(type, options)
+        name = options.name.to_s
+        associations[name] = type
+        define_method(name) do
+          memoized(name) { type.instantiate(self, options) }
+        end
+        define_method("#{name}=") do |object|
+          reset(name) { type.update(object, self, options) }
+        end
+      end
+
+      # Adds a builder for a has_one association. This comes in the form of
+      # build_name(attributes)
+      def add_builder(type, options)
+        name = options.name.to_s
+        define_method("build_#{name}") do |attrs|
+          reset(name) { type.new(self, (attrs || {}).stringify_keys, options) }
+        end
+      end
+
+      # Adds a creator for a has_one association. This comes in the form of
+      # create_name(attributes)
+      def add_creator(type, options)
+        name = options.name.to_s
+        define_method("create_#{name}") do |attrs|
+          document = send("build_#{name}", attrs)
+          document.save; document
+        end
+      end
+    end
+  end
+end

data/lib/humanoid/associations/belongs_to.rb

@@ -0,0 +1,64 @@
+# encoding: utf-8
+module Humanoid #:nodoc:
+  module Associations #:nodoc:
+    class BelongsTo #:nodoc:
+      include Proxy
+
+      # Creates the new association by setting the internal
+      # target as the passed in Document. This should be the
+      # parent.
+      #
+      # All method calls on this object will then be delegated
+      # to the internal document itself.
+      #
+      # Options:
+      #
+      # target: The parent +Document+
+      # options: The association options
+      def initialize(target, options)
+        @target, @options = target, options
+        extends(options)
+      end
+
+      # Returns the parent document. The id param is present for
+      # compatibility with rails, however this could be overwritten
+      # in the future.
+      def find(id)
+        @target
+      end
+
+      class << self
+        # Creates the new association by setting the internal
+        # document as the passed in Document. This should be the
+        # parent.
+        #
+        # Options:
+        #
+        # document: The parent +Document+
+        # options: The association options
+        def instantiate(document, options)
+          target = document._parent
+          target.nil? ? nil : new(target, options)
+        end
+
+        # Returns the macro used to create the association.
+        def macro
+          :belongs_to
+        end
+
+        # Perform an update of the relationship of the parent and child. This
+        # is initialized by setting a parent object as the association on the
+        # +Document+. Will properly set a has_one or a has_many.
+        #
+        # Returns:
+        #
+        # A new +BelongsTo+ association proxy.
+        def update(target, child, options)
+          child.parentize(target, options.inverse_of)
+          child.notify
+          instantiate(child, options)
+        end
+      end
+    end
+  end
+end

data/lib/humanoid/associations/belongs_to_related.rb

@@ -0,0 +1,62 @@
+# encoding: utf-8
+module Humanoid #:nodoc:
+  module Associations #:nodoc:
+    class BelongsToRelated #:nodoc:
+      include Proxy
+
+      # Initializing a related association only requires looking up the object
+      # by its id.
+      #
+      # Options:
+      #
+      # document: The +Document+ that contains the relationship.
+      # options: The association +Options+.
+      def initialize(document, foreign_key, options, target = nil)
+        @options = options
+        @target = target || options.klass.find(foreign_key)
+        extends(options)
+      end
+
+      class << self
+        # Instantiate a new +BelongsToRelated+ or return nil if the foreign key is
+        # nil. It is preferrable to use this method over the traditional call
+        # to new.
+        #
+        # Options:
+        #
+        # document: The +Document+ that contains the relationship.
+        # options: The association +Options+.
+        def instantiate(document, options, target = nil)
+          foreign_key = document.send(options.foreign_key)
+          foreign_key.blank? ? nil : new(document, foreign_key, options, target)
+        end
+
+        # Returns the macro used to create the association.
+        def macro
+          :belongs_to_related
+        end
+
+        # Perform an update of the relationship of the parent and child. This
+        # will assimilate the child +Document+ into the parent's object graph.
+        #
+        # Options:
+        #
+        # related: The related object
+        # parent: The parent +Document+ to update.
+        # options: The association +Options+
+        #
+        # Example:
+        #
+        # <tt>BelongsToRelated.update(game, person, options)</tt>
+        def update(target, parent, options)
+          if target
+            parent.send("#{options.foreign_key}=", target.id)
+            return instantiate(parent, options, target)
+          end
+          target
+        end
+      end
+
+    end
+  end
+end

data/lib/humanoid/associations/has_many.rb

@@ -0,0 +1,180 @@
+# encoding: utf-8
+module Humanoid #:nodoc:
+  module Associations #:nodoc:
+    class HasMany
+      include Proxy
+
+      attr_accessor :association_name, :klass
+
+      # Appends the object to the +Array+, setting its parent in
+      # the process.
+      def <<(*objects)
+        objects.flatten.each do |object|
+          object.parentize(@parent, @association_name)
+          @target << object
+          object.notify
+        end
+      end
+
+      alias :concat :<<
+      alias :push :<<
+
+      # Clears the association, and notifies the parents of the removal.
+      def clear
+        unless @target.empty?
+          object = @target.first
+          object.changed(true)
+          object.notify_observers(object, true)
+          @target.clear
+        end
+      end
+
+      # Builds 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.
+      #
+      # Returns:
+      #
+      # The newly created Document.
+      def build(attrs = {}, type = nil)
+        object = type ? type.instantiate : @klass.instantiate
+        object.parentize(@parent, @association_name)
+        object.write_attributes(attrs)
+        @target << object
+        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:
+      #
+      # Rhe newly created Document.
+      def create(attrs = {}, type = nil)
+        object = build(attrs, type)
+        object.save
+        object
+      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.
+      #
+      # Returns:
+      #
+      # Array or single Document.
+      def find(param)
+        return @target if param == :all
+        return detect { |document| document.id == param }
+      end
+
+      # Creates the new association by finding the attributes in
+      # the parent document with its name, and instantiating a
+      # new document for each one found. These will then be put in an
+      # internal array.
+      #
+      # This then delegated all methods to the array class since this is
+      # essentially a proxy to an array itself.
+      #
+      # Options:
+      #
+      # parent: The parent document to the association.
+      # options: The association options.
+      def initialize(parent, options)
+        @parent, @association_name = parent, options.name
+        @klass, @options = options.klass, options
+        initialize_each(parent.raw_attributes[@association_name])
+        extends(options)
+      end
+
+      # If the target array does not respond to the supplied method then try to
+      # find a named scope or criteria on the class and send the call there.
+      #
+      # If the method exists on the array, use the default proxy behavior.
+      def method_missing(name, *args, &block)
+        unless @target.respond_to?(name)
+          object = @klass.send(name, *args)
+          object.documents = @target
+          return object
+        end
+        super
+      end
+
+      # Used for setting associations via a nested attributes setter from the
+      # parent +Document+.
+      #
+      # Options:
+      #
+      # attributes: A +Hash+ of integer keys and +Hash+ values.
+      #
+      # Returns:
+      #
+      # The newly build target Document.
+      def nested_build(attributes)
+        attributes.values.each do |attrs|
+          build(attrs)
+        end
+      end
+
+      # Paginate the association. Will create a new criteria, set the documents
+      # on it and execute in an enumerable context.
+      #
+      # Options:
+      #
+      # options: A +Hash+ of pagination options.
+      #
+      # Returns:
+      #
+      # A +WillPaginate::Collection+.
+      def paginate(options)
+        criteria = Humanoid::Criteria.translate(@klass, options)
+        criteria.documents = @target
+        criteria.paginate
+      end
+
+      protected
+      # Initializes each of the attributes in the hash.
+      def initialize_each(attributes)
+        @target = attributes ? attributes.collect do |attrs|
+          klass = attrs.klass
+          child = klass ? klass.instantiate(attrs) : @klass.instantiate(attrs)
+          child.parentize(@parent, @association_name)
+          child
+        end : []
+      end
+
+      class << self
+
+        # Preferred method of creating a new +HasMany+ association. It will
+        # delegate to new.
+        #
+        # Options:
+        #
+        # document: The parent +Document+
+        # options: The association options
+        def instantiate(document, options)
+          new(document, options)
+        end
+
+        # Returns the macro used to create the association.
+        def macro
+          :has_many
+        end
+
+        # Perform an update of the relationship of the parent and child. This
+        # is initialized by setting the has_many to the supplied +Enumerable+
+        # and setting up the parentization.
+        def update(children, parent, options)
+          parent.remove_attribute(options.name)
+          children.assimilate(parent, options)
+          instantiate(parent, options)
+        end
+      end
+
+    end
+  end
+end