mongo_doc 0.3.0

data/lib/mongoid/criteria.rb

@@ -0,0 +1,247 @@
+# encoding: utf-8
+require "mongoid/criterion/complex"
+require "mongoid/criterion/exclusion"
+require "mongoid/criterion/inclusion"
+require "mongoid/criterion/optional"
+
+module Mongoid #:nodoc:
+  # The +Criteria+ class is the core object needed in Mongoid to retrieve
+  # objects from the database. It is a DSL that essentially sets up the
+  # selector and options arguments that get passed on to a <tt>Mongo::Collection</tt>
+  # in the Ruby driver. Each method on the +Criteria+ returns self to they
+  # can be chained in order to create a readable criterion to be executed
+  # against the database.
+  #
+  # Example setup:
+  #
+  # <tt>criteria = Criteria.new</tt>
+  #
+  # <tt>criteria.only(:field).where(:field => "value").skip(20).limit(20)</tt>
+  #
+  # <tt>criteria.execute</tt>
+  class Criteria
+    include Criterion::Exclusion
+    include Criterion::Inclusion
+    include Criterion::Optional
+    include Enumerable
+
+    attr_reader :collection, :ids, :klass, :options, :selector
+
+    attr_accessor :documents
+
+    delegate \
+      :aggregate,
+      :count,
+      :execute,
+      :first,
+      :group,
+      :id_criteria,
+      :last,
+      :max,
+      :min,
+      :one,
+      :page,
+      :paginate,
+      :per_page,
+      :sum, :to => :context
+
+    # Concatinate the criteria with another enumerable. If the other is a
+    # +Criteria+ then it needs to get the collection from it.
+    def +(other)
+      entries + comparable(other)
+    end
+
+    # Returns the difference between the criteria and another enumerable. If
+    # the other is a +Criteria+ then it needs to get the collection from it.
+    def -(other)
+      entries - comparable(other)
+    end
+
+    # Returns true if the supplied +Enumerable+ or +Criteria+ is equal to the results
+    # of this +Criteria+ or the criteria itself.
+    #
+    # This will force a database load when called if an enumerable is passed.
+    #
+    # Options:
+    #
+    # other: The other +Enumerable+ or +Criteria+ to compare to.
+    def ==(other)
+      case other
+      when Criteria
+        self.selector == other.selector && self.options == other.options
+      when Enumerable
+        return (execute.entries == other)
+      else
+        return false
+      end
+    end
+
+    # Returns true if the criteria is empty.
+    #
+    # Example:
+    #
+    # <tt>criteria.blank?</tt>
+    def blank?
+      count < 1
+    end
+
+    alias :empty? :blank?
+
+    # Return or create the context in which this criteria should be executed.
+    #
+    # This will return an Enumerable context if the class is embedded,
+    # otherwise it will return a Mongo context for root classes.
+    def context
+      @context ||= Contexts.context_for(self)
+    end
+
+    # Iterate over each +Document+ in the results. This can take an optional
+    # block to pass to each argument in the results.
+    #
+    # Example:
+    #
+    # <tt>criteria.each { |doc| p doc }</tt>
+    def each(&block)
+      context.iterate(&block)
+      self
+    end
+
+    # Merges the supplied argument hash into a single criteria
+    #
+    # Options:
+    #
+    # criteria_conditions: Hash of criteria keys, and parameter values
+    #
+    # Example:
+    #
+    # <tt>criteria.fuse(:where => { :field => "value"}, :limit => 20)</tt>
+    #
+    # Returns <tt>self</tt>
+    def fuse(criteria_conditions = {})
+      criteria_conditions.inject(self) do |criteria, (key, value)|
+        criteria.send(key, value)
+      end
+    end
+
+    # Create the new +Criteria+ object. This will initialize the selector
+    # and options hashes, as well as the type of criteria.
+    #
+    # Options:
+    #
+    # type: One of :all, :first:, or :last
+    # klass: The class to execute on.
+    def initialize(klass)
+      @selector, @options, @klass, @documents = {}, {}, klass, []
+    end
+
+    # Merges another object into this +Criteria+. The other object may be a
+    # +Criteria+ or a +Hash+. This is used to combine multiple scopes together,
+    # where a chained scope situation may be desired.
+    #
+    # Options:
+    #
+    # other: The +Criteria+ or +Hash+ to merge with.
+    #
+    # Example:
+    #
+    # <tt>criteria.merge({ :conditions => { :title => "Sir" } })</tt>
+    def merge(other)
+      @selector.update(other.selector)
+      @options.update(other.options)
+      @documents = other.documents
+    end
+
+    # Used for chaining +Criteria+ scopes together in the for of class methods
+    # on the +Document+ the criteria is for.
+    #
+    # Options:
+    #
+    # name: The name of the class method on the +Document+ to chain.
+    # args: The arguments passed to the method.
+    #
+    # Returns: <tt>Criteria</tt>
+    def method_missing(name, *args)
+      if @klass.respond_to?(name)
+        new_scope = @klass.send(name, *args)
+        new_scope.merge(self)
+        return new_scope
+      else
+        return entries.send(name, *args)
+      end
+    end
+
+    alias :to_ary :to_a
+
+    # Returns the selector and options as a +Hash+ that would be passed to a
+    # scope for use with named scopes.
+    def scoped
+      { :where => @selector }.merge(@options)
+    end
+
+    # Translate the supplied arguments into a +Criteria+ object.
+    #
+    # If the passed in args is a single +String+, then it will
+    # construct an id +Criteria+ from it.
+    #
+    # If the passed in args are a type and a hash, then it will construct
+    # the +Criteria+ with the proper selector, options, and type.
+    #
+    # Options:
+    #
+    # args: either a +String+ or a +Symbol+, +Hash combination.
+    #
+    # Example:
+    #
+    # <tt>Criteria.translate(Person, "4ab2bc4b8ad548971900005c")</tt>
+    # <tt>Criteria.translate(Person, :conditions => { :field => "value"}, :limit => 20)</tt>
+    def self.translate(*args)
+      klass = args[0]
+      params = args[1] || {}
+      unless params.is_a?(Hash)
+        return new(klass).id_criteria(params)
+      end
+      conditions = params.delete(:conditions) || {}
+      if conditions.include?(:id)
+        conditions[:_id] = conditions[:id]
+        conditions.delete(:id)
+      end
+      return new(klass).where(conditions).extras(params)
+    end
+
+    protected
+
+    # Filters the unused options out of the options +Hash+. Currently this
+    # takes into account the "page" and "per_page" options that would be passed
+    # in if using will_paginate.
+    #
+    # Example:
+    #
+    # Given a criteria with a selector of { :page => 1, :per_page => 40 }
+    #
+    # <tt>criteria.filter_options</tt> # selector: { :skip => 0, :limit => 40 }
+    def filter_options
+      page_num = @options.delete(:page)
+      per_page_num = @options.delete(:per_page)
+      if (page_num || per_page_num)
+        @options[:limit] = limits = (per_page_num || 20).to_i
+        @options[:skip] = (page_num || 1).to_i * limits - limits
+      end
+    end
+
+    # Return the entries of the other criteria or the object. Used for
+    # comparing criteria or an enumerable.
+    def comparable(other)
+      other.is_a?(Criteria) ? other.entries : other
+    end
+
+    # Update the selector setting the operator on the value for each key in the
+    # supplied attributes +Hash+.
+    #
+    # Example:
+    #
+    # <tt>criteria.update_selector({ :field => "value" }, "$in")</tt>
+    def update_selector(attributes, operator)
+      attributes.each { |key, value| @selector[key] = { operator => value } }; self
+    end
+  end
+end

