Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

🐛 Fix mailbox attrs #73

Merged
merged 3 commits into from
Nov 22, 2022
Merged

🐛 Fix mailbox attrs #73

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
9a8675a
📖 Add RDoc rake tasks, monkeypatches, styles
nevans Nov 9, 2022
7297a44
📚 Update message flags and mailbox attrs rdoc
nevans Nov 11, 2022
e622732
🐛 Fix incorrectly capitalized mailbox attrs
nevans Nov 11, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions Gemfile
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,9 @@
# frozen_string_literal: true

source "https://rubygems.org"

gemspec

gem "rake"
gem "rdoc"
gem "test-unit"
36 changes: 36 additions & 0 deletions docs/styles.css
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,36 @@
/* this is a work in progress. :) */

main .method-header {
background: rgba(27,31,35,0.05);
border: 1px solid #6C8C22;
padding: 0.5em;
border-radius: 4px;
/* padding: 0 0.5em; */
/* border-width: 0 1px; */
/* border-color: #6C8C22; */
/* border-style: solid; */
}

main .method-description, main .aliases {
padding-left: 1em;
}

body {
/*
* The default (300) can be too low contrast. Also, many fonts don't
* distinguish between 300->400, so <em>...</em> had no effect.
*/
font-weight: 400;
}

@media only screen and (min-width: 600px) {
nav {
height: 100%;
position: fixed;
overflow-y: scroll;
}

nav #class-metadata {
margin-bottom: 5em;
}
}
181 changes: 104 additions & 77 deletions lib/net/imap/flags.rb
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,26 +4,28 @@ module Net
class IMAP < Protocol

# -------------------------------------------------------------------------
# :section: Message Flags: system flags
# :section: System Flags
#
# A message has a list of zero or more named tokens, known as "flags",
# associated with it. A flag is set by its addition to this list and is
# cleared by its removal. There are two types of flags in IMAP4rev2: system
# flags and keywords. A flag of either type can be permanent or
# session-only.
# cleared by its removal. There are two types of flags in
# IMAP4rev1[https://www.rfc-editor.org/rfc/rfc3501.html] and
# IMAP4rev2[https://www.rfc-editor.org/rfc/rfc9051.html]: flags and
# keywords. A flag of either type can be permanent or session-only.
#
# A "system flag" is a message flag name that is predefined in the IMAP
# specification and begins with "\". +Net::IMAP+ returns all system flags
# as symbols, without the "\" prefix.
# A "system flag" is a message flag name that is predefined in the \IMAP
# specifications and begins with <tt>"\"</tt>. Net::IMAP returns all
# system flags as symbols, without the <tt>"\"</tt> prefix.
#
# The descriptions here were copied from the IMAP4rev2 specification:
# [RFC-9051 § 2.3.2](https://www.rfc-editor.org/rfc/rfc9051.html#section-2.3.2)
#
# See [RFC-3501 § 2.3.2](https://www.rfc-editor.org/rfc/rfc3501.html#section-2.3.2)
# for a description of the flags message attribute and system flag semantics
# in IMAP4rev1.
# <em>The descriptions here were copied from</em> {[RFC-9051
# §2.3.2]}[https://www.rfc-editor.org/rfc/rfc9051.html#section-2.3.2].
# <em>See also</em> {[RFC-3501
# §2.3.2]}[https://www.rfc-editor.org/rfc/rfc3501.html#section-2.3.2],
# <em>which describes the flags message attribute semantics under</em>
# IMAP4rev1[https://www.rfc-editor.org/rfc/rfc3501.html].
# -------------------------------------------------------------------------

##
# Flag indicating a message has been read.
SEEN = :Seen

Expand Down Expand Up @@ -52,30 +54,37 @@ class IMAP < Protocol
# of this message.
#
# This flag was defined by
# IMAP4rev1 [RFC-3501](https://www.rfc-editor.org/rfc/rfc3501.html),
# and has been deprecated by
# IMAP4rev2 [RFC-9051](https://www.rfc-editor.org/rfc/rfc9051.html).
# IMAP4rev1[https://www.rfc-editor.org/rfc/rfc3501.html]
# and is deprecated by
# IMAP4rev2[https://www.rfc-editor.org/rfc/rfc9051.html].
RECENT = :Recent

