mongoid-rails2 1.9.3

data/lib/mongoid/deprecation.rb

@@ -0,0 +1,22 @@
+# encoding: utf-8
+module Mongoid #:nodoc:
+  class Deprecation #:nodoc
+    include Singleton
+
+    # Alert of a deprecation. This will delegate to the logger and call warn on
+    # it.
+    #
+    # Example:
+    #
+    # <tt>deprecation.alert("Method no longer used")</tt>
+    def alert(message)
+      @logger.warn("Deprecation: #{message}")
+    end
+
+    protected
+    # Instantiate a new logger to stdout or a rails logger if available.
+    def initialize
+      @logger = defined?(Rails) ? Rails.logger : Logger.new($stdout)
+    end
+  end
+end

data/lib/mongoid/dirty.rb

@@ -0,0 +1,253 @@
+# encoding: utf-8
+module Mongoid #:nodoc:
+  module Dirty #:nodoc:
+    extend ActiveSupport::Concern
+    module InstanceMethods #:nodoc:
+      # Gets the changes for a specific field.
+      #
+      # Example:
+      #
+      #   person = Person.new(:title => "Sir")
+      #   person.title = "Madam"
+      #   person.attribute_change("title") # [ "Sir", "Madam" ]
+      #
+      # Returns:
+      #
+      # An +Array+ containing the old and new values.
+      def attribute_change(name)
+        modifications[name]
+      end
+
+      # Determines if a specific field has chaged.
+      #
+      # Example:
+      #
+      #   person = Person.new(:title => "Sir")
+      #   person.title = "Madam"
+      #   person.attribute_changed?("title") # true
+      #
+      # Returns:
+      #
+      # +true+ if changed, +false+ if not.
+      def attribute_changed?(name)
+        modifications.include?(name)
+      end
+
+      # Gets the old value for a specific field.
+      #
+      # Example:
+      #
+      #   person = Person.new(:title => "Sir")
+      #   person.title = "Madam"
+      #   person.attribute_was("title") # "Sir"
+      #
+      # Returns:
+      #
+      # The old field value.
+      def attribute_was(name)
+        change = modifications[name]
+        change ? change[0] : nil
+      end
+
+      # Gets the names of all the fields that have changed in the document.
+      #
+      # Example:
+      #
+      #   person = Person.new(:title => "Sir")
+      #   person.title = "Madam"
+      #   person.changed # returns [ "title" ]
+      #
+      # Returns:
+      #
+      # An +Array+ of changed field names.
+      def changed
+        modifications.keys
+      end
+
+      # Alerts to whether the document has been modified or not.
+      #
+      # Example:
+      #
+      #   person = Person.new(:title => "Sir")
+      #   person.title = "Madam"
+      #   person.changed? # returns true
+      #
+      # Returns:
+      #
+      # +true+ if changed, +false+ if not.
+      def changed?
+        !modifications.empty?
+      end
+
+      # Gets all the modifications that have happened to the object as a +Hash+
+      # with the keys being the names of the fields, and the values being an
+      # +Array+ with the old value and new value.
+      #
+      # Example:
+      #
+      #   person = Person.new(:title => "Sir")
+      #   person.title = "Madam"
+      #   person.changes # returns { "title" => [ "Sir", "Madam" ] }
+      #
+      # Returns:
+      #
+      # A +Hash+ of changes.
+      def changes
+        modifications
+      end
+
+      # Call this method after save, so the changes can be properly switched.
+      #
+      # Example:
+      #
+      # <tt>person.move_changes</tt>
+      def move_changes
+        @previous_modifications = modifications.dup
+        @modifications = {}
+      end
+
+      # Gets all the new values for each of the changed fields, to be passed to
+      # a MongoDB $set modifier.
+      #
+      # Example:
+      #
+      #   person = Person.new(:title => "Sir")
+      #   person.title = "Madam"
+      #   person.setters # returns { "title" => "Madam" }
+      #
+      # Returns:
+      #
+      # A +Hash+ of new values.
+      def setters
+        modifications.inject({}) do |sets, (field, changes)|
+          key = embedded? ? "#{_position}.#{field}" : field
+          sets[key] = changes[1]; sets
+        end
+      end
+
+      # Gets all the modifications that have happened to the object before the
+      # object was saved.
+      #
+      # Example:
+      #
+      #   person = Person.new(:title => "Sir")
+      #   person.title = "Madam"
+      #   person.save!
+      #   person.previous_changes # returns { "title" => [ "Sir", "Madam" ] }
+      #
+      # Returns:
+      #
+      # A +Hash+ of changes before save.
+      def previous_changes
+        @previous_modifications
+      end
+
+      # Resets a changed field back to its old value.
+      #
+      # Example:
+      #
+      #   person = Person.new(:title => "Sir")
+      #   person.title = "Madam"
+      #   person.reset_attribute!("title")
+      #   person.title # "Sir"
+      #
+      # Returns:
+      #
+      # The old field value.
+      def reset_attribute!(name)
+        value = attribute_was(name)
+        if value
+          @attributes[name] = value
+          modifications.delete(name)
+        end
+      end
+
+      # Sets up the modifications hash. This occurs just after the document is
+      # instantiated.
+      #
+      # Example:
+      #
+      # <tt>document.setup_notifications</tt>
+      def setup_modifications
+        @accessed ||= {}
+        @modifications ||= {}
+        @previous_modifications ||= {}
+      end
+
+      # Reset all modifications for the document. This will wipe all the marked
+      # changes, but not reset the values.
+      #
+      # Example:
+      #
+      # <tt>document.reset_modifications</tt>
+      def reset_modifications
+        @accessed = {}
+        @modifications = {}
+      end
+
+      protected
+
+      # Audit the original value for a field that can be modified in place.
+      #
+      # Example:
+      #
+      # <tt>person.accessed("aliases", [ "007" ])</tt>
+      def accessed(name, value)
+        @accessed ||= {}
+        @accessed[name] = value.dup if (value.is_a?(Array) || value.is_a?(Hash)) && !@accessed.has_key?(name)
+        value
+      end
+
+      # Get all normal modifications plus in place potential changes.
+      #
+      # Example:
+      #
+      # <tt>person.modifications</tt>
+      #
+      # Returns:
+      #
+      # All changes to the document.
+      def modifications
+        @accessed.each_pair do |field, value|
+          current = @attributes[field]
+          @modifications[field] = [ value, current ] if current != value
+        end
+        @accessed.clear
+        @modifications
+      end
+
+      # Audit the change of a field's value.
+      #
+      # Example:
+      #
+      # <tt>person.modify("name", "Jack", "John")</tt>
+      def modify(name, old_value, new_value)
+        @attributes[name] = new_value
+        if @modifications && (old_value != new_value)
+          original = @modifications[name].first if @modifications[name]
+          @modifications[name] = [ (original || old_value), new_value ]
+        end
+      end
+    end
+
+    module ClassMethods #:nodoc:
+      # Add the dynamic dirty methods. These are custom methods defined on a
+      # field by field basis that wrap the dirty attribute methods.
+      #
+      # Example:
+      #
+      #   person = Person.new(:title => "Sir")
+      #   person.title = "Madam"
+      #   person.title_change # [ "Sir", "Madam" ]
+      #   person.title_changed? # true
+      #   person.title_was # "Sir"
+      #   person.reset_title!
+      def add_dirty_methods(name)
+        define_method("#{name}_change") { attribute_change(name) }
+        define_method("#{name}_changed?") { attribute_changed?(name) }
+        define_method("#{name}_was") { attribute_was(name) }
+        define_method("reset_#{name}!") { reset_attribute!(name) }
+      end
+    end
+  end
+end

