net-imap 0.4.4 → 0.4.9

data/lib/net/imap/response_data.rb

@@ -2,6 +2,9 @@
 
 module Net
   class IMAP < Protocol
+    autoload :FetchData,        "#{__dir__}/fetch_data"
+    autoload :SearchResult,     "#{__dir__}/search_result"
+    autoload :SequenceSet,      "#{__dir__}/sequence_set"
 
     # Net::IMAP::ContinuationRequest represents command continuation requests.
     #
@@ -70,7 +73,7 @@ module Net
     # unknown extensions to response types without a well-defined extension
     # grammar.
     #
-    # See also: UnparsedNumericResponseData
+    # See also: UnparsedNumericResponseData, ExtensionData, IgnoredResponse
     class UnparsedData < Struct.new(:unparsed_data)
       ##
       # method: unparsed_data
@@ -86,7 +89,7 @@ module Net
     # Net::IMAP::UnparsedNumericResponseData represents data for unhandled
     # response types with a numeric prefix.  See the documentation for #number.
     #
-    # See also: UnparsedData
+    # See also: UnparsedData, ExtensionData, IgnoredResponse
     class UnparsedNumericResponseData < Struct.new(:number, :unparsed_data)
       ##
       # method: number
@@ -105,6 +108,23 @@ module Net
       # The unparsed data, not including #number or UntaggedResponse#name.
     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::ExtensionData represents data that is parsable according to the
+    # forward-compatible extension syntax in RFC3501, RFC4466, or RFC9051, but
+    # isn't directly known or understood by Net::IMAP yet.
+    #
+    # See also: UnparsedData, UnparsedNumericResponseData, IgnoredResponse
+    class ExtensionData < Struct.new(:data)
+      ##
+      # method: data
+      # :call-seq: data -> string
+      #
+      # The parsed extension data.
+    end
+
     # Net::IMAP::TaggedResponse represents tagged responses.
     #
     # The server completion result response indicates the success or
@@ -186,6 +206,7 @@ module Net
     # defines them.  When unknown response code data is encountered, #data
     # will return an unparsed string.
     #
+    # ==== +IMAP4rev1+ Response Codes
     # See [IMAP4rev1[https://www.rfc-editor.org/rfc/rfc3501]] {§7.1, "Server
     # Responses - Status
     # Responses"}[https://www.rfc-editor.org/rfc/rfc3501#section-7.1] for full
@@ -209,13 +230,32 @@ module Net
     #   {§2.3.1.1, "Unique Identifier (UID) Message
     #   Attribute}[https://www.rfc-editor.org/rfc/rfc3501#section-2.3.1.1].
     # * +UIDVALIDITY+, #data is an Integer, the UID validity value of the
-    #   mailbox  See [{IMAP4rev1}[https://www.rfc-editor.org/rfc/rfc3501]],
+    #   mailbox.  See [{IMAP4rev1}[https://www.rfc-editor.org/rfc/rfc3501]],
     #   {§2.3.1.1, "Unique Identifier (UID) Message
     #   Attribute}[https://www.rfc-editor.org/rfc/rfc3501#section-2.3.1.1].
     # * +UNSEEN+, #data is an Integer, the number of messages which do not have
     #   the <tt>\Seen</tt> flag set.