data/lib/mongoid/criterion/complex.rb

@@ -0,0 +1,21 @@
+# encoding: utf-8
+module Mongoid #:nodoc:
+  module Criterion #:nodoc:
+    # Complex criterion are used when performing operations on symbols to get
+    # get a shorthand syntax for where clauses.
+    #
+    # Example:
+    #
+    # <tt>{ :field => { "$lt" => "value" } }</tt>
+    # becomes:
+    # <tt> { :field.lt => "value }</tt>
+    class Complex
+      attr_accessor :key, :operator
+
+      # Create the new complex criterion.
+      def initialize(opts = {})
+        @key, @operator = opts[:key], opts[:operator]
+      end
+    end
+  end
+end

data/lib/mongoid/criterion/exclusion.rb

@@ -0,0 +1,65 @@
+# encoding: utf-8
+module Mongoid #:nodoc:
+  module Criterion #:nodoc:
+    module Exclusion
+      # Adds a criterion to the +Criteria+ that specifies values that are not allowed
+      # to match any document in the database. The MongoDB conditional operator that
+      # will be used is "$ne".
+      #
+      # Options:
+      #
+      # attributes: A +Hash+ where the key is the field name and the value is a
+      # value that must not be equal to the corresponding field value in the database.
+      #
+      # Example:
+      #
+      # <tt>criteria.excludes(:field => "value1")</tt>
+      #
+      # <tt>criteria.excludes(:field1 => "value1", :field2 => "value1")</tt>
+      #
+      # Returns: <tt>self</tt>
+      def excludes(attributes = {})
+        mongo_id = attributes.delete(:id)
+        attributes = attributes.merge(:_id => mongo_id) if mongo_id
+        update_selector(attributes, "$ne")
+      end
+
+      # Adds a criterion to the +Criteria+ that specifies values where none
+      # should match in order to return results. This is similar to an SQL "NOT IN"
+      # clause. The MongoDB conditional operator that will be used is "$nin".
+      #
+      # Options:
+      #
+      # exclusions: A +Hash+ where the key is the field name and the value is an
+      # +Array+ of values that none can match.
+      #
+      # Example:
+      #
+      # <tt>criteria.not_in(:field => ["value1", "value2"])</tt>
+      #
+      # <tt>criteria.not_in(:field1 => ["value1", "value2"], :field2 => ["value1"])</tt>
+      #
+      # Returns: <tt>self</tt>
+      def not_in(exclusions)
+        exclusions.each { |key, value| @selector[key] = { "$nin" => value } }; self
+      end
+
+      # Adds a criterion to the +Criteria+ that specifies the fields that will
+      # get returned from the Document. Used mainly for list views that do not
+      # require all fields to be present. This is similar to SQL "SELECT" values.
+      #
+      # Options:
+      #
+      # args: A list of field names to retrict the returned fields to.
+      #
+      # Example:
+      #
+      # <tt>criteria.only(:field1, :field2, :field3)</tt>
+      #
+      # Returns: <tt>self</tt>
+      def only(*args)
+        @options[:fields] = args.flatten if args.any?; self
+      end
+    end
+  end
+end