# -------------------------------------------------------------------------
# :section: Mailbox Name Attributes, Base attributes
# Mailbox name attributes will be returned in LIST responses. Base
# :section: Basic Mailbox Attributes
# Mailbox name attributes will be returned in #list responses. Base
# attributes must be returned according to the server's capabilities.
#
# IMAP4 specifies that all mailbox name attributes, including future
# extensions, begin with "\". +Net::IMAP+ returns all mailbox attributes as
# symbols, without the "\" prefix.
# extensions, begin with <tt>"\"</tt>. Net::IMAP returns all mailbox
# attributes as symbols, without the <tt>"\"</tt> prefix.
#
# Mailbox name attributes are not case-sensitive. <em>The current
# implementation</em> normalizes mailbox attribute case using
# String#capitalize, such as +:Noselect+ (not +:NoSelect+). The constants
# (such as NO_SELECT) can also be used for comparison. The contants have
# been defined both with and without underscores between words.
#
# The descriptions here were copied from the IMAP4rev2 specification:
# [RFC9051 § 7.3.1](https://www.rfc-editor.org/rfc/rfc9051.html#section-7.3.1).
# <em>The descriptions here were copied from</em> {[RFC-9051 §
# 7.3.1]}[https://www.rfc-editor.org/rfc/rfc9051.html#section-7.3.1].
#
# Other mailbox name attributes can be found in the [IANA IMAP Mailbox Name
# Attributes registry](https://www.iana.org/assignments/imap-mailbox-name-attributes/imap-mailbox-name-attributes.xhtml)].
# Other mailbox name attributes can be found in the {IANA IMAP Mailbox Name
# Attributes registry}[https://www.iana.org/assignments/imap-mailbox-name-attributes/imap-mailbox-name-attributes.xhtml].
# -------------------------------------------------------------------------

# The "\NonExistent" attribute indicates that a mailbox name does not refer
##
# The +\NonExistent+ attribute indicates that a mailbox name does not refer
# to an existing mailbox. Note that this attribute is not meaningful by
# itself, as mailbox names that match the canonical LIST pattern but don't
# itself, as mailbox names that match the canonical #list pattern but don't
# exist must not be returned unless one of the two conditions listed below
# is also satisfied:
#
Expand All @@ -84,106 +93,122 @@ class IMAP < Protocol
# specified).
#
# 2. "RECURSIVEMATCH" has been specified, and the mailbox name has at least
# one descendant mailbox name that does not match the LIST pattern and
# one descendant mailbox name that does not match the #list pattern and
# does match the selection criteria.
#
# In practice, this means that the "\NonExistent" attribute is usually
# returned with one or more of "\Subscribed", "\Remote", "\HasChildren", or
# In practice, this means that the +\NonExistent+ attribute is usually
# returned with one or more of +\Subscribed+, +\Remote+, +\HasChildren+, or
# the CHILDINFO extended data item.
#
# The client must treat the presence of the \NonExistent attribute as if the
# \NoSelect attribute was also sent by the server
NONEXISTENT = :NonExistent
# The client must treat the presence of the +\NonExistent+ attribute as if the
# +\NoSelect+ attribute was also sent by the server
NONEXISTENT = :Nonexistent

# Mailbox attribute indicating it is not possible for any child levels of
# hierarchy to exist under this name; no child levels exist now and none can
# be created in the future children.
#
# The client must treat the presence of the \NoInferiors attribute as if the
# \HasNoChildren attribute was also sent by the server
NOINFERIORS = :Noinferiors
# The client must treat the presence of the +\NoInferiors+ attribute as if the
# +\HasNoChildren+ attribute was also sent by the server
NO_INFERIORS = :Noinferiors

# Mailbox attribute indicating it is not possible to use this name as a
# selectable mailbox.
NOSELECT = :Noselect
NO_SELECT = :Noselect