-    #
-    # See RFC5530[https://www.rfc-editor.org/rfc/rfc5530], "IMAP Response
+    #   <em>DEPRECATED by IMAP4rev2.</em>
+    #
+    # ==== +BINARY+ extension
+    # See {[RFC3516]}[https://www.rfc-editor.org/rfc/rfc3516].
+    # * +UNKNOWN-CTE+, with a tagged +NO+ response, when the server does not
+    #   known how to decode a CTE (content-transfer-encoding).  #data is +nil+.
+    #   See IMAP#fetch.
+    #
+    # ==== +UIDPLUS+ extension
+    # See {[RFC4315 §3]}[https://www.rfc-editor.org/rfc/rfc4315#section-3].
+    # * +APPENDUID+, #data is UIDPlusData.  See IMAP#append.
+    # * +COPYUID+, #data is UIDPlusData.  See IMAP#copy.
+    # * +UIDNOTSTICKY+, #data is +nil+.  See IMAP#select.
+    #
+    # ==== +SEARCHRES+ extension
+    # See {[RFC5182]}[https://www.rfc-editor.org/rfc/rfc5182].
+    # * +NOTSAVED+, with a tagged +NO+ response, when the search result variable
+    #   is not saved.  #data is +nil+.
+    #
+    # ==== +RFC5530+ Response Codes
+    # See {[RFC5530]}[https://www.rfc-editor.org/rfc/rfc5530], "IMAP Response
     # Codes" for the definition of the following response codes, which are all
     # machine-readable annotations for the human-readable ResponseText#text, and
     # have +nil+ #data of their own:
@@ -237,6 +277,35 @@ module Net
     # * +ALREADYEXISTS+
     # * +NONEXISTENT+
     #
+    # ==== +QRESYNC+ extension
+    # See {[RFC7162]}[https://www.rfc-editor.org/rfc/rfc7162.html].
+    # * +CLOSED+, returned when the currently selected mailbox is closed
+    #   implicity by selecting or examining another mailbox.  #data is +nil+.
+    #
+    # ==== +IMAP4rev2+ Response Codes
+    # See {[RFC9051]}[https://www.rfc-editor.org/rfc/rfc9051] {§7.1, "Server
+    # Responses - Status
+    # Responses"}[https://www.rfc-editor.org/rfc/rfc9051#section-7.1] for full
+    # descriptions of IMAP4rev2 response codes.  IMAP4rev2 includes all of the
+    # response codes listed above (except "UNSEEN") and adds the following:
+    # * +HASCHILDREN+, with a tagged +NO+ response, when a mailbox delete failed
+    #   because the server doesn't allow deletion of mailboxes with children.
+    #   #data is +nil+.
+    #
+    # ==== +CONDSTORE+ extension
+    # See {[RFC7162]}[https://www.rfc-editor.org/rfc/rfc7162.html].
+    # * +NOMODSEQ+, when selecting a mailbox that does not support
+    #   mod-sequences.  #data is +nil+.  See IMAP#select.
+    # * +HIGHESTMODSEQ+, #data is an Integer, the highest mod-sequence value of
+    #   all messages in the mailbox.  See IMAP#select.
+    # * +MODIFIED+, #data is a SequenceSet, the messages that have been modified
+    #   since the +UNCHANGEDSINCE+ mod-sequence given to +STORE+ or <tt>UID
+    #   STORE</tt>.
+    #
+    # ==== +OBJECTID+ extension
+    # See {[RFC8474]}[https://www.rfc-editor.org/rfc/rfc8474.html].
+    # * +MAILBOXID+, #data is a string
+    #
     class ResponseCode < Struct.new(:name, :data)
       ##
       # method: name
@@ -488,210 +557,6 @@ module Net
       # "UIDVALIDITY", "UNSEEN". Each value is a number.
     end
 