data/lib/mongoid/criterion/inclusion.rb

@@ -0,0 +1,92 @@
+# encoding: utf-8
+module Mongoid #:nodoc:
+  module Criterion #:nodoc:
+    module Inclusion
+      # Adds a criterion to the +Criteria+ that specifies values that must all
+      # be matched in order to return results. Similar to an "in" clause but the
+      # underlying conditional logic is an "AND" and not an "OR". The MongoDB
+      # conditional operator that will be used is "$all".
+      #
+      # Options:
+      #
+      # attributes: A +Hash+ where the key is the field name and the value is an
+      # +Array+ of values that must all match.
+      #
+      # Example:
+      #
+      # <tt>criteria.all(:field => ["value1", "value2"])</tt>
+      #
+      # <tt>criteria.all(:field1 => ["value1", "value2"], :field2 => ["value1"])</tt>
+      #
+      # Returns: <tt>self</tt>
+      def all(attributes = {})
+        update_selector(attributes, "$all")
+      end
+
+      # Adds a criterion to the +Criteria+ that specifies values that must
+      # be matched in order to return results. This is similar to a SQL "WHERE"
+      # clause. This is the actual selector that will be provided to MongoDB,
+      # similar to the Javascript object that is used when performing a find()
+      # in the MongoDB console.
+      #
+      # Options:
+      #
+      # selectior: A +Hash+ that must match the attributes of the +Document+.
+      #
+      # Example:
+      #
+      # <tt>criteria.and(:field1 => "value1", :field2 => 15)</tt>
+      #
+      # Returns: <tt>self</tt>
+      def and(selector = nil)
+        where(selector)
+      end
+
+      # Adds a criterion to the +Criteria+ that specifies values where any can
+      # be matched in order to return results. This is similar to an SQL "IN"
+      # clause. The MongoDB conditional operator that will be used is "$in".
+      #
+      # Options:
+      #
+      # attributes: A +Hash+ where the key is the field name and the value is an
+      # +Array+ of values that any can match.
+      #
+      # Example:
+      #
+      # <tt>criteria.in(:field => ["value1", "value2"])</tt>
+      #
+      # <tt>criteria.in(:field1 => ["value1", "value2"], :field2 => ["value1"])</tt>
+      #
+      # Returns: <tt>self</tt>
+      def in(attributes = {})
+        update_selector(attributes, "$in")
+      end
+      alias any_in in
+
+      # Adds a criterion to the +Criteria+ that specifies values that must
+      # be matched in order to return results. This is similar to a SQL "WHERE"
+      # clause. This is the actual selector that will be provided to MongoDB,
+      # similar to the Javascript object that is used when performing a find()
+      # in the MongoDB console.
+      #
+      # Options:
+      #
+      # selectior: A +Hash+ that must match the attributes of the +Document+.
+      #
+      # Example:
+      #
+      # <tt>criteria.where(:field1 => "value1", :field2 => 15)</tt>
+      #
+      # Returns: <tt>self</tt>
+      def where(selector = nil)
+        case selector
+        when String
+          @selector.update("$where" => selector)
+        else
+          @selector.update(selector ? selector.expand_complex_criteria : {})
+        end
+        self
+      end
+    end
+  end
+end