# The presence of this attribute indicates that the mailbox has child
# mailboxes. A server SHOULD NOT set this attribute if there are child
# mailboxes and the user does not have permission to access any of them. In
# this case, \HasNoChildren SHOULD be used. In many cases, however, a server
# may not be able to efficiently compute whether a user has access to any
# child mailboxes. Note that even though the \HasChildren attribute for a
# mailbox must be correct at the time of processing the mailbox, a client
# must be prepared to deal with a situation when a mailbox is marked with
# the \HasChildren attribute, but no child mailbox appears in the response
# to the LIST command. This might happen, for example, due to child
# this case, +\HasNoChildren+ SHOULD be used. In many cases, however, a
# server may not be able to efficiently compute whether a user has access to
# any child mailboxes. Note that even though the +\HasChildren+ attribute
# for a mailbox must be correct at the time of processing the mailbox, a
# client must be prepared to deal with a situation when a mailbox is marked
# with the +\HasChildren+ attribute, but no child mailbox appears in the
# response to the #list command. This might happen, for example, due to child
# mailboxes being deleted or made inaccessible to the user (using access
# control) by another client before the server is able to list them.
#
# It is an error for the server to return both a \HasChildren and a
# \HasNoChildren attribute in the same LIST response. A client that
# encounters a LIST response with both \HasChildren and \HasNoChildren
# attributes present should act as if both are absent in the LIST response.
HAS_CHILDREN = :HasChildren
# It is an error for the server to return both a +\HasChildren+ and a
# +\HasNoChildren+ attribute in the same #list response. A client that
# encounters a #list response with both +\HasChildren+ and +\HasNoChildren+
# attributes present should act as if both are absent in the #list response.
HAS_CHILDREN = :Haschildren

# The presence of this attribute indicates that the mailbox has NO child
# mailboxes that are accessible to the currently authenticated user.
#
# It is an error for the server to return both a \HasChildren and a
# \HasNoChildren attribute in the same LIST response. A client that
# encounters a LIST response with both \HasChildren and \HasNoChildren
# attributes present should act as if both are absent in the LIST response.
# It is an error for the server to return both a +\HasChildren+ and a
# +\HasNoChildren+ attribute in the same #list response. A client that
# encounters a #list response with both +\HasChildren+ and +\HasNoChildren+
# attributes present should act as if both are absent in the #list response.
#
# Note: the \HasNoChildren attribute should not be confused with the
# \NoInferiors attribute, which indicates that no child mailboxes exist now
# and none can be created in the future.
HAS_NO_CHILDREN = :HasNoChildren
# Note: the +\HasNoChildren+ attribute should not be confused with the
# +\NoInferiors+ attribute, which indicates that no child mailboxes exist
# now and none can be created in the future.
HAS_NO_CHILDREN = :Hasnochildren

# The mailbox has been marked "interesting" by the server; the mailbox
# probably contains messages that have been added since the last time the
# mailbox was selected.
#
# If it is not feasible for the server to determine whether or not the
# mailbox is "interesting", the server SHOULD NOT send either \Marked or
# \Unmarked. The server MUST NOT send more than one of \Marked, \Unmarked,
# and \Noselect for a single mailbox, and it MAY send none of these.
# mailbox is "interesting", the server SHOULD NOT send either +\Marked+ or
# +\Unmarked+. The server MUST NOT send more than one of +\Marked+,
# +\Unmarked+, and +\NoSelect+ for a single mailbox, and it MAY send none of
# these.
MARKED = :Marked

# The mailbox does not contain any additional messages since the last time
# the mailbox was selected.
#
# If it is not feasible for the server to determine whether or not the
# mailbox is "interesting", the server SHOULD NOT send either \Marked or
# \Unmarked. The server MUST NOT send more than one of \Marked, \Unmarked,
# and \Noselect for a single mailbox, and it MAY send none of these.
# mailbox is "interesting", the server SHOULD NOT send either +\Marked+ or
# +\Unmarked+. The server MUST NOT send more than one of +\Marked+,
# +\Unmarked+, and +\NoSelect+ for a single mailbox, and it MAY send none of
# these.
UNMARKED = :Unmarked

