diff --git a/lib/net/imap/flags.rb b/lib/net/imap/flags.rb index bc6a94b7..a604f4d0 100644 --- a/lib/net/imap/flags.rb +++ b/lib/net/imap/flags.rb @@ -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. - # - # 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. - # - # 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. + # 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 + # specifications and begins with "\". Net::IMAP returns all + # system flags as symbols, without the "\" prefix. + # + # The descriptions here were copied from {[RFC-9051 + # §2.3.2]}[https://www.rfc-editor.org/rfc/rfc9051.html#section-2.3.2]. + # See also {[RFC-3501 + # §2.3.2]}[https://www.rfc-editor.org/rfc/rfc3501.html#section-2.3.2], + # which describes the flags message attribute semantics under + # IMAP4rev1[https://www.rfc-editor.org/rfc/rfc3501.html]. # ------------------------------------------------------------------------- + ## # Flag indicating a message has been read. SEEN = :Seen @@ -52,30 +54,32 @@ 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 "\". Net::IMAP returns all mailbox + # attributes as symbols, without the "\" prefix. # - # 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). # - # 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 descriptions here were copied from {[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]. # ------------------------------------------------------------------------- - # 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: # @@ -84,23 +88,23 @@ 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 + # 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 + # The client must treat the presence of the +\NoInferiors+ attribute as if the + # +\HasNoChildren+ attribute was also sent by the server NOINFERIORS = :Noinferiors # Mailbox attribute indicating it is not possible to use this name as a @@ -110,33 +114,33 @@ class IMAP < Protocol # 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. + # 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. + # 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 @@ -144,31 +148,34 @@ class IMAP < Protocol # 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 # ------------------------------------------------------------------------- - # :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 @@ -176,14 +183,14 @@ class IMAP < Protocol # 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 "\". Net::IMAP returns all mailbox + # attributes as symbols, without the "\" prefix. # - # 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). + # The descriptions here were copied from {[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 @@ -206,7 +213,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 @@ -223,10 +232,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