uri

Этот модуль реализует разбор URI, как указано в RFC 3986.

Универсальный идентификатор ресурса (URI) предоставляет простой и расширяемый способ идентификации ресурса. URI может быть дополнительно классифицирован как локатор, имя или оба. Термин «Универсальный указатель ресурса» (URL) относится к подмножеству URI.

Основное использование

Объединение URI

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"

Доступ к элементу URI

import uri
let res = parseUri("sftp://127.0.0.1:4343")
if isAbsolute(res):
  assert res.port == "4343"
else:
  echo "Wrong format"

Data URI Base64

doAssert getDataUri("Hello World", "text/plain") == "data:text/plain;charset=utf-8;base64,SGVsbG8gV29ybGQ="
doAssert getDataUri("Nim", "text/plain") == "data:text/plain;charset=utf-8;base64,Tmlt"

Импорты

since, strutils, parseutils, base64

Типы

Url = distinct string: Исходный код Изменить
Uri = object scheme*, username*, password*: string hostname*, port*, path*, query*, anchor*: string opaque*: bool isIpv6: bool: Исходный код Изменить

Процедуры

proc getDataUri(data, mime: string; encoding = "utf-8"): string {...}{.raises: [], tags: [].}

Удобная процедура для base64.encode возвращает стандартный URI данных Base64 (RFC-2397)

См. также:

mimetypes для mime аргумента
https://tools.ietf.org/html/rfc2397
https://en.wikipedia.org/wiki/Data_URI_scheme

Пример:

static: doAssert getDataUri("Nim", "text/plain") == "data:text/plain;charset=utf-8;base64,Tmlt"

Исходный код Изменить

Функции

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

Кодирует URL в соответствии с RFC3986.

Это означает, что символы в наборе {'a'..'z', 'A'..'Z', '0'..'9', '-', '.', '_', '~'} переносятся в результат. Все остальные символы кодируются как %xx, где xx обозначает его шестнадцатеричное значение.

В качестве специального правила, когда значение usePlus равно true, пробелы кодируются как + вместо %20.

См. также:

функция decodeUrl

Пример:

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"

Исходный код Изменить

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

Декодирует URL в соответствии с RFC3986.

Это означает, что любые %xx (где xx обозначает шестнадцатеричное значение) преобразуются в символ с порядковым номером xx, а любой другой символ переносится. Если xx не является допустимым шестнадцатеричным значением, оно остается неизменным.

В качестве специального правила, когда значение decodePlus равно true, символы + преобразуются в пробел.

См. также:

функция encodeUrl

Пример:

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"
assert decodeUrl("abc%xyz") == "abc%xyz"

Исходный код Изменить

func encodeQuery(query: openArray[(string, string)]; usePlus = true; omitEq = true): string {...}{.raises: [], tags: [].}

Кодирует набор параметров (ключ, значение) в строку запроса URL.

Каждая пара (ключ, значение) кодируется в URL и записывается как key=value. Если значение является пустой строкой, то = опускается, если только omitEq не равно false. Парам пары объединяются символом &.

Параметр usePlus передается функции encodeUrl, которая используется для кодирования URL строк значений.

См. также:

функция encodeUrl

Пример:

assert encodeQuery({: }) == ""
assert encodeQuery({"a": "1", "b": "2"}) == "a=1&b=2"
assert encodeQuery({"a": "1", "b": ""}) == "a=1&b"

Исходный код Изменить

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

Инициализирует URI с scheme, username, password, hostname, port, path, query и anchor.

См. также:

тип Uri для доступных полей в типе URI

Пример:

var uri2: Uri
assert initUri() == uri2

Исходный код Изменить

func initUri(isIpv6: bool): Uri {...}{.raises: [], tags: [].}

Инициализирует URI с scheme, username, password, hostname, port, path, query, anchor и isIpv6.

См. также:

тип Uri для доступных полей в типе URI

Пример:

var uri2 = initUri(isIpv6 = true)
uri2.scheme = "tcp"
uri2.hostname = "2001:0db8:85a3:0000:0000:8a2e:0370:7334"
uri2.port = "8080"
assert $uri2 == "tcp://[2001:0db8:85a3:0000:0000:8a2e:0370:7334]:8080"

Исходный код Изменить

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

Парсит URI. Переменная result будет очищена перед этим.

См. также:

тип Uri для доступных полей в типе URI
функция initUri для инициализации URI

Пример:

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"

Исходный код Изменить

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

Парсит URI и возвращает его.

См. также:

тип Uri для доступных полей в типе URI

Пример:

let res = parseUri("ftp://Username:Password@Hostname")
assert res.username == "Username"
assert res.password == "Password"
assert res.scheme == "ftp"

Исходный код Изменить

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

Объединяет базовый URI с URI-ссылкой.

Это использует алгоритм, указанный в разделе 5.2.2 RFC 3986.

Это означает, что косые черты внутри пути базовых URI, а также пути URI-ссылки влияют на результирующий URI.

См. также:

/ функция для построения URI

Пример:

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"

Исходный код Изменить

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

Объединяет несколько URI вместе.

См. также:

/ функция для построения URI

Пример:

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"

Исходный код Изменить

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

Возвращает true, если URI абсолютный, в противном случае false.

Пример:

let foo = parseUri("https://nim-lang.org")
assert isAbsolute(foo) == true
let bar = parseUri("nim-lang")
assert isAbsolute(bar) == false

Исходный код Изменить

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

Конкатенирует указанный путь к пути указанных URI.

В отличие от функции combine, вам не нужно беспокоиться о косых чертах в начале и конце пути соответственно.

См. также:

функция combine

Пример:

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"

Исходный код Изменить

func `?`(u: Uri; query: openArray[(string, string)]): Uri {...}{.raises: [], tags: [].}

Конкатенирует параметры запроса к указанному объекту URI.

Пример:

let foo = parseUri("https://example.com") / "foo" ? {"bar": "qux"}
assert $foo == "https://example.com/foo?bar=qux"

Исходный код Изменить

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

Возвращает строковое представление указанного объекта URI.

Пример:

let foo = parseUri("https://nim-lang.org")
assert $foo == "https://nim-lang.org"

Исходный код Изменить