URI Handling

Synopsis

(import (data uri))

Encode data for inclusion in a uniform resource identifier or interpret it.

Encoding

procedure: (uri-encode string)

Replace characters in the given string by hexadecimal escape sequences. Alphabetic and numeric characters as well as "-", "~", "." and "_" are left unescaped.

procedure: (uri-decode string)

Replaces "+" characters by spaces and hexadecimal escape sequences by their character equivalents in the given string.

procedure: (uri-encode-query alist)

Encodes an association list with string keys and values into a query string that may be included in a URI. The keys and values are passed through uri-encode.

procedure: (uri-decode-query string)

Decodes a query string found in a URI into an association list with string keys and values. The keys and values are passed through uri-decode.

procedure: (uri-encode-path&query items)

Joins a list of path names with an optional query alist tail into a URI path string.

procedure: (uri-decode-path&query path&query)

Splits a relative URI into a list of path names with an optional query alist tail.

procedure: (make-data-uri data)

procedure: (make-data-uri data type)

procedure: (make-data-uri data type charset)

Encodes the string or bytevector data as a Data URI. The media type of the data defaults to "text/plain" for string and "application/octet-stream" for bytevectors. If no charset is specified explicitly, strings are passed through uri-encode and bytevectors are passed through base64-encode for inclusion in the URI. If a charset is specified, strings are converted into that encoding and the result is passed through base64-encode, too.

Dispatching

record: resource

procedure: (resource? any)

procedure: (make-resource method path&query handler)

procedure: (resource-method resource)

procedure: (resource-path&query resource)

procedure: (resource-handler resource)

A record type to store a request method, path and query parameter pattern and handler procedure.

The path and query data should be a list like for uri-encode-path&query, but it may include the symbols $ or ... to indicate a single free parameter or any number of free parameters.

make-resource accepts strings in place of a path and query list, which are parsed using uri-decode-path&query and may contain the placeholders {} or {...} where the symbols $ or ... should appear in the list.

procedure: (resource-uri resource parameter ...)

Replaces the placeholders in the resource-path&query with the given parameters and returns a string representing the resulting URI.

procedure: (resource-apply resource path&query)

Extracts the values for placeholder variables from the given path and query list or string and applies the resource-handler to the resulting argument list.

procedure: ((resource-dispatch default resource ...) method path&query)

Creates a dispatch procedure that selects a unique matching resource based on the path and query patterns as well as the method. If no resource matches, the default procedure is called instead of a resource handler.

Note that the order of fixed named parameters is relevant during dispatch, so it may make sense to include at most one such parameter in a path an query pattern.