mongoid 6.4.4 → 7.1.7

data/lib/mongoid/loggable.rb

@@ -1,13 +1,15 @@
+# frozen_string_literal: true
 # encoding: utf-8
+
 module Mongoid
 
-  # Contains logging behaviour.
+  # Contains logging behavior.
   module Loggable
 
     # Get the logger.
     #
     # @note Will try to grab Rails' logger first before creating a new logger
-    #   with stdout.
+    #   with stderr.
     #
     # @example Get the logger.
     #   Loggable.logger
@@ -23,7 +25,7 @@ module Mongoid
     # Set the logger.
     #
     # @example Set the logger.
-    #   Loggable.logger = Logger.new($stdout)
+    #   Loggable.logger = Logger.new(STDERR)
     #
     # @param [ Logger ] logger The logger to set.
     #
@@ -36,7 +38,7 @@ module Mongoid
 
     private
 
-    # Gets the default Mongoid logger - stdout.
+    # Gets the default Mongoid logger - stderr.
     #
     # @api private
     #
@@ -47,12 +49,12 @@ module Mongoid
     #
     # @since 3.0.0
     def default_logger
-      logger = Logger.new($stdout)
+      logger = Logger.new(STDERR)
       logger.level = Mongoid::Config.log_level
       logger
     end
 
-    # Get the Rails logger if it's defined.
+    # Get the Rails logger if loaded in a Rails application, otherwise nil.
     #
     # @api private
     #
@@ -63,7 +65,11 @@ module Mongoid
     #
     # @since 3.0.0
     def rails_logger
-      defined?(::Rails) && ::Rails.respond_to?(:logger) && ::Rails.logger
+      if defined?(::Rails)
+        ::Rails.logger
+      else
+        nil
+      end
     end
   end
 end

data/lib/mongoid/matchable/all.rb

@@ -1,4 +1,6 @@
+# frozen_string_literal: true
 # encoding: utf-8
+
 module Mongoid
   module Matchable
 
@@ -10,11 +12,12 @@ module Mongoid
       # @example Do the values match?
       #   matcher._matches?({ :key => 10 })
       #
-      # @param [ Hash ] value The values to check.
+      # @param [ Hash ] condition The condition to evaluate. This must be
+      #   a one-element hash like {'$gt' => 1}.
       #
       # @return [ true, false ] If the values match.
-      def _matches?(value)
-        first = first(value)
+      def _matches?(condition)
+        first = condition_value(condition)
         return false if first.is_a?(Array) && first.empty?
 
         attribute_array = Array.wrap(@attribute)

data/lib/mongoid/matchable/and.rb

@@ -1,8 +1,10 @@
+# frozen_string_literal: true
 # encoding: utf-8
+
 module Mongoid
   module Matchable
 
-    # Defines behavior for handling $or expressions in embedded documents.
+    # Defines behavior for handling $and expressions in embedded documents.
     class And < Default
 
       # Does the supplied query match the attribute?

data/lib/mongoid/matchable/default.rb

@@ -1,4 +1,6 @@
+# frozen_string_literal: true
 # encoding: utf-8
+
 module Mongoid
   module Matchable
 
@@ -20,52 +22,99 @@ module Mongoid
         @attribute, @document = attribute, document
       end
 
-      # Return true if the attribute and value are equal, or if it is an array
-      # if the value is included.
+      # Checks whether the attribute matches the value, using the default
+      # MongoDB matching logic (i.e., when no operator is specified in the
+      # criteria).
+      #
+      # If attribute and value are both of basic types like string or number,
+      # this method returns true if and only if the attribute equals the value.
+      #
+      # Value can also be of a type like Regexp or Range which defines
+      # more complex matching/inclusion behavior via the === operator.
+      # If so, and attribute is still of a basic type like string or number,
+      # this method returns true if and only if the value's === operator
+      # returns true for the attribute. For example, this method returns true
+      # if attribute is a string and value is a Regexp and attribute matches
+      # the value, of if attribute is a number and value is a Range and
+      # the value includes the attribute.
+      #
+      # If attribute is an array and value is not an array, the checks just
+      # described (i.e. the === operator invocation) are performed on each item
+      # of the attribute array. If any of the items in the attribute match
+      # the value according to the value type's === operator, this method
+      # returns true.
       #
