Skip to content

Commit

Permalink
📚 Document "What's here?" for Net::IMAP class [🚧 tidy up...]
Browse files Browse the repository at this point in the history
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.
  • Loading branch information
nevans committed Nov 23, 2022
1 parent dff5d5c commit 70d9af7
Showing 1 changed file with 198 additions and 0 deletions.
198 changes: 198 additions & 0 deletions lib/net/imap.rb
Original file line number Diff line number Diff line change
Expand Up @@ -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]].
# <em>Note: Net::IMAP doesn't fully support IMAP4rev2 yet.</em>
#
#--
# 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.
# <em>Some arguments require the +LIST-EXTENDED+ or +IMAP4rev2+ capability.</em>
# <em>Requires either the +ENABLE+ or +IMAP4rev2+ capability.</em>
# <em>Requires either the +NAMESPACE+ or +IMAP4rev2+ capability.</em>
# <em>Requires either the +IDLE+ or +IMAP4rev2+ capability.</em>
# <em>Requires either the +UNSELECT+ or +IMAP4rev2+ capability.</em>
# <em>Requires either the +UIDPLUS+ or +IMAP4rev2+ capability.</em>
# <em>Requires either the +MOVE+ or +IMAP4rev2+ capability.</em>
#++
#
# ==== \IMAP commands for any state
#
# - #capability: Returns the server's capabilities as an array of strings.
#
# <em>Capabilities may change after</em> #starttls, #authenticate, or #login
# <em>and cached capabilities must be reloaded.</em>
# - #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 "<em>not authenticated</em>" state:
#
# - #starttls: Upgrades a clear-text connection to use TLS.
#
# <em>Requires the +STARTTLS+ capability.</em>
# - #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.
#
# <em>Requires the <tt>AUTH=#{mechanism}</tt> capability for the chosen
# mechanism.</em>
#
# <em>The +LOGINDISABLED+ capability</em> <b>must NOT</b> <em>be listed.</em>
# - #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.
#
# <em>The +LOGINDISABLED+ capability</em> <b>must NOT</b> <em>be listed.</em>
#
# ==== \IMAP commands for the "Authenticated" state
#
# In addition to the universal commands, the following commands are valid in
# the "_authenticated_" state:
#
#--
# - #enable: <em>Not implemented by Net::IMAP, yet.</em>
#
# <em>Requires the +ENABLE+ capability.</em>
#++
# - #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.
#
# <em>Requires the +NAMESPACE+ capability.</em>
# - #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.
#
# <em>Requires the +IDLE+ capability.</em>
# - #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.
#
# <em>Requires the +UNSELECT+ capability.</em>
# - #expunge: Permanently removes messages which have the Deleted flag set.
# - #uid_expunge: Restricts #expunge to only remove the specified UIDs.
#
# <em>Requires the +UIDPLUS+ capability.</em>
# - #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.
#
# <em>Requires the +MOVE+ capability.</em>
# - #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 <em>not supported
# yet</em>, 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
#--
Expand Down

0 comments on commit 70d9af7

Please sign in to comment.