net-imap 0.5.1 → 0.5.6

data/lib/net/imap/esearch_result.rb

@@ -0,0 +1,180 @@
+# frozen_string_literal: true
+
+module Net
+  class IMAP
+    # An "extended search" response (+ESEARCH+).  ESearchResult should be
+    # returned (instead of SearchResult) by IMAP#search, IMAP#uid_search,
+    # IMAP#sort, and IMAP#uid_sort under any of the following conditions:
+    #
+    # * Return options were specified for IMAP#search or IMAP#uid_search.
+    #   The server must support a search extension which allows
+    #   RFC4466[https://www.rfc-editor.org/rfc/rfc4466.html] +return+ options,
+    #   such as +ESEARCH+, +PARTIAL+, or +IMAP4rev2+.
+    # * Return options were specified for IMAP#sort or IMAP#uid_sort.
+    #   The server must support the +ESORT+ extension
+    #   {[RFC5267]}[https://www.rfc-editor.org/rfc/rfc5267.html#section-3].
+    #
+    #   *NOTE:* IMAP#search and IMAP#uid_search do not support +ESORT+ yet.
+    # * The server supports +IMAP4rev2+ but _not_ +IMAP4rev1+, or +IMAP4rev2+
+    #   has been enabled.  +IMAP4rev2+ requires +ESEARCH+ results.
+    #
+    # Note that some servers may claim to support a search extension which
+    # requires an +ESEARCH+ result, such as +PARTIAL+, but still only return a
+    # +SEARCH+ result when +return+ options are specified.
+    #
+    # Some search extensions may result in the server sending ESearchResult
+    # responses after the initiating command has completed.  Use
+    # IMAP#add_response_handler to handle these responses.
+    class ESearchResult < Data.define(:tag, :uid, :data)
+      def initialize(tag: nil, uid: nil, data: nil)
+        tag  => String       | nil; tag = -tag if tag
+        uid  => true | false | nil; uid = !!uid
+        data => Array        | nil; data ||= []; data.freeze
+        super
+      end
+
+      # :call-seq: to_a -> Array of integers
+      #
+      # When either #all or #partial contains a SequenceSet of message sequence
+      # numbers or UIDs, +to_a+ returns that set as an array of integers.
+      #
+      # When both #all and #partial are +nil+, either because the server
+      # returned no results or because +ALL+ and +PARTIAL+ were not included in
+      # the IMAP#search +RETURN+ options, #to_a returns an empty array.
+      #
+      # Note that SearchResult also implements +to_a+, so it can be used without
+      # checking if the server returned +SEARCH+ or +ESEARCH+ data.
+      def to_a; all&.numbers || partial&.to_a || [] end
+
+      ##
+      # attr_reader: tag
+      #
+      # The tag string for the command that caused this response to be returned.
+      #
+      # When +nil+, this response was not caused by a particular command.
+
+      ##
+      # attr_reader: uid
+      #
+      # Indicates whether #data in this response refers to UIDs (when +true+) or
+      # to message sequence numbers (when +false+).
+
+      ##
+      alias uid? uid
+
+      ##
+      # attr_reader: data
+      #
+      # Search return data, as an array of <tt>[name, value]</tt> pairs.  Most
+      # return data corresponds to a search +return+ option with the same name.
+      #
+      # Note that some return data names may be used more than once per result.
+      #
+      # This data can be more simply retrieved by #min, #max, #all, #count,
+      # #modseq, and other methods.
+
+      # :call-seq: min -> integer or nil
+      #
+      # The lowest message number/UID that satisfies the SEARCH criteria.
+      #
+      # Returns +nil+ when the associated search command has no results, or when
+      # the +MIN+ return option wasn't specified.
+      #
+      # Requires +ESEARCH+ {[RFC4731]}[https://www.rfc-editor.org/rfc/rfc4731.html#section-3.1] or
+      # +IMAP4rev2+ {[RFC9051]}[https://www.rfc-editor.org/rfc/rfc9051.html#section-7.3.4].
+      def min;        data.assoc("MIN")&.last        end
+
+      # :call-seq: max -> integer or nil
+      #
+      # The highest message number/UID that satisfies the SEARCH criteria.
+      #
+      # Returns +nil+ when the associated search command has no results, or when
+      # the +MAX+ return option wasn't specified.
+      #
+      # Requires +ESEARCH+ {[RFC4731]}[https://www.rfc-editor.org/rfc/rfc4731.html#section-3.1] or
+      # +IMAP4rev2+ {[RFC9051]}[https://www.rfc-editor.org/rfc/rfc9051.html#section-7.3.4].
+      def max;        data.assoc("MAX")&.last        end
+
+      # :call-seq: all -> sequence set or nil
+      #
+      # A SequenceSet containing all message sequence numbers or UIDs that
+      # satisfy the SEARCH criteria.
+      #
+      # Returns +nil+ when the associated search command has no results, or when
+      # the +ALL+ return option was not specified but other return options were.
+      #
+      # Requires +ESEARCH+ {[RFC4731]}[https://www.rfc-editor.org/rfc/rfc4731.html#section-3.1] or
+      # +IMAP4rev2+ {[RFC9051]}[https://www.rfc-editor.org/rfc/rfc9051.html#section-7.3.4].
+      #
+      # See also: #to_a
+      def all;        data.assoc("ALL")&.last        end
+
+      # :call-seq: count -> integer or nil
+      #
+      # Returns the number of messages that satisfy the SEARCH criteria.
+      #
+      # Returns +nil+ when the associated search command has no results, or when
+      # the +COUNT+ return option wasn't specified.
+      #
+      # Requires +ESEARCH+ {[RFC4731]}[https://www.rfc-editor.org/rfc/rfc4731.html#section-3.1] or
+      # +IMAP4rev2+ {[RFC9051]}[https://www.rfc-editor.org/rfc/rfc9051.html#section-7.3.4].
+      def count;      data.assoc("COUNT")&.last      end
+
+      # :call-seq: modseq -> integer or nil
+      #
+      # The highest +mod-sequence+ of all messages being returned.
+      #
+      # Returns +nil+ when the associated search command has no results, or when
+      # the +MODSEQ+ search criterion wasn't specified.
+      #
+      # Note that there is no search +return+ option for +MODSEQ+.  It will be
+      # returned whenever the +CONDSTORE+ extension has been enabled.  Using the
+      # +MODSEQ+ search criteria will implicitly enable +CONDSTORE+.
+      #
+      # Requires +CONDSTORE+ {[RFC7162]}[https://www.rfc-editor.org/rfc/rfc7162.html]
+      # and +ESEARCH+ {[RFC4731]}[https://www.rfc-editor.org/rfc/rfc4731.html#section-3.2].
+      def modseq;     data.assoc("MODSEQ")&.last     end
+
+      # Returned by ESearchResult#partial.
+      #
+      # Requires +PARTIAL+ {[RFC9394]}[https://www.rfc-editor.org/rfc/rfc9394.html]
+      # or <tt>CONTEXT=SEARCH</tt>/<tt>CONTEXT=SORT</tt>
+      # {[RFC5267]}[https://www.rfc-editor.org/rfc/rfc5267.html]
+      #
+      # See also: #to_a
+      class PartialResult < Data.define(:range, :results)
+        def initialize(range:, results:)
+          range   => Range
+          results = SequenceSet[results] unless results.nil?
+          super
+        end
+
+        ##
+        # method: range
+        # :call-seq: range -> range
+
+        ##
+        # method: results
+        # :call-seq: results -> sequence set or nil
+
+        # Converts #results to an array of integers.
+        #
+        # See also: ESearchResult#to_a.
+        def to_a; results&.numbers || [] end
+      end
+
+      # :call-seq: partial -> PartialResult or nil
+      #
+      # A PartialResult containing a subset of the message sequence numbers or
+      # UIDs that satisfy the SEARCH criteria.
+      #
+      # Requires +PARTIAL+ {[RFC9394]}[https://www.rfc-editor.org/rfc/rfc9394.html]
+      # or <tt>CONTEXT=SEARCH</tt>/<tt>CONTEXT=SORT</tt>
+      # {[RFC5267]}[https://www.rfc-editor.org/rfc/rfc5267.html]
+      #
+      # See also: #to_a
+      def partial;    data.assoc("PARTIAL")&.last    end
+
+    end
+  end
+end

