Module uri | Tarantool

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
...
--]]

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.

Functions  
uri.parse() Get a table of URI components
uri.format() Construct a URI from the specified components
uri.escape() Encode a string using the specified encoding options
uri.unescape() Decode a string using the specified encoding options
Properties  
uri.RFC3986 Encoding options that use unreserved symbols defined in RFC 3986
uri.PATH Options used to encode the path URI component
uri.PATH_PART Options used to encode specific path parts
uri.QUERY Options used to encode the query URI component
uri.QUERY_PART Options used to encode specific query parts
uri.FRAGMENT Options used to encode the fragment URI component
uri.FORM_URLENCODED Options used to encode application/x-www-form-urlencoded form parameters
Related objects  
uri_components URI components
uri_encoding_opts URI encoding options

uri.parse(uri-string)

Parse a URI string into components.

See also: uri.format()

Parameters:
  • uri-string (string) – a URI string
Return:

a URI components table (see uri_components)

Rtype:

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/
...
--]]
uri.format(uri_components[, include_password])

Construct a URI from the specified components.

See also: uri.parse()

Parameters:
  • 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
Return:

URI string

Rtype:

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
...
--]]
uri.escape(string[, uri_encoding_opts])

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.
Parameters:
  • string – a string to encode
  • uri_encoding_opts (table) – encoding options (optional, see uri_encoding_opts)
Return:

an encoded string

Rtype:

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'
...
--]]
uri.unescape(string[, uri_encoding_opts])

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.
Parameters:
  • string – a string to decode
  • uri_encoding_opts (table) – encoding options (optional, see uri_encoding_opts)
Return:

a decoded string

Rtype:

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
...
--]]

uri.RFC3986

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

Rtype:table
uri.PATH

Options used to encode the path URI component.

See also: uri_encoding_opts

Rtype:table
uri.PATH_PART

Options used to encode specific path parts.

See also: uri_encoding_opts

Rtype:table
uri.QUERY

Options used to encode the query URI component.

See also: uri_encoding_opts

Rtype:table
uri.QUERY_PART

Options used to encode specific query parts.

See also: uri_encoding_opts

Rtype:table
uri.FRAGMENT

Options used to encode the fragment URI component.

See also: uri_encoding_opts

Rtype:table
uri.FORM_URLENCODED

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

See also: uri_encoding_opts

Rtype:table
Found what you were looking for?
Feedback