This module implements URI parsing as specified by RFC 3986.
A Uniform Resource Identifier (URI) provides a simple and extensible means for identifying a resource. A URI can be further classified as a locator, a name, or both. The term “Uniform Resource Locator” (URL) refers to the subset of URIs.
Basic usage
Combine URIs
import uri let host = parseUri("https://nim-lang.org") let blog = "/blog.html" let bloguri = host / blog assert $host == "https://nim-lang.org" assert $bloguri == "https://nim-lang.org/blog.html"
Access URI item
import uri let res = parseUri("sftp://127.0.0.1:4343") if isAbsolute(res): assert res.port == "4343" else: echo "Wrong format"
Procs
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.
See also:
Examples:
assert encodeUrl("https://nim-lang.org") == "https%3A%2F%2Fnim-lang.org" assert encodeUrl("https://nim-lang.org/this is a test") == "https%3A%2F%2Fnim-lang.org%2Fthis+is+a+test" assert encodeUrl("https://nim-lang.org/this is a test", false) == "https%3A%2F%2Fnim-lang.org%2Fthis%20is%20a%20test"
Source Edit 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.
See also:
Examples:
assert decodeUrl("https%3A%2F%2Fnim-lang.org") == "https://nim-lang.org" assert decodeUrl("https%3A%2F%2Fnim-lang.org%2Fthis+is+a+test") == "https://nim-lang.org/this is a test" assert decodeUrl("https%3A%2F%2Fnim-lang.org%2Fthis%20is%20a%20test", false) == "https://nim-lang.org/this is a test"
Source Edit proc encodeQuery(query: openArray[(string, string)]; usePlus = true; omitEq = true): string {...}{. raises: [], tags: [].}
-
Encodes a set of (key, value) parameters into a URL query string.
Every (key, value) pair is URL-encoded and written as key=value. If the value is an empty string then the = is omitted, unless omitEq is false. The pairs are joined together by a & character.
The usePlus parameter is passed down to the encodeUrl function that is used for the URL encoding of the string values.
See also:
Examples:
assert encodeQuery({:}) == "" assert encodeQuery({"a": "1", "b": "2"}) == "a=1&b=2" assert encodeQuery({"a": "1", "b": ""}) == "a=1&b"
Source Edit proc initUri(): Uri {...}{.raises: [], tags: [].}
-
Initializes a URI with scheme, username, password, hostname, port, path, query and anchor.
See also:
- Uri type for available fields in the URI type
Examples:
var uri2: Uri assert initUri() == uri2
Source Edit proc parseUri(uri: string; result: var Uri) {...}{.raises: [], tags: [].}
-
Parses a URI. The result variable will be cleared before.
See also:
- Uri type for available fields in the URI type
- initUri proc for initializing a URI
Examples:
var res = initUri() parseUri("https://nim-lang.org/docs/manual.html", res) assert res.scheme == "https" assert res.hostname == "nim-lang.org" assert res.path == "/docs/manual.html"
Source Edit proc parseUri(uri: string): Uri {...}{.raises: [], tags: [].}
-
Parses a URI and returns it.
See also:
- Uri type for available fields in the URI type
Examples:
let res = parseUri("ftp://Username:Password@Hostname") assert res.username == "Username" assert res.password == "Password" assert res.scheme == "ftp"
Source Edit 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 URIs path as well as reference URIs path affect the resulting URI.
See also:
- / proc for building URIs
Examples:
let foo = combine(parseUri("https://nim-lang.org/foo/bar"), parseUri("/baz")) assert foo.path == "/baz" let bar = combine(parseUri("https://nim-lang.org/foo/bar"), parseUri("baz")) assert bar.path == "/foo/baz" let qux = combine(parseUri("https://nim-lang.org/foo/bar/"), parseUri("baz")) assert qux.path == "/foo/bar/baz"
Source Edit proc combine(uris: varargs[Uri]): Uri {...}{.raises: [], tags: [].}
-
Combines multiple URIs together.
See also:
- / proc for building URIs
Examples:
let foo = combine(parseUri("https://nim-lang.org/"), parseUri("docs/"), parseUri("manual.html")) assert foo.hostname == "nim-lang.org" assert foo.path == "/docs/manual.html"
Source Edit proc isAbsolute(uri: Uri): bool {...}{.raises: [], tags: [].}
-
Returns true if URI is absolute, false otherwise.
Examples:
let foo = parseUri("https://nim-lang.org") assert isAbsolute(foo) == true let bar = parseUri("nim-lang") assert isAbsolute(bar) == false
Source Edit proc `/`(x: Uri; path: string): Uri {...}{.raises: [], tags: [].}
-
Concatenates the path specified to the specified URIs path.
Contrary to the combine proc you do not have to worry about the slashes at the beginning and end of the path and URIs path respectively.
See also:
Examples:
let foo = parseUri("https://nim-lang.org/foo/bar") / "/baz" assert foo.path == "/foo/bar/baz" let bar = parseUri("https://nim-lang.org/foo/bar") / "baz" assert bar.path == "/foo/bar/baz" let qux = parseUri("https://nim-lang.org/foo/bar/") / "baz" assert qux.path == "/foo/bar/baz"
Source Edit proc `?`(u: Uri; query: openArray[(string, string)]): Uri {...}{.raises: [], tags: [].}
-
Concatenates the query parameters to the specified URI object.
Examples:
let foo = parseUri("https://example.com") / "foo" ? {"bar": "qux"} assert $foo == "https://example.com/foo?bar=qux"
Source Edit proc `$`(u: Uri): string {...}{.raises: [], tags: [].}
-
Returns the string representation of the specified URI object.
Examples:
let foo = parseUri("https://nim-lang.org") assert $foo == "https://nim-lang.org"
Source Edit