data/lib/net/imap/fetch_data.rb

@@ -3,9 +3,9 @@
 module Net
   class IMAP < Protocol
 
-    # 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.
+    # Net::IMAP::FetchStruct is the superclass for FetchData and UIDFetchData.
+    # Net::IMAP#fetch, Net::IMAP#uid_fetch, Net::IMAP#store, and
+    # Net::IMAP#uid_store all return arrays of FetchStruct objects.
     #
     # === Fetch attributes
     #
@@ -63,8 +63,7 @@ module Net
     #   * <b><tt>"X-GM-MSGID"</tt></b> --- unique message ID.  Access via #attr.
     #   * <b><tt>"X-GM-THRID"</tt></b> --- Thread ID.  Access via #attr.
     #
-    # [Note:]
-    #   >>>
+    # [NOTE:]
     #     Additional static fields are defined in other \IMAP extensions, but
     #     Net::IMAP can't parse them yet.
     #
@@ -87,34 +86,23 @@ module Net
     #   extension]}[https://developers.google.com/gmail/imap/imap-extensions]
     #   * <b><tt>"X-GM-LABELS"</tt></b> --- Gmail labels.  Access via #attr.
     #
-    # [Note:]
-    #   >>>
+    # [NOTE:]
     #     Additional dynamic fields are defined in other \IMAP extensions, but
     #     Net::IMAP can't parse them yet.
     #
     # === Implicitly setting <tt>\Seen</tt> and using +PEEK+
     #
