Module uri

This module implements URI parsing as specified by RFC 3986.

Imports

strutils, parseutils

Types

Url = distinct string

Uri = object
  scheme*, username*, password*: string
  hostname*, port*, path*, query*, anchor*: string
  opaque*: bool

Procs

proc `$`(url: Url): string {...}{.deprecated: "use Uri instead", raises: [], tags: [].}

Deprecated since 0.9.6: Use Uri instead.

proc `/`(a, b: Url): Url {...}{.deprecated: "use Uri instead", raises: [], tags: [].}

Joins two URLs together, separating them with / if needed.

Deprecated since 0.9.6: Use Uri instead.

proc add(url: var Url; a: Url) {...}{.deprecated: "use Uri instead", raises: [], tags: [].}

Appends url to url.

Deprecated since 0.9.6: Use Uri instead.

proc encodeUrl(s: string; usePlus = true): string {...}{.raises: [], tags: [].}

Encodes a URL according to RFC3986.

This means that characters in the set {'a'..'z', 'A'..'Z', '0'..'9', '-', '.', '_', '~'} are carried over to the result. All other characters are encoded as ''%xx' where xx denotes its hexadecimal value.

As a special rule, when the value of usePlus is true, spaces are encoded as '+' instead of '%20'.

proc decodeUrl(s: string; decodePlus = true): string {...}{.raises: [], tags: [].}

Decodes a URL according to RFC3986.

This means that any '%xx' (where xx denotes a hexadecimal value) are converted to the character with ordinal number xx, and every other character is carried over.

As a special rule, when the value of decodePlus is true, '+' characters are converted to a space.

proc initUri(): Uri {...}{.raises: [], tags: [].}

Initializes a URI.

proc parseUri(uri: string; result: var Uri) {...}{.raises: [], tags: [].}

Parses a URI. The result variable will be cleared before.

proc parseUri(uri: string): Uri {...}{.raises: [], tags: [].}

Parses a URI and returns it.

proc combine(base: Uri; reference: Uri): Uri {...}{.raises: [], tags: [].}

Combines a base URI with a reference URI.

This uses the algorithm specified in section 5.2.2 of RFC 3986.

This means that the slashes inside the base URI's path as well as reference URI's path affect the resulting URI.

For building URIs you may wish to use `/` instead.

Examples:

let foo = combine(parseUri("http://example.com/foo/bar"), parseUri("/baz"))
assert foo.path == "/baz"

let bar = combine(parseUri("http://example.com/foo/bar"), parseUri("baz"))
assert bar.path == "/foo/baz"

let bar = combine(parseUri("http://example.com/foo/bar/"), parseUri("baz"))
assert bar.path == "/foo/bar/baz"

proc combine(uris: varargs[Uri]): Uri {...}{.raises: [], tags: [].}

Combines multiple URIs together.

proc isAbsolute(uri: Uri): bool {...}{.raises: [], tags: [].}

returns true if URI is absolute, false otherwise

proc `/`(x: Uri; path: string): Uri {...}{.raises: [], tags: [].}

Concatenates the path specified to the specified URI's path.

Contrary to the combine procedure you do not have to worry about the slashes at the beginning and end of the path and URI's path respectively.

Examples:

let foo = parseUri("http://example.com/foo/bar") / "/baz"
assert foo.path == "/foo/bar/baz"

let bar = parseUri("http://example.com/foo/bar") / "baz"
assert bar.path == "/foo/bar/baz"

let bar = parseUri("http://example.com/foo/bar/") / "baz"
assert bar.path == "/foo/bar/baz"

proc `$`(u: Uri): string {...}{.raises: [], tags: [].}

Returns the string representation of the specified URI object.