data/lib/mongoid/criterion/optional.rb

@@ -0,0 +1,136 @@
+# encoding: utf-8
+module Mongoid #: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?
+        @options[:cache] == 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
+
+      # 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>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/mongoid/extensions/hash/criteria_helpers.rb

@@ -0,0 +1,20 @@
+# encoding: utf-8
+module Mongoid #:nodoc:
+  module Extensions #:nodoc:
+    module Hash #:nodoc:
+      module CriteriaHelpers #:nodoc:
+        def expand_complex_criteria
+          hsh = {}
+          self.each_pair do |k,v|
+            if k.class == Mongoid::Criterion::Complex
+              hsh[k.key] = {"$#{k.operator}" => v}
+            else
+              hsh[k] = v
+            end
+          end
+          hsh
+        end
+      end
+    end
+  end
+end

data/lib/mongoid/extensions/symbol/inflections.rb

@@ -0,0 +1,36 @@
+# encoding: utf-8
+module Mongoid #:nodoc:
+  module Extensions #:nodoc:
+    module Symbol #:nodoc:
+      module Inflections #:nodoc:
+
+        REVERSALS = {
+          :asc => :desc,
+          :ascending => :descending,
+          :desc => :asc,
+          :descending => :ascending
+        }
+
+        def invert
+          REVERSALS[self]
+        end
+
+        def singular?
+          to_s.singular?
+        end
+
+        def plural?
+          to_s.plural?
+        end
+
+        ["gt", "lt", "gte", "lte", "ne", "in", "nin", "mod", "all", "size", "exists"].each do |oper|
+          class_eval <<-OPERATORS
+            def #{oper}
+              Criterion::Complex.new(:key => self, :operator => "#{oper}")
+            end
+          OPERATORS
+        end
+      end
+    end
+  end
+end

data/lib/mongoid/matchers/all.rb

@@ -0,0 +1,11 @@
+# encoding: utf-8
+module Mongoid #:nodoc:
+  module Matchers #:nodoc:
+    class All < Default
+      # Return true if the attribute and first value in the hash are equal.
+      def matches?(value)
+        @attribute == value.values.first
+      end
+    end
+  end
+end

data/lib/mongoid/matchers/default.rb

@@ -0,0 +1,26 @@
+# encoding: utf-8
+module Mongoid #:nodoc:
+  module Matchers #:nodoc:
+    class Default
+      # Creating a new matcher only requires the value.
+      def initialize(attribute)
+        @attribute = attribute
+      end
+      # Return true if the attribute and value are equal.
+      def matches?(value)
+        @attribute == value
+      end
+
+      protected
+      # Return the first value in the hash.
+      def first(value)
+        value.values.first
+      end
+
+      # If object exists then compare, else return false
+      def determine(value, operator)
+        @attribute ? @attribute.send(operator, first(value)) : false
+      end
+    end
+  end
+end

data/lib/mongoid/matchers/exists.rb

@@ -0,0 +1,13 @@
+# encoding: utf-8
+module Mongoid #:nodoc:
+  module Matchers #:nodoc:
+    class Exists < Default
+      # Return true if the attribute exists and checking for existence or
+      # return true if the attribute does not exist and checking for
+      # non-existence.
+      def matches?(value)
+        @attribute.nil? != value.values.first
+      end
+    end
+  end
+end

data/lib/mongoid/matchers/gt.rb

@@ -0,0 +1,11 @@
+# encoding: utf-8
+module Mongoid #:nodoc:
+  module Matchers #:nodoc:
+    class Gt < Default
+      # Return true if the attribute is greater than the value.
+      def matches?(value)
+        determine(value, :>)
+      end
+    end
+  end
+end

data/lib/mongoid/matchers/gte.rb

@@ -0,0 +1,11 @@
+# encoding: utf-8
+module Mongoid #:nodoc:
+  module Matchers #:nodoc:
+    class Gte < Default
+      # Return true if the attribute is greater than or equal to the value.
+      def matches?(value)
+        determine(value, :>=)
+      end
+    end
+  end
+end