🥅 Update unknown numeric response-data handling

Unhandled _simple_ numeric responses, which contain only the numeric
prefix and the response name, will now simply return the number as the
response data.

`UnparsedData` was introduced by #200.  That struct has been renamed to
`UnparsedNumericResponseData`, which represents data for unhandled
response types with a numeric prefix.  This prefix _is_ parsed but the
additional response data is not.

A simpler `UnparsedData` struct now represents data for unknown response
types _or_ for unknown extensions to response types without a
well-defined extension grammar.  It is currently only used by
`response_data__unhandled`, but future PRs will use it anywhere we can
safely extract an unparsed string from the larger response: e.g unknown
response code data.

Author: nevans

lib/net/imap/response_data.rb

@@ -62,23 +62,45 @@ class UntaggedResponse < Struct.new(:name, :data, :raw_data)
     class IgnoredResponse < UntaggedResponse
     end
 
-    # Net::IMAP::UnparsedData represents data for unknown or unhandled
-    # response types.  UnparsedData is an intentionally unstable API: where
-    # it is returned, future releases may return a different (incompatible)
-    # object without deprecation or warning.
-    class UnparsedData < Struct.new(:number, :unparsed_data)
+    # **Note:** This represents an intentionally _unstable_ API.  Where
+    # instances of this class are returned, future releases may return a
+    # different (incompatible) object <em>without deprecation or warning</em>.
+    #
+    # Net::IMAP::UnparsedData represents data for unknown response types or
+    # unknown extensions to response types without a well-defined extension
+    # grammar.
+    #
+    # See also: UnparsedNumericResponseData
+    class UnparsedData < Struct.new(:unparsed_data)
+      ##
+      # method: unparsed_data
+      # :call-seq: unparsed_data -> string
+      #
+      # The unparsed data
+    end
+
+    # **Note:** This represents an intentionally _unstable_ API.  Where
+    # instances of this class are returned, future releases may return a
+    # different (incompatible) object <em>without deprecation or warning</em>.
+    #
+    # Net::IMAP::UnparsedNumericResponseData represents data for unhandled
+    # response types with a numeric prefix.  See the documentation for #number.
+    #
+    # See also: UnparsedData
+    class UnparsedNumericResponseData < Struct.new(:number, :unparsed_data)
       ##
       # method: number
       # :call-seq: number -> integer
       #
       # Returns a numeric response data prefix, when available.
       #
-      # Many response types are prefixed with seqno or uid (for message
-      # data) or a message count (for mailbox data).
+      # Many response types are prefixed with a non-negative #number.  For
+      # message data, #number may represent a sequence number or a UID.  For
+      # mailbox data, #number may represent a message count.
 
       ##
       # method: unparsed_data
-      # :call-seq: string -> string
+      # :call-seq: unparsed_data -> string
       #
       # The unparsed data, not including #number or UntaggedResponse#name.
     end

lib/net/imap/response_parser.rb

@@ -601,7 +601,11 @@ def response_data__unhandled(klass = UntaggedResponse)
         num  = number?;          SP?
         type = tagged_ext_label; SP?
         text = remaining_unparsed
-        data = UnparsedData.new(num, text) if num || text
+        data =
+          if num && text then UnparsedNumericResponseData.new(num, text)
+          elsif     text then UnparsedData.new(text)
+          else                num
+          end
         klass.new(type, data, @str)
       end
 

test/net/imap/fixtures/response_parser/quirky_behaviors.yml

@@ -4,6 +4,7 @@
     :response: "* NOOP\r\n"
     :expected: !ruby/struct:Net::IMAP::IgnoredResponse
       name: "NOOP"
+      data:
       raw_data: "* NOOP\r\n"
 
   test_invalid_noop_response_with_unparseable_data:
@@ -18,6 +19,15 @@
     :response: "* 99 NOOP\r\n"
     :expected: !ruby/struct:Net::IMAP::IgnoredResponse
       name: "NOOP"
-      data: !ruby/struct:Net::IMAP::UnparsedData
-        number: 99
+      data: 99
       raw_data: "* 99 NOOP\r\n"
+
+  test_invalid_noop_response_with_numeric_prefix_and_unparseable_data:
+    :response: "* 86 NOOP froopy snood\r\n"
+    :expected: !ruby/struct:Net::IMAP::IgnoredResponse
+      name: "NOOP"
+      data: !ruby/struct:Net::IMAP::UnparsedNumericResponseData
+        number: 86
+        unparsed_data: "froopy snood"
+      raw_data: "* 86 NOOP froopy snood\r\n"
+