From c81e119654747fdd58817920d18068bb0a6463ce Mon Sep 17 00:00:00 2001 From: nick evans Date: Fri, 11 Nov 2022 16:32:25 -0500 Subject: [PATCH] =?UTF-8?q?=F0=9F=93=9A=20Document=20"What's=20here=3F"=20?= =?UTF-8?q?for=20Net::IMAP=20class=20[=F0=9F=9A=A7=20tidy=20up...]?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This "What's here?" section is based on the new documentation style for many core ruby classes. It isn't purely a list of methods; paragraphs of explanatory text are interspersed. --- lib/net/imap.rb | 198 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 198 insertions(+) diff --git a/lib/net/imap.rb b/lib/net/imap.rb index 4e689b3e..19d5714d 100644 --- a/lib/net/imap.rb +++ b/lib/net/imap.rb @@ -154,6 +154,204 @@ module Net # between UTF-8 and UTF-16), and Net::IMAP::ResponseParseError is # thrown if a server response is non-parseable. # + # == What's here? + # + # * {Connection control}[rdoc-ref:Net::IMAP@Connection+control+methods] + # * {Core IMAP commands}[rdoc-ref:Net::IMAP@Core+IMAP+commands] + # * {...in any state}[rdoc-ref:Net::IMAP@IMAP+commands+for+any+state] + # * {...in "not authenticated" state}[rdoc-ref:Net::IMAP@IMAP+commands+for+the+-22Not+Authenticated-22+state] + # * {...in "authenticated" state}[rdoc-ref:Net::IMAP@IMAP+commands+for+the+-22Authenticated-22+state] + # * {...in "selected" state}[rdoc-ref:Net::IMAP@IMAP+commands+for+the+-22Selected-22+state] + # * {...in "logout" state}[rdoc-ref:Net::IMAP@IMAP+commands+for+the+-22Logout-22+state] + # * {IMAP extensions}[rdoc-ref:Net::IMAP@Supported+IMAP+extensions] + # * {Handling server responses}[rdoc-ref:Net::IMAP@Handling+server+responses] + # + # === Connection control methods + # + # - Net::IMAP.new: A new client connects immediately and waits for a + # successful server greeting before returning the new client object. + # - #starttls: Asks the server to upgrade a clear-text connection to use TLS. + # - #logout: Tells the server to end the session. Enters the "_logout_" state. + # - #disconnect: Disconnects the connection (without sending #logout first). + # - #disconnected?: True if the connection has been closed. + # + # === Core \IMAP commands + # + # The following commands are defined either by + # the [IMAP4rev1[https://tools.ietf.org/html/rfc3501]] base specification, or + # by one of the following extensions: + # [IDLE[https://tools.ietf.org/html/rfc2177]], + # [NAMESPACE[https://tools.ietf.org/html/rfc2342]], + # [UNSELECT[https://tools.ietf.org/html/rfc3691]], + #-- + # TODO: [ENABLE[https://tools.ietf.org/html/rfc5161]], + # TODO: [LIST-EXTENDED[https://tools.ietf.org/html/rfc5258]], + # TODO: [LIST-STATUS[https://tools.ietf.org/html/rfc5819]], + #++ + # [MOVE[https://tools.ietf.org/html/rfc6851]]. + # These extensions are widely supported by modern IMAP4rev1 servers and have + # all been integrated into [IMAP4rev2[https://tools.ietf.org/html/rfc9051]]. + # Note: Net::IMAP doesn't fully support IMAP4rev2 yet. + # + #-- + # TODO: When IMAP4rev2 is supported, add the following to the each of the + # appropriate commands below. + # Note:: CHECK has been removed from IMAP4rev2. + # Note:: LSUB is obsoleted by +LIST-EXTENDED and has been removed from IMAP4rev2. + # Some arguments require the +LIST-EXTENDED+ or +IMAP4rev2+ capability. + # Requires either the +ENABLE+ or +IMAP4rev2+ capability. + # Requires either the +NAMESPACE+ or +IMAP4rev2+ capability. + # Requires either the +IDLE+ or +IMAP4rev2+ capability. + # Requires either the +UNSELECT+ or +IMAP4rev2+ capability. + # Requires either the +UIDPLUS+ or +IMAP4rev2+ capability. + # Requires either the +MOVE+ or +IMAP4rev2+ capability. + #++ + # + # ==== \IMAP commands for any state + # + # - #capability: Returns the server's capabilities as an array of strings. + # + # Capabilities may change after #starttls, #authenticate, or #login + # and cached capabilities must be reloaded. + # - #noop: Allows the server to send unsolicited untagged #responses. + # - #logout: Tells the server to end the session. Enters the "_logout_" state. + # + # ==== \IMAP commands for the "Not Authenticated" state + # + # In addition to the universal commands, the following commands are valid in + # the "not authenticated" state: + # + # - #starttls: Upgrades a clear-text connection to use TLS. + # + # Requires the +STARTTLS+ capability. + # - #authenticate: Identifies the client to the server using a {SASL + # mechanism}[https://www.iana.org/assignments/sasl-mechanisms/sasl-mechanisms.xhtml]. + # Enters the "_authenticated_" state. + # + # Requires the AUTH=#{mechanism} capability for the chosen + # mechanism. + # + # The +LOGINDISABLED+ capability must NOT be listed. + # - #login: Identifies the client to the server using a simple plain text + # username and password. Only use as a last resort (after attempting and + # failing with #authenticate). Enters the "_authenticated_" state. + # + # The +LOGINDISABLED+ capability must NOT be listed. + # + # ==== \IMAP commands for the "Authenticated" state + # + # In addition to the universal commands, the following commands are valid in + # the "_authenticated_" state: + # + #-- + # - #enable: Not implemented by Net::IMAP, yet. + # + # Requires the +ENABLE+ capability. + #++ + # - #select: Open a mailbox and enter the "_selected_" state. + # - #examine: Open a mailbox read-only, and enter the "_selected_" state. + # - #create: Creates a new mailbox. + # - #delete: Permanently remove a mailbox. + # - #rename: Change the name of a mailbox. + # - #subscribe: Adds a mailbox to the "subscribed" set. + # - #unsubscribe: Removes a mailbox from the "subscribed" set. + # - #list: Returns names and attributes of mailboxes matching a given pattern. + # - #namespace: Returns the namespaces for personal mailboxes, other users' + # mailboxes, and shared mailboxes, with the prefixes and path delimiters + # used for the mailbox names within each namespace. + # + # Requires the +NAMESPACE+ capability. + # - #status: Returns mailbox information, e.g. message count, unseen message + # count, +UIDVALIDITY+ and +UIDNEXT+. + # - #append: Appends a message to the end of a mailbox. + # - #idle: Allows the server to send updates to the client, without the client + # needing to poll using #noop. + # + # Requires the +IDLE+ capability. + # - #lsub: Lists mailboxes the user has declared "active" or "subscribed". + # + # ==== \IMAP commands for the "Selected" state + # + # In addition to the universal commands and the "authenticated" commands, the + # following commands are valid in the "_selected_" state: + # + # - #close: Closes the mailbox and returns to the "_authenticated_" state. + # Messages with the Deleted flag are permanently removed, unless the mailbox + # was opened as read-only. + # - #unselect: Closes the mailbox and returns to the "_authenticated_" state, + # without expunging any messages. + # + # Requires the +UNSELECT+ capability. + # - #expunge: Permanently removes messages which have the Deleted flag set. + # - #uid_expunge: Restricts #expunge to only remove the specified UIDs. + # + # Requires the +UIDPLUS+ capability. + # - #search, #uid_search: Returns sequence numbers or UIDs of messages that + # match the given searching criteria. + # - #fetch, #uid_fetch: Returns data associated with a set of messages, + # specified by sequence number or UID. + # - #store, #uid_store: Alters a message's flags. + # - #copy, #uid_copy: Copies the specified messages to the end of the + # specified destination mailbox. + # - #move, #uid_move: Moves the specified messages to the end of the + # specified destination mailbox, expunging them from the current mailbox. + # + # Requires the +MOVE+ capability. + # - #check: Mostly obsolete. Can be replaced with #noop or #idle. + # + # ==== \IMAP commands for the "Logout" state + # + # No \IMAP commands are valid in the +logout+ state. If the socket is still + # open, Net::IMAP will close it after receiving server confirmation. + # Exceptions will be raised by \IMAP commands that have already started and + # are waiting for a response, as well as any that are called after logout. + # + # === Supported \IMAP extensions + # + # ==== +IMAP4rev2+ [RFC9051[https://tools.ietf.org/html/rfc9051]] + # + # Although IMAP4rev2[https://tools.ietf.org/html/rfc9051] is not supported + # yet, Net::IMAP supports several extensions that have been folded into + # it: +IDLE+, +MOVE+, +NAMESPACE+, +UIDPLUS+, and +UNSELECT+. + #-- + # TODO: +ENABLE+, +LIST-EXTENDED+, +LIST-STATUS+ + #++ + # Commands for these extensions are included with the {Core IMAP + # commands}[rdoc-ref:Net::IMAP@Core+IMAP+commands], above. Other supported + # extensons are listed below. + # + # ==== +ID+ [RFC2971[https://tools.ietf.org/html/rfc2971]] + # - #id: exchanges client and server implementation information. + # ==== +QUOTA+ [RFC2087[https://tools.ietf.org/html/rfc2087]] + # - #getquota: returns the resource usage and limits for a quota root + # - #getquotaroot: returns the list of quota roots for a mailbox, as well as + # their resource usage and limits. + # - #setquota: sets the resource limits for a given quota root. + # ==== +ACL+ [RFC4314[https://tools.ietf.org/html/rfc4314]] + # - #getacl: lists the authenticated user's access rights to a mailbox. + # - #setacl: sets the access rights for a user on a mailbox + # ==== +SORT+ [RFC5256[https://tools.ietf.org/html/rfc5256]] + # - #sort, #uid_sort: An alternate version of #search or #uid_search which + # sorts the results by specified keys. + # ==== +THREAD+ [RFC5256[https://tools.ietf.org/html/rfc5256]] + # - #thread, #uid_thread: An alternate version of #search or #uid_search, + # which arranges the results into ordered groups or threads according to a + # chosen algorithm. + # ==== +XLIST+ (non-standard, deprecated) + # - #xlist: replaced by +SPECIAL-USE+ attributes in #list responses. + # + # === Handling server responses + # + # - #greeting: The server's initial untagged response, which can indicate a + # pre-authenticated connection. + # - #responses: The untagged responses, as a hash. Keys are the untagged + # response type (e.g. "OK", "FETCH", "FLAGS") and response code (e.g. + # "ALERT", "UIDVALIDITY", "UIDNEXT", "TRYCREATE", etc). Values are arrays + # of UntaggedResponse or ResponseCode. + # - #add_response_handler: Add a block to be called inside the receiver thread + # with every server response. + # - #remove_response_handler: Remove a previously added response handler. + # # # == References #--