MONGOID-5186 .with_scope should restore previous scope (#5127)

Co-authored-by: Oleg Pudeyev <[email protected]>

Author: p-mongo

source/reference/queries.txt

@@ -1577,6 +1577,7 @@ To have Mongoid raise an error when a scope would overwrite an existing class
 method, set the ``scope_overwrite_exception`` :ref:`configuration option
 <configuration-options>` to ``true``.
 
+
 Default Scopes
 --------------
 
@@ -1705,6 +1706,35 @@ that would affect its visibility within the scoped association.
   label.reload.bands # []
 
 
+Runtime Default Scope Override
+------------------------------
+
+You can use the ``with_scope`` method to change the default scope in a block
+at runtime:
+
+.. code-block:: ruby
+
+  class Band
+    include Mongoid::Document
+    field :country, type: String
+    field :genres, type: Array
+
+    scope :english, ->{ where(country: "England") }
+  end
+
+  criteria = Band.with_scope(Band.english) do
+    Band.all
+  end
+  
+  criteria
+  # => 
+  # #<Mongoid::Criteria
+  #   selector: {"country"=>"England"}
+  #   options:  {}
+  #   class:    Band
+  #   embedded: false>
+
+
 Class Methods
 -------------