net-imap 0.5.4 → 0.5.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a871e99f51067e3a509aa5a74fe2c49f4d79496bcec2f21ac50c3c5793d2cdbf
-  data.tar.gz: 302c03e65954f9a118d877f97ea2296f34a7f50c8b1299e3e4f8b589cb620880
+  metadata.gz: c9b92943c4c4d17210f7374b4f5577f95471038a987540a8cdad2088e6bec25d
+  data.tar.gz: 6a28ce5ca7778cbfa3de48c3451be4d17fe6298a01e2a946725caf022a34dd8c
 SHA512:
-  metadata.gz: 85d97c9729220265da03588f175fea22bcdd27d40cd06910ad35bc01ed64bd0c27b2769790464712572166761f3e82fc4eb6330fef64f45cceb0b3e1007f7126
-  data.tar.gz: aa18d53b81e57ddfbdde2b8295ca7324f965fa744846fdd756ec4ca1c30e6e72092b106ff454d100f70d1078ee239f2b3e643bd4650606a2fc3b4ab5a2d0cc1f
+  metadata.gz: 5a575e282b7cd6828d56360003b1de29e8ca0e3d55ce733c8de250f781413dc8e9e6a90549c14b9ed21bb46e0cdc88f3e75d92aeaed769d594f93056359ee40d
+  data.tar.gz: 87d57464c32eab235e241c74efea7953b9798b9c40a14f66170e751560943f728aabe852d38c746283cdcb4c03914ee375021c49fec67f653113d3330a6732d2

data/README.md

@@ -1,7 +1,9 @@
 # Net::IMAP
 
 Net::IMAP implements Internet Message Access Protocol (IMAP) client
-functionality.  The protocol is described in [IMAP](https://tools.ietf.org/html/rfc3501).
+functionality.  The protocol is described in
+[RFC3501](https://www.rfc-editor.org/rfc/rfc3501),
+[RFC9051](https://www.rfc-editor.org/rfc/rfc9051) and various extensions.
 
 ## Installation
 

data/docs/styles.css

@@ -10,18 +10,28 @@ main .method-detail {
   justify-content: space-between;
 }
 
-main .method-header, main .method-controls {
+main .method-header,
+main .method-controls,
+.attribute-method-heading {
   padding: 0.5em;
   /* border: 1px solid var(--highlight-color); */
   background: var(--table-header-background-color);
   line-height: 1.6;
 }
 
+.attribute-method-heading .attribute-access-type {
+  float: right;
+}
+
 main .method-header {
   border-right: none;
   border-radius: 4px 0 0 4px;
 }
 
+main .method-heading :any-link {
+  text-decoration: none;
+}
+
 main .method-controls {
   border-left: none;
   border-radius: 0 4px 4px 0;

data/lib/net/imap/config.rb

@@ -75,7 +75,7 @@ module Net
     #
     #   client = Net::IMAP.new(hostname, config: :future)
     #   client.config.sasl_ir                  # => true
-    #   client.config.responses_without_block  # => :raise
+    #   client.config.responses_without_block  # => :frozen_dup
     #
     # The versioned default configs inherit certain specific config options from
     # Config.global, for example #debug:
@@ -109,9 +109,11 @@ module Net
     # [+:future+]
     #   The _planned_ eventual config for some future +x.y+ version.
     #
-    # For example, to raise exceptions for all current deprecations:
+    # For example, to disable all currently deprecated behavior:
     #   client = Net::IMAP.new(hostname, config: :future)
-    #   client.responses  # raises an ArgumentError
+    #   client.config.response_without_args     # => :frozen_dup
+    #   client.responses.frozen?                # => true
+    #   client.responses.values.all?(&:frozen?) # => true
     #
     # == Thread Safety
     #

data/lib/net/imap/data_lite.rb

@@ -29,7 +29,7 @@ module Net
   class IMAP
     data_or_object = RUBY_VERSION >= "3.2.0" ? ::Data : Object
     class DataLite < data_or_object
-      def encode_with(coder) coder.map = attributes.transform_keys(&:to_s) end
+      def encode_with(coder) coder.map = to_h.transform_keys(&:to_s)        end
       def init_with(coder) initialize(**coder.map.transform_keys(&:to_sym)) end
     end
 
@@ -159,28 +159,27 @@ module Net
 
       ##
       def members;     self.class.members                              end
-      def attributes;  Hash[members.map {|m| [m, send(m)] }]           end
-      def to_h(&block) attributes.to_h(&block)                         end
-      def hash;        [self.class, attributes].hash                   end
+      def to_h(&block) block ? __to_h__.to_h(&block) : __to_h__        end
+      def hash;        [self.class, __to_h__].hash                     end
       def ==(other)    self.class == other.class && to_h == other.to_h end
       def eql?(other)  self.class == other.class && hash == other.hash end
-      def deconstruct; attributes.values                               end
+      def deconstruct; __to_h__.values                                 end
 
       def deconstruct_keys(keys)
         raise TypeError unless keys.is_a?(Array) || keys.nil?
-        return attributes if keys&.first.nil?
-        attributes.slice(*keys)
+        return __to_h__ if keys&.first.nil?
+        __to_h__.slice(*keys)
       end
 
       def with(**kwargs)
         return self if kwargs.empty?
-        self.class.new(**attributes.merge(kwargs))
+        self.class.new(**__to_h__.merge(kwargs))
       end
 
       def inspect
         __inspect_guard__(self) do |seen|
           return "#<data #{self.class}:...>" if seen
-          attrs = attributes.map {|kv| "%s=%p" % kv }.join(", ")
+          attrs = __to_h__.map {|kv| "%s=%p" % kv }.join(", ")
           display = ["data", self.class.name, attrs].compact.join(" ")
           "#<#{display}>"
         end
@@ -190,7 +189,9 @@ module Net
       private
 
       def initialize_copy(source) super.freeze end
-      def marshal_dump; attributes end
+      def marshal_dump; __to_h__ end
+
+      def __to_h__; Hash[members.map {|m| [m, send(m)] }] end
 
       # Yields +true+ if +obj+ has been seen already, +false+ if it hasn't.
       # Marks +obj+ as seen inside the block, so circuler references don't

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