✨ Add keyword argument for search charset

Someday, I'd like to deprecate the positional `charset` parameter.

Author: nevans

lib/net/imap.rb

@@ -1931,6 +1931,7 @@ def uid_expunge(uid_set)
 
     # :call-seq:
     #   search(criteria, charset = nil) -> result
+    #   search(criteria, charset: nil) -> result
     #
     # Sends a {SEARCH command [IMAP4rev1 §6.4.4]}[https://www.rfc-editor.org/rfc/rfc3501#section-6.4.4]
     # to search the mailbox for messages that match the given search +criteria+,
@@ -2210,6 +2211,7 @@ def search(...)
 
     # :call-seq:
     #   uid_search(criteria, charset = nil) -> result
+    #   uid_search(criteria, charset: nil) -> result
     #
     # Sends a {UID SEARCH command [IMAP4rev1 §6.4.8]}[https://www.rfc-editor.org/rfc/rfc3501#section-6.4.8]
     # to search the mailbox for messages that match the given searching
@@ -3150,7 +3152,11 @@ def enforce_logindisabled?
       end
     end
 
-    def search_args(keys, charset = nil)
+    def search_args(keys, charset_arg = nil, charset: nil)
+      if charset && charset_arg
+        raise ArgumentError, "multiple charset arguments"
+      end
+      charset ||= charset_arg
       # NOTE: not handling combined RETURN and CHARSET for raw strings
       if charset && keys in /\ACHARSET\b/i | Array[/\ACHARSET\z/i, *]
         raise ArgumentError, "multiple charset arguments"

test/net/imap/test_imap.rb

@@ -1235,6 +1235,9 @@ def test_unselect
       imap.search('CHARSET UTF-8 SUBJECT "Hello world"')
       assert_equal 'CHARSET UTF-8 SUBJECT "Hello world"', server.commands.pop.args
 
+      imap.search('SUBJECT "Hello world"', charset: "UTF-8")
+      assert_equal 'CHARSET UTF-8 SUBJECT "Hello world"', server.commands.pop.args
+
       imap.search([:*])
       assert_equal "*", server.commands.pop.args
 
@@ -1276,6 +1279,15 @@ def seqset_coercible.to_sequence_set
       assert_raise(ArgumentError) do
         imap.search("charset foo ALL", "bar")
       end
+      assert_raise(ArgumentError) do
+        imap.search(["ALL"], "foo", charset: "bar")
+      end
+      assert_raise(ArgumentError) do
+        imap.search(["charset", "foo", "ALL"], charset: "bar")
+      end
+      assert_raise(ArgumentError) do
+        imap.search("charset foo ALL", charset: "bar")
+      end
       # Parsing return opts is too complicated, for now.
       # assert_raise(ArgumentError) do
       #   imap.search("return () charset foo ALL", "bar")