🚧 Parse sequence-set into SequenceSet object

The SequenceSet class is only a placeholder for now, because the more
complete implementation isn't ready yet.  But we need `sequence-set` for
both `tagged-ext-value`.  And we need `tagged-ext-value` for the RFC4466
extension grammar for `STATUS`, `ESEARCH`, `LIST`, etc.

The more complete SequenceSet implementation is needed for `ESEARCH`.

Author: nevans

lib/net/imap/response_data.rb

@@ -2,7 +2,8 @@
 
 module Net
   class IMAP < Protocol
-    autoload :FetchData, File.expand_path("fetch_data", __dir__)
+    autoload :FetchData,        "#{__dir__}/fetch_data"
+    autoload :SequenceSet,      "#{__dir__}/sequence_set"
 
     # Net::IMAP::ContinuationRequest represents command continuation requests.
     #

lib/net/imap/response_parser.rb

@@ -267,6 +267,56 @@ module RFC3629
         #                      ; Is a valid RFC 3501 "atom".
         TAGGED_EXT_LABEL     = /#{TAGGED_LABEL_FCHAR}#{TAGGED_LABEL_CHAR}*/n
 
+        # nz-number       = digit-nz *DIGIT
+        #                     ; Non-zero unsigned 32-bit integer
+        #                     ; (0 < n < 4,294,967,296)
+        NZ_NUMBER         = /[1-9]\d*/n
+
+        # seq-number      = nz-number / "*"
+        #                     ; message sequence number (COPY, FETCH, STORE
+        #                     ; commands) or unique identifier (UID COPY,
+        #                     ; UID FETCH, UID STORE commands).
+        #                     ; * represents the largest number in use.  In
+        #                     ; the case of message sequence numbers, it is
+        #                     ; the number of messages in a non-empty mailbox.
+        #                     ; In the case of unique identifiers, it is the
+        #                     ; unique identifier of the last message in the
+        #                     ; mailbox or, if the mailbox is empty, the
+        #                     ; mailbox's current UIDNEXT value.
+        #                     ; The server should respond with a tagged BAD
+        #                     ; response to a command that uses a message
+        #                     ; sequence number greater than the number of
+        #                     ; messages in the selected mailbox.  This
+        #                     ; includes "*" if the selected mailbox is empty.
+        SEQ_NUMBER        = /#{NZ_NUMBER}|\*/n
+
+        # seq-range       = seq-number ":" seq-number
+        #                     ; two seq-number values and all values between
+        #                     ; these two regardless of order.
+        #                     ; Example: 2:4 and 4:2 are equivalent and
+        #                     ; indicate values 2, 3, and 4.
+        #                     ; Example: a unique identifier sequence range of
+        #                     ; 3291:* includes the UID of the last message in
+        #                     ; the mailbox, even if that value is less than
+        #                     ; 3291.
+        SEQ_RANGE         = /#{SEQ_NUMBER}:#{SEQ_NUMBER}/n
+
+        # sequence-set    = (seq-number / seq-range) ["," sequence-set]
+        #                     ; set of seq-number values, regardless of order.
+        #                     ; Servers MAY coalesce overlaps and/or execute
+        #                     ; the sequence in any order.
+        #                     ; Example: a message sequence number set of
+        #                     ; 2,4:7,9,12:* for a mailbox with 15 messages is
+        #                     ; equivalent to 2,4,5,6,7,9,12,13,14,15
+        #                     ; Example: a message sequence number set of
+        #                     ; *:4,5:7 for a mailbox with 10 messages is
+        #                     ; equivalent to 10,9,8,7,6,5,4,5,6,7 and MAY
+        #                     ; be reordered and overlap coalesced to be
+        #                     ; 4,5,6,7,8,9,10.
+        SEQUENCE_SET_ITEM = /#{SEQ_NUMBER}|#{SEQ_RANGE}/n
+        SEQUENCE_SET      = /#{SEQUENCE_SET_ITEM}(?:,#{SEQUENCE_SET_ITEM})*/n
+        SEQUENCE_SET_STR  = /\A#{SEQUENCE_SET}\z/n
+
         # RFC3501:
         #   literal          = "{" number "}" CRLF *CHAR8
         #                        ; Number represents the number of CHAR8s
