mime

Look up media types by file extension and parse or build Content-Type values.

import "std:mime"

std:mime knows which media type (also called MIME type or content type) belongs to a file name, and how to read and write the Content-Type header value. Use it when you serve or upload files, decide how to handle a file by what it holds, or parse a header that comes with parameters such as charset.

From file name to type#

mime.typeByFilename(path) looks at the extension and ignores case. mime.typeByExt(ext) takes the extension alone, with or without the dot. Both return null when the extension isn't known, so use ?? for a fallback:

main.osl

import "std:mime"

log mime.typeByFilename("photo.JPG")
log mime.typeByFilename("archive.tar.gz")
log mime.typeByExt(".json")
log mime.typeByExt("png")
log mime.typeByExt(".zzzz")

string type = mime.typeByFilename("data.unknown") ?? "application/octet-stream"
log type

Click the code to edit it

Change the file name to x.svg or x.wasm and see what comes back.

application/octet-stream is the usual answer for "bytes of unknown kind". serve already picks a Content-Type for files it serves, so you need mime when you set one yourself, such as on an upload.

From type to extension#

mime.extByType goes the other way, returning the usual extension with its dot, or null:

main.osl

import "std:mime"

log mime.extByType("text/html")
log mime.extByType("image/png")
log mime.extByType("application/x-nothing")

Click the code to edit it

Telling kinds of file apart#

Five checks cover the common questions. Each exists in two forms: one that takes a media type, and one with File on the end that takes a file name:

main.osl

import "std:mime"

log mime.isImage("image/png") mime.isAudio("audio/mpeg") mime.isVideo("video/mp4")
log mime.isText("application/json") mime.isText("image/png")
log mime.isImageFile("a.webp") mime.isTextFile("notes.md") mime.isVideoFile("x.txt")

Click the code to edit it

isText counts anything readable as text, including JSON and XML, and not only text/*. That makes it a good test for "can I show this in a text box?".

Parse a Content-Type#

A Content-Type header holds a type and parameters. mime.parse returns the type lowercased and the parameters as an object, or an error for text that isn't a media type:

main.osl

import "std:mime"

auto parsed = mime.parse("Text/HTML; charset=UTF-8; boundary=x").unwrap()
log parsed.type
log parsed.params["charset"]
log parsed.params

log mime.parse("???").isErr()

Click the code to edit it

Parameter names are lowercased and their values are left as sent.

Build a Content-Type#

mime.format(type, params) writes the header value, quoting parameter values when they need it:

main.osl

import "std:mime"

log mime.format("text/plain", {charset: "utf-8"})
log mime.format("multipart/form-data", {boundary: "----docs"})

Click the code to edit it

Quick check

What does mime.typeByFilename("data.unknown") return?

Your turn

Content-Type for a file

Write typeFor(name) that returns the media type of a file name, or application/octet-stream when it isn't known.

main.osl

import "std:mime"

def typeFor(string name) string (
  return ""
)

log typeFor("logo.png")
log typeFor("notes.md")
log typeFor("blob.zzz")

import "std:mime"

def typeFor(string name) string (
  return ""
)

log typeFor("logo.png")
log typeFor("notes.md")
log typeFor("blob.zzz")

Ctrl Enter runs

Expected output

image/png
text/markdown; charset=utf-8
application/octet-stream

API reference#

15 members, generated from the std:mime source of OSL 9.3.0.

Functions

#mime.byFilename(any name) string

Deprecated. Deprecated: use mime.typeByFilename(path) instead, which returns null for unknown extensions.

byFilename returns the media type for a file name, or "" when unknown.

#mime.extByType(string mediaType) string?

extByType returns the conventional file extension for a media type, with its leading dot (".png" for "image/png", ".jpg" for "image/jpeg"), or null when the type is unknown. Parameters such as "; charset=utf-8" are ignored.

#mime.format(string mediaType, object params) string

format builds a Content-Type value from a media type and its parameters, quoting values where needed: mime.format("text/plain", {charset: "utf-8"}) is "text/plain; charset=utf-8". Throws ValueError when mediaType or a parameter name is not a valid token.

#mime.isAudio(string mediaType) boolean

isAudio reports whether a media type is an audio/* type. Case and parameters are ignored. A value without "/" is checked as a file name or extension ("clip.mp3", "mp3"), as before; for paths, use mime.isAudioFile.

#mime.isAudioFile(string path) boolean

isAudioFile reports whether a file name or path has the extension of an audio type. The file is not opened.

#mime.isImage(string mediaType) boolean

isImage reports whether a media type is an image/* type. Case and parameters are ignored. A value without "/" is checked as a file name or extension ("cat.png", "png"), as before; for paths, use mime.isImageFile.

#mime.isImageFile(string path) boolean

isImageFile reports whether a file name or path has the extension of an image type. The file is not opened.

#mime.isText(string mediaType) boolean

isText reports whether a media type holds text: text/*, JSON, XML, JavaScript and the +json and +xml suffix types. Case and parameters are ignored. A value without "/" is checked as a file name or extension ("notes.txt", "txt"), as before; for paths, use mime.isTextFile.

#mime.isTextFile(string path) boolean

isTextFile reports whether a file name or path has the extension of a text type, by the same rules as mime.isText. The file is not opened.

#mime.isVideo(string mediaType) boolean

isVideo reports whether a media type is a video/* type. Case and parameters are ignored. A value without "/" is checked as a file name or extension ("movie.mp4", "mp4"), as before; for paths, use mime.isVideoFile.

#mime.isVideoFile(string path) boolean

isVideoFile reports whether a file name or path has the extension of a video type. The file is not opened.

#mime.parse(string text) result<{params: string[string], type: string, valid: boolean (deprecated)}, error>

parse splits a Content-Type value into its lowercased media type and its parameters, returning {type, params} where params maps each parameter name (lowercased) to its unquoted value; the deprecated key valid is always true. Fails with ParseError when text is not a type/subtype pair or repeats a parameter.

#mime.resolve(any input) string

Deprecated. Deprecated: use mime.parse(text).type for a media type, or mime.typeByFilename(path) / mime.typeByExt(ext) for a file name.

resolve returns the bare lowercase media type of a media type string, or of a file name or extension when input has no "/"; "" when unknown.

#mime.typeByExt(string ext) string?

typeByExt returns the media type registered for a file extension, such as "application/json" for "json" or ".json", or null when the extension is unknown. Text types carry a charset parameter ("text/html; charset=utf-8").

#mime.typeByFilename(string path) string?

typeByFilename returns the media type for a file name or path from its extension, such as "image/png" for "photos/cat.png", or null when the name has no known extension.

Edit this page View as Markdown