Update style in documentation (#822)

This commit is contained in:
Daniel Eggert authored and GitHub committed 2026-04-28 18:06:43 +02:00
1 parent 9c56edfa19
commit 34883bcba6
151 files changed
+580 -590

No files matched your search

@@ -152,7 +152,7 @@ extension EncodeBuffer {
}
/// Writes a collection of bytes in the `literal8` syntax defined in RFC 3516.
/// This function allows the `null` byte `\0` to be written.
/// Allows the `null` byte `\0` to be written.
/// - parameters:
/// - bytes: The raw bytes to write to `self`.
/// - returns: The number of bytes written.
@@ -36,7 +36,7 @@ import struct NIO.ByteBuffer
public struct CommandEncodeBuffer: Hashable, Sendable {
/// The underlying buffer containing data to be written.
///
/// This provides access to the raw ``EncodeBuffer`` for advanced operations,
/// Provides access to the raw ``EncodeBuffer`` for advanced operations,
/// though most users should interact through the public API of `CommandEncodeBuffer`.
@_spi(NIOIMAPInternal) public var buffer: EncodeBuffer
@@ -68,7 +68,7 @@ public struct CommandEncodeBuffer: Hashable, Sendable {
extension CommandEncodeBuffer {
/// The encoding options currently in use.
///
/// These options determine how protocol elements are encoded (e.g., whether to use
/// These options determine how protocol elements are encoded (for example, whether to use
/// quoted strings, which literal formats are supported). You can modify these
/// options at runtime to change encoding behavior for subsequent write operations.
///
@@ -88,7 +88,7 @@ extension CommandEncodeBuffer {
/// Creates a new command encoding buffer from server capabilities.
///
/// This initializer converts a list of ``Capability`` values into ``CommandEncodingOptions``,
/// Converts a list of ``Capability`` values into ``CommandEncodingOptions``,
/// which automatically enables extended literal formats and binary support if the
/// server advertises the corresponding capabilities.
///
@@ -53,7 +53,7 @@ public struct CommandEncodingOptions: Hashable, Sendable {
/// Use the RFC 3501 synchronizing literal format (`{20}\r\n`).
///
/// This is the standard literal format that requires the server to send a `+`
/// The standard literal format that requires the server to send a `+`
/// continuation request before the client sends the literal data. Set to `true`
/// for RFC 3501-compliant encoding.
///
@@ -82,7 +82,7 @@ public struct CommandEncodingOptions: Hashable, Sendable {
/// Use binary content literals (`~{20}\r\n`).
///
/// This format is defined in RFC 3516 and allows sending arbitrary binary data.
/// Defined in RFC 3516, this format allows sending arbitrary binary data.
/// Note that binary literals can only be used in certain contexts, such as the
/// `APPEND` command with the `BINARY` extension.
///
@@ -142,7 +142,7 @@ public struct CommandEncodingOptions: Hashable, Sendable {
extension CommandEncodingOptions {
/// Creates encoding options by inspecting server capabilities.
///
/// This initializer automatically enables extended literal formats based on
/// Automatically enables extended literal formats based on
/// server capabilities, making it easy to use the best available encoding strategy.
///
/// The initialization process:
+4 -4
View File
@@ -22,7 +22,7 @@ import struct NIO.CircularBuffer
/// that can be transmitted over the network. It wraps a `ByteBuffer` and tracks
/// encoding state, supporting both client commands and server responses.
///
/// This type is part of the internal SPI and is primarily used by:
/// Part of the internal SPI and is primarily used by:
/// - ``CommandEncodeBuffer`` for encoding client commands
/// - ``ResponseEncodeBuffer`` for encoding server responses
///
@@ -43,7 +43,7 @@ import struct NIO.CircularBuffer
@_spi(NIOIMAPInternal) public struct EncodeBuffer: Hashable, Sendable {
/// Determines whether the buffer encodes for a client or server.
///
/// This affects how the buffer formats protocol elements like literals, strings,
/// Affects how the buffer formats protocol elements like literals, strings,
/// and response codes. The mode also carries encoding options specific to each role.
public enum Mode: Hashable, Sendable {
/// Encodes client commands using the specified options.
@@ -67,7 +67,7 @@ import struct NIO.CircularBuffer
///
/// When `true`, methods like ``writeBytes(_:)`` and ``writeBuffer(_:)`` will
/// write placeholder text like `[N bytes]` instead of the actual binary content.
/// This is useful for logging and debugging without exposing sensitive data.
/// Useful for logging and debugging without exposing sensitive data.
public var loggingMode: Bool
internal var mode: Mode
@@ -159,7 +159,7 @@ extension EncodeBuffer {
public struct Chunk: Hashable, Sendable {
/// The encoded bytes ready to write to the network.
///
/// This buffer contains the next portion of IMAP protocol data to transmit.
/// Contains the next portion of IMAP protocol data to transmit.
public var bytes: ByteBuffer
/// Whether a continuation request (`+`) should be expected before sending the next chunk.
@@ -40,7 +40,7 @@
/// Result: imap://user@example.com/INBOX/;uid=20
/// ```
///
/// ## Related Types
/// ## Related types
///
/// - ``RelativeIMAPURL`` uses absolute message paths as one variant of relative URLs
/// - ``URLCommand`` specifies the fetch operation details
+2 -2
View File
@@ -20,7 +20,7 @@ import struct NIO.ByteBuffer
/// It restricts which users or sessions are permitted to access the message data referenced by the URL.
/// Each ``AuthenticatedURLRump`` includes an access identifier that determines authorization policy.
///
/// ### Access Types
/// ### Access types
///
/// - ``anonymous``: Any user, including non-authenticated sessions, may access the URL
/// - ``authenticateUser``: Only authenticated (non-anonymous) sessions may access the URL
@@ -46,7 +46,7 @@ import struct NIO.ByteBuffer
///
/// Only sessions authenticated as "fred" may use this URL.
///
/// ## Related Types
/// ## Related types
///
/// See ``AuthenticatedURLRump`` for how access identifiers are combined with expiration dates,
/// ``AuthenticatedURLVerifier`` for the verification token, and ``AuthenticatedURL`` for
@@ -61,7 +61,7 @@ public struct AppendData: Hashable, Sendable {
/// not MIME content-transfer-encoded.
///
/// When `false` (default), the data is sent using standard literal syntax `{size}`,
/// indicating the bytes are MIME content-transfer-encoded (e.g., base64 for binary content).
/// indicating the bytes are MIME content-transfer-encoded (for example, base64 for binary content).
///
/// **Requires server capability:** ``Capability/binary`` (when `true`)
///
@@ -25,7 +25,7 @@ import struct NIO.ByteBuffer
/// Attribute flags are case-insensitive for comparison but preserve their original casing when transmitted.
/// They are normalized to lowercase for comparison.
///
/// ### Standard Attribute Flags
/// ### Standard attribute flags
///
/// - ``answered`` - The message has been replied to.
/// - ``flagged`` - The message has been marked for attention.
@@ -69,7 +69,7 @@ public struct AttributeFlag: Hashable, Sendable {
/// The provided string is automatically lowercased to normalize the flag value, allowing case-insensitive
/// comparison while preserving the original casing for transmission.
///
/// - parameter stringValue: The flag string (e.g., `"\\Answered"`, `"\\SEEN"`). Will be lowercased.
/// - parameter stringValue: The flag string (for example, `"\\Answered"` or `"\\SEEN"`). Will be lowercased.
public init(_ stringValue: String) {
self.stringValue = stringValue.lowercased()
}
@@ -18,7 +18,7 @@
/// IMAP URL. It pairs the authorization parameters (expiration and access) with the verification
/// information (mechanism and token).
///
/// This type represents the `;URLAUTH=<access>:<mechanism>:<token>` component appended to IMAP URLs
/// The `;URLAUTH=<access>:<mechanism>:<token>` component is appended to IMAP URLs
/// according to RFC 4467. It is used when:
///
/// 1. **Generating URLAUTH URLs** (GENURLAUTH command): Server creates authorization information
@@ -63,7 +63,7 @@
/// S: a002 OK URLFETCH completed
/// ```
///
/// ## Related Types
/// ## Related types
///
/// - ``AuthenticatedURLRump`` provides expiration and access information
/// - ``AuthenticatedURLVerifier`` provides mechanism and token for verification
@@ -22,7 +22,7 @@
/// Together, ``AuthenticatedURLRump`` and ``AuthenticatedURLVerifier`` form a complete
/// ``AuthenticatedURL`` that defines all authorization parameters for a URLAUTH-authorized URL.
///
/// ### URLAUTH Format
/// ### URLAUTH format
///
/// A complete URLAUTH component has the form:
/// ```
@@ -58,7 +58,7 @@
/// imap://owner@example.com/INBOX/;uid=20;EXPIRE=2025-12-31T23:59:59Z;URLAUTH=anonymous:internal:TOKEN
/// ```
///
/// ## Related Types
/// ## Related types
///
/// - ``Expire`` wraps the optional expiration date
/// - ``Access`` defines the access identifier
@@ -22,7 +22,7 @@
/// The verifier allows the IMAP server to validate that the URL has been properly authorized
/// by verifying the token using the specified mechanism and a stored mailbox access key.
///
/// ### Verification Process (RFC 4467 Section 6)
/// ### Verification process (RFC 4467 Section 6)
///
/// When a URLFETCH command is issued with a URLAUTH-authorized URL:
///
@@ -49,7 +49,7 @@
/// S: * URLFETCH ("imap://user@example.com/INBOX/;uid=20;urlauth=anonymous:internal:91354a473744909de610943775f92038" "message-data")
/// ```
///
/// ## Related Types
/// ## Related types
///
/// - ``URLAuthenticationMechanism`` specifies the token generation algorithm
/// - ``EncodedAuthenticatedURL`` wraps the hexadecimal-encoded token
@@ -60,7 +60,7 @@ public struct AuthenticationMechanism: Hashable, Sendable {
///
/// The provided value is uppercased for consistency with IMAP protocol conventions.
///
/// - parameter value: The mechanism name (e.g., PLAIN, GSSAPI).
/// - parameter value: The mechanism name (for example, PLAIN or GSSAPI).
public init(_ value: String) {
self.rawValue = value.uppercased()
}
+4 -4
View File
@@ -51,7 +51,7 @@ extension MessageAttribute {
/// S: A001 OK FETCH completed
/// ```
///
/// This represents a ``singlepart(_:)`` case containing a ``Singlepart`` with media type `text/plain`.
/// The response is a ``singlepart(_:)`` case containing a ``Singlepart`` with media type `text/plain`.
///
/// **Multipart message:**
/// ```
@@ -60,7 +60,7 @@ extension MessageAttribute {
/// S: A002 OK FETCH completed
/// ```
///
/// This represents a ``multipart(_:)`` case containing two parts (text/plain and text/html) with media subtype `alternative`.
/// The response is a ``multipart(_:)`` case containing two parts (text/plain and text/html) with media subtype `alternative`.
///
/// - SeeAlso: [RFC 3501 Section 7.4.2](https://datatracker.ietf.org/doc/html/rfc3501#section-7.4.2)
/// - SeeAlso: [RFC 3501 Section 2.6.3](https://datatracker.ietf.org/doc/html/rfc3501#section-2.6.3)
@@ -74,7 +74,7 @@ public enum BodyStructure: Hashable, Sendable {
/// A multipart message body containing one or more sub-parts.
///
/// Multipart messages have multiple MIME parts (e.g., `multipart/mixed` for mixed content,
/// Multipart messages have multiple MIME parts (such as `multipart/mixed` for mixed content or
/// `multipart/alternative` for alternative representations).
case multipart(Multipart)
}
@@ -101,7 +101,7 @@ extension BodyStructure: RandomAccessCollection {
/// Gets the body at the given `position`.
///
/// This will assert if `position` is not a valid part of this ``BodyStructure``.
/// Crashes if `position` is not a valid part of this ``BodyStructure``.
///
/// - parameter position: The position of the desired body.
/// - returns: The body located at the given `position`.
@@ -26,8 +26,7 @@ extension BodyStructure {
public struct DispositionKind: Hashable, RawRepresentable, Sendable {
/// The `inline` disposition, indicating the part should be displayed as part of the message body.
///
/// This is the default disposition when not specified. Inline parts are typically displayed automatically
/// by mail clients as part of the message preview.
/// The default disposition when not specified.
public static let inline = Self(rawValue: "inline")
/// The `attachment` disposition, indicating the part should be treated as a downloadable attachment.
@@ -43,7 +42,7 @@ extension BodyStructure {
/// The provided string is automatically lowercased to normalize the disposition value, allowing
/// case-insensitive comparison.
///
/// - parameter rawValue: The disposition kind (e.g., `"inline"`, `"attachment"`). Will be lowercased.
/// - parameter rawValue: The disposition kind (for example, `"inline"` or `"attachment"`). Will be lowercased.
public init(rawValue: String) {
self.rawValue = rawValue.lowercased()
}
@@ -74,7 +73,7 @@ extension BodyStructure {
/// - SeeAlso: [RFC 2183](https://datatracker.ietf.org/doc/html/rfc2183)
/// - SeeAlso: [RFC 3501 Section 7.4.2](https://datatracker.ietf.org/doc/html/rfc3501#section-7.4.2)
public struct Disposition: Hashable, Sendable {
/// The disposition kind (e.g., `inline` or `attachment`).
/// The disposition kind, such as `inline` or `attachment`.
public var kind: DispositionKind
/// Optional parameters associated with the disposition.
@@ -86,7 +85,7 @@ extension BodyStructure {
/// Creates a new disposition.
///
/// - parameter kind: The disposition kind (`inline` or `attachment`).
/// - parameter parameters: An ordered dictionary of disposition parameters (e.g., filename, size).
/// - parameter parameters: An ordered dictionary of disposition parameters (for example, filename and size).
public init(kind: DispositionKind, parameters: OrderedDictionary<String, String>) {
self.kind = kind
self.parameters = parameters
@@ -112,7 +111,6 @@ extension BodyStructure {
/// The `filename` parameter value, if present.
///
/// The `filename` parameter provides a recommended filename for saving the message part to disk.
/// This is commonly used for attachment parts.
///
/// - Returns: The filename string, or `nil` if the parameter is not present.
public var filename: String? {
@@ -17,12 +17,10 @@ import struct NIO.ByteBuffer
extension BodyStructure {
/// Content disposition and language information for a message part.
///
/// This type pairs optional content disposition (indicating how the part should be handled) with optional
/// Pairs optional content disposition (indicating how the part should be handled) with optional
/// language and location information. Both are optional fields in the body structure defined in
/// [RFC 3501 Section 7.4.2](https://datatracker.ietf.org/doc/html/rfc3501#section-7.4.2).
///
/// This is an API abstraction to simplify working with the disposition and language/location pairing from the raw IMAP message.
///
/// ### Example
///
/// ```
@@ -69,7 +69,7 @@ extension BodyStructure {
/// The encoding as an uppercase string.
///
/// - Returns: The encoding name in uppercase (e.g., `"7BIT"`, `"BASE64"`, `"QUOTED-PRINTABLE"`).
/// - Returns: The encoding name in uppercase, for example `"7BIT"`, `"BASE64"`, or `"QUOTED-PRINTABLE"`.
public var debugDescription: String { stringValue }
/// Creates a new encoding from a string representation.
@@ -77,7 +77,7 @@ extension BodyStructure {
/// The provided string is automatically uppercased to normalize the encoding value. This allows
/// case-insensitive comparison between encoding values.
///
/// - parameter stringValue: The encoding name as a string (e.g., `"7bit"`, `"base64"`). Will be uppercased.
/// - parameter stringValue: The encoding name as a string (for example, `"7bit"` or `"base64"`). Will be uppercased.
public init(_ stringValue: String) {
self.stringValue = stringValue.uppercased()
}
@@ -23,7 +23,7 @@ extension BodyStructure {
/// transfer encoding, and octet count.
///
/// These fields are derived from MIME headers (`Content-Type`, `Content-Transfer-Encoding`,
/// etc.) and are essential for understanding how to process each message part.
/// and so on) and are essential for understanding how to process each message part.
///
/// ### Example
///
@@ -58,7 +58,7 @@ extension BodyStructure {
/// The content transfer encoding from the `Content-Transfer-Encoding` header.
///
/// Describes how the message part is encoded (e.g., `7bit`, `base64`, `quoted-printable`).
/// Describes how the message part is encoded (for example, `7bit`, `base64`, or `quoted-printable`).
public var encoding: Encoding?
/// The size of the body part in octets (bytes).
@@ -17,13 +17,11 @@ import struct NIO.ByteBuffer
extension BodyStructure {
/// Language and content location information for a message part.
///
/// This type pairs one or more language identifiers with an optional content location URI. The language values
/// Pairs one or more language identifiers with an optional content location URI. The language values
/// follow [BCP 47](https://datatracker.ietf.org/doc/html/bcp47) language tags and the location follows
/// [RFC 2557](https://datatracker.ietf.org/doc/html/rfc2557) for MIME content location URIs. Both are optional
/// fields in the body structure defined in [RFC 3501 Section 7.4.2](https://datatracker.ietf.org/doc/html/rfc3501#section-7.4.2).
///
/// This is an API abstraction to simplify working with the language/location pairing from the raw IMAP message.
///
/// ### Example
///
/// ```
@@ -42,7 +40,7 @@ extension BodyStructure {
/// One or more language identifiers for the message part.
///
/// Language values follow [BCP 47](https://datatracker.ietf.org/doc/html/bcp47) language tag format
/// (e.g., `"en"` for English, `"en-US"` for US English, `"fr"` for French).
/// (for example, `"en"` for English, `"en-US"` for US English, or `"fr"` for French).
public var languages: [String]
/// Optional content location URI for the message part.
@@ -17,15 +17,13 @@ import struct NIO.ByteBuffer
extension BodyStructure {
/// Content location URI and future extension fields for a message part.
///
/// This type pairs a content location URI (defined in [RFC 2557](https://datatracker.ietf.org/doc/html/rfc2557))
/// Pairs a content location URI (defined in [RFC 2557](https://datatracker.ietf.org/doc/html/rfc2557))
/// with a list of future extension fields. The location provides a URI where the message part content can be
/// retrieved, and extensions allow servers to add new fields without breaking existing clients.
///
/// Both the location and extensions are optional fields in the body structure defined in
/// [RFC 3501 Section 7.4.2](https://datatracker.ietf.org/doc/html/rfc3501#section-7.4.2).
///
/// This is an API abstraction to simplify working with the location/extension pairing from the raw IMAP message.
///
/// ### Example
///
/// ```
@@ -20,8 +20,8 @@ extension BodyStructure {
///
/// A multipart body represents a message divided into multiple MIME parts. Common multipart types include:
/// - `multipart/mixed`: Parts with different media types mixed together
/// - `multipart/alternative`: Alternative representations of the same content (e.g., plain text and HTML)
/// - `multipart/related`: Parts that reference each other (e.g., HTML with embedded images)
/// - `multipart/alternative`: Alternative representations of the same content (such as plain text and HTML)
/// - `multipart/related`: Parts that reference each other (such as HTML with embedded images)
///
/// Each part in a multipart body is itself a ``BodyStructure``, which may be another multipart, creating
/// arbitrarily deep nesting. Optional extension fields provide forward compatibility with future extensions.
@@ -32,7 +32,7 @@ extension BodyStructure {
/// (("text" "plain" ("charset" "us-ascii") NIL NIL "7bit" 1234 20) ("text" "html" ("charset" "us-ascii") NIL NIL "7bit" 5678 45) "alternative")
/// ```
///
/// This is parsed as a ``Multipart`` with two parts (text/plain and text/html) and media subtype `alternative`.
/// The wire format above is parsed as a ``Multipart`` with two parts (text/plain and text/html) and media subtype `alternative`.
///
/// - SeeAlso: [RFC 3501 Section 6.4.5](https://datatracker.ietf.org/doc/html/rfc3501#section-6.4.5)
/// - SeeAlso: [RFC 2045](https://datatracker.ietf.org/doc/html/rfc2045)
@@ -43,7 +43,7 @@ extension BodyStructure {
/// Parts may be accessed using ``SectionSpecifier/Part`` indices.
public var parts: [BodyStructure]
/// The multipart subtype (e.g., `mixed` for `multipart/mixed`, `alternative` for `multipart/alternative`).
/// The multipart subtype (for example, `mixed` for `multipart/mixed` or `alternative` for `multipart/alternative`).
///
/// The subtype indicates how the parts should be interpreted or presented.
public var mediaSubtype: Media.Subtype
@@ -56,7 +56,7 @@ extension BodyStructure {
/// Creates a new multipart body.
/// - parameter parts: The MIME parts that comprise this multipart
/// - parameter mediaSubtype: The multipart subtype (e.g., `mixed`, `alternative`)
/// - parameter mediaSubtype: The multipart subtype (for example, `mixed` or `alternative`)
/// - parameter extension: Optional extension fields (defaults to `nil`)
public init(parts: [BodyStructure], mediaSubtype: Media.Subtype, extension: Extension? = nil) {
self.parts = parts
@@ -73,7 +73,7 @@ extension BodyStructure.Multipart {
/// (parameters and optional disposition/language information) to support future extensions
/// without breaking existing clients.
public struct Extension: Hashable, Sendable {
/// MIME parameters for the multipart structure itself (e.g., `boundary` parameter).
/// MIME parameters for the multipart structure itself (for example, the `boundary` parameter).
///
/// Contains key/value pairs as an ordered dictionary, preserving the server's order.
public var parameters: OrderedDictionary<String, String>
@@ -18,7 +18,7 @@ extension BodyStructure {
/// A single-part MIME message body as defined in RFC 3501.
///
/// A single-part body represents a message containing only one MIME part. This includes simple
/// media types (e.g., `text/plain`, `image/jpeg`), the `message/rfc822` encapsulated message type,
/// media types (for example, `text/plain` or `image/jpeg`), the `message/rfc822` encapsulated message type,
/// and text-specific types. Single-part bodies may have optional extension fields for forward compatibility.
///
/// ### Example
@@ -27,7 +27,7 @@ extension BodyStructure {
/// ("text" "plain" ("charset" "us-ascii") NIL NIL "7bit" 3445 65)
/// ```
///
/// This is parsed as a ``Singlepart`` with `kind: .text(...)`, `fields: Fields(...)`, and no extension.
/// The wire format above is parsed as a ``Singlepart`` with `kind: .text(...)`, `fields: Fields(...)`, and no extension.
///
/// - SeeAlso: [RFC 3501 Section 2.6.3](https://datatracker.ietf.org/doc/html/rfc3501#section-2.6.3)
/// - SeeAlso: ``Kind``
@@ -65,19 +65,19 @@ extension BodyStructure.Singlepart {
/// Represents the three main kinds of single-part bodies: basic media types, encapsulated messages,
/// and text-specific types. Each kind may have additional properties specific to that type.
public indirect enum Kind: Hashable, Sendable {
/// A simple, non-message media type (e.g., `image/jpeg`, `application/pdf`).
/// A simple, non-message media type (for example, `image/jpeg` or `application/pdf`).
///
/// The associated ``Media/MediaType`` specifies the exact MIME type and subtype.
case basic(Media.MediaType)
/// An encapsulated RFC 822 email message (e.g., `message/rfc822`).
/// An encapsulated RFC 822 email message (for example, `message/rfc822`).
///
/// The associated ``Message`` contains the envelope and nested body of the embedded message.
case message(Message)
/// A text-specific body type with optional line count information.
///
/// The associated ``Text`` specifies the text subtype (e.g., `plain` or `html`).
/// The associated ``Text`` specifies the text subtype (for example, `plain` or `html`).
case text(Text)
}
@@ -94,12 +94,10 @@ extension BodyStructure.Singlepart {
/// The hierarchical body structure of the embedded message.
///
/// This may itself be multipart, creating arbitrarily deep nesting of messages.
/// May itself be multipart, creating arbitrarily deep nesting of messages.
public var body: BodyStructure
/// The number of lines in the message (per RFC 2045/RFC 3501).
///
/// This is the line count of the message in its canonical form.
public var lineCount: Int
/// Creates a new encapsulated message.
@@ -117,10 +115,10 @@ extension BodyStructure.Singlepart {
/// A text-specific body part with MIME type `text/*` (RFC 3501).
///
/// Text bodies are specialized single-part bodies with a specific subtype (e.g., `plain`, `html`)
/// Text bodies are specialized single-part bodies with a specific subtype (for example, `plain` or `html`)
/// and an associated line count.
public struct Text: Hashable, Sendable {
/// The text subtype (e.g., `plain` for `text/plain`, `html` for `text/html`).
/// The text subtype (for example, `plain` for `text/plain` or `html` for `text/html`).
public var mediaSubtype: Media.Subtype
/// The number of lines in the text body (per RFC 2045/RFC 3501).
@@ -129,7 +127,7 @@ extension BodyStructure.Singlepart {
public var lineCount: Int
/// Creates a new text body.
/// - parameter mediaSubtype: The text subtype (e.g., `plain` or `html`)
/// - parameter mediaSubtype: The text subtype (for example, `plain` or `html`)
/// - parameter lineCount: The number of lines in the text
public init(mediaSubtype: Media.Subtype, lineCount: Int) {
self.mediaSubtype = mediaSubtype
@@ -15,7 +15,7 @@
extension MessagePath {
/// A byte range suffix for partial IMAP URL fetches.
///
/// This type wraps a ``/NIOIMAPCore/ByteRange`` for use in IMAP URLs with the `/;PARTIAL=` encoding
/// Wraps a ``/NIOIMAPCore/ByteRange`` for use in IMAP URLs with the `/;PARTIAL=` encoding
/// (RFC 5092). It enables clients to request only a portion of a message via URL without
/// downloading the entire body.
///
+12 -12
View File
@@ -30,7 +30,7 @@ import struct NIO.ByteBuffer
/// S: * CAPABILITY IMAP4rev1 STARTTLS AUTH=GSSAPI XPIG-LATIN
/// ```
///
/// This server response advertises capabilities: `IMAP4rev1` (simple), `STARTTLS` (simple), `AUTH=GSSAPI`
/// The server response advertises capabilities: `IMAP4rev1` (simple), `STARTTLS` (simple), `AUTH=GSSAPI`
/// (configurable with name `AUTH` and value `GSSAPI`), and `XPIG-LATIN` (custom vendor extension).
///
/// - SeeAlso: [RFC 3501 Section 7.2.1](https://datatracker.ietf.org/doc/html/rfc3501#section-7.2.1)
@@ -50,9 +50,9 @@ public struct Capability: Hashable, Sendable {
return String(self.rawValue[..<index])
}
/// If the capability is _simple_, e.g. `STARTTLS`, then the value will be `nil`.
/// Otherwise, if the capability is configurable such as `AUTH=GSSAPI`, then the value will
/// be `GSSAPI`.
/// If the capability is _simple_, for example `STARTTLS`, the value is `nil`.
/// Otherwise, if the capability is configurable such as `AUTH=GSSAPI`, the value
/// is `GSSAPI`.
public var value: String? {
guard var index = self.splitIndex else {
return nil
@@ -63,7 +63,7 @@ public struct Capability: Hashable, Sendable {
}
/// Creates a new capability from a `String`, and parses any configuration if present.
/// - parameter value: The raw `String` value of the capability, e.g. *STARTTLS* or *AUTH=GSSAPI*.
/// - parameter value: The raw `String` value of the capability, for example `STARTTLS` or `AUTH=GSSAPI`.
public init(_ value: String) {
self.init(unchecked: value)
}
@@ -98,7 +98,7 @@ extension Capability {
///
/// The provided value is uppercased for consistency with IMAP protocol conventions.
///
/// - parameter value: The context kind as a string (e.g., SEARCH, SORT).
/// - parameter value: The context kind as a string (for example, SEARCH or SORT).
public init(_ value: String) {
self.rawValue = value.uppercased()
}
@@ -125,7 +125,7 @@ extension Capability {
///
/// The provided value is uppercased for consistency with IMAP protocol conventions.
///
/// - parameter value: The sort kind as a string (e.g., DISPLAY).
/// - parameter value: The sort kind as a string (for example, DISPLAY).
public init(_ value: String) {
self.rawValue = value.uppercased()
}
@@ -155,7 +155,7 @@ extension Capability {
///
/// The provided value is uppercased for consistency with IMAP protocol conventions.
///
/// - parameter value: The thread kind as a string (e.g., ORDEREDSUBJECT, REFERENCES).
/// - parameter value: The thread kind as a string (for example, ORDEREDSUBJECT or REFERENCES).
public init(_ value: String) {
self.rawValue = value.uppercased()
}
@@ -182,7 +182,7 @@ extension Capability {
///
/// The provided value is uppercased for consistency with IMAP protocol conventions.
///
/// - parameter value: The status kind as a string (e.g., SIZE).
/// - parameter value: The status kind as a string (for example, SIZE).
public init(_ value: String) {
self.rawValue = value.uppercased()
}
@@ -210,7 +210,7 @@ extension Capability {
///
/// The provided value is uppercased for consistency with IMAP protocol conventions.
///
/// - parameter value: The UTF-8 kind as a string (e.g., ACCEPT).
/// - parameter value: The UTF-8 kind as a string (for example, ACCEPT).
public init(_ value: String) {
self.rawValue = value.uppercased()
}
@@ -237,7 +237,7 @@ extension Capability {
///
/// The provided value is uppercased for consistency with IMAP protocol conventions.
///
/// - parameter value: The rights kind as a string (e.g., TEKX).
/// - parameter value: The rights kind as a string (for example, TEKX).
public init(_ value: String) {
self.rawValue = value.uppercased()
}
@@ -264,7 +264,7 @@ extension Capability {
///
/// The provided value is uppercased for consistency with IMAP protocol conventions.
///
/// - parameter value: The compression kind as a string (e.g., DEFLATE).
/// - parameter value: The compression kind as a string (for example, DEFLATE).
public init(_ value: String) {
self.rawValue = value.uppercased()
}
@@ -56,7 +56,7 @@ public struct ChangedSinceModifier: Hashable, Sendable {
/// the specified value. If the message has changed (higher mod-sequence), the operation is rejected, preventing
/// lost updates in multimailbox environments.
///
/// This implements optimistic concurrency control, allowing multiple clients to safely modify messages without
/// Implements optimistic concurrency control, allowing multiple clients to safely modify messages without
/// overwriting each other's changes.
///
/// **Requires server capability:** ``Capability/condStore``
@@ -26,7 +26,7 @@ import struct OrderedCollections.OrderedDictionary
/// The server responds with untagged data (prefixed with `*`) and a tagged response (using the same tag)
/// indicating success (`OK`), failure (`NO`), or protocol error (`BAD`). See ``Response`` for response types.
///
/// ## Command Structure
/// ## Command structure
///
/// Every IMAP command follows this basic structure:
/// ```
@@ -39,7 +39,7 @@ import struct OrderedCollections.OrderedDictionary
/// A0003 FETCH 1:* (FLAGS BODY)
/// ```
///
/// ## Protocol State Requirements
/// ## Protocol state requirements
///
/// Commands are restricted based on the connection's current state:
/// - **Any State**: Commands like ``capability``, ``noop``, and ``logout`` are valid at any time.
@@ -50,7 +50,7 @@ import struct OrderedCollections.OrderedDictionary
/// - **Selected**: Commands like ``fetch(_:_:_:)`` and ``search(key:charset:returnOptions:)`` work with messages
/// in the currently selected mailbox.
///
/// ## Extension Support
/// ## Extension support
///
/// Many commands support IMAP extensions defined in RFCs beyond [RFC 3501](https://datatracker.ietf.org/doc/html/rfc3501).
/// For example, the ``list(_:reference:_:_:)`` command supports extensions from
@@ -58,7 +58,7 @@ import struct OrderedCollections.OrderedDictionary
/// [RFC 5819](https://datatracker.ietf.org/doc/html/rfc5819) (RETURN option), and
/// [RFC 6154](https://datatracker.ietf.org/doc/html/rfc6154) (SPECIAL-USE mailboxes).
///
/// ## Streaming Commands
/// ## Streaming commands
///
/// Some commands like `APPEND` involve uploading large messages and are handled separately by the
/// ``AppendCommand`` type to support streaming of data.
@@ -127,7 +127,7 @@ public enum Command: Hashable, Sendable {
/// The `LIST` command allows a client to discover what mailboxes are available on the server,
/// with support for pattern matching and filtering.
///
/// ## Base Functionality ([RFC 3501 Section 6.3.8](https://datatracker.ietf.org/doc/html/rfc3501#section-6.3.8))
/// ## Base functionality ([RFC 3501 Section 6.3.8](https://datatracker.ietf.org/doc/html/rfc3501#section-6.3.8))
///
/// The base `LIST` command takes two arguments:
/// - **reference**: A mailbox name or hierarchy level that provides context for interpreting the pattern.
@@ -150,7 +150,7 @@ public enum Command: Hashable, Sendable {
/// pattern as `"*"`. The server responds with zero or more `S: * LIST...` lines (each wrapped as
/// ``MailboxData/list(_:)``), followed by the tagged response `S: A001 OK LIST Completed`.
///
/// ## Selection Options ([RFC 5258](https://datatracker.ietf.org/doc/html/rfc5258))
/// ## Selection options ([RFC 5258](https://datatracker.ietf.org/doc/html/rfc5258))
///
/// The optional `options` parameter uses ``ListSelectOptions`` to control which mailboxes are listed:
/// - ``ListSelectBaseOption/subscribed``: Only list mailboxes that the user has subscribed to
@@ -159,7 +159,7 @@ public enum Command: Hashable, Sendable {
/// - ``ListSelectOption/recursiveMatch``: Include parent mailboxes that don't match but have matching children
/// ([RFC 5258](https://datatracker.ietf.org/doc/html/rfc5258)).
///
/// ## Independent Options ([RFC 5258](https://datatracker.ietf.org/doc/html/rfc5258), [RFC 6154](https://datatracker.ietf.org/doc/html/rfc6154))
/// ## Independent options ([RFC 5258](https://datatracker.ietf.org/doc/html/rfc5258), [RFC 6154](https://datatracker.ietf.org/doc/html/rfc6154))
///
/// When syntax conflicts prevent combining options, use ``listIndependent(_:reference:_:_:)`` instead:
/// - ``ListSelectIndependentOption/remote``: Include remote mailboxes in the results
@@ -167,7 +167,7 @@ public enum Command: Hashable, Sendable {
/// - ``ListSelectIndependentOption/specialUse``: Only return mailboxes with special-use attributes
/// like `\Drafts`, `\Sent`, or `\Trash` ([RFC 6154](https://datatracker.ietf.org/doc/html/rfc6154)).
///
/// ## Return Options ([RFC 5258](https://datatracker.ietf.org/doc/html/rfc5258), [RFC 5819](https://datatracker.ietf.org/doc/html/rfc5819), [RFC 6154](https://datatracker.ietf.org/doc/html/rfc6154))
/// ## Return options ([RFC 5258](https://datatracker.ietf.org/doc/html/rfc5258), [RFC 5819](https://datatracker.ietf.org/doc/html/rfc5819), [RFC 6154](https://datatracker.ietf.org/doc/html/rfc6154))
///
/// The optional `returnOptions` array specifies what additional data should be returned for each mailbox:
/// - ``ReturnOption/subscribed``: Include subscription state for each mailbox
@@ -179,7 +179,7 @@ public enum Command: Hashable, Sendable {
/// - ``ReturnOption/statusOption(_:)``: Request `STATUS` data (mailbox statistics like `MESSAGES`, `UNSEEN`, `UIDVALIDITY`)
/// be returned alongside `LIST` responses ([RFC 5819](https://datatracker.ietf.org/doc/html/rfc5819)).
///
/// ### Example with Return Options
/// ### Example with return options
///
/// ```
/// C: A002 LIST "" "INBOX" RETURN (SUBSCRIBED STATUS (MESSAGES UNSEEN))
@@ -406,7 +406,7 @@ public enum Command: Hashable, Sendable {
/// Searches the currently-selected mailbox for messages that match the search criteria.
///
/// This is a RFC 3501 / RFC 4731 style search. RFC 7377 style searches use `.extendedSearch`.
/// Uses RFC 3501 / RFC 4731 style search. RFC 7377 style searches use `.extendedSearch`.
///
/// If `returnOptions` is empty, this is a RFC 3501 style search. But note that the empty
/// RFC 7377 `RETURN ()` maps to `[.all]` — as it’s equivalent to `RETURN (ALL)`.
@@ -418,7 +418,7 @@ public enum Command: Hashable, Sendable {
/// `MOVE` – Moves each message in the given sequence number set to the destination mailbox.
///
/// Copies the specified messages to the end of the destination mailbox and removes the copies from the current mailbox.
/// This operation is equivalent to performing ``copy(_:_:)`` followed by ``store(_:_:_:)`` with `\Deleted` flag.
/// Equivalent to performing ``copy(_:_:)`` followed by ``store(_:_:_:)`` with `\Deleted` flag.
///
/// - SeeAlso: [RFC 6851](https://datatracker.ietf.org/doc/html/rfc6851)
case move(LastCommandSet<SequenceNumber>, MailboxName)
@@ -472,7 +472,7 @@ public enum Command: Hashable, Sendable {
/// - Parameters:
/// - criteria: One or more ``SortCriterion`` values defining the sort order. Later criteria
/// are used as tie-breakers when earlier criteria produce equal values.
/// - charset: The character set for string comparisons (e.g., `"UTF-8"`, `"US-ASCII"`). Required.
/// - charset: The character set for string comparisons (for example, `"UTF-8"` or `"US-ASCII"`). Required.
/// - key: The ``SearchKey`` filtering which messages to include in the result.
/// - returnOptions: Optional ``SearchReturnOption`` values controlling the response format.
///
@@ -544,7 +544,7 @@ public enum Command: Hashable, Sendable {
/// Performs a “multimailbox” search as defined in RFC 7377.
///
/// This command enables searching across multiple mailboxes in a single request. The search results are
/// Enables searching across multiple mailboxes in a single request. The search results are
/// returned using the `ESEARCH` response format defined in RFC 4731, which includes optional `MIN`, `MAX`,
/// `COUNT`, and `ALL` return options. This command is equivalent to the extended `SEARCH` command but can
/// target multiple mailboxes via the ``MailboxFilter`` and ``Mailboxes`` filters.
@@ -1119,7 +1119,7 @@ extension Command {
}
/// Convenience for creating a *UID MOVE* command.
/// Pass in a `UIDSet`, and if that set is valid (i.e. non-empty) then a command is returned.
/// Pass in a `UIDSet`, and if that set is valid (that is, non-empty) then a command is returned.
/// - parameter messages: The set of message UIDs to use.
/// - parameter mailbox: The destination mailbox.
/// - returns: `nil` if `messages` is empty, otherwise a `Command`.
@@ -1131,7 +1131,7 @@ extension Command {
}
/// Convenience for creating a *UID COPY* command.
/// Pass in a `UIDSet`, and if that set is valid (i.e. non-empty) then a command is returned.
/// Pass in a `UIDSet`, and if that set is valid (that is, non-empty) then a command is returned.
/// - parameter messages: The set of message UIDs to use.
/// - parameter mailbox: The destination mailbox.
/// - returns: `nil` if `messages` is empty, otherwise a `Command`.
@@ -1143,7 +1143,7 @@ extension Command {
}
/// Convenience for creating a *UID FETCH* command.
/// Pass in a `UIDSet`, and if that set is valid (i.e. non-empty) then a command is returned.
/// Pass in a `UIDSet`, and if that set is valid (that is, non-empty) then a command is returned.
/// - parameter messages: The set of message UIDs to use.
/// - parameter attributes: Which attributes to retrieve.
/// - parameter modifiers: Fetch modifiers.
@@ -1157,7 +1157,7 @@ extension Command {
}
/// Convenience for creating a *UID STORE* command.
/// Pass in a `UIDSet`, and if that set is valid (i.e. non-empty) then a command is returned.
/// Pass in a `UIDSet`, and if that set is valid (that is, non-empty) then a command is returned.
/// - parameter messages: The set of message UIDs to use.
/// - parameter modifiers: Store modifiers.
/// - parameter data: The store data to apply.
@@ -1170,7 +1170,7 @@ extension Command {
}
/// Convenience for creating a *UID EXPUNGE* command.
/// Pass in a `UIDSet`, and if that set is valid (i.e. non-empty) then a command is returned.
/// Pass in a `UIDSet`, and if that set is valid (that is, non-empty) then a command is returned.
/// - parameter messages: The set of message UIDs to use.
/// - parameter mailbox: The mailbox on which to perform the expunge.
/// - returns: `nil` if `messages` is empty, otherwise a `Command`.
@@ -34,7 +34,7 @@ import struct NIO.ByteBuffer
/// S: A001 OK APPEND completed
/// ```
///
/// This wire format is managed through multiple `AppendCommand` values:
/// The wire format above is managed through multiple `AppendCommand` values:
/// - `start(tag: "A001", appendingTo: "INBOX")` produces the command prefix
/// - `beginMessage(...)` produces the metadata (flags, date, size)
/// - `messageBytes(buffer)` streams the message data
@@ -137,7 +137,7 @@ public enum AppendCommand: Hashable, Sendable {
extension AppendCommand {
/// Management of inline data catenation using the `CATENATE` extension (RFC 4469).
///
/// This enum manages the lifecycle of sending inline data as part of a catenation.
/// Manages the lifecycle of sending inline data as part of a catenation.
/// One `begin(size:)` message must be sent before exactly one `end` message, with
/// zero or more `bytes(_:)` messages in between.
///
@@ -250,7 +250,7 @@ public enum CommandStreamPart: Hashable, Sendable {
/// Sends data in response to a server continuation request (`+`).
///
/// When a server sends a continuation request (e.g., during authentication or
/// When a server sends a continuation request (for example, during authentication or
/// literal data upload), the client responds with this case. The buffer typically
/// contains base64-encoded credentials for `AUTHENTICATE` commands or raw message
/// bytes for message uploads.
@@ -36,7 +36,7 @@ extension Command {
/// literal with `{size}\r\n` prefix followed by the raw bytes. Otherwise, they
/// are sent as a quoted string with `"..."` syntax.
///
/// This is the safer option when the payload should be treated as data rather
/// The safer option when the payload should be treated as data rather
/// than protocol syntax.
///
/// ### Example
@@ -40,7 +40,7 @@ import struct NIO.ByteBuffer
/// sequence tracking is enabled for this mailbox. The server responds with `* OK [MODSEQ 12345]`
/// indicating the current modification sequence value.
///
/// ## Related Types
/// ## Related types
///
/// - See ``SearchModificationSequence`` for conditional search operations
/// - See ``StoreModifier`` for conditional store modifiers in STORE commands
@@ -17,12 +17,12 @@ import struct NIO.ByteBuffer
/// A calendar day formatted as `dd-MMM-yyyy` as defined in RFC 3501.
///
/// This type represents a date in the IMAP date format, where the month is represented
/// as a three-letter abbreviation (e.g., `Jan`, `Feb`, etc.). This format is used in various
/// as a three-letter abbreviation (for example, `Jan` or `Feb`). This format is used in various
/// IMAP protocol messages including the `INTERNALDATE` message attribute and `APPEND` commands.
///
/// The `IMAPCalendarDay` provides basic validation of date components. Note that the
/// validation checks component ranges but does not validate whether the combination
/// represents a valid calendar date (e.g., February 30 is accepted).
/// represents a valid calendar date (for example, February 30 is accepted).
///
/// ### Example
///
@@ -37,8 +37,8 @@ import struct NIO.ByteBuffer
public struct IMAPCalendarDay: Hashable, Sendable {
/// The year, constrained to the range `1900...2500`.
///
/// This is a 4-digit year value. The range constraint reflects common IMAP server
/// implementations which typically support dates in this range.
/// A 4-digit year value. The range constraint covers common IMAP server
/// implementations.
public let year: Int
/// The month, constrained to the range `1...12`.
@@ -49,7 +49,7 @@ public struct IMAPCalendarDay: Hashable, Sendable {
/// The day of the month, constrained to the range `1...31`.
///
/// The range accepts all valid day numbers across different months. No validation
/// is performed to verify the day is valid for the specific month (e.g., February 30 is accepted).
/// is performed to verify the day is valid for the specific month (for example, February 30 is accepted).
public let day: Int
/// Creates a new `IMAPCalendarDay` and performs basic validation on the input.
@@ -88,7 +88,7 @@ extension EncodeBuffer {
extension IMAPCalendarDay {
/// The three-letter month abbreviation for this calendar day.
///
/// Returns the month name as used in the IMAP date format (e.g., `Jan`, `Feb`, `Mar`, etc.).
/// Returns the month name as used in the IMAP date format (for example, `Jan`, `Feb`, or `Mar`).
fileprivate var monthString: String {
switch month {
case 1: return "Jan"
@@ -14,7 +14,7 @@
/// The internal date and time of a message as stored on the server.
///
/// This type represents the server's record of when a message was received or stored,
/// Represents the server's record of when a message was received or stored,
/// not the date from the message's headers (which is represented by ``InternetMessageDate``).
/// The internal date consists of a calendar date, time of day, and timezone offset.
///
@@ -28,7 +28,7 @@
/// * 1 FETCH (INTERNALDATE “15-Mar-2026 10:30:45 +0100”)
/// ```
///
/// This response indicates the message was received on March 15, 2026 at 10:30:45 AM
/// The response indicates the message was received on March 15, 2026 at 10:30:45 AM
/// in the UTC+01:00 timezone. This is wrapped as ``ServerMessageDate`` with components
/// accessible via the ``components`` property.
///
@@ -38,7 +38,7 @@ public struct ServerMessageDate: Hashable, Sendable {
/// The individual date and time components for this internal date.
///
/// This computed property extracts the encoded date, time, and timezone components
/// Extracts the encoded date, time, and timezone components
/// from the compact internal representation. The components can be used to
/// display or work with individual date and time fields.
///
@@ -82,7 +82,7 @@ public struct ServerMessageDate: Hashable, Sendable {
/// Creates a new `ServerMessageDate` from individual date and time components.
///
/// This initializer constructs a ``ServerMessageDate`` by encoding the provided
/// Constructs a ``ServerMessageDate`` by encoding the provided
/// components into the compact rawValue representation.
///
/// - Parameter components: A ``Components`` structure containing the date, time, and timezone information.
@@ -139,11 +139,11 @@ extension ServerMessageDate {
/// let date = ServerMessageDate(components)
/// ```
///
/// This creates an ``ServerMessageDate`` representing March 15, 2026 at 10:30:45 UTC+01:00.
/// Creates a ``ServerMessageDate`` representing March 15, 2026 at 10:30:45 UTC+01:00.
public struct Components: Sendable {
/// The year, typically represented as a 4-digit integer.
///
/// This is a full year value (e.g., 2026), constrained to fit within an unsigned 16-bit integer.
/// A full year value (for example, 2026), constrained to fit within an unsigned 16-bit integer.
public let year: Int
/// The month, typically represented as a 2-digit integer in the range `1...12`.
@@ -36,7 +36,7 @@ import struct NIO.ByteBuffer
/// `UNSEEN` search criteria. The response is ``Response/untagged(_:)`` containing
/// ``ResponsePayload/mailboxData(_:)`` with ``MailboxData/extendedSearch(_:)``.
///
/// ## Related Types
/// ## Related types
///
/// - See ``SearchKey`` for search criteria
/// - See ``SearchReturnOption`` for return options
@@ -60,14 +60,14 @@ public struct ExtendedSearchOptions: Hashable, Sendable {
/// Return options that filter and shape the data returned from the search.
///
/// Specifies which fields should be returned in the search response (e.g., ``SearchReturnOption/min``,
/// ``SearchReturnOption/max``, ``SearchReturnOption/all``, etc.).
/// Specifies which fields should be returned in the search response (for example, ``SearchReturnOption/min``,
/// ``SearchReturnOption/max``, or ``SearchReturnOption/all``).
public var returnOptions: [SearchReturnOption]
/// The mailboxes and scope to search across.
///
/// Specifies which mailbox(es) to include in the search operation using mailbox filters
/// (e.g., personal namespace, specific mailbox names). When `nil`, the current mailbox context is used.
/// (for example, personal namespace or specific mailbox names). When `nil`, the current mailbox context is used.
public var sourceOptions: ExtendedSearchSourceOptions?
/// Creates a new `ExtendedSearchOptions` for multi-mailbox search.
@@ -24,7 +24,7 @@ import struct OrderedCollections.OrderedDictionary
/// These options are specified as key-value pairs and are optional in search commands.
/// See [RFC 7377 Section 2.1.1](https://datatracker.ietf.org/doc/html/rfc7377#section-2.1.1) for details.
///
/// ## Related Types
/// ## Related types
///
/// - See ``ExtendedSearchSourceOptions`` for mailbox selection
/// - See ``ExtendedSearchOptions`` for complete search options
@@ -19,7 +19,7 @@ import struct NIO.ByteBuffer
/// **Requires server capability:** ``Capability/multiSearch``
///
/// Source options define the mailbox context for an extended search operation, allowing searches to span
/// multiple mailboxes using mailbox filters (e.g., personal namespace mailboxes, specific named mailboxes).
/// multiple mailboxes using mailbox filters (for example, personal namespace mailboxes or specific named mailboxes).
/// The `IN` clause specifies one or more mailbox filters, and optional scope options can further refine
/// the search context. See [RFC 7377 Section 2.1.1](https://datatracker.ietf.org/doc/html/rfc7377#section-2.1.1).
///
@@ -35,7 +35,7 @@ import struct NIO.ByteBuffer
/// - ``MailboxFilter/personal`` - all personal mailboxes
/// - ``MailboxFilter/subtree(_:)`` - the "Archive" mailbox and its subfolders
///
/// ## Related Types
/// ## Related types
///
/// - See ``MailboxFilter`` for individual mailbox filter types
/// - See ``ExtendedSearchOptions`` for complete search options
@@ -46,7 +46,7 @@ public struct ExtendedSearchSourceOptions: Hashable, Sendable {
/// Array of mailbox filters specifying which mailboxes to search.
///
/// At least one mailbox filter must be present. Multiple filters can be combined to search
/// across different mailbox categories (e.g., personal mailboxes, specific named mailboxes,
/// across different mailbox categories (for example, personal mailboxes, specific named mailboxes, or
/// subscribed mailboxes).
public let sourceMailbox: [MailboxFilter]
@@ -16,7 +16,7 @@ import struct NIO.ByteBuffer
/// An RFC 2822 electronic mail address with structured components.
///
/// This type represents an address as returned in the `ENVELOPE` structure of a `FETCH` response.
/// Represents an address as returned in the `ENVELOPE` structure of a `FETCH` response.
/// The `ENVELOPE` address format breaks email addresses into four distinct components to help applications
/// display mail headers consistently and reliably.
///
@@ -30,7 +30,7 @@ import struct NIO.ByteBuffer
/// S: * 1 FETCH (ENVELOPE (NIL "Alice Smith" "alice" "example.com" ...))
/// ```
///
/// This response contains an address with nil at-domain-list, personName "Alice Smith", mailbox "alice", and host "example.com".
/// The response contains an address with nil at-domain-list, personName "Alice Smith", mailbox "alice", and host "example.com".
///
/// - SeeAlso: [RFC 3501 Section 7.4.2](https://datatracker.ietf.org/doc/html/rfc3501#section-7.4.2)
public struct EmailAddress: Hashable, Sendable {
@@ -20,7 +20,7 @@ import struct NIO.ByteBuffer
/// When the mechanism name contains characters that are not allowed in URLs, the name must be
/// percent-encoded using UTF-8 followed by hexadecimal encoding (RFC 2192, RFC 3986).
///
/// This type wraps a percent-encoded authentication mechanism name for use in URL construction.
/// Wraps a percent-encoded authentication mechanism name for use in URL construction.
/// The encoded string contains only ASCII-safe characters and can be safely included in IMAP URL syntax.
///
/// ### Examples
@@ -48,7 +48,7 @@ import struct NIO.ByteBuffer
/// )
/// ```
///
/// ## Related Types
/// ## Related types
///
/// See ``IMAPURLAuthenticationMechanism`` for the authentication mechanism specification,
/// ``UserAuthenticationMechanism`` for how mechanisms are combined with user identifiers,
@@ -21,7 +21,7 @@ import struct NIO.ByteBuffer
/// characters), the name must be percent-encoded using UTF-8 followed by hexadecimal encoding
/// (RFC 2192, RFC 3986).
///
/// This type wraps a percent-encoded mailbox name for use in URL construction. The encoded
/// Wraps a percent-encoded mailbox name for use in URL construction. The encoded
/// string contains only ASCII-safe characters and can be safely included in IMAP URL syntax.
///
/// ### Example
@@ -46,7 +46,7 @@ import struct NIO.ByteBuffer
/// )
/// ```
///
/// ## Related Types
/// ## Related types
///
/// See ``MailboxUIDValidity`` for mailbox references with UID validity values, and
/// ``MessagePath`` for the complete message location specification in URLs.
@@ -14,7 +14,7 @@
/// A mailbox reference paired with an optional percent-encoded search query.
///
/// This type combines a mailbox identifier with UID validity and an optional search query for use
/// Combines a mailbox identifier with UID validity and an optional search query for use
/// in IMAP URLs (RFC 5092). It specifies both which mailbox to search and what to search for.
///
/// - SeeAlso: [RFC 5092 IMAP URL Scheme](https://datatracker.ietf.org/doc/html/rfc5092)
@@ -17,10 +17,10 @@ import struct NIO.ByteBuffer
/// A percent-encoded message section reference for use in IMAP URLs.
///
/// IMAP message sections (as defined in RFC 3501) specify parts of message structures
/// using dot-separated numeric notation (e.g., "1", "1.2", "1.2.3"). When used in IMAP URLs,
/// using dot-separated numeric notation (for example, "1", "1.2", or "1.2.3"). When used in IMAP URLs,
/// section references are percent-encoded to ensure URL safety (RFC 2192, RFC 3986).
///
/// This type wraps a percent-encoded section reference for use in URL construction.
/// Wraps a percent-encoded section reference for use in URL construction.
/// The encoded string contains only ASCII-safe characters and can be safely included in IMAP URL syntax.
///
/// ### Example
@@ -42,7 +42,7 @@ import struct NIO.ByteBuffer
/// )
/// ```
///
/// ## Related Types
/// ## Related types
///
/// See ``URLMessageSection`` for the complete message section specification,
/// ``MessagePath`` for the full message location including sections, and
@@ -24,7 +24,7 @@ import struct NIO.ByteBuffer
/// The token appears in the final component of the URLAUTH extension:
/// `;URLAUTH=<access>:<mechanism>:<token>`
///
/// This type wraps the hexadecimal-encoded token string for use in URLAUTH verification
/// Wraps the hexadecimal-encoded token string for use in URLAUTH verification
/// structures (via ``AuthenticatedURLVerifier``).
///
/// ### Example
@@ -45,7 +45,7 @@ import struct NIO.ByteBuffer
/// When a client later uses this URL with URLFETCH, the server re-calculates the token
/// to verify authorization before returning the message data.
///
/// ## Related Types
/// ## Related types
///
/// See ``URLAuthenticationMechanism`` for the mechanism specification, ``AuthenticatedURLVerifier``
/// for the complete mechanism and token pair, and ``AuthenticatedURL`` for the full
@@ -57,7 +57,7 @@ import struct NIO.ByteBuffer
public struct EncodedAuthenticatedURL: Hashable, Sendable {
/// The hexadecimal-encoded authorization token string.
///
/// This is an ASCII-encoded hexadecimal representation of the token bytes. The RFC 4467
/// An ASCII-encoded hexadecimal representation of the token bytes. The RFC 4467
/// specification recommends using hexadecimal instead of Base64 to avoid URL-problematic
/// padding characters.
public var data: String
@@ -20,7 +20,7 @@ import struct NIO.ByteBuffer
/// characters. This encoding is applied when a user identifier contains non-ASCII characters,
/// spaces, or special characters that are not allowed in URL syntax (RFC 2192, RFC 3986).
///
/// This type wraps a percent-encoded user identifier for use in server specifications
/// Wraps a percent-encoded user identifier for use in server specifications
/// (via ``UserAuthenticationMechanism`` and ``IMAPServer``) and in URLAUTH access identifiers
/// (via ``Access`` with `user+` and `submit+` prefixes).
///
@@ -43,7 +43,7 @@ import struct NIO.ByteBuffer
/// imap://owner@example.com/INBOX/;uid=20;urlauth=submit+Fr%C3%A9d%C3%A9ric:internal:...
/// ```
///
/// ## Related Types
/// ## Related types
///
/// See ``Access`` for how encoded users are used in URLAUTH access identifiers,
/// ``UserAuthenticationMechanism`` for server-level user specifications, and
@@ -16,7 +16,7 @@
///
/// **Requires server capability:** ``Capability/metadata`` or ``Capability/metadataServer``
///
/// This type wraps an ``AttributeFlag`` to represent it as a metadata entry name in the special
/// Wraps an ``AttributeFlag`` to represent it as a metadata entry name in the special
/// `/flags/` namespace. Flag entries allow metadata operations on flag modification sequences
/// through the entry name format `/flags/flagname`. See [RFC 5464](https://datatracker.ietf.org/doc/html/rfc5464)
/// for details on metadata entry organization.
@@ -32,7 +32,7 @@
/// The entry name `/flags/\Seen` is represented using ``EntryFlagName`` wrapping the
/// ``AttributeFlag`` for `\Seen`. The value `12345` is the modification sequence for that flag.
///
/// ## Related Types
/// ## Related types
///
/// - See ``AttributeFlag`` for system flag representation
/// - See ``MetadataEntryName`` for general metadata entry names
@@ -42,7 +42,7 @@
public struct EntryFlagName: Hashable, Sendable {
/// The flag wrapped as a metadata entry.
///
/// Represents a system flag (e.g., `\Seen`, `\Flagged`, `\Deleted`) in metadata entry form.
/// Represents a system flag (for example, `\Seen`, `\Flagged`, or `\Deleted`) in metadata entry form.
public var flag: AttributeFlag
/// Creates a new `EntryFlagName` wrapping an `AttributeFlag`.
@@ -33,7 +33,7 @@ import struct NIO.ByteBuffer
/// The `ALL` option in the command queries modification sequences for the specified flags,
/// considering both private and shared metadata sources.
///
/// ## Related Types
/// ## Related types
///
/// - See ``EntryKindResponse`` for server-returned entry type information
/// - See ``MetadataOption`` for other metadata query options
@@ -20,7 +20,7 @@ import struct NIO.ByteBuffer
///
/// Entry kind response indicates whether a metadata entry belongs to the private namespace
/// (visible only to the authenticated user) or the shared namespace (visible to all users).
/// This information is returned by the server when responding to metadata queries.
/// The server returns this information when responding to metadata queries.
/// See [RFC 5464 Section 3.3](https://datatracker.ietf.org/doc/html/rfc5464#section-3.3).
///
/// ### Example
@@ -34,7 +34,7 @@ import struct NIO.ByteBuffer
/// The response includes the entry type `priv` to indicate that the `/flags/\Seen` modification
/// sequence metadata is private to the authenticated user.
///
/// ## Related Types
/// ## Related types
///
/// - See ``EntryKindRequest`` for client-side entry type specification
/// - See ``MetadataResponse`` for complete metadata responses
+4 -4
View File
@@ -46,13 +46,13 @@ public struct Envelope: Hashable, Sendable {
/// The sender(s) of the message, as from the `From:` header.
///
/// This is the author or originator of the message content. Multiple addresses indicate
/// The author or originator of the message content. Multiple addresses indicate
/// multiple authors are credited with writing the message.
public var from: [EmailAddressListElement]
/// The actual sender on behalf of the author, as from the `Sender:` header.
///
/// This is used when one entity sends a message on behalf of another (e.g., an assistant
/// Used when one entity sends a message on behalf of another (for example, an assistant
/// sending mail on behalf of their boss). If absent, the `from` field should be used.
public var sender: [EmailAddressListElement]
@@ -80,12 +80,12 @@ public struct Envelope: Hashable, Sendable {
/// The message ID of the message this message is replying to, as from the `In-Reply-To:` header.
///
/// This field links this message to a previous message in a conversation thread.
/// Links this message to a previous message in a conversation thread.
public var inReplyTo: MessageID?
/// The unique message identifier, as from the `Message-ID:` header.
///
/// This identifier is assigned by the originating SMTP server and is globally unique
/// Assigned by the originating SMTP server and globally unique
/// for the originating system.
public var messageID: MessageID?
+3 -3
View File
@@ -18,7 +18,7 @@
/// remains valid. After the expiration date and time, the IMAP server must reject the URL
/// (RFC 4467 Section 3).
///
/// This is an optional component appended to IMAP URLs as `;EXPIRE=<datetime>` (in RFC 3339 format).
/// An optional component appended to IMAP URLs as `;EXPIRE=<datetime>` (in RFC 3339 format).
/// If not specified, the URL has no expiration time, though it can still be revoked by other means
/// (such as regenerating the mailbox access key).
///
@@ -31,7 +31,7 @@
///
/// The `;expire=2025-12-31T23:59:59Z` component indicates the URL expires at that date and time.
///
/// ## Related Types
/// ## Related types
///
/// See ``AuthenticatedURLRump`` for how expiration is combined with ``Access`` identifiers,
/// and ``FullDateTime`` for the datetime format specification.
@@ -41,7 +41,7 @@ public struct Expire: Hashable, Sendable {
/// The latest date and time that a URLAUTH-authorized URL is valid.
///
/// After this date and time, the URL must be rejected by the IMAP server. The datetime is
/// encoded in RFC 3339 format (e.g., `2025-12-31T23:59:59Z`).
/// encoded in RFC 3339 format (for example, `2025-12-31T23:59:59Z`).
public var dateTime: FullDateTime
/// Creates a new expiration date and time.
@@ -20,11 +20,11 @@ import struct NIO.ByteBuffer
/// This enum represents all available fetch attributes, including standard RFC 3501 attributes and
/// attributes from various IMAP extensions.
///
/// ### Standard Attributes (RFC 3501)
/// ### Standard attributes (RFC 3501)
///
/// Basic message properties like envelope, flags, internal date, and RFC 822 message format.
///
/// ### Extension Attributes
/// ### Extension attributes
///
/// - `BODYSTRUCTURE`: Detailed message structure information (RFC 3501)
/// - `BINARY`: Raw binary content of message sections (RFC 3516 BINARY extension)
@@ -33,7 +33,7 @@ import struct NIO.ByteBuffer
/// - `EMAILID` / `THREADID`: Message and thread identifiers (RFC 8474)
/// - `X-GM-*`: Gmail-specific attributes (non-standard)
///
/// ### Attributes with Options
/// ### Attributes with options
///
/// Some attributes support optional parameters:
/// - ``bodySection(peek:_:_:)`` supports a `peek` flag (prevents \\Seen flag modification) and partial byte ranges
@@ -57,7 +57,7 @@ public enum FetchAttribute: Hashable, Sendable {
/// The message envelope structure containing sender, recipient, subject, and date information.
///
/// Returns an ``Envelope`` structure with the sender, recipient lists, subject, and other message metadata.
/// This is a parsed representation of the message headers.
/// A parsed representation of the message headers.
///
/// - SeeAlso: [RFC 3501 Section 7.4.2](https://datatracker.ietf.org/doc/html/rfc3501#section-7.4.2)
case envelope
@@ -126,7 +126,7 @@ public enum FetchAttribute: Hashable, Sendable {
/// their headers. Supports partial byte ranges for efficient fetching of large parts.
///
/// - parameter peek: If `true`, does not set the `\Seen` flag on the message; if `false`, sets `\Seen`
/// - parameter section: The section specifier (e.g., `1`, `1.1`, `HEADER`, `TEXT`)
/// - parameter section: The section specifier (for example, `1`, `1.1`, `HEADER`, or `TEXT`)
/// - parameter partial: Optional byte range `startOctet..<endOctet` to fetch only a portion
/// - SeeAlso: [RFC 3501 Section 7.4.2](https://datatracker.ietf.org/doc/html/rfc3501#section-7.4.2)
case bodySection(peek: Bool, _ section: SectionSpecifier, ClosedRange<UInt32>?)
@@ -168,7 +168,7 @@ public enum FetchAttribute: Hashable, Sendable {
/// **Requires server capability:** ``Capability/binary``
///
/// - parameter peek: If `true`, does not set the `\Seen` flag; if `false`, sets `\Seen`
/// - parameter section: The specific MIME part to fetch (e.g., `1`, `1.1`)
/// - parameter section: The specific MIME part to fetch (for example, `1` or `1.1`)
/// - parameter partial: Optional byte range to fetch only a portion
/// - SeeAlso: [RFC 3516](https://datatracker.ietf.org/doc/html/rfc3516)
case binary(peek: Bool, section: SectionSpecifier.Part, partial: ClosedRange<UInt32>?)
@@ -185,7 +185,7 @@ public enum FetchAttribute: Hashable, Sendable {
/// The message's Gmail-assigned message ID (Gmail extension, non-standard).
///
/// This is a Gmail-specific extension that returns the unique message identifier within
/// A Gmail-specific extension that returns the unique message identifier within
/// Gmail's system. Not part of the IMAP standard.
///
/// - SeeAlso: https://developers.google.com/gmail/imap/imap-extensions
@@ -193,7 +193,7 @@ public enum FetchAttribute: Hashable, Sendable {
/// The message's Gmail thread ID (Gmail extension, non-standard).
///
/// This is a Gmail-specific extension that returns the identifier for the thread/conversation
/// A Gmail-specific extension that returns the identifier for the thread/conversation
/// this message belongs to. Not part of the IMAP standard.
///
/// - SeeAlso: https://developers.google.com/gmail/imap/imap-extensions
@@ -201,7 +201,7 @@ public enum FetchAttribute: Hashable, Sendable {
/// The message's Gmail labels (Gmail extension, non-standard).
///
/// This is a Gmail-specific extension that returns the list of labels (like folders) applied
/// A Gmail-specific extension that returns the list of labels (like folders) applied
/// to this message. Not part of the IMAP standard.
///
/// - SeeAlso: https://developers.google.com/gmail/imap/imap-extensions
@@ -57,7 +57,7 @@ public enum FetchModifier: Hashable, Sendable {
/// A server extension modifier not defined in this library.
///
/// This case captures future `FETCH` modifiers defined by extensions, allowing forward compatibility
/// Captures future `FETCH` modifiers defined by extensions, allowing forward compatibility
/// with new IMAP capabilities without requiring library updates.
case other(KeyValue<String, ParameterValue?>)
}
+9 -10
View File
@@ -19,7 +19,7 @@ import struct NIO.ByteBuffer
/// Flags are attributes attached to messages that indicate message state or special properties.
/// They are part of the base [IMAP protocol](https://datatracker.ietf.org/doc/html/rfc3501).
///
/// ## Standard Flags
/// ## Standard flags
///
/// [RFC 3501](https://datatracker.ietf.org/doc/html/rfc3501) defines five standard system flags:
/// - ``answered`` - The message has been replied to.
@@ -28,12 +28,12 @@ import struct NIO.ByteBuffer
/// - ``seen`` - The message has been read by the user.
/// - ``draft`` - The message is incomplete and has not been sent.
///
/// ## Case Handling
/// ## Case handling
///
/// Flags are compared case-insensitively, meaning `Flag("\\SEEN")` and `Flag("\\Seen")` are considered equal.
/// Flags also preserve their original casing when encoded and decoded.
///
/// ## Extension Flags
/// ## Extension flags
///
/// Beyond the five standard flags, custom flags can be created. These are defined in
/// [RFC 3501 Section 2.3.2](https://datatracker.ietf.org/doc/html/rfc3501#section-2.3.2).
@@ -94,30 +94,29 @@ extension Flag: CustomDebugStringConvertible {
extension Flag {
/// `\Answered` - The message has been replied to.
///
/// This standard flag ([RFC 3501](https://datatracker.ietf.org/doc/html/rfc3501)) indicates that the
/// Defined in [RFC 3501](https://datatracker.ietf.org/doc/html/rfc3501). Indicates the
/// message is a response to another message.
public static let answered = Self("\\Answered")
/// `\Flagged` - The message has been marked for attention.
///
/// This standard flag ([RFC 3501](https://datatracker.ietf.org/doc/html/rfc3501)).
/// Defined in [RFC 3501](https://datatracker.ietf.org/doc/html/rfc3501).
public static let flagged = Self("\\Flagged")
/// `\Deleted` - The message has been deleted.
///
/// This standard flag ([RFC 3501](https://datatracker.ietf.org/doc/html/rfc3501)) marks a message for
/// deletion. The message is not permanently removed until the ``Command/expunge`` command is executed
/// or the mailbox is closed.
/// Defined in [RFC 3501](https://datatracker.ietf.org/doc/html/rfc3501). Marks a message for
/// deletion until the ``Command/expunge`` command is executed or the mailbox is closed.
public static let deleted = Self("\\Deleted")
/// `\Seen` - The message has been read by the user.
///
/// This standard flag ([RFC 3501](https://datatracker.ietf.org/doc/html/rfc3501)).
/// Defined in [RFC 3501](https://datatracker.ietf.org/doc/html/rfc3501).
public static let seen = Self("\\Seen")
/// `\Draft` - The message is not yet complete.
///
/// This standard flag ([RFC 3501](https://datatracker.ietf.org/doc/html/rfc3501)).
/// Defined in [RFC 3501](https://datatracker.ietf.org/doc/html/rfc3501).
public static let draft = Self("\\Draft")
/// Convenience function to create a new flag from a `Keyword`.
@@ -51,7 +51,7 @@ extension Flag {
/// The case-preserved raw string representation of the keyword.
///
/// This value preserves the original casing for wire format transmission, while comparison operations
/// Preserves the original casing for wire format transmission, while comparison operations
/// use case-insensitive matching.
let rawValue: String
@@ -119,52 +119,52 @@ extension Flag.Keyword: CustomDebugStringConvertible {
extension Flag.Keyword {
/// The `$Forwarded` keyword, commonly used to mark messages that have been forwarded.
///
/// This is a registered keyword in the special-use keywords registry.
/// A registered keyword in the special-use keywords registry.
public static let forwarded = Self(unchecked: "$Forwarded")
/// The `$Junk` keyword, commonly used to mark messages as spam or junk mail.
///
/// This is a registered keyword in the special-use keywords registry.
/// A registered keyword in the special-use keywords registry.
public static let junk = Self(unchecked: "$Junk")
/// The `$NotJunk` keyword, commonly used to mark messages as not spam.
///
/// This is a registered keyword in the special-use keywords registry.
/// A registered keyword in the special-use keywords registry.
public static let notJunk = Self(unchecked: "$NotJunk")
/// The `Redirected` keyword (unregistered).
///
/// This is a non-standard keyword sometimes used by mail systems to mark redirected messages.
/// A non-standard keyword sometimes used by mail systems to mark redirected messages.
public static let unregistered_redirected = Self(unchecked: "Redirected")
/// The `Forwarded` keyword (unregistered).
///
/// This is a non-standard keyword for marking forwarded messages. Prefer ``forwarded`` for standard usage.
/// A non-standard keyword for marking forwarded messages. Prefer ``forwarded`` for standard usage.
public static let unregistered_forwarded = Self(unchecked: "Forwarded")
/// The `Junk` keyword (unregistered).
///
/// This is a non-standard keyword for marking spam. Prefer ``junk`` for standard usage.
/// A non-standard keyword for marking spam. Prefer ``junk`` for standard usage.
public static let unregistered_junk = Self(unchecked: "Junk")
/// The `NotJunk` keyword (unregistered).
///
/// This is a non-standard keyword for marking non-spam messages. Prefer ``notJunk`` for standard usage.
/// A non-standard keyword for marking non-spam messages. Prefer ``notJunk`` for standard usage.
public static let unregistered_notJunk = Self(unchecked: "NotJunk")
/// The `$MailFlagBit0` keyword for color marking (bit 0).
///
/// This keyword is commonly used by mail systems to represent color flags on messages, with different bits representing different colors.
/// A color-flag keyword for messages, where different bits represent different colors.
public static let colorBit0 = Self(unchecked: "$MailFlagBit0")
/// The `$MailFlagBit1` keyword for color marking (bit 1).
///
/// This keyword is commonly used by mail systems to represent color flags on messages.
/// A color-flag keyword for messages.
public static let colorBit1 = Self(unchecked: "$MailFlagBit1")
/// The `$MailFlagBit2` keyword for color marking (bit 2).
///
/// This keyword is commonly used by mail systems to represent color flags on messages.
/// A color-flag keyword for messages.
public static let colorBit2 = Self(unchecked: "$MailFlagBit2")
/// The `$MDNSent` keyword, indicating a Message Disposition Notification has been sent for this message.
@@ -176,7 +176,7 @@ extension Flag.Keyword {
extension Flag: ExpressibleByStringLiteral {
/// Creates a flag from a string literal, used for creating static custom keywords.
///
/// This allows writing flags directly as string literals (e.g., `let flag: Flag = "$Custom"`),
/// This allows writing flags directly as string literals (for example, `let flag: Flag = "$Custom"`),
/// which is useful for static keyword definitions and testing.
///
/// - parameter value: The string literal to construct a keyword flag from.
@@ -106,7 +106,7 @@ public struct StoreGmailLabels: Hashable, Sendable {
/// Standard IMAP message flags for a `STORE` command.
///
/// This type specifies a set of flags to add to, remove from, or replace on messages via the `STORE` command.
/// Specifies a set of flags to add to, remove from, or replace on messages via the `STORE` command.
/// The operation (add/remove/replace) and whether to suppress the server response are configured separately.
///
/// Flags are described in [RFC 3501 Section 2.3](https://datatracker.ietf.org/doc/html/rfc3501#section-2.3)
@@ -22,10 +22,10 @@ import struct NIO.ByteBuffer
/// 1. **Network Message Path**: Server location and message content reference
/// 2. **Authorization Information**: Complete URLAUTH with access, expiration, mechanism, and token
///
/// This is the endpoint of the GENURL AUTH flow: after GENURLAUTH is issued by the client,
/// The endpoint of the GENURL AUTH flow: after GENURLAUTH is issued by the client,
/// the server returns one or more ``FullAuthenticatedURL`` structures wrapped in a GENURLAUTH response.
///
/// ### Complete URL Structure
/// ### Complete URL structure
///
/// A full authenticated URL encompasses:
/// ```
@@ -66,7 +66,7 @@ import struct NIO.ByteBuffer
/// 4. **Client Uses URL**: Submits the complete URL to URLFETCH command
/// 5. **Server Validates and Returns Data**: Verifies token and returns message content
///
/// ## Related Types
/// ## Related types
///
/// - ``NetworkMessagePath`` provides server and message content specification
/// - ``AuthenticatedURL`` provides complete URLAUTH authorization
@@ -14,7 +14,7 @@
/// A complete date and time value in RFC 3339 format with an optional fraction-of-second.
///
/// This type represents a full date-time specification as defined in RFC 3339, combining
/// Represents a full date-time specification as defined in RFC 3339, combining
/// a ``FullDate`` and ``FullTime`` into a single value. RFC 3339 is used in IMAP extensions
/// such as MULTIMAILBOX SEARCH (RFC 7377) and METADATA (RFC 5464) for precise timestamp representation.
///
@@ -56,11 +56,11 @@ public struct FullDateTime: Hashable, Sendable {
/// A calendar date in RFC 3339 format (`YYYY-MM-DD`).
///
/// This type represents a date value as defined in RFC 3339, containing year, month, and day
/// Represents a date value as defined in RFC 3339, containing year, month, and day
/// components. It is used in combination with ``FullTime`` to form a complete ``FullDateTime``.
///
/// The initializer uses `precondition` to verify month and day are within valid ranges but does
/// not validate whether the day is appropriate for the given month (e.g., February 30 is accepted).
/// not validate whether the day is appropriate for the given month (for example, February 30 is accepted).
public struct FullDate: Hashable, Sendable {
/// The year as any non-negative integer.
///
@@ -76,12 +76,12 @@ public struct FullDate: Hashable, Sendable {
/// The day in the range `1...31`.
///
/// The range accepts all valid day numbers. No validation is performed to verify
/// the day is valid for the specific month (e.g., February 30 is accepted).
/// the day is valid for the specific month (for example, February 30 is accepted).
public let day: Int
/// Creates a new `FullDate`.
///
/// This initializer validates that month is in the range `1...12` and day is in the
/// Validates that month is in the range `1...12` and day is in the
/// range `1...31` using `precondition`. The year can be any non-negative integer.
///
/// - Parameters:
@@ -99,7 +99,7 @@ public struct FullDate: Hashable, Sendable {
/// A time of day in RFC 3339 format (`HH:MM:SS[.FRACTION]`).
///
/// This type represents a time value as defined in RFC 3339, containing hour, minute, second,
/// Represents a time value as defined in RFC 3339, containing hour, minute, second,
/// and an optional fractional-second component. It is used in combination with ``FullDate``
/// to form a complete ``FullDateTime``.
///
@@ -120,7 +120,7 @@ public struct FullTime: Hashable, Sendable {
/// The fractional-second component, or `nil` if not included.
///
/// This is a partially-dynamic field and does not directly represent milliseconds,
/// A partially-dynamic field that does not directly represent milliseconds,
/// microseconds, or any specific fractional unit. The number you provide is the number
/// that will be written directly to the output. For example:
/// - `123` encodes as `HH:MM:SS.123`
+1 -1
View File
@@ -55,7 +55,7 @@ import struct NIO.ByteBuffer
/// S: * GENURLAUTH "imap://owner@example.com/INBOX/;uid=20;urlauth=user+fred:internal:..."
/// ```
///
/// ## Related Types
/// ## Related types
///
/// See ``UserAuthenticationMechanism`` for the optional user and authentication specification,
/// ``IMAPURLAuthenticationMechanism`` for authentication mechanism constraints, and
+1 -1
View File
@@ -57,7 +57,7 @@
/// - **`/`**: Path separator
/// - **Command** (``URLCommand``, optional): Mailbox, search, or fetch operation
///
/// ## Related Types
/// ## Related types
///
/// - ``IMAPServer`` provides server connection specification
/// - ``UserAuthenticationMechanism`` specifies user and auth mechanism
@@ -52,7 +52,7 @@
/// // Represents: imap://user@example.com/;auth=PLAIN
/// ```
///
/// ## Related Types
/// ## Related types
///
/// - ``UserAuthenticationMechanism`` combines user and mechanism specifications
/// - ``IMAPServer`` uses mechanism specifications in server definitions
@@ -14,7 +14,7 @@
/// A textual RFC 2822 date as it appears in email message headers.
///
/// This type represents the date field value from an email message's `Date` header,
/// Represents the date field value from an email message's `Date` header,
/// formatted according to RFC 2822 section 3.3. Unlike ``ServerMessageDate``, which records
/// when the server received the message, this date represents the date the message was
/// composed by its sender.
@@ -40,7 +40,7 @@ public struct InternetMessageDate: Hashable, Sendable {
/// The string is stored as-is without parsing or validation. The caller is responsible
/// for ensuring the string represents a valid RFC 2822 date format.
///
/// - Parameter string: A `String` containing the RFC 2822 date value (e.g., `”Fri, 15 Mar 2026 10:30:45 +0100”`).
/// - Parameter string: A `String` containing the RFC 2822 date value (for example, `”Fri, 15 Mar 2026 10:30:45 +0100”`).
public init(_ string: String) {
self.value = string
}
@@ -49,7 +49,7 @@ public struct InternetMessageDate: Hashable, Sendable {
extension String {
/// Creates a new ``Swift/String`` from an ``InternetMessageDate``.
///
/// This extracts the underlying string value from the ``InternetMessageDate``.
/// Extracts the underlying string value from the ``InternetMessageDate``.
///
/// - Parameter date: The ``InternetMessageDate`` to convert.
public init(_ date: InternetMessageDate) {
@@ -60,7 +60,7 @@ extension String {
extension InternetMessageDate: ExpressibleByStringLiteral {
/// Creates a new `InternetMessageDate` from a string literal.
///
/// This allows you to write RFC 2822 dates as string literals:
/// Allows writing RFC 2822 dates as string literals:
/// ```swift
/// let date: InternetMessageDate = “Fri, 15 Mar 2026 10:30:45 +0100”
/// ```
+1 -1
View File
@@ -14,7 +14,7 @@
/// A generic key-value pair container.
///
/// This generic type is used throughout the IMAP protocol implementation to pair related values,
/// Used throughout the IMAP protocol implementation to pair related values,
/// such as extension names with their parameters, vendor tags with their values, or tagged
/// extension data with their content.
///
@@ -47,7 +47,7 @@
/// See [RFC 5182](https://datatracker.ietf.org/doc/html/rfc5182) for the full specification
/// of the search result reference extension.
///
/// ## Related Types
/// ## Related types
///
/// - ``LastCommandSet`` allows referencing the last search result as a message set instead of a single identifier.
/// - ``MessageIdentifier`` represents a specific message identifier (``UID`` or ``SequenceNumber``).
@@ -20,7 +20,7 @@
///
/// **Requires server capability:** ``Capability/searchRes``
///
/// The `$` marker can be used anywhere a message set is expected (e.g., in `FETCH`, `STORE`,
/// The `$` marker can be used anywhere a message set is expected (for example, in `FETCH`, `STORE`,
/// `COPY`, `EXPUNGE` commands). It allows clients to pipeline a `SEARCH` command with subsequent
/// operations without waiting for results and reformatting them.
///
@@ -51,7 +51,7 @@
/// See [RFC 5182](https://datatracker.ietf.org/doc/html/rfc5182) for the full specification
/// of the search result reference extension.
///
/// ## Related Types
/// ## Related types
///
/// - ``LastCommandMessageID`` allows referencing the last search result as a single identifier instead of a set.
/// - ``MessageIdentifierSet`` represents a specific non-empty set of message identifiers.
@@ -59,7 +59,7 @@
public enum LastCommandSet<N: MessageIdentifier>: Hashable, Sendable {
/// A specific non-empty set of message identifiers.
///
/// This set will be encoded and sent to the IMAP server. Example values: `1`, `5:10`, or `1,3,5:7,9:*`.
/// Encoded and sent to the IMAP server. Example values: `1`, `5:10`, or `1,3,5:7,9:*`.
case set(MessageIdentifierSetNonEmpty<N>)
/// References the result of the most recent `SEARCH` command.
@@ -32,7 +32,7 @@ import struct NIO.ByteBuffer
///
/// The command `LIST SUBSCRIBED "" "*"` uses the ``subscribed`` base option to return only subscribed mailboxes.
///
/// ## Related Types
/// ## Related types
///
/// Combine this with ``ListSelectOption`` values to add additional filtering constraints.
/// See ``ListSelectOptions`` for how to construct a complete set of `LIST` selection options.
@@ -41,7 +41,7 @@ import struct NIO.ByteBuffer
public enum ListSelectBaseOption: Hashable, Sendable {
/// The `SUBSCRIBED` base option returns only mailboxes the user has subscribed to.
///
/// This is the primary filtering mode that controls which mailboxes are included in the response.
/// The primary filtering mode that controls which mailboxes are included in the response.
/// From [RFC 5258 Section 3.1](https://datatracker.ietf.org/doc/html/rfc5258#section-3.1).
case subscribed
@@ -35,7 +35,7 @@ import struct NIO.ByteBuffer
/// The command `LIST SUBSCRIBED (REMOTE SPECIAL-USE) "" "*"` uses the independent options
/// ``remote`` and ``specialUse`` to return subscribed remote mailboxes marked with special-use attributes.
///
/// ## Related Types
/// ## Related types
///
/// These differ from ``ListSelectOption`` which may have syntactic relationships.
/// Combine independent options with ``ListSelectBaseOption`` using ``ListSelectOptions``.
@@ -44,13 +44,13 @@ import struct NIO.ByteBuffer
public enum ListSelectIndependentOption: Hashable, Sendable {
/// The `REMOTE` independent option returns information about remote mailbox stores.
///
/// This asks the server to include mailboxes from remote mailbox stores in addition
/// Asks the server to include mailboxes from remote mailbox stores in addition
/// to local mailboxes. From [RFC 5258 Section 3.2](https://datatracker.ietf.org/doc/html/rfc5258#section-3.2).
case remote
/// The `SPECIAL-USE` independent option returns only mailboxes with special-use attributes.
///
/// This filters results to mailboxes marked with attributes like `\All`, `\Archive`, `\Drafts`,
/// Filters results to mailboxes marked with attributes like `\All`, `\Archive`, `\Drafts`,
/// `\Flagged`, `\Junk`, `\Sent`, or `\Trash` (from [RFC 6154](https://datatracker.ietf.org/doc/html/rfc6154)).
case specialUse
@@ -34,7 +34,7 @@ import struct NIO.ByteBuffer
/// The command `LIST (SUBSCRIBED) "" "*"` uses the ``subscribed`` selection option to return only subscribed mailboxes.
/// The resulting responses wrap mailbox information in ``Response/untagged(_:)`` cases.
///
/// ## Related Types
/// ## Related types
///
/// Use ``ListSelectBaseOption`` for options that control the basic filtering mode,
/// ``ListSelectIndependentOption`` for options that don't interact syntactically with other options,
@@ -44,19 +44,19 @@ import struct NIO.ByteBuffer
public enum ListSelectOption: Hashable, Sendable {
/// The `SUBSCRIBED` selection option returns only mailboxes that the user has subscribed to.
///
/// This option filters the mailbox list to show subscription state rather than all mailboxes.
/// Filters the mailbox list to show subscription state rather than all mailboxes.
/// From [RFC 5258 Section 3.1](https://datatracker.ietf.org/doc/html/rfc5258#section-3.1).
case subscribed
/// The `REMOTE` selection option requests mailbox information from remote mailbox stores.
///
/// This is used to include both remote and local mailboxes in the response.
/// Includes both remote and local mailboxes in the response.
/// From [RFC 5258 Section 3.2](https://datatracker.ietf.org/doc/html/rfc5258#section-3.2).
case remote
/// The `SPECIAL-USE` selection option returns only mailboxes with special-use attributes.
///
/// This filters results to mailboxes marked with attributes like `\All`, `\Archive`, `\Drafts`,
/// Filters results to mailboxes marked with attributes like `\All`, `\Archive`, `\Drafts`,
/// `\Flagged`, `\Junk`, `\Sent`, or `\Trash` (from [RFC 6154](https://datatracker.ietf.org/doc/html/rfc6154)).
case specialUse
@@ -77,7 +77,7 @@ public enum ListSelectOption: Hashable, Sendable {
///
/// **Requires server capability:** ``Capability/listExtended``
///
/// This structure represents the complete set of selection options for a `LIST` command,
/// Represents the complete set of selection options for a `LIST` command,
/// combining a base mode with additional filtering criteria. The base option determines
/// the primary filtering mode, while the selection options provide additional constraints.
public struct ListSelectOptions: Hashable, Sendable {
@@ -90,14 +90,14 @@ public struct ListSelectOptions: Hashable, Sendable {
/// Additional selection criteria to apply.
///
/// These options further constrain which mailboxes are returned. Multiple options
/// can be combined (e.g., both ``ListSelectOption/remote`` and ``ListSelectOption/specialUse``
/// can be combined (for example, both ``ListSelectOption/remote`` and ``ListSelectOption/specialUse``
/// to get remote special-use mailboxes).
public var options: [ListSelectOption]
/// Creates a new combination of `LIST` selection options.
///
/// - Parameters:
/// - baseOption: The base selection mode (e.g., ``ListSelectBaseOption/subscribed``)
/// - baseOption: The base selection mode (for example, ``ListSelectBaseOption/subscribed``)
/// - options: Additional selection criteria to apply
public init(baseOption: ListSelectBaseOption, options: [ListSelectOption]) {
self.baseOption = baseOption
@@ -36,19 +36,19 @@ import struct NIO.ByteBuffer
public enum MailboxAttribute: String, CaseIterable, Sendable {
/// The `MESSAGES` attribute: the number of messages in the mailbox.
///
/// This attribute returns the total count of messages in the mailbox.
/// Returns the total count of messages in the mailbox.
/// See [RFC 3501 Section 7.3.2](https://datatracker.ietf.org/doc/html/rfc3501#section-7.3.2).
case messageCount = "MESSAGES"
/// The `RECENT` attribute: the number of messages with the `\Recent` flag.
///
/// This attribute returns the count of messages that have been added to the mailbox since
/// Returns the count of messages that have been added to the mailbox since
/// the last time it was selected. See [RFC 3501 Section 7.3.2](https://datatracker.ietf.org/doc/html/rfc3501#section-7.3.2).
case recentCount = "RECENT"
/// The `UIDNEXT` attribute: the next unique identifier value.
///
/// This attribute predicts the UID value that will be assigned to the next message appended
/// Predicts the UID value that will be assigned to the next message appended
/// to the mailbox. See [RFC 3501 Section 7.3.2](https://datatracker.ietf.org/doc/html/rfc3501#section-7.3.2).
case uidNext = "UIDNEXT"
@@ -60,20 +60,20 @@ public enum MailboxAttribute: String, CaseIterable, Sendable {
/// The `UNSEEN` attribute: the number of messages without the `\Seen` flag.
///
/// This attribute returns the count of messages in the mailbox that do not have the `\Seen` flag set.
/// Returns the count of messages in the mailbox that do not have the `\Seen` flag set.
/// See [RFC 3501 Section 7.3.2](https://datatracker.ietf.org/doc/html/rfc3501#section-7.3.2).
case unseenCount = "UNSEEN"
/// The `SIZE` attribute: the total size of the mailbox in octets.
///
/// This attribute returns the total size of all messages in the mailbox in bytes (octets).
/// Returns the total size of all messages in the mailbox in bytes (octets).
/// **Requires server capability:** ``Capability/status(_:)`` with ``Capability/StatusKind/size``
/// See [RFC 8438](https://datatracker.ietf.org/doc/html/rfc8438).
case size = "SIZE"
/// The `HIGHESTMODSEQ` attribute: the highest modification sequence value.
///
/// This attribute returns the highest mod-sequence value assigned to any message in the mailbox.
/// Returns the highest mod-sequence value assigned to any message in the mailbox.
/// The `CONDSTORE` extension uses modification sequences to track message changes.
/// **Requires server capability:** ``Capability/condStore``
/// See [RFC 7162 Section 3.1](https://datatracker.ietf.org/doc/html/rfc7162#section-3.1).
@@ -81,14 +81,14 @@ public enum MailboxAttribute: String, CaseIterable, Sendable {
/// The `APPENDLIMIT` attribute: the maximum message upload size in octets.
///
/// This attribute specifies the maximum size (in bytes) of a single message that can be appended to the mailbox.
/// Specifies the maximum size (in bytes) of a single message that can be appended to the mailbox.
/// **Requires server capability:** ``Capability/mailboxSpecificAppendLimit`` or ``Capability/appendLimit(_:)``
/// See [RFC 7889 Section 4](https://datatracker.ietf.org/doc/html/rfc7889#section-4).
case appendLimit = "APPENDLIMIT"
/// The `MAILBOXID` attribute: the server's object identifier for the mailbox.
///
/// This attribute returns a permanent, server-assigned identifier that uniquely identifies the mailbox.
/// Returns a permanent, server-assigned identifier that uniquely identifies the mailbox.
/// Unlike `UIDVALIDITY`, this identifier is globally unique and never reused.
/// **Requires server capability:** ``Capability/objectID``
/// See [RFC 8474 Section 3](https://datatracker.ietf.org/doc/html/rfc8474#section-3).
@@ -119,19 +119,19 @@ public enum MailboxAttribute: String, CaseIterable, Sendable {
public struct MailboxStatus: Hashable, Sendable {
/// The `MESSAGES` attribute: total number of messages in the mailbox.
///
/// This property is `nil` if the `MESSAGES` attribute was not requested or returned.
/// `nil` if the `MESSAGES` attribute was not requested or returned.
/// See [RFC 3501 Section 7.3.2](https://datatracker.ietf.org/doc/html/rfc3501#section-7.3.2).
public var messageCount: Int?
/// The `RECENT` attribute: number of messages with the `\Recent` flag.
///
/// This property is `nil` if the `RECENT` attribute was not requested or returned.
/// `nil` if the `RECENT` attribute was not requested or returned.
/// See [RFC 3501 Section 7.3.2](https://datatracker.ietf.org/doc/html/rfc3501#section-7.3.2).
public var recentCount: Int?
/// The `UIDNEXT` attribute: the next unique identifier value to be assigned.
///
/// This property is `nil` if the `UIDNEXT` attribute was not requested or returned.
/// `nil` if the `UIDNEXT` attribute was not requested or returned.
/// See [RFC 3501 Section 7.3.2](https://datatracker.ietf.org/doc/html/rfc3501#section-7.3.2).
public var nextUID: UID?
@@ -145,20 +145,20 @@ public struct MailboxStatus: Hashable, Sendable {
/// The `UNSEEN` attribute: number of messages without the `\Seen` flag.
///
/// This property is `nil` if the `UNSEEN` attribute was not requested or returned.
/// `nil` if the `UNSEEN` attribute was not requested or returned.
/// See [RFC 3501 Section 7.3.2](https://datatracker.ietf.org/doc/html/rfc3501#section-7.3.2).
public var unseenCount: Int?
/// The `SIZE` attribute: total size of the mailbox in bytes (octets).
///
/// This property is `nil` if the `SIZE` attribute was not requested or returned.
/// `nil` if the `SIZE` attribute was not requested or returned.
/// **Requires server capability:** ``Capability/status(_:)`` with ``Capability/StatusKind/size``
/// See [RFC 8438](https://datatracker.ietf.org/doc/html/rfc8438).
public var size: Int?
/// The `HIGHESTMODSEQ` attribute: the highest modification sequence value assigned to any message.
///
/// This property is `nil` if the `HIGHESTMODSEQ` attribute was not requested or returned.
/// `nil` if the `HIGHESTMODSEQ` attribute was not requested or returned.
/// The `CONDSTORE` extension uses modification sequences to track which messages have changed.
/// **Requires server capability:** ``Capability/condStore``
/// See [RFC 7162 Section 3.1](https://datatracker.ietf.org/doc/html/rfc7162#section-3.1).
@@ -166,7 +166,7 @@ public struct MailboxStatus: Hashable, Sendable {
/// The `APPENDLIMIT` attribute: maximum size per message in bytes (octets).
///
/// This property is `nil` if the `APPENDLIMIT` attribute was not requested or returned.
/// `nil` if the `APPENDLIMIT` attribute was not requested or returned.
/// The `APPENDLIMIT` extension specifies per-mailbox upload limits.
/// **Requires server capability:** ``Capability/mailboxSpecificAppendLimit`` or ``Capability/appendLimit(_:)``
/// See [RFC 7889 Section 4](https://datatracker.ietf.org/doc/html/rfc7889#section-4).
@@ -174,7 +174,7 @@ public struct MailboxStatus: Hashable, Sendable {
/// The `MAILBOXID` attribute: the server's permanent object identifier for the mailbox.
///
/// This property is `nil` if the `MAILBOXID` attribute was not requested or returned.
/// `nil` if the `MAILBOXID` attribute was not requested or returned.
/// The `OBJECTID` extension assigns stable, unique identifiers to mailboxes that persist
/// even if the mailbox is renamed or moved.
/// **Requires server capability:** ``Capability/objectID``
@@ -17,7 +17,7 @@ import struct NIO.ByteBuffer
/// Untagged response data from the server about mailboxes, messages, or search results.
///
/// Servers send untagged responses (prefixed with `*`) that convey information about mailboxes, messages, and operation results.
/// This enum represents the various types of mailbox-related untagged data that a server can send.
/// Represents the various types of mailbox-related untagged data that a server can send.
///
/// These responses are typically encountered as the data within ``Response`` untagged responses, which may
/// be wrapped in ``ResponsePayload/mailboxData(_:)``.
@@ -43,18 +43,18 @@ import struct NIO.ByteBuffer
public struct EmailAddressGroup: Hashable, Sendable {
/// The name of the address group.
///
/// This is the human-readable name for the collection of addresses, such as "Family" or "Work Team".
/// The human-readable name for the collection of addresses, such as "Family" or "Work Team".
public var groupName: ByteBuffer
/// The optional source root for the address group.
///
/// This field may contain additional routing information for the group.
/// May contain additional routing information for the group.
/// Per [RFC 5322](https://datatracker.ietf.org/doc/html/rfc5322), this is typically `nil`.
public var sourceRoot: ByteBuffer?
/// The nested addresses and groups within this group.
///
/// This list can contain both individual addresses (``EmailAddressListElement/singleAddress(_:)``)
/// Can contain both individual addresses (``EmailAddressListElement/singleAddress(_:)``)
/// and nested address groups (``EmailAddressListElement/group(_:)``), allowing for arbitrarily
/// deep hierarchies.
public var children: [EmailAddressListElement]
@@ -78,7 +78,7 @@ public struct EmailAddressGroup: Hashable, Sendable {
/// the ENVELOPE structure includes address lists (such as `To:`, `From:`, `Cc:`) that may contain
/// both individual email addresses and named address groups.
///
/// This is an indirect enum, allowing arbitrarily deep nesting of groups within groups.
/// An indirect enum, allowing arbitrarily deep nesting of groups within groups.
///
/// ### Example
///
@@ -101,12 +101,12 @@ public struct EmailAddressGroup: Hashable, Sendable {
public indirect enum EmailAddressListElement: Hashable, Sendable {
/// A single email address with no children.
///
/// This case wraps a single ``EmailAddress`` in the address list.
/// Wraps a single ``EmailAddress`` in the address list.
case singleAddress(EmailAddress)
/// A collection of addresses organized under a group name.
///
/// This case wraps an ``EmailAddressGroup`` containing a group name and nested
/// Wraps an ``EmailAddressGroup`` containing a group name and nested
/// ``EmailAddressListElement`` children (which can themselves be addresses or groups).
case group(EmailAddressGroup)
}
@@ -92,7 +92,7 @@ extension MailboxInfo {
public struct Attribute: Hashable, Sendable {
/// The mailbox cannot be selected with a `SELECT` command.
///
/// This attribute indicates that the mailbox exists but is not selectable.
/// Indicates that the mailbox exists but is not selectable.
/// A common example is a mailbox used only to contain child mailboxes.
/// See [RFC 3501 Section 7.2.2](https://datatracker.ietf.org/doc/html/rfc3501#section-7.2.2).
public static var noSelect: Self { Self(#"\Noselect"#) }
@@ -157,7 +157,7 @@ extension MailboxInfo {
/// or create custom attributes for extension or server-specific attributes.
/// Attribute names are case-insensitive per the IMAP specification.
///
/// - Parameter str: The attribute name, typically starting with backslash (e.g., "\\Noselect")
/// - Parameter str: The attribute name, typically starting with backslash (for example, "\\Noselect")
public init(_ str: String) {
self.backing = str
}
@@ -29,7 +29,7 @@ public struct MailboxTooBigError: Error, Equatable {
/// A mailbox name contained invalid characters or violated naming constraints.
///
/// This error is raised when a mailbox name contains characters that are not permitted by the IMAP protocol,
/// Raised when a mailbox name contains characters that are not permitted by the IMAP protocol,
/// such as path separators in the display name.
public struct InvalidMailboxNameError: Error, Equatable {
/// A description of why the mailbox name was considered invalid.
@@ -73,7 +73,7 @@ public struct InvalidPathSeparatorError: Error, Equatable {
public struct MailboxPath: Hashable, Sendable {
/// The full mailbox path in Modified UTF-7 encoding.
///
/// This name may contain path separator characters and represents the complete hierarchical path
/// May contain path separator characters and represents the complete hierarchical path
/// to the mailbox as known to the server. The encoding follows
/// [RFC 2152](https://datatracker.ietf.org/doc/html/rfc2152) as required by RFC 3501.
public let name: MailboxName
@@ -99,7 +99,7 @@ public struct MailboxPath: Hashable, Sendable {
/// Creates a new `MailboxPath` with the given name and optional path separator.
///
/// This initializer accepts raw bytes and does not perform encoding. Use ``makeRootMailbox(displayName:pathSeparator:)``
/// Accepts raw bytes and does not perform encoding. Use ``makeRootMailbox(displayName:pathSeparator:)``
/// to create a new mailbox from a display string with automatic encoding, or ``makeSubMailbox(displayName:)``
/// to create a hierarchical mailbox path.
///
@@ -146,7 +146,7 @@ extension MailboxPath {
/// Splits the mailbox path into human-readable display components using the path separator.
///
/// This method converts the Modified UTF-7-encoded mailbox name to a display string by splitting on
/// Converts the Modified UTF-7-encoded mailbox name to a display string by splitting on
/// the path separator. The conversion is lossy and intended for display purposes only. Do not use the
/// returned components as mailbox names for protocol operations.
///
@@ -172,7 +172,7 @@ extension MailboxPath {
/// Creates a new root mailbox path from a display name.
///
/// This factory method encodes the display name using Modified UTF-7 (RFC 2152) and validates
/// Encodes the display name using Modified UTF-7 (RFC 2152) and validates
/// that the resulting mailbox name does not contain the path separator character (if provided).
/// Root mailboxes are top-level mailboxes with no parent hierarchy.
///
@@ -202,7 +202,7 @@ extension MailboxPath {
/// Creates a nested child mailbox path within this mailbox.
///
/// This method encodes the display name using Modified UTF-7 and appends it as a child to the current
/// Encodes the display name using Modified UTF-7 and appends it as a child to the current
/// mailbox path. The path separator is inserted between the parent and child names.
///
/// **Important:** This method should only be used when creating new mailboxes that do not yet exist
@@ -26,7 +26,7 @@ import struct NIO.ByteBuffer
/// - `*` - matches any sequence of zero or more characters, including the hierarchy delimiter
///
/// To list **all mailboxes** on the server, use the pattern `*` (the wildcard that matches everything).
/// This is the most common LIST usage and returns the complete mailbox hierarchy.
/// Using `*` is the most common LIST usage and returns the complete mailbox hierarchy.
///
/// ### Example
///
@@ -41,7 +41,7 @@ import struct NIO.ByteBuffer
/// LIST request, and the server returns matching mailboxes wrapped as ``Response/untagged(_:)``
/// containing ``ResponsePayload/mailboxData(_:)`` entries for each match.
///
/// ### Listing All Mailboxes
/// ### Listing all mailboxes
///
/// ```
/// C: A001 LIST "" "*"
@@ -16,10 +16,10 @@
///
/// In IMAP URLs, a mailbox is identified by its percent-encoded name and an optional UID validity value.
/// The UID validity (``UIDValidity``) is a server-assigned value that helps detect when messages in a
/// mailbox have been invalidated (e.g., after a mailbox has been deleted and recreated).
/// mailbox have been invalidated (for example, after a mailbox has been deleted and recreated).
/// Including the UID validity in a URL helps ensure the URL is not referencing stale or invalid message UIDs.
///
/// This type combines a ``EncodedMailbox`` and optional ``UIDValidity`` to create a complete mailbox
/// Combines a ``EncodedMailbox`` and optional ``UIDValidity`` to create a complete mailbox
/// reference for use in ``MessagePath`` structures. It forms the core of IMAP URL mailbox addressing.
///
/// ### Examples
@@ -40,7 +40,7 @@
/// S: * GENURLAUTH "imap://user@example.com/INBOX/;uidvalidity=4294967295/;uid=20;urlauth=anonymous:internal:..."
/// ```
///
/// ## Related Types
/// ## Related types
///
/// See ``MessagePath`` for the complete message location (mailbox reference, UID, optional section, optional byte range),
/// ``UIDValidity`` for UID validity value details, and ``NetworkMessagePath`` for the full network-accessible URL.
@@ -16,7 +16,7 @@ import struct NIO.ByteBuffer
/// An authorization mechanism paired with base64-encoded authentication data.
///
/// This type is used in URLAUTH contexts (RFC 4467) to specify both the mechanism used to
/// Used in URLAUTH contexts (RFC 4467) to specify both the mechanism used to
/// generate authorization credentials and the base64-encoded credentials themselves.
///
/// - SeeAlso: [RFC 4467 IMAP4 Capabilities for SMTP and SUBMIT](https://datatracker.ietf.org/doc/html/rfc4467)
+22 -22
View File
@@ -14,15 +14,15 @@
/// Namespace grouping MIME media type related types.
///
/// This namespace organizes MIME media type components as defined in [RFC 2045](https://datatracker.ietf.org/doc/html/rfc2045).
/// Organizes MIME media type components as defined in [RFC 2045](https://datatracker.ietf.org/doc/html/rfc2045).
public enum Media {}
extension Media {
/// A MIME media type consisting of a top-level type and subtype.
///
/// MIME media types (also called MIME types or content types) identify the format of message part content.
/// Each media type is composed of a top-level type (e.g., `text`, `image`, `application`) and a subtype
/// (e.g., `plain`, `html`, `jpeg`), separated by a slash in standard notation (e.g., `text/plain`).
/// Each media type is composed of a top-level type (for example, `text`, `image`, or `application`) and a subtype
/// (for example, `plain`, `html`, or `jpeg`), separated by a slash in standard notation (for example, `text/plain`).
///
/// Media types are defined in [RFC 2045 Section 5](https://datatracker.ietf.org/doc/html/rfc2045#section-5) and
/// are included in message body structures retrieved via the `BODYSTRUCTURE` FETCH attribute.
@@ -41,10 +41,10 @@ extension Media {
/// - SeeAlso: ``TopLevelType``
/// - SeeAlso: ``Subtype``
public struct MediaType: Hashable, Sendable {
/// The top-level type component (e.g., `text`, `image`, `application`).
/// The top-level type component (for example, `text`, `image`, or `application`).
public var topLevel: TopLevelType
/// The subtype component (e.g., `plain`, `html`, `jpeg`).
/// The subtype component (for example, `plain`, `html`, or `jpeg`).
public var sub: Subtype
/// Creates a media type from top-level type and subtype components.
@@ -61,11 +61,11 @@ extension Media {
extension Media.MediaType {
/// Creates a media type from string components.
///
/// This is a convenience initializer that creates ``TopLevelType`` and ``Subtype`` instances
/// A convenience initializer that creates ``TopLevelType`` and ``Subtype`` instances
/// from the provided strings, which are automatically lowercased.
///
/// - parameter topLevel: The top-level type as a string (e.g., `"text"`, `"image"`).
/// - parameter sub: The subtype as a string (e.g., `"plain"`, `"html"`).
/// - parameter topLevel: The top-level type as a string (for example, `"text"` or `"image"`).
/// - parameter sub: The subtype as a string (for example, `"plain"` or `"html"`).
public init(topLevel: String, sub: String) {
self.topLevel = Media.TopLevelType(topLevel)
self.sub = Media.Subtype(sub)
@@ -77,7 +77,7 @@ extension Media.MediaType {
extension Media {
/// The top-level type component of a MIME media type.
///
/// The top-level type is the first component of a media type (e.g., `text` in `text/plain`).
/// The top-level type is the first component of a media type (for example, `text` in `text/plain`).
/// Standard top-level types are registered with IANA and are case-insensitive, normalized to lowercase.
///
/// Defined in [RFC 2045 Section 5](https://datatracker.ietf.org/doc/html/rfc2045#section-5) with types
@@ -130,7 +130,7 @@ extension Media {
/// The top-level type as a lowercase string.
///
/// - Returns: The type name in lowercase (e.g., `"text"`, `"image"`, `"multipart"`).
/// - Returns: The type name in lowercase (for example, `"text"`, `"image"`, or `"multipart"`).
public var debugDescription: String {
self.stringValue
}
@@ -140,7 +140,7 @@ extension Media {
/// The provided string is automatically lowercased to normalize the type value. This allows
/// case-insensitive comparison between type values.
///
/// - parameter stringValue: The type name as a string (e.g., `"TEXT"`, `"Image"`, `"text"`). Will be lowercased.
/// - parameter stringValue: The type name as a string (for example, `"TEXT"`, `"Image"`, or `"text"`). Will be lowercased.
public init(_ stringValue: String) {
self.stringValue = stringValue.lowercased()
}
@@ -150,10 +150,10 @@ extension Media {
extension Media.TopLevelType: ExpressibleByStringLiteral {
/// Creates a top-level type from a string literal.
///
/// This allows direct initialization like `let topLevel: Media.TopLevelType = "text"`.
/// Allows direct initialization like `let topLevel: Media.TopLevelType = "text"`.
/// The string literal is automatically lowercased.
///
/// - parameter stringLiteral: The type name as a string literal (e.g., `"text"`, `"image"`).
/// - parameter stringLiteral: The type name as a string literal (for example, `"text"` or `"image"`).
public init(stringLiteral: String) {
self.init(stringLiteral)
}
@@ -173,7 +173,7 @@ extension String {
extension Media {
/// The subtype component of a MIME media type.
///
/// The subtype is the second component of a media type (e.g., `plain` in `text/plain`).
/// The subtype is the second component of a media type (for example, `plain` in `text/plain`).
/// Subtypes are case-insensitive, normalized to lowercase, and are specific to their top-level type.
///
/// Defined in [RFC 2045](https://datatracker.ietf.org/doc/html/rfc2045) with subtypes registered at
@@ -186,20 +186,20 @@ extension Media {
/// Clients should display the most appropriate alternative according to user preferences.
public static let alternative = Self("alternative")
/// The `multipart/related` subtype, specifying related body parts (e.g., HTML with embedded images).
/// The `multipart/related` subtype, specifying related body parts (for example, HTML with embedded images).
///
/// Parts in a multipart/related message are typically related to one another (e.g., an HTML
/// Parts in a multipart/related message are typically related to one another (for example, an HTML
/// document with embedded images or stylesheets).
public static let related = Self("related")
/// The `multipart/mixed` subtype, specifying a generic set of mixed data types.
///
/// This is the default multipart subtype for messages with multiple unrelated parts.
/// The default multipart subtype for messages with multiple unrelated parts.
public static let mixed = Self("mixed")
/// The `message/rfc822` subtype for encapsulated email messages.
///
/// This subtype indicates the message part contains a complete RFC 822 (email) message,
/// Indicates the message part contains a complete RFC 822 (email) message,
/// which may have its own headers, body structure, and attachments.
public static let rfc822 = Self("rfc822")
@@ -208,7 +208,7 @@ extension Media {
/// The subtype as a lowercase string.
///
/// - Returns: The subtype name in lowercase (e.g., `"plain"`, `"html"`, `"mixed"`).
/// - Returns: The subtype name in lowercase (for example, `"plain"`, `"html"`, or `"mixed"`).
public var debugDescription: String { self.stringValue }
/// Creates a subtype from a string.
@@ -216,7 +216,7 @@ extension Media {
/// The provided string is automatically lowercased to normalize the subtype value. This allows
/// case-insensitive comparison between subtype values.
///
/// - parameter stringValue: The subtype name as a string (e.g., `"PLAIN"`, `"Html"`, `"plain"`). Will be lowercased.
/// - parameter stringValue: The subtype name as a string (for example, `"PLAIN"`, `"Html"`, or `"plain"`). Will be lowercased.
public init(_ stringValue: String) {
self.stringValue = stringValue.lowercased()
}
@@ -226,10 +226,10 @@ extension Media {
extension Media.Subtype: ExpressibleByStringLiteral {
/// Creates a subtype from a string literal.
///
/// This allows direct initialization like `let subtype: Media.Subtype = "plain"`.
/// Allows direct initialization like `let subtype: Media.Subtype = "plain"`.
/// The string literal is automatically lowercased.
///
/// - parameter stringLiteral: The subtype name as a string literal (e.g., `"plain"`, `"html"`).
/// - parameter stringLiteral: The subtype name as a string literal (for example, `"plain"` or `"html"`).
public init(stringLiteral: String) {
self.init(stringLiteral)
}
@@ -37,7 +37,7 @@
/// for this message. If copied to another mailbox, the copied message will receive the same
/// `EMAILID`, allowing clients to recognize the messages as identical content.
///
/// ## Related Proprietary Identifiers
/// ## Related proprietary identifiers
///
/// Gmail servers provide a similar but proprietary identifier via the `X-GM-MSGID` field (see
/// ``FetchAttribute/gmailMessageID``). While both serve similar purposes, `EMAILID` is
@@ -19,7 +19,7 @@ import struct NIO.ByteBuffer
/// in the X-GM-LABELS attribute of a FETCH response. Labels are stored as byte buffers and may be
/// encoded in modified UTF-7 format (the same encoding used for mailbox names).
///
/// This is a Gmail-specific extension not part of the standard IMAP protocol. It is available when
/// A Gmail-specific extension not part of the standard IMAP protocol. It is available when
/// the server advertises the X-GM-EXT-1 capability.
///
/// ### Example
@@ -29,7 +29,7 @@ import struct NIO.ByteBuffer
/// S: * 1 FETCH (X-GM-LABELS ("Important" "Work"))
/// ```
///
/// This response indicates message 1 has two labels: "Important" and "Work".
/// The response indicates message 1 has two labels: "Important" and "Work".
///
/// - SeeAlso: [Gmail IMAP Extensions](https://developers.google.com/gmail/imap/imap-extensions)
/// - SeeAlso: ``MessageAttribute/gmailLabels(_:)``
@@ -30,13 +30,13 @@ import struct NIO.ByteBuffer
/// The response line contains three attributes: ``flags(_:)`` wrapping `\Seen`, ``envelope(_:)`` containing the message envelope,
/// and ``uid(_:)`` with UID `123`.
///
/// ## Request vs Response
/// ## Request versus response
///
/// Use ``FetchAttribute`` to request specific message attributes in a `FETCH` command. The server responds with ``MessageAttribute``
/// values containing the requested data. Not all ``FetchAttribute`` cases have corresponding ``MessageAttribute`` cases — for example,
/// ``FetchAttribute/bodyStructure(extensions:)`` (a request) produces ``body(_:hasExtensionData:)`` (response).
///
/// ## Related Types
/// ## Related types
///
/// - ``FetchAttribute`` — Request side (what the client asks for)
/// - ``FetchModifier`` — Modifiers for `FETCH` commands (RFC 7162)
@@ -56,7 +56,7 @@ public enum MessageAttribute: Hashable, Sendable {
/// S: * 1 FETCH (FLAGS (\Seen \Flagged))
/// ```
///
/// This response contains the ``flags(_:)`` case with two system flags.
/// The response contains the ``flags(_:)`` case with two system flags.
///
/// - SeeAlso: [RFC 3501 Section 7.4.2](https://datatracker.ietf.org/doc/html/rfc3501#section-7.4.2)
case flags([Flag])
@@ -149,7 +149,7 @@ public enum MessageAttribute: Hashable, Sendable {
/// S: * 1 FETCH (BINARY.SIZE[2] 5000)
/// ```
///
/// This indicates body part 2 has 5000 octets when decoded.
/// Indicates body part 2 has 5000 octets when decoded.
///
/// - SeeAlso: [RFC 3516 IMAP4 Binary Content Extension](https://datatracker.ietf.org/doc/html/rfc3516)
case binarySize(section: SectionSpecifier.Part, size: Int)
@@ -166,7 +166,7 @@ public enum MessageAttribute: Hashable, Sendable {
/// S: * 1 FETCH (BODY[4.TEXT] NIL)
/// ```
///
/// This indicates that body part 4 has no TEXT section (it doesn’t exist).
/// Indicates that body part 4 has no TEXT section (it doesn’t exist).
///
/// - SeeAlso: [RFC 3501 Section 7.4.2](https://datatracker.ietf.org/doc/html/rfc3501#section-7.4.2)
case nilBody(StreamingKind)
@@ -174,7 +174,7 @@ public enum MessageAttribute: Hashable, Sendable {
/// The modification sequence number for the message.
///
/// The `MODSEQ` attribute contains a modification sequence number indicating when the message or its flags last changed.
/// This is used with the `CONDSTORE` extension for efficient synchronization.
/// Used with the `CONDSTORE` extension for efficient synchronization.
///
/// - SeeAlso: [RFC 7162 IMAP4 Extensions: CONDSTORE and QRESYNC](https://datatracker.ietf.org/doc/html/rfc7162)
case fetchModificationSequence(ModificationSequenceValue)
@@ -182,7 +182,7 @@ public enum MessageAttribute: Hashable, Sendable {
/// Gmail-specific message unique identifier (vendor extension).
///
/// The `X-GM-MSGID` attribute contains a Gmail-specific unique message ID that remains stable across mailboxes.
/// This is a 64-bit unsigned integer. This is a Gmail-only extension, not part of the standard IMAP protocol.
/// A 64-bit unsigned integer and Gmail-only extension, not part of the standard IMAP protocol.
///
/// For standard IMAP object identifiers, see ``emailID(_:)`` which uses RFC 8474.
///
@@ -192,7 +192,7 @@ public enum MessageAttribute: Hashable, Sendable {
/// Gmail-specific thread identifier (vendor extension).
///
/// The `X-GM-THRID` attribute contains a Gmail-specific thread ID that associates messages belonging to the same thread.
/// This is a 64-bit unsigned integer. This is a Gmail-only extension, not part of the standard IMAP protocol.
/// A 64-bit unsigned integer and Gmail-only extension, not part of the standard IMAP protocol.
///
/// For standard IMAP object identifiers, see ``threadID(_:)`` which uses RFC 8474.
///
@@ -202,7 +202,7 @@ public enum MessageAttribute: Hashable, Sendable {
/// Gmail-specific message labels (vendor extension).
///
/// The `X-GM-LABELS` attribute contains a list of labels (tags) applied to the message in Gmail. Each label is a ``GmailLabel``.
/// This is a Gmail-only extension, not part of the standard IMAP protocol.
/// A Gmail-only extension, not part of the standard IMAP protocol.
///
/// - SeeAlso: [Gmail IMAP Extensions](https://developers.google.com/gmail/imap/imap-extensions)
case gmailLabels([GmailLabel])
@@ -219,7 +219,7 @@ public enum MessageAttribute: Hashable, Sendable {
/// An object identifier for the message content.
///
/// The `EMAILID` attribute contains an object identifier that uniquely identifies the message’s content.
/// This is stable across servers and can be used to detect when a message with the same content exists
/// Stable across servers and can be used to detect when a message with the same content exists
/// in different mailboxes or on different servers.
///
/// For Gmail-specific message identifiers, see ``gmailMessageID(_:)`` which uses the `X-GM-MSGID` extension.
@@ -230,7 +230,7 @@ public enum MessageAttribute: Hashable, Sendable {
/// An object identifier for the message thread.
///
/// The `THREADID` attribute contains an object identifier for the thread the message belongs to.
/// This is `nil` if the message is not part of a thread or if the server does not support threading.
/// `nil` if the message is not part of a thread or if the server does not support threading.
///
/// For Gmail-specific thread identifiers, see ``gmailThreadID(_:)`` which uses the `X-GM-THRID` extension.
///
@@ -40,7 +40,7 @@ public enum MessageData: Hashable, Sendable {
///
/// The EXPUNGE response indicates that the message at the specified sequence number
/// no longer exists. Clients must renumber remaining messages accordingly.
/// This response is not sent for UID-based commands.
/// Not sent for UID-based commands.
///
/// - SeeAlso: [RFC 3501 Section 7.4.1 EXPUNGE](https://datatracker.ietf.org/doc/html/rfc3501#section-7.4.1)
case expunge(SequenceNumber)
@@ -42,7 +42,7 @@
/// Messages 1 and 2 have the same `THREADID (abc123def456)`, indicating they are related.
/// Message 3 has a different `THREADID (xyz789abc123)`, indicating it belongs to a different thread.
///
/// ## Related Proprietary Identifiers
/// ## Related proprietary identifiers
///
/// Gmail servers provide a similar but proprietary identifier via the `X-GM-THRID` field (see
/// ``FetchAttribute/gmailThreadID``). While both serve similar purposes, `THREADID` is
+1 -1
View File
@@ -18,7 +18,7 @@
/// formatted as angle-bracketed text, for example <B27397-0100000@cac.washington.edu>. The Message-ID
/// appears in the In-Reply-To header and is used to correlate related messages in threads.
///
/// This type wraps the raw string value including angle brackets as sent by the server.
/// Wraps the raw string value including angle brackets as sent by the server.
///
/// ### Example
///
@@ -23,7 +23,7 @@
/// - **URLAUTH URLs**: `imap://server/mailbox/;uidvalidity=V/;uid=N;urlauth=...`
/// - **CATENATE operations**: Reference existing messages when composing new messages (RFC 4469)
///
/// ### Message Path Components
/// ### Message path components
///
/// 1. **Mailbox Reference** (``MailboxUIDValidity``): Identifies the mailbox with optional UID validity
/// 2. **Message UID** (``IUID``): The message unique identifier
@@ -53,7 +53,7 @@
/// S: * GENURLAUTH "imap://user@example.com/INBOX/;uidvalidity=4294967295/;uid=20;urlauth=anonymous:internal:..."
/// ```
///
/// ## Related Types
/// ## Related types
///
/// - ``MailboxUIDValidity`` provides the mailbox reference
/// - ``IUID`` wraps the message unique identifier
@@ -74,7 +74,7 @@ public struct MessagePath: Hashable, Sendable {
/// The unique identifier of the message within the mailbox.
public var iUID: IUID
/// Optional section of the message (e.g., "1", "2.MIME", "TEXT").
/// Optional section of the message (for example, "1", "2.MIME", or "TEXT").
///
/// When `nil`, refers to the entire message. When specified, refers to a specific
/// part or substructure of the message.
@@ -35,7 +35,7 @@ import NIO
/// in the ``MetadataResponse/values(values:mailbox:)`` response. They appear in ``Response/untagged(_:)``
/// containing ``ResponsePayload/metadata(_:)``.
///
/// ## Related Types
/// ## Related types
///
/// - See ``MetadataValue`` for metadata entry values
/// - See ``MetadataResponse`` for complete metadata responses
@@ -54,7 +54,7 @@ public struct MetadataEntryName: Hashable, Sendable {
/// Creates a `MetadataEntryName` from a `String`.
///
/// - parameter string: The entry name as a string (e.g., `"/shared/comment"`, `"/private/notes"`).
/// - parameter string: The entry name as a string (for example, `"/shared/comment"` or `"/private/notes"`).
public init(_ string: String) {
self.backing = ByteBuffer(string: string)
}
@@ -31,7 +31,7 @@
/// The options `(MAXSIZE 1024 DEPTH 1)` are ``MetadataOption`` values that limit results to entries
/// with a maximum size of 1024 bytes and restrict the search to a depth of 1 level.
///
/// ## Related Types
/// ## Related types
///
/// - See ``MetadataEntryName`` for metadata entry names
/// - See ``MetadataValue`` for metadata entry values
@@ -35,7 +35,7 @@ import struct OrderedCollections.OrderedDictionary
/// ``ResponsePayload/metadata(_:)`` with a ``MetadataResponse/values(values:mailbox:)`` case.
/// Each entry name maps to a ``MetadataValue`` (which may be `nil` if not found).
///
/// ## Related Types
/// ## Related types
///
/// - See ``MetadataEntryName`` for entry name representation
/// - See ``MetadataValue`` for entry values
@@ -35,7 +35,7 @@ import struct NIO.ByteBuffer
/// - `MetadataValue(ByteBuffer("Team folder"))` for `/shared/comment`
/// - `MetadataValue(nil)` for `/private/notes` (not set or deleted)
///
/// ## Related Types
/// ## Related types
///
/// - See ``MetadataEntryName`` for entry names
/// - See ``MetadataResponse`` for complete metadata responses
@@ -17,7 +17,7 @@ import struct OrderedCollections.OrderedDictionary
/// A description of a single namespace, including its prefix and hierarchy delimiter.
///
/// This type represents one namespace descriptor in the server's namespace configuration (RFC 2342).
/// Represents one namespace descriptor in the server's namespace configuration (RFC 2342).
/// It consists of a prefix string that specifies the mailbox path hierarchy and an optional hierarchy
/// delimiter that separates mailbox name components. For namespaces that do not use a hierarchy delimiter,
/// the delimiter is `nil`.
@@ -30,7 +30,7 @@ import struct OrderedCollections.OrderedDictionary
/// S: * NAMESPACE (("" "/") ("INBOX." ".")) NIL NIL
/// ```
///
/// This response contains two personal namespace descriptors:
/// The response contains two personal namespace descriptors:
/// - The first is ``NamespaceDescription`` with prefix `""` (empty string) and delimiter `/`
/// - The second is ``NamespaceDescription`` with prefix `INBOX.` and delimiter `.`
///
@@ -38,7 +38,7 @@ import struct OrderedCollections.OrderedDictionary
public struct NamespaceDescription: Hashable, Sendable {
/// The namespace prefix string.
///
/// This prefix specifies the root of the namespace. Mailboxes within this namespace
/// Specifies the root of the namespace. Mailboxes within this namespace
/// are accessed by appending the mailbox name to this prefix, separated by the delimiter.
/// An empty string indicates the namespace has no prefix (mailboxes are accessed directly).
public var string: ByteBuffer
@@ -52,7 +52,7 @@ public struct NamespaceDescription: Hashable, Sendable {
/// Response extensions for this namespace, supporting future protocol enhancements.
///
/// This dictionary contains arbitrary key-value pairs that may be included by servers
/// Contains arbitrary key-value pairs that may be included by servers
/// to provide additional namespace information. Keys are extension names, and values are
/// arrays of strings containing the extension parameters.
/// Non-standard extensions should be prefixed with `X-` as per RFC 2342.
@@ -16,7 +16,7 @@ import struct NIO.ByteBuffer
/// A response containing the server's namespace configuration for personal, other users', and shared mailboxes.
///
/// This type represents the response to a `NAMESPACE` command (RFC 2342), which allows clients to discover
/// Represents the response to a `NAMESPACE` command (RFC 2342), which allows clients to discover
/// the mailbox namespace structure used by the server. The response contains three namespace categories,
/// each consisting of zero or more ``NamespaceDescription`` objects. Any category that is not available
/// on the server will contain an empty array.
@@ -32,7 +32,7 @@ import struct NIO.ByteBuffer
/// S: A001 OK NAMESPACE command completed
/// ```
///
/// This response is wrapped as ``NamespaceResponse`` where:
/// The response is wrapped as ``NamespaceResponse`` where:
/// - `userNamespace` is `[NamespaceDescription(string: "", delimiter: "/")]`
/// - `otherUserNamespace` is `[NamespaceDescription(string: "~", delimiter: "/")]`
/// - `sharedNamespace` is `[]` (NIL indicates no shared namespace available)
@@ -25,7 +25,7 @@ import struct NIO.ByteBuffer
///
/// ### Usage in IMAP URLs
///
/// This type represents the base URL before any URLAUTH authorization is added:
/// Represents the base URL before any URLAUTH authorization is added:
/// ```
/// imap://user@example.com/INBOX/;uidvalidity=100/;uid=20
/// ```
@@ -52,7 +52,7 @@ import struct NIO.ByteBuffer
///
/// The `imap://owner@example.com/INBOX/;uid=20` portion would be a ``NetworkMessagePath``.
///
/// ## Related Types
/// ## Related types
///
/// - ``MessagePath`` provides the message location (mailbox, UID, section, range)
/// - ``IMAPServer`` provides the server connection details
@@ -46,7 +46,7 @@
/// Result: imap://other.com/
/// ```
///
/// ## Related Types
/// ## Related types
///
/// - ``RelativeIMAPURL`` uses network paths as one variant of relative URLs
/// - ``IMAPServer`` provides the server connection specification
@@ -18,7 +18,7 @@ import struct NIO.ByteBuffer
///
/// **Requires server capability:** ``Capability/multiSearch``
///
/// This type represents a non-empty list of mailbox names used with mailbox filters in RFC 7377 MULTIMAILBOX SEARCH.
/// Represents a non-empty list of mailbox names used with mailbox filters in RFC 7377 MULTIMAILBOX SEARCH.
/// The filter types are defined in RFC 5465 NOTIFY but are re-used by RFC 7377. Certain filters like
/// ``MailboxFilter/subtree(_:)`` and ``MailboxFilter/mailboxes(_:)`` require one or more specific mailbox names.
/// See [RFC 7377 Section 3](https://datatracker.ietf.org/doc/html/rfc7377#section-3).
@@ -34,7 +34,7 @@ import struct NIO.ByteBuffer
/// The mailbox names `"Archive"` and `"Sent Mail"` form a ``Mailboxes`` collection that specifies
/// which mailboxes (via ``MailboxFilter``) are included in a multi-mailbox search operation.
///
/// ## Related Types
/// ## Related types
///
/// - See ``MailboxFilter`` for different ways to select mailboxes
/// - See ``MailboxName`` for individual mailbox name representation
@@ -43,7 +43,7 @@ import struct NIO.ByteBuffer
public struct Mailboxes: Hashable, Sendable {
/// Array of one or more mailbox names.
///
/// This collection must contain at least one mailbox. The mailboxes are represented as
/// Must contain at least one mailbox. The mailboxes are represented as
/// ``MailboxName`` values, which can include standard or UTF-7-modified mailbox names.
public let content: [MailboxName]
@@ -16,7 +16,7 @@ import struct NIO.ByteBuffer
/// An option value, which can be a single string or a nested array of values.
///
/// This recursive enum allows option values to be nested arbitrarily deep, enabling representation
/// Allows option values to be nested arbitrarily deep, enabling representation
/// of complex structured data in the RFC 4466 extension mechanism. Values can be simple strings
/// or arrays of other option values, supporting flexible data representation.
///
@@ -16,7 +16,7 @@
///
/// The `PARTIAL` extension (RFC 9394) allows clients to request `SEARCH` and `FETCH` results
/// in fixed-size pages, either from the beginning (`.first`) or end (`.last`) of the result set.
/// This enables efficient pagination of large result sets without retrieving the entire list.
/// Enables efficient pagination of large result sets without retrieving the entire list.
///
/// The two forms are:
/// - `.first`: Requests N results starting from the lowest UID (beginning)
@@ -30,7 +30,7 @@ public enum PartialRange: Hashable, Sendable {
case first(SequenceRange)
/// A range relative to the newest (highest UID) message.
///
/// This is encoded as negative number.
/// Encoded as a negative number.
///
/// Aka. `partial-range-last`.
case last(SequenceRange)
@@ -17,7 +17,7 @@ import struct NIO.ByteBuffer
extension SearchReturnData {
/// Partial search results with a specified range.
///
/// This type contains the range that was requested via the `PARTIAL` modifier and the
/// Contains the range that was requested via the `PARTIAL` modifier and the
/// message numbers matching the search within that range. The `PARTIAL` extension (RFC 9394)
/// enables efficient pagination of large search results.
///
@@ -37,7 +37,7 @@ import struct NIO.ByteBuffer
///
/// These appear as part of the ``ResponsePayload/quota(_:_:)`` response.
///
/// ## Related Types
/// ## Related types
///
/// - See ``QuotaResource`` for current usage along with limits
/// - See ``QuotaRoot`` for quota root names
@@ -59,7 +59,7 @@ public struct QuotaLimit: Hashable, Sendable {
/// Creates a new `QuotaLimit` with a resource name and maximum limit.
///
/// - parameter resourceName: The resource name (e.g., `"STORAGE"`, `"MESSAGE"`).
/// - parameter resourceName: The resource name (for example, `"STORAGE"` or `"MESSAGE"`).
/// - parameter limit: The maximum allowed value for the resource.
public init(resourceName: String, limit: Int) {
self.resourceName = resourceName
@@ -37,7 +37,7 @@ import struct NIO.ByteBuffer
///
/// These appear as part of the ``ResponsePayload/quota(_:_:)`` response.
///
/// ## Related Types
/// ## Related types
///
/// - See ``QuotaLimit`` for just the maximum limit without usage
/// - See ``QuotaRoot`` for quota root names
@@ -65,7 +65,7 @@ public struct QuotaResource: Hashable, Sendable {
/// Creates a new `QuotaResource` with current usage and maximum limit.
///
/// - parameter resourceName: The resource name (e.g., `"STORAGE"`, `"MESSAGE"`).
/// - parameter resourceName: The resource name (for example, `"STORAGE"` or `"MESSAGE"`).
/// - parameter usage: The current usage of the resource.
/// - parameter limit: The maximum allowed value for the resource.
public init(resourceName: String, usage: Int, limit: Int) {
@@ -35,7 +35,7 @@ import struct NIO.ByteBufferView
/// along with an array of ``QuotaResource`` values. This response is wrapped as
/// ``Response/untagged(_:)`` containing ``ResponsePayload/quota(_:_:)``.
///
/// ## Related Types
/// ## Related types
///
/// - See ``QuotaResource`` for resource usage and limits
/// - See ``ResponsePayload/quotaRoot(_:_:)`` for mailbox-to-quota-root associations
@@ -55,7 +55,7 @@
/// imap://user@example.com/INBOX/
/// ```
///
/// ## Related Types
/// ## Related types
///
/// - ``IMAPURL`` provides absolute URL specification
/// - ``NetworkPath`` represents network-accessible paths
@@ -35,7 +35,7 @@ import struct NIO.ByteBuffer
/// indicates the search matched 42 messages (COUNT 42) and provides the UIDs of all matches
/// (ALL 1,3,5,7,9,...) because UID was specified and RETURN (COUNT ALL) was requested.
///
/// ## Related Types
/// ## Related types
///
/// Link to related types using DocC symbol links: ``SearchReturnOption``, ``SearchReturnData``,
/// ``SearchCorrelator``.
@@ -115,7 +115,7 @@ extension ExtendedSearchResponse {
/// Returns `nil` if this is not a UID response or if the response does not contain matched UIDs.
/// When no matching UIDs exist, this property returns an empty set rather than `nil`.
///
/// This property extracts UIDs from ``SearchReturnData/all(_:)`` if present, or falls back to
/// Extracts UIDs from ``SearchReturnData/all(_:)`` if present, or falls back to
/// ``SearchReturnData/partial(_:_:)`` if only partial results are available. Per RFC 9394, a
/// single SEARCH response should contain either ALL or PARTIAL, but not both; if both are
/// present, ALL takes precedence.
@@ -132,7 +132,7 @@ extension ExtendedSearchResponse {
/// Returns `nil` if this is not a sequence number response or if the response does not contain matched sequence numbers.
/// When no matching sequence numbers exist, this property returns an empty set rather than `nil`.
///
/// This property extracts sequence numbers from ``SearchReturnData/all(_:)`` if present, or falls back to
/// Extracts sequence numbers from ``SearchReturnData/all(_:)`` if present, or falls back to
/// ``SearchReturnData/partial(_:_:)`` if only partial results are available. Per RFC 9394, a
/// single SEARCH response should contain either ALL or PARTIAL, but not both; if both are
/// present, ALL takes precedence.
@@ -27,7 +27,7 @@ public enum ResponseOrContinuationRequest: Hashable, Sendable {
/// and command continuation requests (prefixed with `+`). This enum wraps all response variants.
/// See [RFC 3501 Section 7](https://datatracker.ietf.org/doc/html/rfc3501#section-7) for details.
///
/// ## Response Types
/// ## Response types
///
/// **Untagged responses** (``untagged(_:)``) convey server data or status information that does not
/// indicate command completion. Examples include capabilities, mailbox status, and message data.
@@ -123,7 +123,7 @@ public enum Response: Hashable, Sendable {
/// S: * BYE Server shutting down
/// ```
///
/// This line is wrapped as ``Response/fatal(_:)`` containing a ``ResponseText`` with the
/// The line is wrapped as ``Response/fatal(_:)`` containing a ``ResponseText`` with the
/// server's message.
///
/// - SeeAlso: ``ResponseText``, [RFC 3501 Section 7.1.3](https://datatracker.ietf.org/doc/html/rfc3501#section-7.1.3)
@@ -195,7 +195,7 @@ extension Response: CustomDebugStringConvertible {
/// Creates a string from the array of `Response` with all _personally identifiable information_ redacted.
///
/// This is equivalent to joining `debugDescription` of all elements.
/// Equivalent to joining `debugDescription` of all elements.
public static func descriptionWithoutPII(_ responses: some Sequence<Response>) -> String {
ResponseEncodeBuffer.makeDescription(loggingMode: true) {
for response in responses {
@@ -228,7 +228,7 @@ extension Response: CustomDebugStringConvertible {
/// S: )
/// ```
///
/// This represents a fetch for message 1. The first line contains the simple attributes
/// The above represents a fetch for message 1. The first line contains the simple attributes
/// (UID and FLAGS), wrapped in separate ``FetchResponse/simpleAttribute(_:)`` events. The
/// second part begins a streaming section with ``FetchResponse/streamingBegin(kind:byteCount:)``
/// for the message body, followed by ``FetchResponse/streamingBytes(_:)`` events, and
@@ -238,7 +238,7 @@ extension Response: CustomDebugStringConvertible {
public enum FetchResponse: Hashable, Sendable {
/// The beginning of a fetch response for the message at the given sequence number.
///
/// This is the first event in a fetch response sequence. The sequence number can be used to
/// The first event in a fetch response sequence. The sequence number can be used to
/// correlate this fetch with the original FETCH command.
///
/// - SeeAlso: ``SequenceNumber``, [RFC 3501 Section 2.3.1.2](https://datatracker.ietf.org/doc/html/rfc3501#section-2.3.1.2)
@@ -248,7 +248,7 @@ public enum FetchResponse: Hashable, Sendable {
///
/// When a client uses “UID Only” mode (see [RFC 9586](https://datatracker.ietf.org/doc/html/rfc9586)),
/// the server returns only the UID in the FETCH response rather than the sequence number.
/// This is more efficient for pipelined commands.
/// More efficient for pipelined commands.
///
/// - SeeAlso: ``UID``, [RFC 9586](https://datatracker.ietf.org/doc/html/rfc9586) - IMAP Extension: SUBMIT
case startUID(UID)
@@ -264,7 +264,7 @@ public enum FetchResponse: Hashable, Sendable {
/// The start of a streaming section containing potentially large data.
///
/// This event indicates that a large message part (body, RFC 822 header, etc.) is about to be
/// Indicates that a large message part (body, RFC 822 header, etc.) is about to be
/// streamed to the client. The ``StreamingKind`` specifies which part is being streamed,
/// and the `byteCount` parameter indicates the total bytes that will follow.
///
@@ -288,7 +288,7 @@ public enum FetchResponse: Hashable, Sendable {
/// The end of the currently streaming section.
///
/// This marks the completion of a streaming section started by ``streamingBegin(kind:byteCount:)``.
/// Marks the completion of a streaming section started by ``streamingBegin(kind:byteCount:)``.
/// More streaming sections may immediately follow, or the fetch may complete with ``finish``.
///
/// - SeeAlso: ``streamingBegin(kind:byteCount:)``
@@ -296,7 +296,7 @@ public enum FetchResponse: Hashable, Sendable {
/// The end of all fetch data for this message.
///
/// This is the final event in a fetch response sequence. After this, processing of the message
/// The final event in a fetch response sequence. After this, processing of the message
/// is complete, and a new fetch (or other response) may begin.
case finish
}
@@ -328,7 +328,7 @@ public enum StreamingKind: Hashable, Sendable {
/// The `BINARY[1] {512}` indicates that 512 bytes of binary data from message part 1 will be
/// streamed. This corresponds to ``StreamingKind/binary(section:offset:)`` with an empty offset.
///
/// - parameter section: The part of the message to fetch (e.g., 1, 2.1)
/// - parameter section: The part of the message to fetch (for example, 1 or 2.1)
/// - parameter offset: Optional byte offset for partial fetch (requires RFC 9394 PARTIAL extension)
///
/// - SeeAlso: ``SectionSpecifier/Part``, [RFC 3516](https://datatracker.ietf.org/doc/html/rfc3516)
@@ -337,7 +337,7 @@ public enum StreamingKind: Hashable, Sendable {
/// A body section being streamed.
///
/// The `BODY` fetch item returns message structure and content according to [RFC 3501](https://datatracker.ietf.org/doc/html/rfc3501).
/// The `section` specifies which part of the message is being returned (e.g., TEXT for the message body,
/// The `section` specifies which part of the message is being returned (for example, TEXT for the message body,
/// HEADER for headers, or 1.2.3 for nested MIME parts). The `offset` specifies a byte offset for
/// partial fetches.
///
@@ -350,7 +350,7 @@ public enum StreamingKind: Hashable, Sendable {
/// ```
///
/// The `BODY[TEXT] {1024}` indicates that 1024 bytes of the message body text will be streamed.
/// This corresponds to ``StreamingKind/body(section:offset:)`` with the TEXT section specifier.
/// Corresponds to ``StreamingKind/body(section:offset:)`` with the TEXT section specifier.
///
/// - parameter section: The section specifier (part and section type)
/// - parameter offset: Optional byte offset for partial fetch (requires RFC 9394 PARTIAL extension)
@@ -372,7 +372,7 @@ public enum StreamingKind: Hashable, Sendable {
/// ```
///
/// The `RFC822 {2048}` indicates that 2048 bytes of the complete message will be streamed.
/// This corresponds to ``StreamingKind/rfc822``.
/// Corresponds to ``StreamingKind/rfc822``.
///
/// - SeeAlso: [RFC 3501 Section 6.4.5](https://datatracker.ietf.org/doc/html/rfc3501#section-6.4.5)
case rfc822
@@ -391,7 +391,7 @@ public enum StreamingKind: Hashable, Sendable {
/// ```
///
/// The `RFC822.TEXT {1024}` indicates that 1024 bytes of the message body will be streamed.
/// This corresponds to ``StreamingKind/rfc822Text``.
/// Corresponds to ``StreamingKind/rfc822Text``.
///
/// - SeeAlso: [RFC 3501 Section 6.4.5](https://datatracker.ietf.org/doc/html/rfc3501#section-6.4.5)
case rfc822Text
@@ -410,7 +410,7 @@ public enum StreamingKind: Hashable, Sendable {
/// ```
///
/// The `RFC822.HEADER {512}` indicates that 512 bytes of the message headers will be streamed.
/// This corresponds to ``StreamingKind/rfc822Header``.
/// Corresponds to ``StreamingKind/rfc822Header``.
///
/// - SeeAlso: [RFC 3501 Section 6.4.5](https://datatracker.ietf.org/doc/html/rfc3501#section-6.4.5)
case rfc822Header
@@ -35,7 +35,7 @@
public struct ResponseCodeAppend: Hashable, Sendable {
/// The UID validity value of the destination mailbox.
///
/// This value allows clients to validate that the UIDs returned in this response are still
/// Allows clients to validate that the UIDs returned in this response are still
/// correct if they are later referenced. If the UID validity changes, all cached UIDs are invalid.
///
/// - SeeAlso: ``UIDValidity``
@@ -43,7 +43,7 @@ public struct ResponseCodeAppend: Hashable, Sendable {
/// The UIDs of the messages after they have been appended.
///
/// This set contains the UID or UIDs assigned by the server to the messages that were just
/// Contains the UID or UIDs assigned by the server to the messages that were just
/// appended. The sequence and count of UIDs corresponds to the number of messages appended by
/// the APPEND command.
///
@@ -39,7 +39,7 @@
public struct ResponseCodeCopy: Hashable, Sendable {
/// The UID validity value of the destination mailbox.
///
/// This value allows clients to validate that the destination UIDs are still correct if
/// Allows clients to validate that the destination UIDs are still correct if
/// referenced later. If the UID validity of the destination mailbox changes, the cached
/// destination UIDs become invalid.
///
@@ -44,7 +44,7 @@ import struct OrderedCollections.OrderedDictionary
/// The third line corresponds to ``capabilityData(_:)``, while the fourth corresponds
/// to ``id(_:)``.
///
/// ## Related Types
/// ## Related types
///
/// See ``Response`` for the main response wrapper, ``UntaggedStatus`` for conditional status responses,
/// and ``ResponsePayload`` cases for detailed information types.
@@ -53,7 +53,7 @@ import struct OrderedCollections.OrderedDictionary
public enum ResponsePayload: Hashable, Sendable {
/// Indicates if a command executed successfully or encountered an error.
///
/// This case wraps an ``UntaggedStatus`` which can be `OK` (success), `NO` (warning/rejection),
/// Wraps an ``UntaggedStatus`` which can be `OK` (success), `NO` (warning/rejection),
/// `BAD` (protocol error), `PREAUTH` (pre-authenticated), or `BYE` (server closing connection).
/// See [RFC 3501 Section 7.1](https://datatracker.ietf.org/doc/html/rfc3501#section-7.1) for
/// details on status responses.
@@ -61,33 +61,33 @@ public enum ResponsePayload: Hashable, Sendable {
/// Contains information on a single mailbox.
///
/// This case wraps mailbox-specific data such as flags, existence counts, recent count,
/// Wraps mailbox-specific data such as flags, existence counts, recent count,
/// and search results. See ``MailboxData`` for the various mailbox information types.
case mailboxData(MailboxData)
/// Contains information on a single message.
///
/// This case wraps message-specific data returned during FETCH operations or other
/// Wraps message-specific data returned during FETCH operations or other
/// message queries. See ``MessageData`` for the various message attribute types.
case messageData(MessageData)
/// An array of capabilities supported by the server.
///
/// This case is returned in response to `CAPABILITY` commands or as part of the initial
/// Returned in response to `CAPABILITY` commands or as part of the initial
/// server greeting. It indicates which IMAP extensions and features the server supports.
/// See [RFC 3501 Section 7.1](https://datatracker.ietf.org/doc/html/rfc3501#section-7.1) and ``Capability``.
case capabilityData([Capability])
/// An array of capabilities that have been enabled on the server by the client.
///
/// This case is returned in response to an `ENABLE` command and lists the capabilities
/// Returned in response to an `ENABLE` command and lists the capabilities
/// that were successfully enabled. See [RFC 5161](https://datatracker.ietf.org/doc/html/rfc5161)
/// (ENABLE Extension) for details.
case enableData([Capability])
/// The server's implementation details used for identification.
///
/// This case contains an ordered dictionary of key-value pairs providing server identification
/// Contains an ordered dictionary of key-value pairs providing server identification
/// information. Common keys include "name", "version", and "os". Returned in response to
/// the ID command. See [RFC 2971](https://datatracker.ietf.org/doc/html/rfc2971) (ID Extension)
/// for details.
@@ -95,26 +95,26 @@ public enum ResponsePayload: Hashable, Sendable {
/// Matches a quota root with a mailbox.
///
/// This case associates a mailbox with its quota root. Multiple mailboxes may share the same
/// Associates a mailbox with its quota root. Multiple mailboxes may share the same
/// quota root. See [RFC 2087](https://datatracker.ietf.org/doc/html/rfc2087) (QUOTA Extension)
/// for details and ``QuotaRoot``.
case quotaRoot(MailboxName, QuotaRoot)
/// Contains quotas and resource limits for the specified quota root.
///
/// This case provides the usage and limit information for a quota root. See [RFC 2087](https://datatracker.ietf.org/doc/html/rfc2087)
/// Provides the usage and limit information for a quota root. See [RFC 2087](https://datatracker.ietf.org/doc/html/rfc2087)
/// for details on quota resources and ``QuotaResource``.
case quota(QuotaRoot, [QuotaResource])
/// Metadata for a mailbox.
///
/// This case provides metadata entries for a mailbox, as requested by a `GETMETADATA` command.
/// Provides metadata entries for a mailbox, as requested by a `GETMETADATA` command.
/// See [RFC 5464](https://datatracker.ietf.org/doc/html/rfc5464) (METADATA Extension) for details.
case metadata(MetadataResponse)
/// JMAP Access URL for the mailbox.
///
/// This case provides a URL that allows clients to access mailbox data via JMAP (JSON Mail
/// Provides a URL that allows clients to access mailbox data via JMAP (JSON Mail
/// Access Protocol). See [RFC 9698](https://datatracker.ietf.org/doc/html/rfc9698) (JMAPACCESS Extension)
/// for details.
case jmapAccess(URL)
@@ -37,7 +37,7 @@ import struct NIO.ByteBuffer
public struct ResponseText: Hashable, Sendable {
/// The optional structured status code providing additional semantic information.
///
/// Status codes are brief tokens that communicate specific server conditions (e.g., `[ALERT]`,
/// Status codes are brief tokens that communicate specific server conditions (for example, `[ALERT]`,
/// `[CANNOT]`, `[PERMANENT]`). They provide machine-readable information to clients that extends
/// the human-readable text. Not all responses include a code; `nil` indicates no code is present.
///
Loaded 100 of 151 files, more files were not shown because too many files have changed in this diff. Show more