@@ -405,6 +455,24 @@ def unescape_quoted(quoted)
       # ATOM-CHAR       = <any CHAR except atom-specials>
       ATOM_TOKENS = [T_ATOM, T_NUMBER, T_NIL, T_LBRA, T_PLUS]
 
+      SEQUENCE_SET_TOKENS = [T_ATOM, T_NUMBER, T_STAR]
+
+      #   sequence-set    = (seq-number / seq-range) ["," sequence-set]
+      #   sequence-set    =/ seq-last-command
+      #                       ; Allow for "result of the last command"
+      #                       ; indicator.
+      #   seq-last-command   = "$"
+      #
+      # *note*: doesn't match seq-last-command
+      def sequence_set
+        str = combine_adjacent(*SEQUENCE_SET_TOKENS)
+        if Patterns::SEQUENCE_SET_STR.match?(str)
+          SequenceSet.new(str)
+        else
+          parse_error("unexpected atom %p, expected sequence-set", str)
+        end
+      end
+
       # ASTRING-CHAR    = ATOM-CHAR / resp-specials
       # resp-specials   = "]"
       ASTRING_CHARS_TOKENS = [*ATOM_TOKENS, T_RBRA].freeze

lib/net/imap/sequence_set.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module Net
+  class IMAP
+
+    ##
+    # An IMAP {sequence
+    # set}[https://www.rfc-editor.org/rfc/rfc9051.html#section-4.1.1],
+    # is a set of message sequence numbers or unique identifier numbers
+    # ("UIDs").  It contains numbers and ranges of numbers.  The numbers are all
+    # non-zero unsigned 32-bit integers and one special value, <tt>*</tt>, that
+    # represents the largest value in the mailbox.
+    #
+    # *NOTE:* This SequenceSet class is currently a placeholder for unhandled
+    # extension data.  All it does now is validate.  It will be expanded to a
+    # full API in a future release.
+    class SequenceSet
+
+      def self.[](str) new(str).freeze end
+
+      def initialize(input)
+        @atom = -String.try_convert(input)
+        validate
+      end
+
+      # Returns the IMAP string representation.  In the IMAP grammar,
+      # +sequence-set+ is a subset of +atom+ which is a subset of +astring+.
+      attr_accessor :atom
+
+      # Returns #atom.  In the IMAP grammar, +atom+ is a subset of +astring+.
+      alias astring atom
+
+      # Returns the value of #atom
+      alias to_s atom
+
+      # Hash equality requires the same encoded #atom representation.
+      #
+      #   Net::IMAP::SequenceSet["1:3"]  .eql? Net::IMAP::SequenceSet["1:3"]  # => true
+      #   Net::IMAP::SequenceSet["1,2,3"].eql? Net::IMAP::SequenceSet["1:3"]  # => false
+      #   Net::IMAP::SequenceSet["1,3"]  .eql? Net::IMAP::SequenceSet["3,1"]  # => false
+      #   Net::IMAP::SequenceSet["9,1:*"].eql? Net::IMAP::SequenceSet["1:*"]  # => false
+      #
+      def eql?(other) self.class == other.class && atom == other.atom end
+      alias == eql?
+
+      # See #eql?
+      def hash; [self.class. atom].hash end
+
+      def inspect
+        (frozen? ? "%s[%p]" : "#<%s %p>") % [self.class, to_s]
+      end
+
+      # Unstable API, for internal use only (Net::IMAP#validate_data)
+      def validate # :nodoc:
+        ResponseParser::Patterns::SEQUENCE_SET_STR.match?(@atom) or
+          raise ArgumentError, "invalid sequence-set: %p" % [input]
+        true
+      end
+
+      # Unstable API, for internal use only (Net::IMAP#send_data)
+      def send_data(imap, tag) # :nodoc:
+        imap.__send__(:put_string, atom)
+      end
+
+    end
+  end
+end