mongoid-locomotive 2.0.0.beta9

data/lib/mongoid/criterion/optional.rb

@@ -0,0 +1,189 @@
+# encoding: utf-8
+module Mongoid #:nodoc:
+  module Criterion #:nodoc:
+    module Optional
+
+      # Adds fields to be sorted in ascending order. Will add them in the order
+      # they were passed into the method.
+      #
+      # Example:
+      #
+      # <tt>criteria.ascending(:title, :dob)</tt>
+      def ascending(*fields)
+        @options[:sort] = [] unless @options[:sort] || fields.first.nil?
+        fields.flatten.each { |field| @options[:sort] << [ field, :asc ] }
+        self
+      end
+
+      alias :asc :ascending
+
+      # 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?
+        @options[:cache] == true
+      end
+
+      # Adds fields to be sorted in descending order. Will add them in the order
+      # they were passed into the method.
+      #
+      # Example:
+      #
+      # <tt>criteria.descending(:title, :dob)</tt>
+      def descending(*fields)
+        @options[:sort] = [] unless @options[:sort] || fields.first.nil?
+        fields.flatten.each { |field| @options[:sort] << [ field, :desc ] }
+        self
+      end
+
+      alias :desc :descending
+
+      # 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
+
+      # Will return true if the criteria is enslaved.
+      #
+      # Example:
+      #
+      # <tt>criteria.enslaved?</tt>
+      def enslaved?
+        @options[:enslave] == true
+      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>BSON::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(*args)
+        @options[:sort] = [] unless @options[:sort] || args.first.nil?
+        arguments = args.first
+        case arguments
+        when Hash then arguments.each { |field, direction| @options[:sort] << [ field, direction ] }
+        when Array then @options[:sort].concat(arguments)
+        when Complex
+          args.flatten.each { |complex| @options[:sort] << [ complex.key, complex.operator.to_sym ] }
+        end; 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
+
+      # Adds a criterion to the +Criteria+ that specifies a type or an Array of type that must be matched.
+      #
+      # Options:
+      #
+      # types : An +Array+ of types of a +String+ representing the Type of you search
+      #
+      # Example:
+      #
+      # <tt>criteria.type('Browser')</tt>
+      # <tt>criteria.type(['Firefox', 'Browser'])</tt>
+      #
+      # Returns: <tt>self</tt>
+      def type(types)
+        types = [types] unless types.is_a?(Array)
+        self.in(:_type => types)
+      end
+    end
+  end
+end

data/lib/mongoid/cursor.rb

@@ -0,0 +1,81 @@
+# encoding: utf-8
+module Mongoid #:nodoc
+  class Cursor
+    include Enumerable
+    # Operations on the Mongo::Cursor object that will not get overriden by the
+    # Mongoid::Cursor are defined here.
+    OPERATIONS = [
+      :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 Mongoid::Factory.build(@klass, document)
+      end
+    end
+
+    # Create the new +Mongoid::Cursor+.
+    #
+    # Options:
+    #
+    # collection: The Mongoid::Collection instance.
+    # cursor: The Mongo::Cursor to be proxied.
+    #
+    # Example:
+    #
+    # <tt>Mongoid::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 Mongoid
+    # document with the attributes.
+    #
+    # Example:
+    #
+    # <tt>cursor.next_document</tt>
+    def next_document
+      Mongoid::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| Mongoid::Factory.build(@klass, attrs) }
+    end
+  end
+end

data/lib/mongoid/deprecation.rb

@@ -0,0 +1,21 @@
+# 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
+    def initialize
+      @logger = Mongoid::Logger.new
+    end
+  end
+end

data/lib/mongoid/dirty.rb

@@ -0,0 +1,252 @@
+# encoding: utf-8
+module Mongoid #:nodoc:
+  module Dirty #:nodoc:
+    extend ActiveSupport::Concern
+
+    # 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
+
+    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) } unless instance_methods.include?("#{name}_change")
+        define_method("#{name}_changed?") { attribute_changed?(name) } unless instance_methods.include?("#{name}_changed?")
+        define_method("#{name}_was") { attribute_was(name) } unless instance_methods.include?("#{name}_was")
+        define_method("reset_#{name}!") { reset_attribute!(name) } unless instance_methods.include?("reset_#{name}!")
+      end
+    end
+  end
+end