From 4a4559afcd50aace3fdfc93f1f3ac469fe44d29e Mon Sep 17 00:00:00 2001
From: nick evans <nicholas.evans@gmail.com>
Date: Sat, 7 Jan 2023 10:01:46 -0500
Subject: [PATCH] =?UTF-8?q?=F0=9F=94=8A=20Warn=20about=20deprecated=20resp?=
 =?UTF-8?q?onses=20usage?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

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.
---
 lib/net/imap.rb            |  8 +++++++-
 lib/net/imap/config.rb     | 14 ++++++++++++++
 test/net/imap/test_imap.rb | 20 ++++++++++++++++----
 3 files changed, 37 insertions(+), 5 deletions(-)

diff --git a/lib/net/imap.rb b/lib/net/imap.rb
index 1e4c9ae8..1c40dbe9 100644
--- a/lib/net/imap.rb
+++ b/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
diff --git a/lib/net/imap/config.rb b/lib/net/imap/config.rb
index 9294804f..31a3b5aa 100644
--- a/lib/net/imap/config.rb
+++ b/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
diff --git a/test/net/imap/test_imap.rb b/test/net/imap/test_imap.rb
index 30012666..27044414 100644
--- a/test/net/imap/test_imap.rb
+++ b/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