Module uri

The URI module provides functions that convert URI strings into their components, or turn components into URI strings, for example:

 
local uri = require('uri')parsed_uri = uri.parse('https://www.tarantool.io/doc/latest/reference/reference_lua/http/#api-reference')--[[---- host: www.tarantool.io  fragment: api-reference  scheme: https  path: /doc/latest/reference/reference_lua/http/...--]]formatted_uri = uri.format({ scheme = 'https',                             host = 'www.tarantool.io',                             path = '/doc/latest/reference/reference_lua/http/',                             fragment = 'api-reference' })--[[---- https://www.tarantool.io/doc/latest/reference/reference_lua/http/#api-reference...--]]

To escape and unescape special characters, corresponding functions must be used:

 
formatted_uri3_e = uri.format({    login = uri.escape('replic@ator'),    password = uri.escape(':::'),    host = 'foo.bar',    params = {x = uri.escape('sec ret?', uri.FORM_URLENCODED)}    },    true)--[[---- replic%40ator:%3A%3A%3A@foo.bar?x=sec+ret%3F...]]--parsed_uri3_e = uri.parse(formatted_uri3_e)--[[---- password: '%3A%3A%3A'  login: replic%40ator  query: x=sec+ret%3F  params:    x:    - sec+ret%3F  host: foo.bar...]]--parsed_uri3 = {    login = uri.unescape(parsed_uri3_e.login),    password = uri.unescape(parsed_uri3_e.password),    host = parsed_uri3_e.host,    params = {x = {uri.unescape(parsed_uri3_e.params.x[1], uri.FORM_URLENCODED)}},}--[[---- password: ':::'  params:    x:    - sec ret?  host: foo.bar  login: replic@ator...]]--

You can also use this module to encode and decode arbitrary strings using the specified encoding options.

Below is a list of uri functions, properties, and related objects.

Parse a URI string into components.

See also: uri.format()

Parameters:

• uri-string (string) — a URI string

• uri-table (table) — a URI table with an URI string and an optional override of URI query parameters. The URI string table key must be 'uri' or 1 (the first array-like element). The override of URI query parameters must be given in the 'params' element of the table.

Returns

a URI components table (see uri_components)

Return type

table

Example:

 
local uri = require('uri')parsed_uri = uri.parse('https://www.tarantool.io/doc/latest/reference/reference_lua/http/#api-reference')--[[---- host: www.tarantool.io  fragment: api-reference  scheme: https  path: /doc/latest/reference/reference_lua/http/...--]]parsed_uri11 = uri.parse({'foo.bar?x=1&x=2'})parsed_uri12 = uri.parse({uri = 'foo.bar?x=1&x=2'})--[[---- host: foo.bar  params:    x:    - '1'    - '2'  query: x=1&x=2...--]]parsed_uri21 = uri.parse({'foo.bar?x=1', params = {x = 2, y = 3}})parsed_uri22 = uri.parse({uri = 'foo.bar?x=1', params = {x = 2, y = 3}})--[[---- host: foo.bar  params:    y:    - '3'    x:    - '2'  query: x=1...--]]

Construct a URI from the specified components.

See also: uri.parse()

• uri_components (table) — a series of name=value pairs, one for each component (see uri_components)

• include_password (boolean) — specify whether the password component is rendered in clear text; otherwise, it is omitted

Returns

URI string

Return type

string

Example:

 
local uri = require('uri')formatted_uri = uri.format({ scheme = 'https',                             host = 'www.tarantool.io',                             path = '/doc/latest/reference/reference_lua/http/',                             fragment = 'api-reference' })--[[---- https://www.tarantool.io/doc/latest/reference/reference_lua/http/#api-reference...--]]parsed_uri12 = uri.parse({uri = 'foo.bar?x=1&x=2'})formatted_uri1 = uri.format(parsed_uri12)--[[---- foo.bar?x=1&x=2...--]]parsed_uri21 = uri.parse({'foo.bar?x=1', params = {x = 2, y = 3}})formatted_uri2 = uri.format(parsed_uri21)--[[---- foo.bar?y=3&x=2...--]]

Since: 2.11.0

Encode a string using the specified encoding options.

By default, uri.escape() uses encoding options defined by the uri.RFC3986 table. If required, you can customize encoding options using the uri_encoding_opts optional parameter, for example:

• Pass the predefined set of options targeted for encoding a specific URI part (for example, uri.PATH or uri.QUERY).

• Pass custom encoding options using the uri_encoding_opts object.

• string — a string to encode

• uri_encoding_opts (table) — encoding options (optional, see uri_encoding_opts)

Returns

an encoded string

Return type

string

Example 1:

This example shows how to encode a string using the default encoding options.

 
local uri = require('uri')escaped_string = uri.escape('C++')--[[---- C%2B%2B...--]]

Example 2:

This example shows how to encode a string using the uri.FORM_URLENCODED encoding options.

 
local uri = require('uri')escaped_string_url_enc = uri.escape('John Smith', uri.FORM_URLENCODED)--[[---- John+Smith...--]]

Example 3:

This example shows how to encode a string using custom encoding options.

 
local uri = require('uri')local escape_opts = {    plus = true,    unreserved = uri.unreserved("a-z")}escaped_string_custom = uri.escape('Hello World', escape_opts)--[[---- '%48ello+%57orld'...--]]

Since: 2.11.0

Decode a string using the specified encoding options.

By default, uri.escape() uses encoding options defined by the uri.RFC3986 table. If required, you can customize encoding options using the uri_encoding_opts optional parameter, for example:

• Pass the predefined set of options targeted for encoding a specific URI part (for example, uri.PATH or uri.QUERY).

• Pass custom encoding options using the uri_encoding_opts object.

• string — a string to decode

• uri_encoding_opts (table) — encoding options (optional, see uri_encoding_opts)

Returns

a decoded string

Return type

string

Example 1:

This example shows how to decode a string using the default encoding options.

 
local uri = require('uri')unescaped_string = uri.unescape('C%2B%2B')--[[---- C++...--]]

Example 2:

This example shows how to decode a string using the uri.FORM_URLENCODED encoding options.

 
local uri = require('uri')unescaped_string_url_enc = uri.unescape('John+Smith', uri.FORM_URLENCODED)--[[---- John Smith...--]]

Example 3:

This example shows how to decode a string using custom encoding options.

 
local uri = require('uri')local escape_opts = {    plus = true,    unreserved = uri.unreserved("a-z")}unescaped_string_custom = uri.unescape('%48ello+%57orld', escape_opts)--[[---- Hello World...--]]

Encoding options that use unreserved symbols defined in RFC 3986. These are default options used to encode and decode using the uri.escape() and uri.unescape() functions, respectively.

See also: uri_encoding_opts

Return type

table

Options used to encode the path URI component.

See also: uri_encoding_opts

Return type

table

Options used to encode specific path parts.

See also: uri_encoding_opts

Return type

table

Options used to encode the query URI component.

See also: uri_encoding_opts

Return type

table

Options used to encode specific query parts.

See also: uri_encoding_opts

Return type

table

Options used to encode the fragment URI component.

See also: uri_encoding_opts

Return type

table

Options used to encode application/x-www-form-urlencoded form parameters.

See also: uri_encoding_opts

Return type

table

uri_components URI components. The uri_components object is used in the following functions:

• The uri.parse() function returns the uri_components object.
• The uri.format() function accepts the uri_components object as an argument.

A URI scheme.

Examples: https, http

A user name, which is a part of the userinfo subcomponent.

A password, which is a part of the userinfo subcomponent.

A host subcomponent.

Example: www.tarantool.io

A service subcomponent. This property might return different values depending on the used URI scheme, for example:

• If the https or http scheme is used, service returns the port value.
• If the Unix domain socket is used, service returns the socket path.

Examples: 3301, /tmp/unix.sock

A path component.

Example: /doc/latest/reference/reference_lua/http/

A query component.

Example: key1=value1&key2=value2

Parameters of a query component. Overrides query. The table elements may be string or arrays of string.

Example: {key1 = 'value1', key2 = 'value2', key3 = {'1', '2'}}

A fragment component.

Example: api-reference

An IPv4 address.

Example: 127.0.0.1

An IPv6 address.

Example: 2a00:1148:b0ba:2016:12bf:48ff:fe78:fd10

A Unix domain socket.

Example: /tmp/unix.sock

Since: 2.11.0

URI encoding options. These options can be passed to the uri.escape() and uri.unescape() functions.

Example:

The example below shows how to encode a string using custom encoding options.

 
local uri = require('uri')local escape_opts = {    plus = true,    unreserved = uri.unreserved("a-z")}escaped_string_custom = uri.escape('Hello World', escape_opts)--[[---- '%48ello+%57orld'...--]]

Enable encoding of + as the space character. By default, this property is set to false.

Return type

boolean

Specify a Lua pattern defining unreserved symbols that are not encoded.

Return type

table

Example: 'a-zA-Z0-9%-._~'