MONGOID-5351 Implement Dots and Dollars in Mongoid (#5272)

* MONGOID-5300 fix dotted getter and add integration tests

* MONGOID-5300 add docs

* MONGOID-5351 add ProhibitedSetter error

* MONGOID-5351 add ProhibitedSetter to docs

* MONGOID-5351 import error and remove read_only
stuff

* MONGOID-5351 prohibit updates of dots and dollar fields

* MONGOID-5351 correct language

* MONGOID-5351 condition on driver 2.18

* Update docs/reference/fields.txt

* MONGOID-5351 answer comments

* MONGOID-5351 add api privates

Author: neilshweky

docs/reference/fields.txt

@@ -1415,8 +1415,47 @@ requiring the usage of the aggregation pipeline for both queries and updates,
 applications should avoid using dots in field names and starting field names
 with the dollar sign if possible.
 
-The Ruby driver `currently prohibits
-<https://jira.mongodb.org/browse/RUBY-2528>`_ inserting documents whose
-field names contain dots or begin with the dollar sign. However, if such
-documents are inserted using other software, Mongoid and the Ruby driver
-provide limited support for retrieving and operating on these documents.
+Mongoid, starting in version 8, now allows users to access fields that begin with
+dollar signs and that contain dots/periods. They can be accessed using the ``send``
+method as follows:
+
+.. code::
+
+    class User
+      include Mongoid::Document
+      field :"first.last", type: String
+      field :"$_amount", type: Integer
+    end
+
+    user = User.first
+    user.send(:"first.last")
+    # => Mike.Trout
+    user.send(:"$_amount")
+    # => 42650000
+
+It is also possible to use ``read_attribute`` to access these fields:
+
+.. code::
+
+    user.read_attribute("first.last")
+    # => Mike.Trout
+
+Due to `server limitations <https://www.mongodb.com/docs/manual/core/dot-dollar-considerations/>`_,
+updating and replacing fields containing dots and dollars requires using special
+operators. For this reason, calling setters on these fields is prohibited and
+will raise an error:
+
+.. code::
+
+    class User
+      include Mongoid::Document
+      field :"first.last", type: String
+      field :"$_amount", type: Integer
+    end
+
+    user = User.new
+    user.send(:"first.last=", "Shohei.Ohtani")
+    # raises a InvalidDotDollarAssignment error
+    user.send(:"$_amount=", 8500000)
+    # raises a InvalidDotDollarAssignment error
+

lib/config/locales/en.yml

@@ -132,6 +132,17 @@ en:
             allowed."
           resolution: "Try setting the discriminator key on %{superclass} or one of %{class_name}'s
             ancestors."
+        invalid_dot_dollar_assignment:
+          message: "Cannot set the %{attr} attribute on the %{klass} class."
+          summary: "Calling the setters for fields that start with a dollar
+            sign ($) or contain a dot/period (.) is prohibited. See the
+            Mongoid documentation on Field Names with Dots/Periods (.) and
+            Dollar Signs ($) for more information."
+          resolution: "In order to set fields that start with a dollar
+            sign ($) or contain a dot/period (.), the aggregation pipeline can
+            be used. MongoDB provides specific operators for working with these
+            fields. Refer to the MongoDB documentation here:
+            https://www.mongodb.com/docs/manual/core/dot-dollar-considerations/"
         invalid_elem_match_operator:
           message: "Invalid $elemMatch operator '%{operator}'."
           summary: "You misspelled an operator or are using an operator that

lib/mongoid/attributes.rb

@@ -123,6 +123,7 @@ def read_attribute_before_type_cast(name)
     # @raise [ Errors::ReadonlyAttribute ] If the field cannot be removed due
     #   to being flagged as reaodnly.
     def remove_attribute(name)
+      validate_writable_field_name!(name.to_s)
       as_writable_attribute!(name) do |access|
         _assigning do
           attribute_will_change!(access)
@@ -145,6 +146,8 @@ def remove_attribute(name)
     # @param [ String, Symbol ] name The name of the attribute to update.
     # @param [ Object ] value The value to set for the attribute.
     def write_attribute(name, value)
+      validate_writable_field_name!(name.to_s)
+
       field_name = database_field_name(name)
 
       if attribute_missing?(field_name)
@@ -273,7 +276,11 @@ def read_raw_attribute(name)
       end
 
       if hash_dot_syntax?(normalized)
-        attributes.__nested__(normalized)
+        if fields.key?(normalized)
+          attributes[normalized]
+        else
+          attributes.__nested__(normalized)
+        end
       else
         attributes[normalized]
       end

lib/mongoid/errors.rb

@@ -24,6 +24,7 @@
 require "mongoid/errors/invalid_query"
 # Must be after invalid_query.
 require "mongoid/errors/invalid_discriminator_key_target"
+require "mongoid/errors/invalid_dot_dollar_assignment"
 require "mongoid/errors/invalid_elem_match_operator"
 require "mongoid/errors/invalid_estimated_count_criteria"
 require "mongoid/errors/invalid_expression_operator"

lib/mongoid/errors/invalid_dot_dollar_assignment.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Mongoid
+  module Errors
+
+    # This error is raised when trying to use the setter for a field that starts
+    # with a dollar sign ($) or contains a dot/period (.).
+    class InvalidDotDollarAssignment < MongoidError
+
+      # Create the new error.
+      #
+      # @param [ Class ] klass The class of the document.
+      # @param [ Class ] attr The attribute attempted to be written.
+      #
+      # @api private
+      def initialize(klass, attr)
+        super(
+          compose_message("invalid_dot_dollar_assignment", { klass: klass, attr: attr })
+        )
+      end
+    end
+  end
+end

lib/mongoid/fields.rb

@@ -246,6 +246,32 @@ def using_object_ids?
       self.class.using_object_ids?
     end
 
+    # Does this field start with a dollar sign ($) or contain a dot/period (.)?
+    #
+    # @api private
+    #
+    # @param [ String ] name The field name.
+    #
+    # @return [ true, false ] If this field is dotted or dollared.
+    def dot_dollar_field?(name)
+      n = aliased_fields[name] || name
+      fields.key?(n) && (n.include?('.') || n.start_with?('$'))
+    end
+
+    # Validate whether or not the field starts with a dollar sign ($) or
+    # contains a dot/period (.).
+    #
+    # @api private
+    #
+    # @raise [ InvalidDotDollarAssignment ] If contains dots or starts with a dollar.
+    #
+    # @param [ String ] name The field name.
+    def validate_writable_field_name!(name)
+      if dot_dollar_field?(name)
+        raise Errors::InvalidDotDollarAssignment.new(self.class, name)
+      end
+    end
+
     class << self
 
       # Stores the provided block to be run when the option name specified is