data/lib/mongoid/document.rb

@@ -0,0 +1,311 @@
+# encoding: utf-8
+module Mongoid #:nodoc:
+  module Document
+    extend ActiveSupport::Concern
+    include Mongoid::Components
+    included do
+      include Mongoid::Components
+
+      cattr_accessor :primary_key, :hereditary
+      self.hereditary = false
+
+      attr_accessor :association_name, :_parent
+
+      delegate :db, :primary_key, :to => "self.class"
+    end
+
+    module ClassMethods
+      # Return the database associated with this class.
+      def db
+        collection.db
+      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)
+          document.setup_modifications
+          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 Mongoid::Document
+      #     key :first_name, :last_name
+      #   end
+      def key(*fields)
+        self.primary_key = fields
+        before_save :identify
+      end
+
+      # Returns all types to query for when using this class as the base.
+      def _types
+        @_type ||= (self.subclasses + [ self.name ])
+      end
+
+      # return the list of subclassses for an object
+      def subclasses_of(*superclasses) #:nodoc:
+        subclasses = []
+        superclasses.each do |sup|
+          ObjectSpace.each_object(class << sup; self; end) do |k|
+            if k != sup && (k.name.blank? || eval("defined?(::#{k}) && ::#{k}.object_id == k.object_id"))
+              subclasses << k
+            end
+          end
+        end
+        subclasses
+      end
+    end
+
+    module InstanceMethods
+      # Performs equality checking on the document ids. For more robust
+      # equality checking please override this method.
+      def ==(other)
+        return false unless other.is_a?(Document)
+        id == other.id
+      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
+
+      # Is inheritance in play here?
+      #
+      # Returns:
+      #
+      # <tt>true</tt> if inheritance used, <tt>false</tt> if not.
+      def hereditary?
+        !!self.hereditary
+      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.
+      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 +BSON::ObjectId+ string.
+      #
+      # Options:
+      #
+      # attrs: The attributes +Hash+ to set up the document with.
+      def initialize(attrs = nil)
+        @attributes = default_attributes
+        process(attrs)
+        @new_record = true
+        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}" }
+        if Mongoid.allow_dynamic_fields
+          dynamic_keys = @attributes.keys - fields.keys - associations.keys - ["_id", "_type"]
+          attrs += dynamic_keys.map { |name| "#{name}: #{@attributes[name].inspect}" }
+        end
+        "#<#{self.class.name} _id: #{id}, #{attrs * ', '}>"
+      end
+
+      # Notify observers of an update.
+      #
+      # Example:
+      #
+      # <tt>person.notify</tt>
+      def notify
+        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
+        reloaded = collection.find_one(:_id => id)
+        if Mongoid.raise_not_found_error
+          raise Errors::DocumentNotFound.new(self.class, id) if reloaded.nil?
+        end
+        @attributes = {}.merge(reloaded || {})
+        self.associations.keys.each { |association_name| unmemoize(association_name) }; 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 Mongoid 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
+
+      # Return an object to be encoded into a JSON string.
+      # Used by Rails 3's object->JSON chain to create JSON
+      # in a backend-agnostic way
+      #
+      # Example:
+      #
+      # <tt>person.as_json</tt>
+      def as_json(options = nil)
+        attributes
+      end
+
+      # Return this document as an object to be encoded as JSON,
+      # with any particular items modified on a per-encoder basis.
+      # Nothing special is required here since Mongoid bubbles up
+      # all the child associations to the parent attribute +Hash+
+      # using observers throughout the +Document+ lifecycle.
+      #
+      # Example:
+      #
+      # <tt>person.encode_json(encoder)</tt>
+      def encode_json(encoder)
+        attributes
+      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 observe(child, clear = false)
+        name = child.association_name
+        attrs = child.instance_variable_get(:@attributes)
+        if clear
+          @attributes.delete(name)
+        else
+          @attributes.insert(name, attrs) unless @attributes[name] && @attributes[name].include?(attrs)
+        end
+        notify
+      end
+
+      protected
+      # apply default values to attributes - calling procs as required
+      def attributes_with_defaults(attributes = {})
+        default_values = defaults
+        default_values.each_pair do |key, val|
+          default_values[key] = val.call if val.respond_to?(:call)
+        end
+        default_values.merge(attributes)
+      end
+    end
+  end
+end

