#lang scribble/manual

@(require (for-label racket/base
                     racket/contract
                     racket-mimetypes))

@title{MIME Types}
@author[@author+email["Hans Dijkema" "hans@dijkewijk.nl"]]

@defmodule[racket-mimetypes]

The @racketmodname[racket-mimetypes] library maps file extensions to MIME type
strings. It uses a built-in table and does not inspect the contents of a file.

@defproc[(mimetype-for-ext
          [ext (or/c path-string? symbol?)]
          [#:default default string? "application/octet-stream"]
          [#:context context
                     (or/c #f
                           'application
                           'audio
                           'example
                           'font
                           'haptics
                           'image
                           'message
                           'model
                           'multipart
                           'text
                           'video)
                     #f])
         string?]{

Returns the MIME type associated with @racket[ext]. The argument can be an
extension, a path string, or a path. Symbols are accepted for extensions.

The following forms are accepted:

@itemlist[
 #:style 'compact
 @item{A string containing a bare extension, such as @racket["mp3"] or
       @racket[".MP3"].}
 @item{A symbol containing a bare extension, such as @racket['mp3].}
 @item{A string containing a file name or path, such as
       @racket["track.flac"], @racket["/music/track.flac"], or
       @racket["c:\\music\\track.flac"].}
 @item{A Racket path value, such as
       @racket[(string->path "/music/track.flac")].}
]

The final path component is used and the text following its last dot is taken
as the extension. A leading dot on a bare extension is therefore ignored.
Both slash and backslash are recognized as path separators, independent of the
current operating system. The resulting extension is converted to lowercase
and stored internally as a symbol.

A string without a dot is treated as a bare extension. Consequently,
@racket["README"] is looked up as the extension @racket['readme]. A name ending
in a dot has no recognized extension and normally produces @racket[default].

The procedure accepts file-system paths, not URLs. Query strings and fragments
are not removed. The contents of a file are not inspected.

An extension can have more than one MIME type. Without @racket[context], the
first and most common type is returned. A context selects a MIME type whose
top-level type matches the context. For example,
@racket[(mimetype-for-ext "track.mp4")] returns @racket["video/mp4"], while
@racket[(mimetype-for-ext "track.mp4" #:context 'audio)] returns
@racket["audio/mp4"].

If the extension is unknown, or no type matches the supplied context,
@racket[default] is returned.

For example, @racket[(mimetype-for-ext "MP3")] returns
@racket["audio/mpeg"], @racket[(mimetype-for-ext ".flac")] returns
@racket["audio/flac"], and
@racket[(mimetype-for-ext "unknown" #:default "text/plain")]
returns @racket["text/plain"].
}