moonmime

#What it does

• Media types. Parse a Content-Type into an essence and ordered parameters, and write it back with correct quoting (RFC 2045 §5.1, RFC 2046 §4.2).
• The registry. Map a filename to the media type its extension implies, and a media type to the extension people actually use.
• Content-Disposition. Build and parse the header that names a download, with filename* (RFC 5987) for names that leave ASCII.
• Multipart. Split any multipart body into parts (RFC 2046 §5.1) — the shape an email and a form upload share.
• Form data. Read multipart/form-data (RFC 7578) into text fields and file uploads, and build the same type from either.
• Encoded words. Write a header value as RFC 2047 encoded words, B or Q, split so no word passes 75 characters, and read any mix of words and plain text back.
• Quoted-printable. moonmime/qp encodes and decodes a body (RFC 2045 §6.7): soft breaks at 76 columns, =XY escapes, trailing whitespace protected.
• Charsets. UTF-8, US-ASCII and ISO-8859-1 come with the library; any other set is a Charset you pass in, so nothing is registered globally.

#Install

moon add moonbitstack/moonmime

import {
  "moonbitstack/moonmime",
}

#Use it

#Read a media type

let mt = @moonmime.media_type("Text/HTML; charset=UTF-8")
println(mt.essence)                         // text/html
println(mt.type_())                         // text
println(mt.subtype())                       // html
println(mt.param("charset").unwrap_or(""))  // UTF-8
println(mt.to_string())                     // text/html; charset=UTF-8

#Name a download

println(@moonmime.content_disposition("menu.pdf"))
// attachment; filename="menu.pdf"

println(@moonmime.content_disposition("receta \"de la abuela\".pdf"))
// attachment; filename*=utf-8''receta%20%22de%20la%20abuela%22.pdf

let d = @moonmime.Disposition::parse(
  "attachment; filename=\"fallback.txt\"; filename*=utf-8''r%C3%A9sum%C3%A9.txt",
)
println(d.filename().unwrap_or(""))  // résumé.txt

#Guess from a filename

println(@moonmime.guess_type("photo.jpg"))                    // image/jpeg
println(@moonmime.guess_type("archive.tar.gz"))               // application/gzip
println(@moonmime.guess_extension("image/jpeg").unwrap_or(""))  // .jpg

#Split a body, then read it as a form

// `body` is the raw bytes; `boundary` is the delimiter without its leading dashes.
let parts = @moonmime.multipart(body, boundary)
for part in parts {
  println(part.header("content-type").unwrap_or(""))
}

let form = @moonmime.formdata(body, boundary)
let title = form.field("title")            // String?
for tag in form.values("tags") {           // every value under one name
  println(tag)
}
let upload = form.file("photo")            // Upload?

#Write a header that leaves ASCII, and a body that must stay 7-bit

let subject = @moonmime.encode_words("Grüße aus München")  // =?utf-8?B?...?=
let back = @moonmime.decode_words(subject)                 // Grüße aus München
let body = @qp.encode(b"caf\xc3\xa9 = coffee")             // caf=C3=A9 =3D coffee
let text = @qp.decode(body)

let charsets : Map[String, &@moonmime.Charset] = { "windows-1252": cp1252 }
let name = @moonmime.decode_words(header, charsets~)

#Interface

#Bounds

let small = @moonmime.Limits::new(parts=8, part_size=64 * 1024)
let form = @moonmime.formdata(body, boundary, limits=small)

#Examples

• src/examples/lookup — filenames and media types, both directions.
• src/examples/form — read a multipart/form-data upload, then the raw parts.
• src/examples/tour — every call once, end to end.
• src/examples/browser — the same library compiled to JavaScript for the live demos.

moon run src/examples/lookup
moon run src/examples/form
moon run src/examples/tour

#Licence