data/lib/mongoid/errors.rb

@@ -0,0 +1,108 @@
+# encoding: utf-8
+module Mongoid #:nodoc
+  module Errors #:nodoc
+
+    # Raised when querying the database for a document by a specific id which
+    # does not exist. If multiple ids were passed then it will display all of
+    # those.
+    #
+    # Example:
+    #
+    # <tt>DocumentNotFound.new(Person, ["1", "2"])</tt>
+    class DocumentNotFound < RuntimeError
+      def initialize(klass, ids)
+        @klass, @identifier = klass, ids.is_a?(Array) ? ids.join(", ") : ids
+      end
+      def message
+        "Document not found for class #{@klass} and id(s) #{@identifier}"
+      end
+    end
+
+    # Raised when invalid options are passed into a constructor or method.
+    #
+    # Example:
+    #
+    # <tt>InvalidOptions.new</tt>
+    class InvalidOptions < RuntimeError; end
+
+    # Raised when the database connection has not been set up properly, either
+    # by attempting to set an object on the db that is not a +Mongo::DB+, or
+    # not setting anything at all.
+    #
+    # Example:
+    #
+    # <tt>InvalidDatabase.new("Not a DB")</tt>
+    class InvalidDatabase < RuntimeError
+      def initialize(database)
+        @database = database
+      end
+      def message
+        "Database should be a Mongo::DB, not #{@database.class.name}"
+      end
+    end
+
+    # Raised when the database version is not supported by Mongoid.
+    #
+    # Example:
+    #
+    # <tt>UnsupportedVersion.new(Mongo::ServerVersion.new("1.3.1"))</tt>
+    class UnsupportedVersion < RuntimeError
+      def initialize(version)
+        @version = version
+      end
+      def message
+        "MongoDB #{@version} not supported, please upgrade to #{Mongoid::MONGODB_VERSION}"
+      end
+    end
+
+    # Raised when a persisence method ending in ! fails validation. The message
+    # will contain the full error messages from the +Document+ in question.
+    #
+    # Example:
+    #
+    # <tt>Validations.new(person.errors)</tt>
+    class Validations < RuntimeError
+      def initialize(errors)
+        @errors = errors
+      end
+      def message
+        "Validation Failed: #{@errors.full_messages.join(", ")}"
+      end
+    end
+
+    # This error is raised when trying to access a Mongo::Collection from an
+    # embedded document.
+    #
+    # Example:
+    #
+    # <tt>InvalidCollection.new(Address)</tt>
+    class InvalidCollection < RuntimeError
+      def initialize(klass)
+        @klass = klass
+      end
+      def message
+        "Access to the collection for #{@klass.name} is not allowed " +
+          "since it is an embedded document, please access a collection from " +
+          "the root document"
+      end
+    end
+
+    # This error is raised when trying to create a field that conflicts with
+    # a Mongoid internal attribute or method.
+    #
+    # Example:
+    #
+    # <tt>InvalidField.new('collection')</tt>
+    class InvalidField < RuntimeError
+      def initialize(name)
+        @name = name
+      end
+      def message
+        "Defining a field named '#{@name}' is not allowed. " +
+          "Do not define fields that conflict with Mongoid internal attributes " +
+          "or method names. Use Document#instance_methods to see what " +
+          "names this includes."
+      end
+    end
+  end
+end

data/lib/mongoid/extensions/array/accessors.rb

@@ -0,0 +1,17 @@
+# encoding: utf-8
+module Mongoid #:nodoc:
+  module Extensions #:nodoc:
+    module Array #:nodoc:
+      module Accessors #:nodoc:
+        # If the attributes already exists in the array then they will be
+        # updated, otherwise they will be appended.
+        def update(attributes)
+          delete_if { |e| attributes["_id"] && (e["_id"] == attributes["_id"]) }
+          self.<< attributes
+        end
+
+        alias :merge! :update
+      end
+    end
+  end
+end