#uri API reference

URL parsing, building, and query-string handling (RFC 3986). The shared URL layer the network modules (http, rest, s3, oauth, influxdb, ...) build on instead of re-splitting strings and hand-rolling percent-encoding.

parse splits a URL into a Uri (scheme / user / host / port / path / query / fragment); build reassembles one. encode / decode are RFC 3986 percent-encoding (over the encoding library's uri-percent codec), and encodeForm / decodeForm are the application/x-www-form-urlencoded variant (space as "+", the uri-form codec). buildQuery / parseQuery convert between a map of string to string and a key=value&... string using form encoding (the query-string convention). resolve applies a relative reference to a base URL (RFC 3986 section 5), the operation a feed reader or crawler needs to turn a relative link absolute.

Pure Jennifer over strings + encoding + convert - no Go, no network - so it runs on both binaries. An IPv6 literal host keeps its brackets in host ([::1]) with the port split out; everything else follows RFC 3986.

Import with import "uri.j" as uri;. See the uri guide for prose and examples.

#Functions

#uri.build(u as Uri)

Reassemble a URL string from its parts (the inverse of parse). Components are emitted verbatim (already-encoded); build does not re-encode.

Parameters

• u {Uri} - the parts to assemble

Returns {string} - the URL string

#uri.buildQuery(params as map of string to string)

Build a key=value&... query string from a map, form-encoding every key and value (the query-string convention: a space becomes "+"). Pairs keep the map's insertion order.

Parameters

• params {map of string to string} - the query parameters

Returns {string} - the encoded query string (without a leading "?")

#uri.decode(s as string)

Reverse percent-encoding: %XX triples decode to their byte, and a literal "+" is left as "+" (RFC 3986, not form encoding - use parseQuery for query strings, which treats "+" as a space).

Parameters

• s {string} - the percent-encoded text

Returns {string} - the decoded text

Throws

• {Error} - on a malformed "%" escape

#uri.decodeForm(s as string)

Reverse form-encoding: %XX triples decode to their byte and a "+" decodes to a space (the form-urlencoded convention). Use this for query-string values; use decode for RFC 3986 path segments where "+" is literal.

Parameters

• s {string} - the form-encoded text

Returns {string} - the decoded text

Throws

• {Error} - on a malformed "%" escape

#uri.encode(s as string)

Percent-encode a string per RFC 3986 (component encoding): every byte outside the unreserved set A-Za-z0-9-._~ becomes %XX, space becomes %20. Safe in any URL position (a path segment, a query value).

Parameters

• s {string} - the text to encode

Returns {string} - the percent-encoded text

#uri.encodeForm(s as string)

Form-encode a string per application/x-www-form-urlencoded: like encode, but a space becomes "+" instead of "%20". This is the encoding for query-string values and HTML form bodies (buildQuery uses it).

Parameters

• s {string} - the text to encode

Returns {string} - the form-encoded text

#uri.parse(raw as string)

Parse a URL into its parts. Absent components are "". The authority (user/host/port) is only populated when the URL has a "//" authority, so a scheme-only URL like "mailto:x@y" keeps "x@y" in path.

Parameters

• raw {string} - the URL text

Returns {Uri} - the parsed parts

#uri.parseQuery(q as string)

Parse a key=value&... query string into a map, decoding each component. A "+" decodes to a space (the form-urlencoded convention), a repeated key keeps its last value, and a bare "key" (no "=") maps to "".

Parameters

• q {string} - the query string (without a leading "?")

Returns {map of string to string} - the decoded parameters

Throws

• {Error} - on a malformed "%" escape

#uri.resolve(base as string, ref as string)

Resolve a (possibly relative) reference against a base URL, per RFC 3986 section 5: turn "../img.png" plus "https://h/a/b/page" into "https://h/a/img.png". An absolute reference (with its own scheme) is returned as-is.

Parameters

• base {string} - the absolute base URL
• ref {string} - the reference to resolve (absolute or relative)

Returns {string} - the resolved absolute URL

#Structs

#uri.Uri

The parts of a parsed URL. Missing components are the empty string (so a relative URL has an empty scheme and host). port is a string ("" when absent) rather than an int, to distinguish "no port" from port 0.