Luce packages
LuceLuce BaseLuciaOS

dymokomi/luce-mime

Internet messages in luce-base: RFC 5322 headers, addresses and dates, RFC 2047 encoded words, the MIME part tree, base64 and quoted-printable, charsets decoded to UTF-8, a readable text view of a body, and outgoing messages built for SMTP.

A library written in luce-base. Latest release 0.6.0.

Install#

luc add dymokomi/luce-mime

Documentation#

luce-mime

Internet messages in 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

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:

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.

MessageAnswers
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:

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

./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.

Dependencies#

PackageVersion
dymokomi/luce-stdnewest

Versions#

0.6.0

Browse source · pack · commit d8e6d600e275

SHA-256 0186bf1061cc15023afa0197d7ff83e73230b2b372a1a83174cd7662bd79d136

byte spans compare with ==; dependencies name no version