net-imap 0.4.12 → 0.5.6

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