# The mailbox name was subscribed to using the SUBSCRIBE command.
# The mailbox name was subscribed to using the #subscribe command.
SUBSCRIBED = :Subscribed

# The mailbox is a remote mailbox.
REMOTE = :Remove

# Alias for NO_INFERIORS, to match the \IMAP spelling.
NOINFERIORS = NO_INFERIORS
# Alias for NO_SELECT, to match the \IMAP spelling.
NOSELECT = NO_SELECT
# Alias for HAS_CHILDREN, to match the \IMAP spelling.
HASCHILDREN = HAS_CHILDREN
# Alias for HAS_NO_CHILDREN, to match the \IMAP spelling.
HASNOCHILDREN = HAS_NO_CHILDREN

# -------------------------------------------------------------------------
# :section: Mailbox Name Attributes, Special Use
# Mailbox name attributes will be returned in LIST responses. In addition
# to the base mailbox name attributes defined above, an IMAP server MAY also
# include any or all of the following attributes that denote "role" (or
# :section: Mailbox role attributes
#
# Mailbox name attributes will be returned in #list responses. In addition
# to the base mailbox name attributes defined above, an \IMAP server MAY
# also include any or all of the following attributes that denote "role" (or
# "special-use") of a mailbox. These attributes are included along with base
# attributes defined above. A given mailbox may have none, one, or more than
# one of these attributes. In some cases, a special use is advice to a
# client about what to put in that mailbox. In other cases, it's advice to a
# client about what to expect to find there.
#
# IMAP4 specifies that all mailbox name attributes, including future
# extensions, begin with "\". +Net::IMAP+ returns all mailbox attributes as
# symbols, without the "\" prefix.
# extensions, begin with <tt>"\"</tt>. Net::IMAP returns all mailbox
# attributes as symbols, without the <tt>"\"</tt> prefix.
#
# The special use attributes were first defined as part of the
# SPECIAL-USE[https://www.rfc-editor.org/rfc/rfc6154.html] extension, but
# servers may return them without including the +SPECIAL-USE+ #capability.
#
# The descriptions here were copied from the IMAP4rev2 specification:
# [RFC-9051 § 7.3.1](https://www.rfc-editor.org/rfc/rfc9051.html#section-7.3.1).
# <em>The descriptions here were copied from</em> {[RFC-9051 §
# 7.3.1]}[https://www.rfc-editor.org/rfc/rfc9051.html#section-7.3.1].
#
# Other mailbox name attributes can be found in the [IANA IMAP Mailbox Name
# Attributes registry](https://www.iana.org/assignments/imap-mailbox-name-attributes/imap-mailbox-name-attributes.xhtml)].
# Other mailbox name attributes can be found in the {IANA IMAP Mailbox Name
# Attributes registry}[https://www.iana.org/assignments/imap-mailbox-name-attributes/imap-mailbox-name-attributes.xhtml].
# -------------------------------------------------------------------------

# Mailbox attribute indicating that this mailbox presents all messages in
Expand All @@ -206,7 +231,9 @@ class IMAP < Protocol
# client put drafts here
DRAFTS = :Drafts

# FLAGGED is defined with the system flags section.
#--
# n.b. FLAGGED is defined in the system flags section.
#++

# Mailbox attribute indicating that this mailbox is where messages deemed to
# be junk mail are held. Some server implementations might put messages here
Expand All @@ -223,10 +250,10 @@ class IMAP < Protocol
# Mailbox attribute indicating that this mailbox is used to hold messages
# that have been deleted or marked for deletion. In some server
# implementations, this might be a virtual mailbox, containing messages from
# other mailboxes that are marked with the "\Deleted" message flag.
# other mailboxes that are marked with the +\Deleted+ message flag.
# Alternatively, this might just be advice that a client that chooses not to
# use the IMAP "\Deleted" model should use as its trash location. In server
# implementations that strictly expect the IMAP "\Deleted" model, this
# use the \IMAP +\Deleted+ model should use as its trash location. In server
# implementations that strictly expect the \IMAP +\Deleted+ model, this
# special use is likely not to be supported.
TRASH = :Trash

Expand Down
Loading