dymokomi/luce-mime
Source of release 0.6.0
0.6.0 / src / mime / message.lucb
#==============================================================================================
#
# mime/message - A parsed message and what a reader asks of it
#
# DESCRIPTION:
# `parse` copies the message's bytes and reads its part tree; nothing else is
# decoded until asked. Header text, addresses, a part's content and the body text
# are decoded on request into the message's pool and handed out as views, valid
# until `close`. From Luce, a Message is an object (`mime.parse(data)`) and each
# text it returns is an owned copy.
#
# The body a reader shows (`body_text`) walks the tree as a mail client does: of a
# multipart/alternative it takes the plain text if there is one and the HTML
# otherwise, of other multiparts every inline text part in order; HTML is made
# into text. Attachments are the parts a user would save: those marked as
# attachments, and every non-text leaf.
#
#==============================================================================================
## Address fields a message may hold, for the address accessors.
let address_fields: str[7] = ["from", "sender", "reply-to", "to", "cc", "bcc", "delivered-to"]
## A parsed message.
pub struct Message:
var raw: u8[]
var pool: TextPool
var parts: PartList
## Parse a copy of `data`.
pub static func read(data: const u8[]) -> Message!:
if data.length > maximum_message:
error(limit_exceeded, "the message is larger than this package reads")
let raw = try new u8[data.length] in memory.heap
memory.copy(raw, data, data.length)
var message = Message(raw = raw)
errdefer message.close()
try read_entity(message.raw, 0, message.raw.length, -1, 0, false, &message.parts)
return message
static func own(native: Message*) -> interop.Reference[Message]!:
return try interop.Reference[Message].adopt(native, message_type)
## The message's bytes, as parsed.
pub func bytes() -> const u8[]:
return self.raw
## The size of the message in bytes.
pub func size() -> usize:
return self.raw.length
## The top-level header.
func header_block() -> const Header*:
return &self.parts.items[0].header
# mark: header fields ========================================================================
## The text of the first header field called `name`: unfolded, encoded words decoded.
pub func header(name: str) -> str?!:
let value = self.header_block().find(name) else return none
return try self.text_of(value)
## The text of the first `name` field, or empty text when there is none.
pub func field(name: str) -> str!:
return (try self.header(name)) else ""
## How many fields the top-level header has.
pub func field_count() -> usize:
return self.header_block().length()
## The name of field `index`, as written.
pub func field_name(index: usize) -> str!:
let field = try self.header_block().at(index)
return (str)field.name
## The text of field `index`.
pub func field_value(index: usize) -> str!:
let field = try self.header_block().at(index)
return try self.text_of(field.value)
func text_of(value: const u8[]) -> str!:
var text: Bytes
defer text.close()
try header_text(value, &text)
return (str)(try self.pool.keep(text.view()))
## The subject, or empty text.
pub func subject() -> str!:
return try self.field("Subject")
## The first message ID in field `name`, without its angle brackets; empty when none.
func message_id_in(name: str) -> str!:
let value = self.header_block().find(name) else return ""
let trimmed = trim(value)
if let first = index_of(trimmed, '<'):
if let last = index_of(trimmed, '>', first):
return (str)(try self.pool.keep(trim(trimmed[first + 1..<last])))
return (str)(try self.pool.keep(trimmed))
## The Message-ID, without angle brackets.
pub func message_id() -> str!:
return try self.message_id_in("Message-ID")
## The In-Reply-To ID, without angle brackets.
pub func in_reply_to() -> str!:
return try self.message_id_in("In-Reply-To")
## The References field unfolded: message IDs with their brackets, space separated.
pub func references() -> str!:
let value = self.header_block().find("References") else return ""
var text: Bytes
defer text.close()
try unfold(value, &text)
return (str)(try self.pool.keep(text.view()))
## The Date field, or none when it is missing or unreadable.
pub func date() -> Date?:
let value = self.header_block().find("Date") else return none
return read_date(value)
## The date in seconds since 1970 UTC, or zero when there is none.
pub func date_seconds() -> i64:
if let date = self.date():
return date.seconds
return 0
## The sender's offset from UTC in minutes, or zero.
pub func date_offset() -> i64:
if let date = self.date():
return date.offset
return 0
# mark: addresses ============================================================================
## The addresses of every `name` field (From, To, Cc, …) in order. The caller closes
## the list; its text lives in the message.
pub func addresses(name: str) -> AddressList!:
var list: AddressList
errdefer list.close()
var nth: usize = 0
while let value = self.header_block().find_nth(name, nth):
try read_addresses(value, &self.pool, &list)
nth += 1
return list
## How many addresses field `name` holds.
pub func address_count(name: str) -> usize!:
var list = try self.addresses(name)
defer list.close()
return list.length()
## The display name of address `index` of field `name`; empty when it has none.
pub func address_name(name: str, index: usize) -> str!:
var list = try self.addresses(name)
defer list.close()
return (try list.at(index)).name
## The mailbox (`local@domain`) of address `index` of field `name`.
pub func address_mailbox(name: str, index: usize) -> str!:
var list = try self.addresses(name)
defer list.close()
return (try list.at(index)).mailbox
## Field `name`'s addresses as a reader shows them: `Name <mailbox>, …`, the name
## alone when `short`.
pub func address_line(name: str, short: bool = false) -> str!:
var list = try self.addresses(name)
defer list.close()
var line: Bytes
defer line.close()
for index in 0..<list.length():
let address = try list.at(index)
if index > 0:
try line.put(b", ")
if address.name.length > 0:
try line.text(address.name)
if not short:
try line.put(b" <")
try line.text(address.mailbox)
try line.byte('>')
else:
try line.text(address.mailbox)
return (str)(try self.pool.keep(line.view()))
# mark: parts ================================================================================
## How many parts the tree has; part 0 is the message itself.
pub func part_count() -> usize:
return self.parts.length()
## The index of part `index`'s parent; -1 for the message.
pub func part_parent(index: usize) -> i64!:
return (try self.parts.at(index)).parent
## How many parts enclose part `index`.
pub func part_depth(index: usize) -> u32!:
return (try self.parts.at(index)).depth
## Part `index`'s media type in lower case, `text/plain`.
pub func part_type(index: usize) -> str!:
let part = try self.parts.at(index)
var text: Bytes
defer text.close()
for byte in part.kind:
try text.byte(lower(byte))
try text.byte('/')
for byte in part.subtype:
try text.byte(lower(byte))
return (str)(try self.pool.keep(text.view()))
## Part `index`'s file name, or empty text.
pub func part_filename(index: usize) -> str!:
let part = try self.parts.at(index)
var name: Bytes
defer name.close()
_ = try file_name(part, &name)
return (str)(try self.pool.keep(name.view()))
## Part `index`'s charset parameter, or empty text.
pub func part_charset(index: usize) -> str!:
return try self.part_parameter(index, "Content-Type", "charset")
## Part `index`'s Content-ID, without angle brackets.
pub func part_content_id(index: usize) -> str!:
let part = try self.parts.at(index)
let value = part.header.find("Content-ID") else return ""
var text = trim(value)
if text.length >= 2 and text[0] == '<' and text[text.length - 1] == '>':
text = text[1..<text.length - 1]
return (str)(try self.pool.keep(text))
func part_parameter(index: usize, field: str, name: str) -> str!:
let part = try self.parts.at(index)
var text: Bytes
defer text.close()
if let value = part.header.find(field):
_ = try parameter(value, name, &text)
return (str)(try self.pool.keep(text.view()))
## Whether part `index` is an attachment: marked as one, or a leaf that is not text
## shown in the body.
pub func part_is_attachment(index: usize) -> bool!:
let part = try self.parts.at(index)
if part.is("multipart"):
return false
if same(disposition(part), b"attachment"):
return true
if part.parent >= 0 and (try self.parts.at((usize)part.parent)).is("message"):
# The body of a forwarded message belongs to that message.
return false
return not (part.is("text", "plain") or part.is("text", "html"))
## The encoded size of part `index`'s body in bytes.
pub func part_size(index: usize) -> usize!:
let part = try self.parts.at(index)
return part.body_end - part.body_start
## Part `index`'s content with its transfer encoding undone.
pub func part_data(index: usize) -> const u8[]!:
let part = try self.parts.at(index)
var data: Bytes
defer data.close()
try decode_body(self.raw, part, &data)
return try self.pool.keep(data.view())
## Part `index`'s content as UTF-8 text, converted from its charset.
pub func part_text(index: usize) -> str!:
let part = try self.parts.at(index)
var text: Bytes
defer text.close()
try decode_text(self.raw, part, &text)
return (str)(try self.pool.keep(text.view()))
## Write part `index`'s decoded content to the file at `path`.
pub func save_part(index: usize, path: str) -> !:
let part = try self.parts.at(index)
var data: Bytes
defer data.close()
try decode_body(self.raw, part, &data)
let terminated = try strings.copy(path)
defer strings.release(terminated)
try files.write((c.str)terminated, data.view())
## How many attachments there are.
pub func attachment_count() -> usize!:
var count: usize = 0
for index in 0..<self.parts.length():
if try self.part_is_attachment(index):
count += 1
return count
## The part index of attachment `nth`.
pub func attachment(nth: usize) -> usize!:
var seen: usize = 0
for index in 0..<self.parts.length():
if try self.part_is_attachment(index):
if seen == nth:
return index
seen += 1
error(out_of_range, "no attachment at that index")
# mark: the body a reader shows ==============================================================
## Append the text of part `index` and of what it holds, as a reader shows it. Of
## alternatives it takes the HTML one (made into text) with `prefer_html`, the plain
## one otherwise, and whichever there is when only one kind is.
func gather(index: usize, prefer_html: bool, out: Bytes*) -> !:
let part = try self.parts.at(index)
if part.is("multipart"):
let children = self.children(index)
if part.is("multipart", "alternative"):
var chosen: usize? = none
for child in children.0..<children.1:
let candidate = try self.parts.at(child)
if candidate.parent != (i64)index:
continue
let rich = candidate.is("text", "html") or candidate.is("multipart", "related")
let wanted = rich if prefer_html else candidate.is("text", "plain")
if wanted or chosen == none:
chosen = child
if let child = chosen:
try self.gather(child, prefer_html, out)
return
for child in children.0..<children.1:
if (try self.parts.at(child)).parent == (i64)index:
try self.gather(child, prefer_html, out)
return
if same(disposition(part), b"attachment"):
return
let plain = part.is("text", "plain")
let rich = part.is("text", "html")
if not plain and not rich:
return
if out.used > 0:
try out.put(b"\n\n")
var text: Bytes
defer text.close()
try decode_text(self.raw, part, &text)
if rich:
try html_to_text(text.view(), out)
else:
try out.put(text.view())
## The parts after `index` that lie inside it: a half-open range of part indices.
func children(index: usize) -> (usize, usize):
let depth = self.parts.items[index].depth
var end = index + 1
while end < self.parts.count and self.parts.items[end].depth > depth:
end += 1
return (index + 1, end)
## The text a reader shows for the body: the plain alternative, or with `prefer_html`
## the HTML one made into text (as Mail shows HTML first); a message with only one
## kind shows that one.
pub func body_text(prefer_html: bool = false) -> str!:
var text: Bytes
defer text.close()
try self.gather(0, prefer_html, &text)
return (str)(try self.pool.keep(trim(text.view())))
## The HTML body, when the message has one; empty text otherwise.
pub func body_html() -> str!:
for index in 0..<self.parts.length():
let part = try self.parts.at(index)
if part.is("text", "html") and not same(disposition(part), b"attachment"):
return try self.part_text(index)
return ""
## The opening of the body on one line, for a message list (from the HTML alternative
## when there is one, as `body_text(prefer_html = true)` reads it): quoted lines and
## signatures skipped, whitespace collapsed, at most `limit` characters.
pub func preview(limit: usize = 200) -> str!:
var body: Bytes
defer body.close()
try self.gather(0, true, &body)
var line: Bytes
defer line.close()
var characters: usize = 0
var space = false
var at_line_start = true
var skipping = false
for byte in body.view():
if at_line_start:
skipping = byte == '>'
at_line_start = false
if byte == '\n':
at_line_start = true
space = line.used > 0
continue
if skipping:
continue
if is_space(byte):
space = line.used > 0
continue
# Count characters, not bytes: continuation bytes do not start one.
if (byte & 0xC0) != 0x80:
if characters == limit:
break
characters += 1
if space:
try line.byte(' ')
characters += 1
space = false
try line.byte(byte)
return (str)(try self.pool.keep(line.view()))
## Give everything back; every view handed out becomes invalid.
pub func close():
self.parts.close()
self.pool.close()
if self.raw.length > 0:
free(self.raw) in memory.heap
var empty: u8[]
self.raw = empty
## The interop type of a `Message`.
pub let message_type: interop.Type[Message] = interop.Type[Message]("MIME message", Message.close, closeable = true)
## Parse a copy of `data` into a Message object for Luce.
pub func parse(data: const u8[]) -> interop.Reference[Message]!:
let native = try new Message in memory.heap
errdefer free(native) in memory.heap
*native = try Message.read(data)
return try Message.own(native)
## Read and parse the message in the file at `path`.
pub func open(path: str) -> interop.Reference[Message]!:
let terminated = try strings.copy(path)
defer strings.release(terminated)
let data = try files.read((c.str)terminated)
defer data.release()
return try parse(data.value)