-      # @example Does this value match?
-      #   default._matches?("value")
+      # If attribute and value are both arrays, this method returns true if and
+      # only if the arrays are equal (including the order of the elements).
       #
-      # @param [ Object ] value The value to check if it matches.
+      # @param [ Object ] value The value to check.
       #
-      # @return [ true, false ] True if matches, false if not.
+      # @return [ true, false ] True if attribute matches the value, false if not.
       #
       # @since 1.0.0
       def _matches?(value)
-        attribute.is_a?(Array) && !value.is_a?(Array) ? attribute.any? { |_attribute| value === _attribute } : value === attribute
+        if attribute.is_a?(Array) && !value.is_a?(Array)
+          attribute.any? { |_attribute| value === _attribute }
+        else
+          value === attribute
+        end
       end
 
       protected
 
-      # Convenience method for getting the first value in a hash.
+      # Given a condition, which is a one-element hash consisting of an
+      # operator and a value like {'$gt' => 1}, return the value.
       #
-      # @example Get the first value.
-      #   matcher.first(:test => "value")
+      # @example Get the condition value.
+      #   matcher.condition_value({'$gt' => 1})
+      #   # => 1
       #
-      # @param [ Hash ] hash The has to pull from.
+      # @param [ Hash ] condition The condition.
       #
-      # @return [ Object ] The first value.
+      # @return [ Object ] The value of the condition.
       #
       # @since 1.0.0
-      def first(hash)
-        hash.values.first
+      def condition_value(condition)
+        unless condition.is_a?(Hash)
+          raise ArgumentError, 'Condition must be a hash'
+        end
+
+        unless condition.length == 1
+          raise ArgumentError, 'Condition must have one element'
+        end
+
+        condition.values.first
       end
 
-      # If object exists then compare the two, otherwise return false
+      # Determines whether the attribute value stored in this matcher
+      # satisfies the provided condition using the provided operator.
+      #
+      # For example, given an instance of Gt matcher with the @attribute of
+      # 2, the matcher is set up to answer whether the attribute is
+      # greater than some input value. This input value is provided in
+      # the condition, which could be {"$gt" => 1}, and the operator is
+      # provided (somewhat in a duplicate fashion) in the operator argument,
+      # in this case :>.
       #
-      # @example Determine if we can compare.
-      #   matcher.determine("test", "$in")
+      # @example
+      #   matcher = Matchable::Gt.new(2)
+      #   matcher.determine({'$gt' => 1}, :>)
+      #   # => true
       #
-      # @param [ Object ] value The value to compare with.
-      # @param [ Symbol, String ] operator The comparison operation.
+      # @param [ Hash ] condition The condition to evaluate. This must be
+      #   a one-element hash; the key is ignored, and the value is passed
+      #   as the argument to the operator.
+      # @param [ Symbol, String ] operator The comparison operator or method.
+      #   The operator is invoked on the attribute stored in the matcher
+      #   instance.
       #
-      # @return [ true, false ] The comparison or false.
+      # @return [ true, false ] Result of condition evaluation.
       #
       # @since 1.0.0
-      def determine(value, operator)
-        attribute.__array__.any? {|attr|
-          attr ? attr.send(operator, first(value)) : false
-        }
+      def determine(condition, operator)
+        attribute.__array__.any? do |attr|
+          attr && attr.send(operator, condition_value(condition))
+        end
       end
     end
   end

data/lib/mongoid/matchable/elem_match.rb

@@ -1,4 +1,6 @@
+# frozen_string_literal: true
 # encoding: utf-8
+
 module Mongoid
   module Matchable
 
@@ -13,13 +15,19 @@ module Mongoid
       #
       # @return [ true, false ] If the values match.
       def _matches?(value)
-        if !@attribute.is_a?(Array) || !value.kind_of?(Hash) || !value["$elemMatch"].kind_of?(Hash)
+        elem_match = value["$elemMatch"] || value[:$elemMatch]
+
+        if !@attribute.is_a?(Array) || !value.kind_of?(Hash) || !elem_match.kind_of?(Hash)
           return false
         end
 
         return @attribute.any? do |sub_document|
