Skip to content

Commit d59fb98

Browse files
nevansnevans
authored
🔀 Merge pull request #73 from ruby/fix-mailbox-attrs
🐛 Fix mailbox attrs
2 parents 8c20002 + e622732 commit d59fb98

File tree

4 files changed

+213
-77
lines changed

4 files changed

+213
-77
lines changed

‎Gemfile‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,9 @@
1+
# frozen_string_literal: true
2+
13
source "https://rubygems.org"
24

35
gemspec
46

57
gem "rake"
8+
gem "rdoc"
69
gem "test-unit"

‎docs/styles.css‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
/* this is a work in progress. :) */
2+
3+
main .method-header {
4+
background: rgba(27,31,35,0.05);
5+
border: 1px solid #6C8C22;
6+
padding: 0.5em;
7+
border-radius: 4px;
8+
/* padding: 0 0.5em; */
9+
/* border-width: 0 1px; */
10+
/* border-color: #6C8C22; */
11+
/* border-style: solid; */
12+
}
13+
14+
main .method-description, main .aliases {
15+
padding-left: 1em;
16+
}
17+
18+
body {
19+
/*
20+
* The default (300) can be too low contrast. Also, many fonts don't
21+
* distinguish between 300->400, so <em>...</em> had no effect.
22+
*/
23+
font-weight: 400;
24+
}
25+
26+
@media only screen and (min-width: 600px) {
27+
nav {
28+
height: 100%;
29+
position: fixed;
30+
overflow-y: scroll;
31+
}
32+
33+
nav #class-metadata {
34+
margin-bottom: 5em;
35+
}
36+
}

‎lib/net/imap/flags.rb‎

Lines changed: 104 additions & 77 deletions
Original file line numberDiff line numberDiff line change
@@ -4,26 +4,28 @@ module Net
44
class IMAP < Protocol
55

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

28+
##
2729
# Flag indicating a message has been read.
2830
SEEN = :Seen
2931

@@ -52,30 +54,37 @@ class IMAP < Protocol
5254
# of this message.
5355
#
5456
# This flag was defined by
55-
# IMAP4rev1 [RFC-3501](https://www.rfc-editor.org/rfc/rfc3501.html),
56-
# and has been deprecated by
57-
# IMAP4rev2 [RFC-9051](https://www.rfc-editor.org/rfc/rfc9051.html).
57+
# IMAP4rev1[https://www.rfc-editor.org/rfc/rfc3501.html]
58+
# and is deprecated by
59+
# IMAP4rev2[https://www.rfc-editor.org/rfc/rfc9051.html].
5860
RECENT = :Recent
5961

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

76-
# The "\NonExistent" attribute indicates that a mailbox name does not refer
84+
##
85+
# The +\NonExistent+ attribute indicates that a mailbox name does not refer
7786
# to an existing mailbox. Note that this attribute is not meaningful by
78-
# itself, as mailbox names that match the canonical LIST pattern but don't
87+
# itself, as mailbox names that match the canonical #list pattern but don't
7988
# exist must not be returned unless one of the two conditions listed below
8089
# is also satisfied:
8190
#
@@ -84,106 +93,122 @@ class IMAP < Protocol
8493
# specified).
8594
#
8695
# 2. "RECURSIVEMATCH" has been specified, and the mailbox name has at least
87-
# one descendant mailbox name that does not match the LIST pattern and
96+
# one descendant mailbox name that does not match the #list pattern and
8897
# does match the selection criteria.
8998
#
90-
# In practice, this means that the "\NonExistent" attribute is usually
91-
# returned with one or more of "\Subscribed", "\Remote", "\HasChildren", or
99+
# In practice, this means that the +\NonExistent+ attribute is usually
100+
# returned with one or more of +\Subscribed+, +\Remote+, +\HasChildren+, or
92101
# the CHILDINFO extended data item.
93102
#
94-
# The client must treat the presence of the \NonExistent attribute as if the
95-
# \NoSelect attribute was also sent by the server
96-
NONEXISTENT = :NonExistent
103+
# The client must treat the presence of the +\NonExistent+ attribute as if the
104+
# +\NoSelect+ attribute was also sent by the server
105+
NONEXISTENT = :Nonexistent
97106

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

106115
# Mailbox attribute indicating it is not possible to use this name as a
107116
# selectable mailbox.
108-
NOSELECT = :Noselect
117+
NO_SELECT = :Noselect
109118

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

129138
# The presence of this attribute indicates that the mailbox has NO child
130139
# mailboxes that are accessible to the currently authenticated user.
131140
#
132-
# It is an error for the server to return both a \HasChildren and a
133-
# \HasNoChildren attribute in the same LIST response. A client that
134-
# encounters a LIST response with both \HasChildren and \HasNoChildren
135-
# attributes present should act as if both are absent in the LIST response.
141+
# It is an error for the server to return both a +\HasChildren+ and a
142+
# +\HasNoChildren+ attribute in the same #list response. A client that
143+
# encounters a #list response with both +\HasChildren+ and +\HasNoChildren+
144+
# attributes present should act as if both are absent in the #list response.
136145
#
137-
# Note: the \HasNoChildren attribute should not be confused with the
138-
# \NoInferiors attribute, which indicates that no child mailboxes exist now
139-
# and none can be created in the future.
140-
HAS_NO_CHILDREN = :HasNoChildren
146+
# Note: the +\HasNoChildren+ attribute should not be confused with the
147+
# +\NoInferiors+ attribute, which indicates that no child mailboxes exist
148+
# now and none can be created in the future.
149+
HAS_NO_CHILDREN = :Hasnochildren
141150