-    # Net::IMAP::FetchData represents the contents of a FETCH response.
-    #
-    # Net::IMAP#fetch and Net::IMAP#uid_fetch both return an array of
-    # FetchData objects.
-    #
-    # === Fetch attributes
-    #
-    #--
-    # TODO: merge branch with accessor methods for each type of attr.  Then
-    # move nearly all of the +attr+ documentation onto the appropriate
-    # accessor methods.
-    #++
-    #
-    # Each key of the #attr hash is the data item name for the fetched value.
-    # Each data item represents a message attribute, part of one, or an
-    # interpretation of one.  #seqno is not a message attribute.  Most message
-    # attributes are static and must never change for a given <tt>[server,
-    # account, mailbox, UIDVALIDITY, UID]</tt> tuple.  A few message attributes
-    # can be dynamically changed, e.g. using the {STORE
-    # command}[rdoc-ref:Net::IMAP#store].
-    #
-    # See {[IMAP4rev1] §7.4.2}[https://www.rfc-editor.org/rfc/rfc3501.html#section-7.4.2]
-    # and {[IMAP4rev2] §7.5.2}[https://www.rfc-editor.org/rfc/rfc9051.html#section-7.5.2]
-    # for full description of the standard fetch response data items, and
-    # Net::IMAP@Message+envelope+and+body+structure for other relevant RFCs.
-    #
-    # ==== Static fetch data items
-    #
-    # The static data items
-    # defined by [IMAP4rev1[https://www.rfc-editor.org/rfc/rfc3501.html]] are:
-    #
-    # [<tt>"UID"</tt>]
-    #   A number expressing the unique identifier of the message.
-    #
-    # [<tt>"BODY[]"</tt>, <tt>"BODY[]<#{offset}>"</tt>]
-    #   The [RFC5322[https://tools.ietf.org/html/rfc5322]] expression of the
-    #   entire message, as a string.
-    #
-    #   If +offset+ is specified, this returned string is a substring of the
-    #   entire contents, starting at that origin octet.  This means that
-    #   <tt>BODY[]<0></tt> MAY be truncated, but <tt>BODY[]</tt> is NEVER
-    #   truncated.
-    #
-    #   <em>Messages can be parsed using the "mail" gem.</em>
-    #
-    #   [Note]
-    #     When fetching <tt>BODY.PEEK[#{specifier}]</tt>, the data will be
-    #     returned in <tt>BODY[#{specifier}]</tt>, without the +PEEK+.  This is
-    #     true for all of the <tt>BODY[...]</tt> attribute forms.
-    #
-    # [<tt>"BODY[HEADER]"</tt>, <tt>"BODY[HEADER]<#{offset}>"</tt>]
-    #   The [RFC5322[https://tools.ietf.org/html/rfc5322]] header of the
-    #   message.
-    #
-    #   <em>Message headers can be parsed using the "mail" gem.</em>
-    #
-    # [<tt>"BODY[HEADER.FIELDS (#{fields.join(" ")})]"</tt>,]
-    # [<tt>"BODY[HEADER.FIELDS (#{fields.join(" ")})]<#{offset}>"</tt>]
-    #   When field names are given, the subset contains only the header fields
-    #   that matches one of the names in the list.  The field names are based
-    #   on what was requested, not on what was returned.
-    #
-    # [<tt>"BODY[HEADER.FIELDS.NOT (#{fields.join(" ")})]"</tt>,]
-    # [<tt>"BODY[HEADER.FIELDS.NOT (#{fields.join(" ")})]<#{offset}>"</tt>]
-    #   When the <tt>HEADER.FIELDS.NOT</tt> is used, the subset is all of the
-    #   fields that <em>do not</em> match any names in the list.
-    #
-    # [<tt>"BODY[TEXT]"</tt>, <tt>"BODY[TEXT]<#{offset}>"</tt>]
-    #   The text body of the message, omitting
-    #   the [RFC5322[https://tools.ietf.org/html/rfc5322]] header.
-    #
-    # [<tt>"BODY[#{part}]"</tt>, <tt>"BODY[#{part}]<#{offset}>"</tt>]
-    #   The text of a particular body section, if it was fetched.
-    #
-    #   Multiple part specifiers will be joined with <tt>"."</tt>.  Numeric
-    #   part specifiers refer to the MIME part number, counting up from +1+.
-    #   Messages that don't use MIME, or MIME messages that are not multipart
-    #   and don't hold an encapsulated message, only have a part +1+.
-    #
-    #   8-bit textual data is permitted if
-    #   a [CHARSET[https://tools.ietf.org/html/rfc2978]] identifier is part of
-    #   the body parameter parenthesized list for this section.  See
-    #   BodyTypeBasic.
-    #
-    #   MESSAGE/RFC822 or MESSAGE/GLOBAL message, or a subset of the header, if
-    #   it was fetched.
-    #
-    # [<tt>"BODY[#{part}.HEADER]"</tt>,]
-    # [<tt>"BODY[#{part}.HEADER]<#{offset}>"</tt>,]
-    # [<tt>"BODY[#{part}.HEADER.FIELDS.NOT (#{fields.join(" ")})]"</tt>,]
-    # [<tt>"BODY[#{part}.HEADER.FIELDS.NOT (#{fields.join(" ")})]<#{offset}>"</tt>,]
-    # [<tt>"BODY[#{part}.TEXT]"</tt>,]
-    # [<tt>"BODY[#{part}.TEXT]<#{offset}>"</tt>,]
-    # [<tt>"BODY[#{part}.MIME]"</tt>,]
-    # [<tt>"BODY[#{part}.MIME]<#{offset}>"</tt>]
-    #   +HEADER+, <tt>HEADER.FIELDS</tt>, <tt>HEADER.FIELDS.NOT</tt>, and
-    #   <tt>TEXT</tt> can be prefixed by numeric part specifiers, if it refers
-    #   to a part of type <tt>message/rfc822</tt> or <tt>message/global</tt>.
-    #
-    #   +MIME+ refers to the [MIME-IMB[https://tools.ietf.org/html/rfc2045]]
-    #   header for this part.
-    #
-    # [<tt>"BODY"</tt>]
-    #   A form of +BODYSTRUCTURE+, without any extension data.
-    #
-    # [<tt>"BODYSTRUCTURE"</tt>]
-    #   Returns a BodyStructure object that describes
-    #   the [MIME-IMB[https://tools.ietf.org/html/rfc2045]] body structure of
-    #   a message, if it was fetched.
-    #
-    # [<tt>"ENVELOPE"</tt>]
-    #   An Envelope object that describes the envelope structure of a message.
-    #   See the documentation for Envelope for a description of the envelope
-    #   structure attributes.
-    #
-    # [<tt>"INTERNALDATE"</tt>]
-    #   The internal date and time of the message on the server.  This is not
-    #   the date and time in
-    #   the [RFC5322[https://tools.ietf.org/html/rfc5322]] header, but rather
-    #   a date and time which reflects when the message was received.
-    #
-    # [<tt>"RFC822.SIZE"</tt>]
-    #   A number expressing the [RFC5322[https://tools.ietf.org/html/rfc5322]]
-    #   size of the message.
-    #
-    #   [Note]
-    #     \IMAP was originally developed for the older RFC-822 standard, and
-    #     as a consequence several fetch items in \IMAP incorporate "RFC822"
-    #     in their name.  With the exception of +RFC822.SIZE+, there are more
-    #     modern replacements; for example, the modern version of
-    #     +RFC822.HEADER+ is <tt>BODY.PEEK[HEADER]</tt>.  In all cases,
-    #     "RFC822" should be interpreted as a reference to the
-    #     updated [RFC5322[https://tools.ietf.org/html/rfc5322]] standard.
-    #
-    # [<tt>"RFC822"</tt>]
-    #   Semantically equivalent to <tt>BODY[]</tt>.
-    # [<tt>"RFC822.HEADER"</tt>]
-    #   Semantically equivalent to <tt>BODY[HEADER]</tt>.
-    # [<tt>"RFC822.TEXT"</tt>]
-    #   Semantically equivalent to <tt>BODY[TEXT]</tt>.
-    #
-    # [Note:]
-    #   >>>
-    #     Additional static fields are defined in \IMAP extensions and
-    #     [IMAP4rev2[https://www.rfc-editor.org/rfc/rfc9051.html]], but
-    #     Net::IMAP can't parse them yet.
-    #
-    #--
-    # <tt>"BINARY[#{section_binary}]<#{offset}>"</tt>:: TODO...
-    # <tt>"BINARY.SIZE[#{sectionbinary}]"</tt>::        TODO...
-    # <tt>"EMAILID"</tt>::                              TODO...
-    # <tt>"THREADID"</tt>::                             TODO...
-    # <tt>"SAVEDATE"</tt>::                             TODO...
-    #++
-    #
-    # ==== Dynamic message attributes
-    # The only dynamic item defined
-    # by [{IMAP4rev1}[https://www.rfc-editor.org/rfc/rfc3501.html]] is:
-    # [<tt>"FLAGS"</tt>]
-    #   An array of flags that are set for this message.  System flags are
-    #   symbols that have been capitalized by String#capitalize.  Keyword
-    #   flags are strings and their case is not changed.
-    #
-    # \IMAP extensions define new dynamic fields, e.g.:
-    #
-    # [<tt>"MODSEQ"</tt>]
-    #   The modification sequence number associated with this IMAP message.
-    #
-    #   Requires the [CONDSTORE[https://tools.ietf.org/html/rfc7162]]
-    #   server {capability}[rdoc-ref:Net::IMAP#capability].
-    #
-    # [Note:]
-    #   >>>
-    #     Additional dynamic fields are defined in \IMAP extensions, but
-    #     Net::IMAP can't parse them yet.
-    #
-    #--
-    # <tt>"ANNOTATE"</tt>:: TODO...
-    # <tt>"PREVIEW"</tt>::  TODO...
-    #++
-    #
-    class FetchData < Struct.new(:seqno, :attr)
-      ##
-      # method: seqno
-      # :call-seq: seqno -> Integer
-      #
-      # The message sequence number.
-      #
-      # [Note]
-      #   This is never the unique identifier (UID), not even for the
-      #   Net::IMAP#uid_fetch result.  If it was returned, the UID is available
-      #   from <tt>attr["UID"]</tt>.
-
-      ##
-      # method: attr
-      # :call-seq: attr -> hash
-      #
-      # A hash.  Each key is specifies a message attribute, and the value is the
-      # corresponding data item.
-      #
-      # See rdoc-ref:FetchData@Fetch+attributes for descriptions of possible
-      # values.
-    end
-
     # Net::IMAP::Envelope represents envelope structures of messages.
     #
     # [Note]
