Module maildir 

Messages on disk: a Maildir (new/ and cur/), or a plain folder of .eml files.

Sioul writes what it fetches as a Maildir (https://cr.yp.to/proto/maildir.html), so notmuch, mutt or any other reader can open the same folders. Each file name carries where the message sits on the server, U<uidvalidity>-<uid>, so the Porch knows what you have seen without opening the files.

After the flags, two IMAP keywords (RFC 9051 §2.3.2) are kept as Dovecot keeps them: a lowercase letter each, named in the folder’s dovecot-keywords file. They say what you, or a mail client, said of a message: junk ($Junk), or not junk ($NotJunk).

Structs

CardsKept

While it lives, each message file this thread reads is parsed once (read_one): one look at the mail (the Porch, then the money lines it holds, each going through every message kept) parses each message once, not once each. Nothing is kept once it ends: a card holds a few kilobytes, and every message kept would stay in memory between looks. One begun inside another changes nothing.

Fetched

A message fetched from the server, ready to be written.

Keywords

What a stored message’s file name says of it, junk or not.

Constants

INFO

What separates a message’s unique name from its flags: “:” by the Maildir convention, “!” on Windows, where “:” cannot be in a file name (mbsync does the same). Both are read on every system.

JUNK

$Junk’s letter.

KEPT 🔒

The cards read in this thread while a CardsKept lives.

KEYWORDS

The keywords kept, by letter, as the folder’s dovecot-keywords file numbers them (a is 0, b is 1).

NOT_JUNK

$NotJunk’s letter.

Functions

flags_of

The Maildir flags of a stored message, from its name, with the keywords’ letters: “FS”, “Sb”; none in new/.

flags_part 🔒

The flags after “:2,” or “!2,”.

has_unread

Whether a Maildir holds a message not read yet: one in new/, or one in cur/ without the S flag. Only names are read.

is_hidden 🔒

kept_key 🔒

A message file as CardsKept knows it: its name less its flags, its size, its time (nanoseconds).

keyword_letter

The letter of an IMAP keyword Sioul keeps; none for the others. Case does not matter: $junk is $Junk to IMAP servers.

keywords_of

The keywords in a stored message’s file name.

locate

Where a stored message is now: its flags rename it, and a first reading moves it from new/ to cur/. The part of the name before “:2,” never changes.

message_ids

The Message-IDs of a Maildir’s messages, from their headers only.

name_keywords 🔒

The folder’s dovecot-keywords file, which names the letters, written once, when a letter is first kept there: Dovecot reads the same folder alike.

origin_of

1759400000.U1700000000-4521.sioul:2,S → validity 1700000000, UID 4521.

read_folder 🔒

read_messages

Every message of a Maildir or folder, oldest first.

read_messages_where

The messages whose server origin passes keep, oldest first; the others are not even read.

read_one

One message file as a card. While a CardsKept lives in this thread, a message already read in it is not parsed again: the file’s name less its flags, its size and its time say it is the same (a message’s content never changes; its flags move it between new/ and cur/).

set_flags

Gives a stored message other flags: it is renamed in cur/, where every message that has been seen or flagged lives. Returns where it is now.

sorted 🔒

Maildir wants the flag letters in ASCII order.

store

Writes one message into a Maildir: first in tmp/, then moved, so a reader never sees half a message. Mail without any flag goes to new/; mail with some (read, flagged, a keyword kept) to cur/ with its letters, as the Maildir convention says, so that none is lost until the next sync.

unique_part

“1759400000.U17-4521.sioul:2,FS” → “1759400000.U17-4521.sioul”.

Type Aliases

KeptCards 🔒