142151
# The mailbox has been marked "interesting" by the server; the mailbox
143152
# probably contains messages that have been added since the last time the
144153
# mailbox was selected.
145154
#
146155
# If it is not feasible for the server to determine whether or not the
147-
# mailbox is "interesting", the server SHOULD NOT send either \Marked or
148-
# \Unmarked. The server MUST NOT send more than one of \Marked, \Unmarked,
149-
# and \Noselect for a single mailbox, and it MAY send none of these.
156+
# mailbox is "interesting", the server SHOULD NOT send either +\Marked+ or
157+
# +\Unmarked+. The server MUST NOT send more than one of +\Marked+,
158+
# +\Unmarked+, and +\NoSelect+ for a single mailbox, and it MAY send none of
159+
# these.
150160
MARKED = :Marked
151161

152162
# The mailbox does not contain any additional messages since the last time
153163
# the mailbox was selected.
154164
#
155165
# If it is not feasible for the server to determine whether or not the
156-
# mailbox is "interesting", the server SHOULD NOT send either \Marked or
157-
# \Unmarked. The server MUST NOT send more than one of \Marked, \Unmarked,
158-
# and \Noselect for a single mailbox, and it MAY send none of these.
166+
# mailbox is "interesting", the server SHOULD NOT send either +\Marked+ or
167+
# +\Unmarked+. The server MUST NOT send more than one of +\Marked+,
168+
# +\Unmarked+, and +\NoSelect+ for a single mailbox, and it MAY send none of
169+
# these.
159170
UNMARKED = :Unmarked
160171

161-
# The mailbox name was subscribed to using the SUBSCRIBE command.
172+
# The mailbox name was subscribed to using the #subscribe command.
162173
SUBSCRIBED = :Subscribed
163174

164175
# The mailbox is a remote mailbox.
165176
REMOTE = :Remove
166177

178+
# Alias for NO_INFERIORS, to match the \IMAP spelling.
179+
NOINFERIORS = NO_INFERIORS
180+
# Alias for NO_SELECT, to match the \IMAP spelling.
181+
NOSELECT = NO_SELECT
182+
# Alias for HAS_CHILDREN, to match the \IMAP spelling.
183+
HASCHILDREN = HAS_CHILDREN
184+
# Alias for HAS_NO_CHILDREN, to match the \IMAP spelling.
185+
HASNOCHILDREN = HAS_NO_CHILDREN
186+
167187
# -------------------------------------------------------------------------
168-
# :section: Mailbox Name Attributes, Special Use
169-
# Mailbox name attributes will be returned in LIST responses. In addition
170-
# to the base mailbox name attributes defined above, an IMAP server MAY also
171-
# include any or all of the following attributes that denote "role" (or
188+
# :section: Mailbox role attributes
189+
#
190+
# Mailbox name attributes will be returned in #list responses. In addition
191+
# to the base mailbox name attributes defined above, an \IMAP server MAY
192+
# also include any or all of the following attributes that denote "role" (or
172193
# "special-use") of a mailbox. These attributes are included along with base
173194
# attributes defined above. A given mailbox may have none, one, or more than
174195
# one of these attributes. In some cases, a special use is advice to a
175196
# client about what to put in that mailbox. In other cases, it's advice to a
176197
# client about what to expect to find there.
177198
#
178199
# IMAP4 specifies that all mailbox name attributes, including future
179-
# extensions, begin with "\". +Net::IMAP+ returns all mailbox attributes as
180-
# symbols, without the "\" prefix.
200+
# extensions, begin with <tt>"\"</tt>. Net::IMAP returns all mailbox
201+
# attributes as symbols, without the <tt>"\"</tt> prefix.
202+
#
203+
# The special use attributes were first defined as part of the
204+
# SPECIAL-USE[https://www.rfc-editor.org/rfc/rfc6154.html] extension, but
205+
# servers may return them without including the +SPECIAL-USE+ #capability.
181206
#
182-
# The descriptions here were copied from the IMAP4rev2 specification:
183-
# [RFC-9051 § 7.3.1](https://www.rfc-editor.org/rfc/rfc9051.html#section-7.3.1).
207+
# <em>The descriptions here were copied from</em> {[RFC-9051 §
208+
# 7.3.1]}[https://www.rfc-editor.org/rfc/rfc9051.html#section-7.3.1].
184209
#
185-
# Other mailbox name attributes can be found in the [IANA IMAP Mailbox Name
186-
# Attributes registry](https://www.iana.org/assignments/imap-mailbox-name-attributes/imap-mailbox-name-attributes.xhtml)].
210+
# Other mailbox name attributes can be found in the {IANA IMAP Mailbox Name
211+
# Attributes registry}[https://www.iana.org/assignments/imap-mailbox-name-attributes/imap-mailbox-name-attributes.xhtml].
187212
# -------------------------------------------------------------------------
188213

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

209-
# FLAGGED is defined with the system flags section.
234+
#--
235+
# n.b. FLAGGED is defined in the system flags section.
236+
#++
210237

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

0 commit comments

Comments
 (0)