Luce packages
LuceLuce BaseLuciaOS

dymokomi/luce-mime

Source of release 0.6.0

0.6.0 / README.md

# luce-mime

Internet messages in [luce-base](https://github.com/dymokomi/luce-base). Read a
message, show it, write one:

- RFC 5322 header blocks, unfolded, with fields looked up by name.
- RFC 2047 encoded words. Adjacent words are joined before charset conversion,
  and raw 8-bit header text is accepted as well (RFC 6532).
- RFC 2231 parameters, including continuations and charsets.
- Address lists, including groups, routes and old `addr (Name)` comments.
- Dates in the strict and the obsolete forms.
- The MIME part tree: multipart, message/rfc822 and digest.
- Base64 and quoted-printable in both directions.
- Charsets converted to UTF-8: UTF-8, US-ASCII, ISO-8859-1/15 and Windows-1252
  are built in, and other charsets go through a decoder the application installs.
- The body text a mail reader shows: the plain alternative, or HTML made into text.
- A list preview.
- `Draft`, which writes an outgoing message in 7-bit form for SMTP.

luce-mime reads leniently, as mail clients have to. Malformed input degrades
instead of failing: a stray `=` stays as it is, an unclosed multipart keeps its
parts, and an unknown charset is read as UTF-8 or Windows-1252.

## Use it

```prisma
def dependency "luce-mime" {
    str owner = "dymokomi"
    str version = "^0.5.0"
}
```

From Luce, a parsed message is an object and each text it returns is an owned
copy:

```luce
from luce_mime import mime

let message = mime.open("message.eml")          # or mime.parse(bytes)
print(message.subject())                          # "Quarterly plan — draft"
print(message.address_line("From"))               # "Carol Åberg <carol@example.org>"
print(message.body_text())                        # plain text, or HTML as text
for index in 0..<message.attachment_count():
    let part = message.attachment(index)
    message.save_part(part, message.part_filename(part))

let draft = mime.create_draft()
draft.set_from("Alice", "alice@example.test")
draft.add_recipients("to", "Bob <bob@example.test>, carol@example.org")
draft.set_subject("Café at ten?")
draft.set_text("See you there.")
draft.attach_file("plan.pdf")
let outgoing = draft.encode()                     # CRLF, 7-bit: ready for SMTP DATA
```

From Base, `Message.read(data)` gives a value you close. It also offers
`part_data(index)` as bytes, `addresses(name)` as an `AddressList`, and the
codecs and parsers on their own (`decode_base64`, `header_text`, `parameter`,
`read_addresses`, `read_date`, `html_to_text`, …). Every view a message hands out
stays valid until the message closes.

| Message | Answers |
| --- | --- |
| `subject()`, `header(name)`, `field(name)` | header text, unfolded and decoded |
| `field_count()`, `field_name(i)`, `field_value(i)` | every top-level field in order |
| `message_id()`, `in_reply_to()`, `references()` | threading IDs |
| `date_seconds()`, `date_offset()`, `date()` | the Date field, as Unix seconds and the sender's offset |
| `address_line(name)`, `address_count(name)`, `address_name(name, i)`, `address_mailbox(name, i)` | From, To, Cc, Reply-To, … |
| `part_count()`, `part_type(i)`, `part_parent(i)`, `part_depth(i)` | the part tree; part 0 is the message |
| `part_filename(i)`, `part_charset(i)`, `part_content_id(i)`, `part_size(i)` | a part's metadata |
| `part_text(i)`, `part_data(i)`, `save_part(i, path)` | a part's content, decoded |
| `attachment_count()`, `attachment(n)`, `part_is_attachment(i)` | what a user would save |
| `body_text(prefer_html)`, `body_html()`, `preview(limit)` | what a reader and a list show; HTML alternatives as text with `prefer_html` |

Charsets beyond the built-in ones: install a decoder once, for example one over
luce-browser-foundation's `text_codec`:

```luce-base
mime.set_charset_decoder(my_decoder)   # func(str, const u8[], mime.Bytes*) -> bool!
```

## Limits

A message can be at most 512 MiB. Multiparts nest at most 32 deep, a message has
at most 4096 parts, and a header block keeps at most 4096 fields. HTML is shown
as text until luced-message renders it through the browser engine. Links show
their text only, and remote content is never fetched.

## Test

```sh
./test.sh        # every test, native and through the C backend
```

`tests/run.py --base PATH` uses another compiler. On macOS, also run the tests
under Guard Malloc before pushing changes to error paths:
`DYLD_INSERT_LIBRARIES=/usr/lib/libgmalloc.dylib luce-base test src/mime --native`.

## License

Dual-licensed under Apache-2.0 or MIT, at your option.