🔊 Warn about deprecated responses usage

This was extracted from #93 and split into a separate PR.

A new config option is added: `responses_without_block`.  This is
provided as a workaround, until dependant projects can update their
usage.  A future release may remove this backwards compatibility, but
_no sooner_ than v0.6.

Author: nevans

lib/net/imap.rb

@@ -2499,6 +2499,7 @@ def idle_done
     #
     #   Calling without a block is unsafe and deprecated.  Future releases will
     #   raise ArgumentError unless a block is given.
+    #   See Config#responses_without_block.
     #
     # Previously unhandled responses are automatically cleared before entering a
     # mailbox with #select or #examine.  Long-lived connections can receive many
@@ -2523,7 +2524,12 @@ def responses(type = nil)
       elsif type
         raise ArgumentError, "Pass a block or use #clear_responses"
       else
-        # warn("DEPRECATED: pass a block or use #clear_responses", uplevel: 1)
+        case config.responses_without_block
+        when :raise
+          raise ArgumentError, "Pass a block or use #clear_responses"
+        when :warn
+          warn("DEPRECATED: pass a block or use #clear_responses", uplevel: 1)
+        end
         @responses
       end
     end

lib/net/imap/config.rb

@@ -104,6 +104,19 @@ def self.[](config) # :nodoc: unfinished API
       # The default value is +5+ seconds.
       attr_accessor :idle_response_timeout, type: Integer
 
+      # :markup: markdown
+      #
+      # Controls the behavior of Net::IMAP#responses when called without a
+      # block.  Valid options are `:warn`, `:raise`, or
+      # `:silence_deprecation_warning`.
+      #
+      # | Starting with version | The default value is           |
+      # |-----------------------|--------------------------------|
+      # | v0.4.13               | +:silence_deprecation_warning+ |
+      # | v0.5                  | +:warn+                        |
+      # | _eventually_          | +:raise+                       |
+      attr_accessor :responses_without_block
+
       # Creates a new config object and initialize its attribute with +attrs+.
       #
       # If +parent+ is not given, the global config is used by default.
@@ -119,6 +132,7 @@ def initialize(parent = Config.global, **attrs)
         debug: false,
         open_timeout: 30,
         idle_response_timeout: 5,
+        responses_without_block: :silence_deprecation_warning,
       ).freeze
 
       @global = default.new

test/net/imap/test_imap.rb

@@ -1105,10 +1105,22 @@ def test_responses
       assert_equal(1, imap.responses("RECENT", &:last))
       assert_raise(ArgumentError) do imap.responses("UIDNEXT") end
       # Deprecated style, without a block:
-      # assert_warn(/Pass a block.*or.*clear_responses/i) do
-      #   assert_equal(%i[Answered Flagged Deleted Seen Draft],
-      #                imap.responses["FLAGS"]&.last)
-      # end
+      imap.config.responses_without_block = :raise
+      assert_raise(ArgumentError) do imap.responses end
+      imap.config.responses_without_block = :warn
+      assert_raise(ArgumentError) do imap.responses("UIDNEXT") end
+      assert_warn(/Pass a block.*or.*clear_responses/i) do
+        assert_equal(%i[Answered Flagged Deleted Seen Draft],
+                     imap.responses["FLAGS"]&.last)
+      end
+      # TODO: assert_no_warn?
+      imap.config.responses_without_block = :silence_deprecation_warning
+      assert_raise(ArgumentError) do imap.responses("UIDNEXT") end
+      stderr = EnvUtil.verbose_warning {
+        assert_equal(%i[Answered Flagged Deleted Seen Draft],
+                     imap.responses["FLAGS"]&.last)
+      }
+      assert_empty stderr
     end
   end