-          value["$elemMatch"].all? do |k, v|
-            Matchable.matcher(sub_document, k, v)._matches?(v)
+          elem_match.all? do |k, v|
+            if v.try(:first).try(:[],0) == "$not".freeze || v.try(:first).try(:[],0) == :$not
+              !Matchable.matcher(sub_document, k, v.first[1])._matches?(v.first[1])
+            else
+              Matchable.matcher(sub_document, k, v)._matches?(v)
+            end
           end
         end
       end

data/lib/mongoid/matchable/eq.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+# encoding: utf-8
+
+module Mongoid
+  module Matchable
+
+    # Performs equivalency checks.
+    class Eq < Default
+
+      # Return true if the attribute and first value are equal.
+      #
+      # @example Do the values match?
+      #   matcher._matches?({ :key => 10 })
+      #
+      # @param [ Hash ] value The values to check.
+      #
+      # @return [ true, false ] True if matches, false if not.
+      def _matches?(value)
+        super(value.values.first)
+      end
+    end
+  end
+end

data/lib/mongoid/matchable/exists.rb

@@ -1,4 +1,6 @@
+# frozen_string_literal: true
 # encoding: utf-8
+
 module Mongoid
   module Matchable
 

data/lib/mongoid/matchable/gt.rb

@@ -1,4 +1,6 @@
+# frozen_string_literal: true
 # encoding: utf-8
+
 module Mongoid
   module Matchable
 

data/lib/mongoid/matchable/gte.rb

@@ -1,4 +1,6 @@
+# frozen_string_literal: true
 # encoding: utf-8
+
 module Mongoid
   module Matchable
 

data/lib/mongoid/matchable/in.rb

@@ -1,4 +1,6 @@
+# frozen_string_literal: true
 # encoding: utf-8
+
 module Mongoid
   module Matchable
 

data/lib/mongoid/matchable/lt.rb

@@ -1,4 +1,6 @@
+# frozen_string_literal: true
 # encoding: utf-8
+
 module Mongoid
   module Matchable
 

data/lib/mongoid/matchable/lte.rb

@@ -1,4 +1,6 @@
+# frozen_string_literal: true
 # encoding: utf-8
+
 module Mongoid
   module Matchable
 

data/lib/mongoid/matchable/ne.rb

@@ -1,4 +1,6 @@
+# frozen_string_literal: true
 # encoding: utf-8
+
 module Mongoid
   module Matchable
 
@@ -12,7 +14,7 @@ module Mongoid
       #
       # @param [ Hash ] value The values to check.
       #
-      # @return [ true, false ] If a value exists.
+      # @return [ true, false ] True if matches, false if not.
       def _matches?(value)
         !super(value.values.first)
       end

data/lib/mongoid/matchable/nin.rb

@@ -1,4 +1,6 @@
+# frozen_string_literal: true
 # encoding: utf-8
+
 module Mongoid
   module Matchable
 

data/lib/mongoid/matchable/nor.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 # encoding: utf-8
+
 module Mongoid
   module Matchable
 
@@ -18,7 +19,7 @@ module Mongoid
       #
       # @return [ true, false ] True if matches, false if not.
       #
-      # @since 6.4.2/7.0.2/7.1.0
+      # @since 7.1.0
       def _matches?(conditions)
         if conditions.length == 0
           # MongoDB does not allow $nor array to be empty, but

data/lib/mongoid/matchable/or.rb

@@ -1,4 +1,6 @@
+# frozen_string_literal: true
 # encoding: utf-8
+
 module Mongoid
   module Matchable
 

data/lib/mongoid/matchable/regexp.rb

@@ -1,3 +1,6 @@
+# frozen_string_literal: true
+# encoding: utf-8
+
 module Mongoid
   module Matchable
 
@@ -7,8 +10,8 @@ module Mongoid
       # Does the supplied query match the attribute?
       #
       # @example Does this match?
-      #   matcher._matches?(/^Em/)
-      #   matcher._matches?(BSON::Regex::Raw.new("^Em"))
+      #   matcher._matches?(/\AEm/)
+      #   matcher._matches?(BSON::Regex::Raw.new("\\AEm"))
       #
       # @param [ BSON::Regexp::Raw, Regexp ] regexp The regular expression object.
       #