-    # Unless the mailbox is has been opened as read-only, fetching
+    # Unless the mailbox has been opened as read-only, fetching
     # <tt>BODY[#{section}]</tt> or <tt>BINARY[#{section}]</tt>
     # will implicitly set the <tt>\Seen</tt> flag.  To avoid this, fetch using
     # <tt>BODY.PEEK[#{section}]</tt> or <tt>BINARY.PEEK[#{section}]</tt>
     # instead.
     #
-    # Note that the data will always be _returned_ without <tt>".PEEK"</tt>, in
-    # <tt>BODY[#{specifier}]</tt> or <tt>BINARY[#{section}]</tt>.
+    # [NOTE:]
+    #   The data will always be _returned_ without the <tt>".PEEK"</tt> suffix,
+    #   as <tt>BODY[#{specifier}]</tt> or <tt>BINARY[#{section}]</tt>.
     #
-    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.  The UID is available from #uid, if it was
-      #   returned.
-
+    class FetchStruct < Struct
       ##
       # method: attr
       # :call-seq: attr -> hash
@@ -123,9 +111,6 @@ module Net
       # corresponding data item.  Standard data items have corresponding
       # accessor methods.  The definitions of each attribute type is documented
       # on its accessor.
-      #
-      # >>>
-      #   *Note:* #seqno is not a message attribute.
 
       # :call-seq: attr_upcase -> hash
       #
@@ -142,7 +127,7 @@ module Net
       #
       # This is the same as getting the value for <tt>"BODY"</tt> from #attr.
       #
-      # [Note]
+      # [NOTE:]
       #   Use #message, #part, #header, #header_fields, #header_fields_not,
       #   #text, or #mime to retrieve <tt>BODY[#{section_spec}]</tt> attributes.
       def body; attr["BODY"] end
@@ -235,7 +220,7 @@ module Net
         fields && except and
           raise ArgumentError, "conflicting 'fields' and 'except' arguments"
         if fields
-          text = "HEADER.FIELDS (%s)"     % [fields.join(" ").upcase]
+          text = "HEADER.FIELDS (%s)" % [fields.join(" ").upcase]
           attr_upcase[body_section_attr(part_nums, text, offset: offset)]
         elsif except
           text = "HEADER.FIELDS.NOT (%s)" % [except.join(" ").upcase]
@@ -308,6 +293,7 @@ module Net
       # This is the same as getting the value for <tt>"BODYSTRUCTURE"</tt> from
       # #attr.
       def bodystructure; attr["BODYSTRUCTURE"] end
+
       alias body_structure bodystructure
 
       # :call-seq: envelope -> Envelope or nil
@@ -320,7 +306,7 @@ module Net
       # #attr.
       def envelope; attr["ENVELOPE"] end
 
-      # :call-seq: flags -> array of Symbols and Strings
+      # :call-seq: flags -> array of Symbols and Strings, or nil
       #
       # A array of flags that are set for this message.  System flags are
       # symbols that have been capitalized by String#capitalize.  Keyword flags
