Spec-Zone.ru › Nim

std/uri

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

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

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

Предупреждение: Парсеры URI в этом модуле не выполняют проверку безопасности.

Основные примеры использования

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

Пример:

import std/uri
let host = parseUri("https://nim-lang.org")
assert $host == "https://nim-lang.org"
assert $(host / "/blog.html") == "https://nim-lang.org/blog.html"
assert $(host / "blog2.html") == "https://nim-lang.org/blog2.html"

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

Пример:

import std/uri
let res = parseUri("sftp://127.0.0.1:4343")
assert isAbsolute(res)
assert res.port == "4343"

URI данных Base64

Пример:

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

Импорты

strutils, parseutils, base64, since, decode_helpers

Типы

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

Процедуры

func `$`(u: Uri): string {....raises: [], tags: [], forbids: [].}
Возвращает строковое представление указанного объекта URI.

Пример:

assert $parseUri("https://nim-lang.org") == "https://nim-lang.org"
Исходный код Редактировать 
func `/`(x: Uri; path: string): Uri {....raises: [], tags: [], forbids: [].}

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

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

См. также:

  • функция 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: [], forbids: [].}
Конкатенирует параметры запроса к указанному объекту URI.

Пример:

let foo = parseUri("https://example.com") / "foo" ? {"bar": "qux"}
assert $foo == "https://example.com/foo?bar=qux"
Исходный код Редактировать 
func combine(base: Uri; reference: Uri): Uri {....raises: [], tags: [], forbids: [].}

Комбинирует базовый 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: [], forbids: [].}

Комбинирует несколько 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 decodeUrl(s: string; decodePlus = true): string {....raises: [], tags: [],
    forbids: [].}

Декодирует 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; sep = '&'): string {....raises: [], tags: [],
    forbids: [].}

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

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

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

См. также:

  • функция encodeUrl

Пример:

assert encodeQuery({: }) == ""
assert encodeQuery({"a": "1", "b": "2"}) == "a=1&b=2"
assert encodeQuery({"a": "1", "b": ""}) == "a=1&b"
assert encodeQuery({"a": "1", "b": ""}, omitEq = false, sep = ';') == "a=1;b="
Исходный код Редактировать 
func encodeUrl(s: string; usePlus = true): string {....raises: [], tags: [],
    forbids: [].}

Кодирует 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"
Исходный код Редактировать 
proc getDataUri(data, mime: string; encoding = "utf-8"): string {....raises: [],
    tags: [], forbids: [].}

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

См. также:

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

Пример:

static: assert getDataUri("Nim", "text/plain") == "data:text/plain;charset=utf-8;base64,Tmlt"
Исходный код Редактировать 
func initUri(isIpv6 = false): Uri {....raises: [], tags: [], forbids: [].}

Инициализирует 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 isAbsolute(uri: Uri): bool {....raises: [], tags: [], forbids: [].}
Возвращает true, если URI является абсолютным, иначе false.

Пример:

assert parseUri("https://nim-lang.org").isAbsolute
assert not parseUri("nim-lang").isAbsolute
Исходный код Редактировать 
func parseUri(uri: string): Uri {....raises: [], tags: [], forbids: [].}

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

См. также:

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

Пример:

let res = parseUri("ftp://Username:Password@Hostname")
assert res.username == "Username"
assert res.password == "Password"
assert res.scheme == "ftp"
Исходный код Редактировать 
func parseUri(uri: string; result: var Uri) {....raises: [], tags: [], forbids: [].}

Парсит 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"
Исходный код Редактировать 
proc uriParseError(msg: string) {.noreturn, ...raises: [UriParseError], tags: [],
                                  forbids: [].}
Вызывает исключение UriParseError с сообщением msg. Исходный код Редактировать

Итераторы

iterator decodeQuery(data: string; sep = '&'): tuple[key, value: string] {.
    ...raises: [], tags: [], forbids: [].}
Читает и декодирует строку запроса data и возвращает пары (key, value) , из которых состоят данные. Если скомпилировано с -d:nimLegacyParseQueryStrict, исключение UriParseError выбрасывается, когда в декодированном значении есть не закодированный символ =, что было поведением Nim < 1.5.1.

Пример:

import std/sequtils
assert toSeq(decodeQuery("foo=1&bar=2=3")) == @[("foo", "1"), ("bar", "2=3")]
assert toSeq(decodeQuery("foo=1;bar=2=3", ';')) == @[("foo", "1"), ("bar", "2=3")]
assert toSeq(decodeQuery("&a&=b&=&&")) == @[("", ""), ("a", ""), ("", "b"), ("", ""), ("", "")]
Исходный код Редактировать

© 2006–2024 Andreas Rumpf
Licensed under the MIT License.
https://nim-lang.org/docs/uri.html

Spec-Zone.ru

Настройки Оффлайн Что нового Помощь О нас
Spec-Zone .ru
спецификации, руководства, описания, API