data/lib/mongoid/matchable/size.rb

@@ -1,4 +1,6 @@
+# frozen_string_literal: true
 # encoding: utf-8
+
 module Mongoid
   module Matchable
 

data/lib/mongoid/matchable.rb

@@ -1,7 +1,11 @@
+# frozen_string_literal: true
 # encoding: utf-8
+
 require "mongoid/matchable/default"
 require "mongoid/matchable/all"
 require "mongoid/matchable/and"
+require "mongoid/matchable/elem_match"
+require "mongoid/matchable/eq"
 require "mongoid/matchable/exists"
 require "mongoid/matchable/gt"
 require "mongoid/matchable/gte"
@@ -10,15 +14,14 @@ require "mongoid/matchable/lt"
 require "mongoid/matchable/lte"
 require "mongoid/matchable/ne"
 require "mongoid/matchable/nin"
-require "mongoid/matchable/or"
 require "mongoid/matchable/nor"
-require "mongoid/matchable/size"
-require "mongoid/matchable/elem_match"
+require "mongoid/matchable/or"
 require "mongoid/matchable/regexp"
+require "mongoid/matchable/size"
 
 module Mongoid
 
-  # This module contains all the behavior for ruby implementations of MongoDB
+  # This module contains all the behavior for Ruby implementations of MongoDB
   # selectors.
   #
   # @since 4.0.0
@@ -30,8 +33,9 @@ module Mongoid
     # @since 1.0.0
     MATCHERS = {
       "$all" => All,
-      "$elemMatch" => ElemMatch,
       "$and" => And,
+      "$elemMatch" => ElemMatch,
+      "$eq" => Eq,
       "$exists" => Exists,
       "$gt" => Gt,
       "$gte" => Gte,
@@ -40,9 +44,9 @@ module Mongoid
       "$lte" => Lte,
       "$ne" => Ne,
       "$nin" => Nin,
-      "$or" => Or,
       "$nor" => Nor,
-      "$size" => Size
+      "$or" => Or,
+      "$size" => Size,
     }.with_indifferent_access.freeze
 
     # Determines if this document has the attributes to match the supplied
@@ -62,13 +66,13 @@ module Mongoid
           value.each do |item|
             if item[0].to_s == "$not".freeze
               item = item[1]
-              return false if matcher(self, key, item)._matches?(item)
+              return false if matcher(key, item)._matches?(item)
             else
-              return false unless matcher(self, key, Hash[*item])._matches?(Hash[*item])
+              return false unless matcher(key, Hash[*item])._matches?(Hash[*item])
             end
           end
         else
-          return false unless matcher(self, key, value)._matches?(value)
+          return false unless matcher(key, value)._matches?(value)
         end
       end
       true
@@ -79,20 +83,18 @@ module Mongoid
     # Get the matcher for the supplied key and value. Will determine the class
     # name from the key.
     #
-    # @api private
-    #
     # @example Get the matcher.
     #   document.matcher(:title, { "$in" => [ "test" ] })
     #
-    # @param [ Document ] document The document to check.
     # @param [ Symbol, String ] key The field name.
     # @param [ Object, Hash ] value The value or selector.
     #
     # @return [ Matcher ] The matcher.
     #
     # @since 2.0.0.rc.7
-    def matcher(document, key, value)
-      Matchable.matcher(document, key, value)
+    # @api private
+    def matcher(key, value)
+      Matchable.matcher(self, key, value)
     end
 
     class << self
@@ -103,7 +105,7 @@ module Mongoid
       # @api private
       #
       # @example Get the matcher.
-      #   document.matcher(:title, { "$in" => [ "test" ] })
+      #   Matchable.matcher(document, :title, { "$in" => [ "test" ] })
       #
       # @param [ Document ] document The document to check.
       # @param [ Symbol, String ] key The field name.
@@ -147,6 +149,7 @@ module Mongoid
       # @return [ Object ] The value of the attribute.
       #
       # @since 2.2.1
+      # @api private
       def extract_attribute(document, key)
         if (key_string = key.to_s) =~ /.+\..+/
           key_string.split('.').inject(document.send(:as_attributes)) do |_attribs, _key|