@@ -705,6 +570,7 @@ module Net
     # for full description of the envelope fields, and
     # Net::IMAP@Message+envelope+and+body+structure for other relevant RFCs.
     #
+    # Returned by FetchData#envelope
     class Envelope < Struct.new(:date, :subject, :from, :sender, :reply_to,
                                 :to, :cc, :bcc, :in_reply_to, :message_id)
       ##
@@ -908,6 +774,19 @@ module Net
       #
       # An array of Net::IMAP::ThreadMember objects for mail items that are
       # children of this in the thread.
+
+      # Returns a SequenceSet containing #seqno and all #children's seqno,
+      # recursively.
+      def to_sequence_set
+        SequenceSet.new all_seqnos
+      end
+
+      protected
+
+      def all_seqnos(node = self)
+        [node.seqno].concat node.children.flat_map { _1.all_seqnos }
+      end
+
     end
 
     # Net::IMAP::BodyStructure is included by all of the structs that can be
@@ -1123,7 +1002,6 @@ module Net
     # * description[rdoc-ref:BodyTypeBasic#description]
     # * encoding[rdoc-ref:BodyTypeBasic#encoding]
     # * size[rdoc-ref:BodyTypeBasic#size]
-    #
     class BodyTypeMessage < Struct.new(:media_type, :subtype,
                                        :param, :content_id,
                                        :description, :encoding, :size,

data/lib/net/imap/response_parser/parser_utils.rb

@@ -8,7 +8,7 @@ module Net
       # (internal API, subject to change)
       module ParserUtils # :nodoc:
 
-        module Generator
+        module Generator # :nodoc:
 
           LOOKAHEAD = "(@token ||= next_token)"
           SHIFT_TOKEN = "(@token = nil)"