<h1>URI Handling</h1>

<h2>Synopsis</h2>

<code>(import (data uri))</code>

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

<h2>Encoding</h2>

<h3>procedure: <code>(uri-encode

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

<h3>procedure: <code>(uri-decode

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

<h3>procedure: <code>(uri-encode-query

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 <tt>uri-encode</tt>.

<h3>procedure: <code>(uri-decode-query

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

<h3>procedure: <code>(uri-encode-path&query

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

<h3>procedure: <code>(uri-decode-path&query

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

<h3>procedure: <code>(make-data-uri
<h3>procedure: <code>(make-data-uri <i>data</i>
<h3>procedure: <code>(make-data-uri <i>data</i> <i>type</i>

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

<h2>Dispatching</h2>

<h3>record:
<h3>procedure: <code>(resource?
<h3>procedure: <code>(make-resource <i>method</i> <i>path&query</i>
<h3>procedure: <code>(resource-method
<h3>procedure: <code>(resource-path&query
<h3>procedure: <code>(resource-handler

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 <tt>uri-encode-path&query</tt>, but it may include the symbols <tt>$</tt> or <tt>...</tt> to indicate a single free parameter or any number of free parameters.

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

<h3>procedure: <code>(resource-uri <i>resource</i> <i>parameter</i>

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

<h3>procedure: <code>(resource-apply <i>resource</i>

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

<h3>procedure: <code>((resource-dispatch <i>default</i> <i>resource</i> ...) <i>method</i>

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.