@@ -328,7 +314,7 @@ module Net
       #
       # This is the same as getting the value for <tt>"FLAGS"</tt> from #attr.
       #
-      # [Note]
+      # [NOTE:]
       #   The +FLAGS+ field is dynamic, and can change for a uniquely identified
       #   message.
       def flags; attr["FLAGS"] end
@@ -336,40 +322,41 @@ module Net
       # :call-seq: internaldate -> Time or nil
       #
       # 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]]
+      # the date and time in the [RFC5322[https://www.rfc-editor.org/rfc/rfc5322]]
       # header, but rather a date and time which reflects when the message was
       # received.
       #
       # This is similar to getting the value for <tt>"INTERNALDATE"</tt> from
       # #attr.
       #
-      # [Note]
+      # [NOTE:]
       #   <tt>attr["INTERNALDATE"]</tt> returns a string, and this method
       #   returns a Time object.
       def internaldate
         attr["INTERNALDATE"]&.then { IMAP.decode_time _1 }
       end
+
       alias internal_date internaldate
 
-      # :call-seq: rfc822 -> String
+      # :call-seq: rfc822 -> String or nil
       #
       # Semantically equivalent to #message with no arguments.
       #
       # This is the same as getting the value for <tt>"RFC822"</tt> from #attr.
       #
-      # [Note]
+      # [NOTE:]
       #   +IMAP4rev2+ deprecates <tt>RFC822</tt>.
       def rfc822; attr["RFC822"] end
 
-      # :call-seq: rfc822_size -> Integer
+      # :call-seq: rfc822_size -> Integer or nil
       #
-      # A number expressing the [RFC5322[https://tools.ietf.org/html/rfc5322]]
+      # A number expressing the [RFC5322[https://www.rfc-editor.org/rfc/rfc5322]]
       # size of the message.
       #
       # This is the same as getting the value for <tt>"RFC822.SIZE"</tt> from
       # #attr.
       #
-      # [Note]
+      # [NOTE:]
       #   \IMAP was originally developed for the older
       #   RFC822[https://www.rfc-editor.org/rfc/rfc822.html] standard, and as a
       #   consequence several fetch items in \IMAP incorporate "RFC822" in their
@@ -379,34 +366,45 @@ module Net
       #   interpreted as a reference to the updated
       #   RFC5322[https://www.rfc-editor.org/rfc/rfc5322.html] standard.
       def rfc822_size; attr["RFC822.SIZE"] end
-      alias size rfc822_size
 
-      # :call-seq: rfc822_header -> String
+      # NOTE: a bug in rdoc 6.7 prevents us from adding a call-seq to
+      # rfc822_size _and_ aliasing size => rfc822_size.  Is it because this
+      # class inherits from Struct?
+
+      # Alias for: rfc822_size
+      def size; rfc822_size end
+
+
+      # :call-seq: rfc822_header -> String or nil
       #
       # Semantically equivalent to #header, with no arguments.
       #
       # This is the same as getting the value for <tt>"RFC822.HEADER"</tt> from #attr.
       #
-      # [Note]
+      # [NOTE:]
       #   +IMAP4rev2+ deprecates <tt>RFC822.HEADER</tt>.
       def rfc822_header; attr["RFC822.HEADER"] end
 
-      # :call-seq: rfc822_text -> String
+      # :call-seq: rfc822_text -> String or nil
       #
       # Semantically equivalent to #text, with no arguments.
       #
       # This is the same as getting the value for <tt>"RFC822.TEXT"</tt> from
       # #attr.
       #
-      # [Note]
+      # [NOTE:]
       #   +IMAP4rev2+ deprecates <tt>RFC822.TEXT</tt>.
       def rfc822_text; attr["RFC822.TEXT"] end
 
-      # :call-seq: uid -> Integer
+      # :call-seq: uid -> Integer or nil
       #
       # A number expressing the unique identifier of the message.
       #
       # This is the same as getting the value for <tt>"UID"</tt> from #attr.
+      #
+      # [NOTE:]
+      #   For UIDFetchData, this returns the uniqueid at the beginning of the
+      #   +UIDFETCH+ response, _not_ the value from #attr.
       def uid; attr["UID"] end
 
       # :call-seq:
@@ -452,7 +450,7 @@ module Net
         attr[section_attr("BINARY.SIZE", part_nums)]
       end
 
