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). Strict reading follows the MIME Sniffing standard for the places where a wrong guess is worse than a refusal.
• 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

let mt = @moonmime.MediaType::parse("Text/HTML; charset=\"utf-8\"").unwrap()
println(mt.essence)                          // text/html
println(mt.param("charset").unwrap_or(""))   // utf-8

let listed = @moonmime.MediaType::parse("text/html, text/plain")
println(listed is None)                      // true

#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

#Conformance

• mimesniff/sniffing/* and mimesniff/media/* ask what a browser does with a response — whether an <img>, an <iframe>, or a navigation keeps the type it was handed. Answering them needs an HTML parser and a network stack. This library decides the type of a value it is given; it does not sniff content.
• mimesniff/mime-types/charset-parameter.window.js checks which encoding a frame derives from a charset parameter, which is document decoding rather than the header itself.
• resources/mime-groups.json lists the groups a type belongs to for Accept computation; this library has no group API.
• resources/mime-types-minimized.json covers the navigation algorithm's minimized MIME type, which also needs a browsing context.

#Licence