documentation and tests.

2026-07-27 09:42:29 +02:00
parent 046db6456e
commit 7e26cfd6d3
5 changed files with 213 additions and 37 deletions
@@ -0,0 +1,79 @@
+#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"].
+}