-      # :call-seq: modseq -> Integer
+      # :call-seq: modseq -> Integer or nil
       #
       # The modification sequence number associated with this IMAP message.
       #
@@ -461,7 +459,7 @@ module Net
       # The server must support the +CONDSTORE+ extension
       # {[RFC7162]}[https://www.rfc-editor.org/rfc/rfc7162.html].
       #
-      # [Note]
+      # [NOTE:]
       #   The +MODSEQ+ field is dynamic, and can change for a uniquely
       #   identified message.
       def modseq; attr["MODSEQ"] end
@@ -508,11 +506,92 @@ module Net
         spec = Array(part).flatten.map { Integer(_1) }
         spec << text if text
         spec = spec.join(".")
-        if offset then "%s[%s]<%d>" % [attr, spec, Integer(offset)]
-        else           "%s[%s]"     % [attr, spec]
-        end
+        if offset then "%s[%s]<%d>" % [attr, spec, Integer(offset)] else "%s[%s]" % [attr, spec] end
       end
+    end
 
+    # Net::IMAP::FetchData represents the contents of a +FETCH+ response.
+    # Net::IMAP#fetch, Net::IMAP#uid_fetch, Net::IMAP#store, and
+    # Net::IMAP#uid_store all return arrays of FetchData objects, except when
+    # the +UIDONLY+ extension is enabled.
+    #
+    # See FetchStruct documentation for a list of standard message attributes.
+    class FetchData < FetchStruct.new(:seqno, :attr)
+      ##
+      # method: seqno
+      # :call-seq: seqno -> Integer
+      #
+      # The message sequence number.
+      #
+      # [NOTE:]
+      #   This is not the same as the unique identifier (UID), not even for the
+      #   Net::IMAP#uid_fetch result.  The UID is available from #uid, if it was
+      #   returned.
+      #
+      # [NOTE:]
+      #   UIDFetchData will raise a NoMethodError.
+
+      ##
+      # method: attr
+      # :call-seq: attr -> hash
+      #
+      # Each key specifies a message attribute, and the value is the
+      # corresponding data item.  Standard data items have corresponding
+      # accessor methods.  The definitions of each attribute type is documented
+      # on its accessor.
+      #
+      # See FetchStruct documentation for message attribute accessors.
+      #
+      # [NOTE:]
+      #   #seqno is not a message attribute.
+    end
+
+    # Net::IMAP::UIDFetchData represents the contents of a +UIDFETCH+ response,
+    # When the +UIDONLY+ extension has been enabled, Net::IMAP#uid_fetch and
+    # Net::IMAP#uid_store will both return an array of UIDFetchData objects.
+    #
+    # UIDFetchData contains the same message attributes as FetchData.  However,
+    # +UIDFETCH+ responses return the UID at the beginning of the response,
+    # replacing FetchData#seqno.  UIDFetchData never contains a message sequence
+    # number.
+    #
+    # See FetchStruct documentation for a list of standard message attributes.
+    class UIDFetchData < FetchStruct.new(:uid, :attr)
+      ##
+      # method: uid
+      # call-seq: uid -> Integer
+      #
+      # A number expressing the unique identifier of the message.
+      #
+      # [NOTE:]
+      #   Although #attr may _also_ have a redundant +UID+ attribute, #uid
+      #   returns the uniqueid at the beginning of the +UIDFETCH+ response.
+
+      ##
+      # method: attr
+      # call-seq: attr -> hash
+      #
+      # Each key specifies a message attribute, and the value is the
+      # corresponding data item.  Standard data items have corresponding
+      # accessor methods.  The definitions of each attribute type is documented
+      # on its accessor.
+      #
+      # See FetchStruct documentation for message attribute accessors.
+      #
+      # [NOTE:]
+      #   #uid is not a message attribute.  Although the server may return a
+      #   +UID+ message attribute, it is not required to.  #uid is taken from
+      #   its corresponding +UIDFETCH+ field.
+
+      # UIDFetchData will print a warning if <tt>#attr["UID"]</tt> is present
+      # but not identical to #uid.
+      def initialize(...)
+        super
+        attr and
+          attr_uid = attr["UID"] and
+          attr_uid != uid and
+          warn "#{self.class} UIDs do not match (#{attr_uid} != #{uid})"
+      end
     end
   end
 end