Module `resty.ada`

Provides URL parsing and manipulation functionality.

See: https://url.spec.whatwg.org/#url-representation

Constructors

parse (url)	Parses URL and returns an instance of Ada URL.
parse_with_base (url, base)	Parses URL with base URL and returns an instance of Ada URL.

Convert Functions

idna_to_ascii (domain)	Converts a domain (e.g., www.google.com) possibly containing international characters to an ascii domain (with punycode).
idna_to_unicode (domain)	Converts possibly international ascii domain to unicode.

Validate Functions

can_parse (url)	Checks whether the URL can be parsed.
can_parse_with_base (url, base)	Checks whether the URL can be parsed with a base URL.

Decode Functions

decode ()

Decodes URL and return its components in Lua table.

Has Functions

has_credentials (url)	Checks whether the URL has credentials.
has_non_empty_username (url)	Checks whether the URL has a non-empty username.
has_password (url)	Checks whether the URL has a password.
has_non_empty_password (url)	Checks whether the URL has a non-empty password.
has_hostname (url)	Checks whether the URL has a hostname (included an empty host).
has_empty_hostname (url)	Checks whether the URL has an host but it is the empty string.
has_port (url)	Checks whether the URL has a (non default) port.
has_search (url)	Checks whether the URL has a search component.
has_hash (url)	Checks whether the URL has a hash component.

Get Functions

get_components (url)	Parses URL and returns a table with URL component positions in a string (Lua 1-based indexing).
get_href (url)	Get URL in a normalized form.
get_protocol (url)	Get protocol from the URL.
get_scheme_type (url)	Get scheme type from the URL.
get_origin (url)	Get origin of the URL.
get_username (url)	Get URL’s username.
get_password (url)	Get URL’s password.
get_host (url)	Get URL’s host, serialized, followed by U+003A (:) and url’s port, serialized.
get_hostname (url)	Get URL’s host (name only), serialized.
get_host_type (url)	Get host type from the URL.
get_port (url)	Get URL’s port.
get_pathname (url)	Get URL’s path.
get_search (url)	Get URL’s search (query).
get_hash (url)	Get URL’s hash (fragment).

Set Functions

set_protocol (url, protocol)	Sets protocol to the URL.
set_username (url, username)	Sets username to the URL.
set_password (url, password)	Sets password to the URL.
set_host (url, host)	Sets host to the URL.
set_hostname (url, hostname)	Sets host (name only) to the URL.
set_port (url, port)	Sets port to the URL.
set_pathname (url, pathname)	Sets path to the URL.
set_search (url, query)	Sets search (query) to the URL.
set_hash (url, hash)	Sets hash (fragment) to the URL.

Clear Functions

clear_port (url)	Clear URL’s port.
clear_search (url)	Clear URL’s search (query string).
clear_hash (url)	Clear URL’s hash (fragment).

Search Functions

search_parse (url)	Parses search from URL and returns an instance of Ada URL Search.
search_encode (url)	Encodes search parameters from URL and returns an query string.
search_decode (url)	Decodes search parameters from URL and returns a Lua table of them.
search_decode_all (url)	Decodes all search parameters and returns a Lua table of them.
search_has (url, key)	Checks whether the url has a search with a key.
search_has_value (url, key, value)	Checks whether the url has a search with a key with a specific value.
search_get (url, key)	Get URL’s search parameter’s value.
search_get_all (url, key)	Get all the URL’s search parameter’s values.
search_set (url, key, value)	Set the URL’s search parameter’s value.
search_append (url, key, value)	Append value to the the URL’s search parameter.
search_remove (url, key)	Remove search parameter from URL.
search_remove_value (url, key, value)	Remove search parameter’s value from URL.
search_sort (url)	Sort the URL’s search parameters.
search_size (url)	Count search parameters in URL.
search_each (url)	Iterate over search parameters in URL.
search_each_key (url)	Iterate over each key in parameters in URL.
search_each_value (url)	Iterate over each value in search parameters in URL.
search_pairs (url)	Iterate over each key and value in search parameters in URL.
search_ipairs (url)	Iterate over each parameter in search parameters in URL.

Fields

_VERSION	resty.ada version
search	resty.ada.search

Constructors

parse (url)

Parses URL and returns an instance of Ada URL.

Parameters:

url string url to parse

Returns:

url or nil Ada URL instance
nil or string error message

Raises:

error when url is not a string

Usage:

local ada = require("resty.ada")
local url, err = ada.parse("https://user:pass@host:1234/path?search#hash")

parse_with_base (url, base)

Parses URL with base URL and returns an instance of Ada URL.

Parameters:

url string URL (or part of it) to parse
base string base url to parse

Returns:

url or nil Ada URL instance
nil or string error message

Raises:

error when url or base is not a string

Usage:

local ada = require("resty.ada")
local url, err = ada.parse_with_base("/path?search#hash",
                                     "https://user:pass@host:1234")

Convert Functions

idna_to_ascii (domain)

Converts a domain (e.g., www.google.com) possibly containing international characters to an ascii domain (with punycode).

See: https://url.spec.whatwg.org/#concept-domain-to-ascii

It will not do percent decoding: percent decoding should be done prior to calling this function. We do not remove tabs and spaces, they should have been removed prior to calling this function. We also do not trim control characters. We also assume that the input is not empty. We return “” on error.

This function may accept or even produce invalid domains.

We receive a UTF-8 string representing a domain name. If the string is percent encoded, we apply percent decoding.

Given a domain, we need to identify its labels.

They are separated by label-separators:

U+002E (.) FULL STOP
U+FF0E FULLWIDTH FULL STOP
U+3002 IDEOGRAPHIC FULL STOP
U+FF61 HALFWIDTH IDEOGRAPHIC FULL STOP

They are all mapped to U+002E.

We process each label into a string that should not exceed 63 octets. If the string is already punycode (starts with “xn–”), then we must scan it to look for unallowed code points.

Otherwise, if the string is not pure ASCII, we need to transcode it to punycode by following RFC 3454 which requires us to:

Map characters (see section 3),
Normalize (see section 4),
Reject forbidden characters,
Check for right-to-left characters and if so, check all requirements (see section 6),
Optionally reject based on unassigned code points (section 7).

The Unicode standard provides a table of code points with a mapping, a list of forbidden code points and so forth. This table is subject to change and will vary based on the implementation. For Unicode 15, the table is at https://www.unicode.org/Public/idna/15.0.0/IdnaMappingTable.txt

The resulting strings should not exceed 255 octets according to RFC 1035 section 2.3.4. ICU checks for label size and domain size, but these errors are ignored.

Parameters:

domain string URL (or part of it) to parse

Returns:

string or nil

Raises:

error when domain not a string

Usage:

local ada = require("resty.ada")
local res = ada.idna_to_ascii("www.7‑Eleven.com") -- www.xn--7eleven-506c.com

idna_to_unicode (domain)

Converts possibly international ascii domain to unicode.

See: https://www.unicode.org/reports/tr46/#ToUnicode

Parameters:

domain string URL (or part of it) to parse

Returns:

string or nil

Raises:

error when domain not a string

Usage:

local ada = require("resty.ada")
local res = ada.idna_to_unicode("www.xn--7eleven-506c.com") -- www.7‑Eleven.com

Validate Functions

can_parse (url)

Checks whether the URL can be parsed.

See: https://url.spec.whatwg.org/#dom-url-canparse

Parameters:

url string URL (or part of it) to check

Returns:

boolean

true

false

Usage:

local ada = require("resty.ada")
local ok = ada.can_parse("https://user:pass@host:1234/path?search#hash")

can_parse_with_base (url, base)

Checks whether the URL can be parsed with a base URL.

See: https://url.spec.whatwg.org/#dom-url-canparse

Parameters:

url string URL (or part of it) to check
base string base url to check

Returns:

boolean

true

false

Usage:

local ada = require("resty.ada")
local ok = ada.can_parse_with_base("/path?search#hash",
                                   "https://user:pass@host:1234")

Decode Functions

decode ()

Decodes URL and return its components in Lua table.

Given a following URL: https://user:pass@example.com:1234/foo/bar?baz#quux

This function will return the following table:

{
  origin = "https://example.com:1234",
  scheme_type = 2,
  protocol = "https:",
  username = "user",
  password = "pass",
  host_type = 0,
  host = "example.com:1234",
  hostname = "example.com",
  port = 1234,
  pathname = "/foo/bar",
  search = "?baz",
  hash = "#quux",
}

The missing ones will be returned as empty string "" (rather than nil).

Returns:

table or nil table of URL components (except on errors nil)
nil or string error message

Raises:

error when url is not a string

Usage:

local ada = require("resty.ada")
local res = ada.decode("https://user:pass@host:1234/path?search#hash")

Has Functions

has_credentials (url)

Checks whether the URL has credentials.

A URL includes credentials if its username or password is not the empty string.

Parameters:

url string URL (or part of it) to check

Returns:

boolean or nil true if URL has credentials, otherwise false (except on errors nil)
nil or string error message

Raises:

error when url is not a string

Usage:

local ada = require("resty.ada")
local res = ada.has_credentials("https://user:pass@host:1234/path?search#hash")

has_non_empty_username (url)

Checks whether the URL has a non-empty username.

Parameters:

url string URL (or part of it) to check

Returns:

boolean or nil true if URL has a non-empty username, otherwise false (except on errors nil)
nil or string error message

Raises:

error when url is not a string

Usage:

local ada = require("resty.ada")
local res = ada.has_non_empty_username("https://user:pass@host:1234/path?search#hash")

has_password (url)

Checks whether the URL has a password.

Parameters:

url string URL (or part of it) to check

Returns:

boolean or nil true if URL has a password, otherwise false (except on errors nil)
nil or string error message

Raises:

error when url is not a string

Usage:

local ada = require("resty.ada")
local res = ada.has_password("https://user:pass@host:1234/path?search#hash")

has_non_empty_password (url)

Checks whether the URL has a non-empty password.

Parameters:

url string URL (or part of it) to check

Returns:

boolean or nil true if URL has a non-empty password, otherwise false (except on errors nil)
nil or string error message

Raises:

error when url is not a string

Usage:

local ada = require("resty.ada")
local res = ada.has_non_empty_password("https://user:pass@host:1234/path?search#hash")

has_hostname (url)

Checks whether the URL has a hostname (included an empty host).

Parameters:

url string URL (or part of it) to check

Returns:

boolean or nil true if URL has a hostname (included an empty host), otherwise false (except on errors nil)
nil or string error message

Raises:

error when url is not a string

Usage:

local ada = require("resty.ada")
local res = ada.has_hostname("https://user:pass@host:1234/path?search#hash")

has_empty_hostname (url)

Checks whether the URL has an host but it is the empty string.

Parameters:

url string URL (or part of it) to check

Returns:

boolean or nil true if URL has an empty hostname, otherwise false (except on errors nil)
nil or string error message

Raises:

error when url is not a string

Usage:

local ada = require("resty.ada")
local res = ada.has_empty_hostname("https://user:pass@host:1234/path?search#hash")

has_port (url)

Checks whether the URL has a (non default) port.

Parameters:

url string URL (or part of it) to check

Returns:

boolean or nil true if URL has a (non default) port, otherwise false (except on errors nil)
nil or string error message

Raises:

error when url is not a string

Usage:

local ada = require("resty.ada")
local res = ada.has_port("https://user:pass@host:1234/path?search#hash")

has_search (url)

Checks whether the URL has a search component.

Parameters:

url string URL (or part of it) to check

Returns:

boolean or nil true if URL has a search, otherwise false (except on errors nil)
nil or string error message

Raises:

error when url is not a string

Usage:

local ada = require("resty.ada")
local res = ada.has_search("https://user:pass@host:1234/path?search#hash")

has_hash (url)

Checks whether the URL has a hash component.

Parameters:

url string URL (or part of it) to check

Returns:

boolean or nil true if URL has a hash, otherwise false (except on errors nil)
nil or string error message

Raises:

error when url is not a string

Usage:

local ada = require("resty.ada")
local res = ada.has_hash("https://user:pass@host:1234/path?search#hash")

Get Functions

get_components (url)

Parses URL and returns a table with URL component positions in a string (Lua 1-based indexing).

Please be careful with the output of this function as it normalizes the input string.

https://user:pass@example.com:1234/foo/bar?baz#quux
      |     |    |          | ^^^^|       |   |
      |     |    |          | |   |       |   ------ hash_start
      |     |    |          | |   |       ---------- search_start
      |     |    |          | |   ------------------ pathname_start
      |     |    |          | ---------------------- port
      |     |    |          ------------------------ host_end
      |     |    ----------------------------------- host_start
      |     ---------------------------------------- username_end
      ---------------------------------------------- protocol_end

Given a following URL: https://user:pass@example.com:1234/foo/bar?baz#quux

This function will return following table:

{
  protocol_end = 7,
  username_end = 13,
  host_start = 18,
  host_end = 29,
  port = 1234,
  pathname_start = 35,
  search_start = 43,
  hash_start = 47,
}

Parameters:

url string URL (or part of it) to from which the URL component positions are extracted

Returns:

table or nil table of URL components (or their positions) (except on errors nil)
nil or string error message

Raises:

error when url is not a string

Usage:

local ada = require("resty.ada")
local res = ada.get_components("https://user:pass@host:1234/path?search#hash")

get_href (url)

Get URL in a normalized form.

See: https://url.spec.whatwg.org/#dom-url-href See: https://url.spec.whatwg.org/#concept-url-serializer

Parameters:

url string URL (or part of it) from which to get href

Returns:

string or nil URL in a normalized form (except on errors nil)
nil or string error message

Raises:

error when url is not a string

Usage:

local ada = require("resty.ada")
local res = ada.get_href("https://user:pass@host:1234/path?search#hash")

get_protocol (url)

Get protocol from the URL.

See: https://url.spec.whatwg.org/#dom-url-protocol

Parameters:

url string URL (or part of it) from which to extract the protocol

Returns:

string or nil protocol part of the URL (except on errors nil)
nil or string error message

Raises:

error when url is not a string

Usage:

local ada = require("resty.ada")
local res = ada.get_protocol("https://user:pass@host:1234/path?search#hash")

get_scheme_type (url)

Get scheme type from the URL.

See: https://url.spec.whatwg.org/#url-miscellaneous

Scheme type definitions:

0 = HTTP
1 = NOT_SPECIAL
2 = HTTPS
3 = WS
4 = FTP
5 = WSS
6 = FILE

Parameters:

url string URL (or part of it) from which to get scheme type

Returns:

number or nil scheme type of the URL (except on errors nil)
nil or string error message

Raises:

error when url is not a string

Usage:

local ada = require("resty.ada")
local res = ada.get_scheme_type("https://user:pass@host:1234/path?search#hash")

get_origin (url)

Get origin of the URL.

See: https://url.spec.whatwg.org/#concept-url-origin

Parameters:

url string URL (or part of it) from which to get origin

Returns:

string or nil origin of the URL (except on errors nil)
nil or string error message

Raises:

error when url is not a string

Usage:

local ada = require("resty.ada")
local res = ada.get_origin("https://user:pass@host:1234/path?search#hash")

get_username (url)

Get URL’s username.

See: https://url.spec.whatwg.org/#dom-url-username

Parameters:

url string URL (or part of it) from which to get username

Returns:

string or nil URL’s username (except on errors nil)
nil or string error message

Raises:

error when url is not a string

Usage:

local ada = require("resty.ada")
local res = ada.get_username("https://user:pass@host:1234/path?search#hash")

get_password (url)

Get URL’s password.

See: https://url.spec.whatwg.org/#dom-url-password

Parameters:

url string URL (or part of it) from which to get password

Returns:

string or nil URL’s password (except on errors nil)
nil or string error message

Raises:

error when url is not a string

Usage:

local ada = require("resty.ada")
local res = ada.get_password("https://user:pass@host:1234/path?search#hash")

get_host (url)

Get URL’s host, serialized, followed by U+003A (:) and url’s port, serialized.

See: https://url.spec.whatwg.org/#dom-url-host

Parameters:

url string URL (or part of it) from which to get host

Returns:

string or nil URL’s host (except on errors nil)
nil or string error message

Raises:

error when url is not a string

Usage:

local ada = require("resty.ada")
local res = ada.get_host("https://user:pass@host:1234/path?search#hash")

get_hostname (url)

Get URL’s host (name only), serialized.

When there is no host, this function returns the empty string.

See: https://url.spec.whatwg.org/#dom-url-hostname

Parameters:

url string URL (or part of it) from which to get host (name only)

Returns:

string or nil URL’s host (name only) (except on errors nil)
nil or string error message

Raises:

error when url is not a string

Usage:

local ada = require("resty.ada")
local res = ada.get_hostname("https://user:pass@host:1234/path?search#hash")

get_host_type (url)

Get host type from the URL.

Host type definitions:

0 = DEFAULT: e.g. "https://www.google.com"
1 = IPV4:    e.g. "http://127.0.0.1"
2 = IPV6:    e.g. "http://[2001:db8:3333:4444:5555:6666:7777:8888]"

Parameters:

url string URL (or part of it) from which to get scheme type

Returns:

number or nil scheme type of the URL (except on errors nil)
nil or string error message

Raises:

error when url is not a string

Usage:

local ada = require("resty.ada")
local res = ada.get_host_type("https://user:pass@host:1234/path?search#hash")

get_port (url)

Get URL’s port.

See: https://url.spec.whatwg.org/#dom-url-port

Parameters:

url string URL (or part of it) from which to get port

Returns:

number, string or nil URL’s port (except on errors nil)
nil or string error message

Raises:

error when url is not a string

Usage:

local ada = require("resty.ada")
local res = ada.get_port("https://user:pass@host:1234/path?search#hash")

get_pathname (url)

Get URL’s path.

See: https://url.spec.whatwg.org/#dom-url-pathname

Parameters:

url string URL (or part of it) from which to get path

Returns:

string or nil URL’s path (except on errors nil)
nil or string error message

Raises:

error when url is not a string

Usage:

local ada = require("resty.ada")
local res = ada.get_pathname("https://user:pass@host:1234/path?search#hash")

get_search (url)

Get URL’s search (query).

Return U+003F (?), followed by URL’s query.

See: https://url.spec.whatwg.org/#dom-url-search

Parameters:

url string URL (or part of it) from which to get query

Returns:

string or nil URL’s query (except on errors nil)
nil or string error message

Raises:

error when url is not a string

Usage:

local ada = require("resty.ada")
local res = ada.get_search("https://user:pass@host:1234/path?search#hash")

get_hash (url)

Get URL’s hash (fragment).

Return U+0023 (#), followed by URL’s fragment.

See: https://url.spec.whatwg.org/#dom-url-hash

Parameters:

url string URL (or part of it) from which to get fragment

Returns:

string or nil URL’s fragment (except on errors nil)
nil or string error message

Raises:

error when url is not a string

Usage:

local ada = require("resty.ada")
local res = ada.get_hash("https://user:pass@host:1234/path?search#hash")

Set Functions

set_protocol (url, protocol)

Sets protocol to the URL.

See: https://url.spec.whatwg.org/#dom-url-protocol

Parameters:

url string URL (or part of it) for which to set the protocol
protocol string the protocol to set to the URL

Returns:

string or nil URL in a normalized form (except on errors nil)
nil or string error message

Raises:

error when url or protocol is not a string

Usage:

local ada = require("resty.ada")
local res = ada.set_protocol("https://user:pass@host:1234/path?search#hash", "wss")

set_username (url, username)

Sets username to the URL.

See: https://url.spec.whatwg.org/#dom-url-username

Parameters:

url string URL (or part of it) for which to set the username
username string the username to set to the URL

Returns:

string or nil URL in a normalized form (except on errors nil)
nil or string error message

Raises:

error when url or username is not a string

Usage:

local ada = require("resty.ada")
local res = ada.set_username("https://user:pass@host:1234/path?search#hash", "guest")

set_password (url, password)

Sets password to the URL.

See: https://url.spec.whatwg.org/#dom-url-password

Parameters:

url string URL (or part of it) for which to set the password
password string the password to set to the URL

Returns:

string or nil URL in a normalized form (except on errors nil)
nil or string error message

Raises:

error when url or password is not a string

Usage:

local ada = require("resty.ada")
local res = ada.set_password("https://user:pass@host:1234/path?search#hash", "secret")

set_host (url, host)

Sets host to the URL.

See: https://url.spec.whatwg.org/#dom-url-host

Parameters:

url string URL (or part of it) for which to set the host
host string the host to set to the URL

Returns:

string or nil URL in a normalized form (except on errors nil)
nil or string error message

Raises:

error when url or host is not a string

Usage:

local ada = require("resty.ada")
local res = ada.set_host("https://user:pass@host:1234/path?search#hash", "test:4321")

set_hostname (url, hostname)

Sets host (name only) to the URL.

See: https://url.spec.whatwg.org/#dom-url-hostname

Parameters:

url string URL (or part of it) for which to set the host (name only)
hostname string the host (name only) to set to the URL

Returns:

string or nil URL in a normalized form (except on errors nil)
nil or string error message

Raises:

error when url or hostname is not a string

Usage:

local ada = require("resty.ada")
local res = ada.set_hostname("https://user:pass@host:1234/path?search#hash", "test")

set_port (url, port)

Sets port to the URL.

See: https://url.spec.whatwg.org/#dom-url-port

Parameters:

url string URL (or part of it) for which to set the port
port number or string the port to set to the URL

Returns:

string or nil URL in a normalized form (except on errors nil)
nil or string error message

Raises:

error when url is not a string or port is not a number or a string

Usage:

local ada = require("resty.ada")
local res = ada.set_port("https://user:pass@host:1234/path?search#hash", 4321)

set_pathname (url, pathname)

Sets path to the URL.

See: https://url.spec.whatwg.org/#dom-url-pathname

Parameters:

url string URL (or part of it) for which to set the path
pathname string the path to set to the URL

Returns:

string or nil URL in a normalized form (except on errors nil)
nil or string error message

Raises:

error when url or pathname is not a string

Usage:

local ada = require("resty.ada")
local res = ada.set_pathname("https://user:pass@host:1234/path?search#hash", "foo")

set_search (url, query)

Sets search (query) to the URL.

See: https://url.spec.whatwg.org/#dom-url-search

Parameters:

url string URL (or part of it) for which to set the query string
query string the query string to set to the URL

Returns:

string or nil URL in a normalized form (except on errors nil)
nil or string error message

Raises:

error when url or search is not a string

Usage:

local ada = require("resty.ada")
local res = ada.set_search("https://user:pass@host:1234/path?search#hash", "q=1&done")

set_hash (url, hash)

Sets hash (fragment) to the URL.

See: https://url.spec.whatwg.org/#dom-url-hash

Parameters:

url string URL (or part of it) for which to set the fragment string
hash string the fragment to set to the URL

Returns:

string or nil URL in a normalized form (except on errors nil)
nil or string error message

Raises:

error when url or hash is not a string

Usage:

local ada = require("resty.ada")
local res = ada.set_hash("https://user:pass@host:1234/path?search#hash", "home")

Clear Functions

clear_port (url)

Clear URL’s port.

See: https://url.spec.whatwg.org/#dom-url-port

Parameters:

url string URL (or part of it) from which to clear the port

Returns:

string or nil URL in a normalized form (except on errors nil)
nil or string error message

Raises:

error when url is not a string

Usage:

local ada = require("resty.ada")
local res = ada.clear_port("https://user:pass@host:1234/path?search#hash")

clear_search (url)

Clear URL’s search (query string).

See: https://url.spec.whatwg.org/#dom-url-port

Parameters:

url string URL (or part of it) from which to clear the query string

Returns:

string or nil URL in a normalized form (except on errors nil)
nil or string error message

Raises:

error when url is not a string

Usage:

local ada = require("resty.ada")
local res = ada.clear_search("https://user:pass@host:1234/path?search#hash")

clear_hash (url)

Clear URL’s hash (fragment).

See: https://url.spec.whatwg.org/#dom-url-port

Parameters:

url string URL (or part of it) from which to clear the fragment

Returns:

string or nil URL in a normalized form (except on errors nil)
nil or string error message

Raises:

error when url is not a string

Usage:

local ada = require("resty.ada")
local res = ada.clear_hash("https://user:pass@host:1234/path?search#hash")

Search Functions

search_parse (url)

Parses search from URL and returns an instance of Ada URL Search.

Parameters:

url string url (with search) to parse

Returns:

search or nil Ada URL Search instance (except on errors nil)
nil or string error message

Raises:

error when url is not a string

Usage:

local ada = require("resty.ada")
local res = ada.search_parse("http://host/?a=b&c=d&e=f&a=g")

search_encode (url)

Encodes search parameters from URL and returns an query string.

Parameters:

url string url (with search) to parse

Returns:

string

Raises:

error when url is not a string

Usage:

local ada = require("resty.ada")
local res = ada.search_encode("http://host/?a=b&c=d&e=f&a=g")

search_decode (url)

Decodes search parameters from URL and returns a Lua table of them.

If same parameter appears multiple times, only the value of the first is returned.

Given the following URL: “http://host/?a=b&c=d&e=f&a=g”

The following table is returned: { a = “b”, c = “d”, e = “f”, }

Parameters:

url string url (with search) to parse

Returns:

table or nil a table of all search parameters (a string:string map).
nil or string error message

Raises:

error when url is not a string

Usage:

local ada = require("resty.ada")
local res = ada.search_decode("http://host/?a=b&c=d&e=f&a=g")

search_decode_all (url)

Decodes all search parameters and returns a Lua table of them.

Given the following URL: “http://host/?a=b&a=c&d=e”"

The following table is returned: { a = { “b”, “c” }, d = { “e” }, }

Parameters:

url string url (with search) to parse

Returns:

table or nil a table of all search parameters (a string:table [array] map).
nil or string error message

Raises:

error when url is not a string

Usage:

local ada = require("resty.ada")
local res = ada.search_decode_all("http://host/?a=b&a=c&d=e")

search_has (url, key)

Checks whether the url has a search with a key.

Parameters:

url string url (with search) to parse
key string search parameter name to check

Returns:

boolean true if search has the key, otherwise false (except on errors nil)
nil or string error message

Raises:

error when url or key is not a string

Usage:

local ada = require("resty.ada")
local res = ada.search_has("https://user:pass@host:1234/?a=b&c=d&e=f", "a")

search_has_value (url, key, value)

Checks whether the url has a search with a key with a specific value.

Parameters:

url string url (with search) to parse
key string search parameter name to check
value string search parameter value to check

Returns:

boolean true if search has the key with the value, otherwise false (except on errors nil)
nil or string error message

Raises:

error when url, key or value is not a string

Usage:

local ada = require("resty.ada")
local res = ada.search_has_value("https://user:pass@host:1234/?a=b&c=d&e=f", "a", "b")

search_get (url, key)

Get URL’s search parameter’s value.

Parameters:

url string url (with search) to parse
key string search parameter name

Returns:

string or nil parameter value or nil (and on errors nil)
nil or string error message

Raises:

error when url or key is not a string

Usage:

local ada = require("resty.ada")
local res = ada.search_get("https://user:pass@host:1234/?a=b&c=d&e=f", "a")

search_get_all (url, key)

Get all the URL’s search parameter’s values.

Parameters:

url string url (with search) to parse
key string search parameter name

Returns:

table or nil array of all the values (or an empty array) (except on errors nil)
nil or string error message

Raises:

error when url or key is not a string

Usage:

local ada = require("resty.ada")
local res = ada.search_get_all("https://user:pass@host:1234/?a=b&c=d&e=f", "a")

search_set (url, key, value)

Set the URL’s search parameter’s value.

Parameters:

url string url (with search) to parse
key string search parameter name
value string search parameter value

Returns:

string or nil string presentation of the URL (except on errors nil)
nil or string error message

Raises:

error when url, key or value is not a string

Usage:

local ada = require("resty.ada")
local res = ada.search_set("https://user:pass@host:1234/?a=b&c=d&e=f", "a", "g")

search_append (url, key, value)

Append value to the the URL’s search parameter.

Parameters:

url string url (with search) to parse
key string search parameter name
value string search parameter value

Returns:

string or nil string presentation of the URL (except on errors nil)
nil or string error message

Raises:

error when url, key or value is not a string

Usage:

local ada = require("resty.ada")
local res = ada.search_append("https://user:pass@host:1234/?a=b&c=d&e=f", "a", "g")

search_remove (url, key)

Remove search parameter from URL.

Parameters:

url string url (with search) to parse
key string search parameter name

Returns:

string or nil string presentation of the URL (except on errors nil)
nil or string error message

Raises:

error when url or key is not a string

Usage:

local ada = require("resty.ada")
local res = ada.search_remove("https://user:pass@host:1234/?a=b&c=d&e=f", "a")

search_remove_value (url, key, value)

Remove search parameter’s value from URL.

Parameters:

url string url (with search) to parse
key string search parameter name
value string search parameter’s value

Returns:

string or nil string presentation of the URL (except on errors nil)
nil or string error message

Raises:

error when url, key or value is not a string

Usage:

local ada = require("resty.ada")
local res = ada.search_remove_value("https://user:pass@host:1234/?a=b&c=d&e=f", "a", "b")

search_sort (url)

Sort the URL’s search parameters.

Parameters:

url string url (with search) to parse

Returns:

string or nil string presentation of the URL (except on errors nil)
nil or string error message

Raises:

error when url is not a string

Usage:

local ada = require("resty.ada")
local res = ada.search_sort("https://user:pass@host:1234/?e=f&c=d&a=b")

search_size (url)

Count search parameters in URL.

Parameters:

url string url (with search) to parse

Returns:

number or nil search parameters count (except on errors nil)
nil or string error message

Raises:

error when url is not a string

Usage:

local ada = require("resty.ada")
local res = ada.search_size("https://user:pass@host:1234/?a=b&c=d&e=f")

search_each (url)

Iterate over search parameters in URL.

Parameters:

url string url (with search) to parse

Returns:

function iterator function (except on errors nil)
cdata or string state or error message

Raises:

error when url is not a string

Usage:

local ada = require("resty.ada")
for param in ada.search_each("https://user:pass@host:1234/?a=b&c=d&e=f") do
  print(param.key, " = ", param.value)
end

search_each_key (url)

Iterate over each key in parameters in URL.

Parameters:

url string url (with search) to parse

Returns:

function iterator function (except on errors nil)
cdata or string state or error message

Raises:

error when url is not a string

Usage:

local ada = require("resty.ada")
for key in ada.search_each_key("https://user:pass@host:1234/?a=b&c=d&e=f") do
  print("key: ", key)
end

search_each_value (url)

Iterate over each value in search parameters in URL.

Parameters:

url string url (with search) to parse

Returns:

function iterator function (except on errors nil)
cdata or string state or error message

Raises:

error when url is not a string

Usage:

local ada = require("resty.ada")
for value in ada.search_each_value("https://user:pass@host:1234/?a=b&c=d&e=f") do
  print("value: ", value)
end

search_pairs (url)

Iterate over each key and value in search parameters in URL.

Parameters:

url string url (with search) to parse

Returns:

function iterator function (except on errors nil)
cdata or string state or error message

Raises:

error when url is not a string

Usage:

local ada = require("resty.ada")
for key, value in ada.search_pairs("https://user:pass@host:1234/?a=b&c=d&e=f") do
  print(key, " = ", value)
end

search_ipairs (url)

Iterate over each parameter in search parameters in URL.

Parameters:

url string url (with search) to parse

Returns:

function iterator function (except on errors nil)
cdata or string state or error message

Raises:

error when url is not a string

Usage:

local ada = require("resty.ada")
for i, param in ada.search_ipairs("https://user:pass@host:1234/?a=b&c=d&e=f") do
  print(i, ". ", param.key, " = ", param.value)
end

Fields

_VERSION

resty.ada version

Usage:

local ada = require("resty.ada")
local ver = ada._VERSION

search

resty.ada.search

Usage:

local ada = require("resty.ada")
local res = ada.search.has("a=b&c=d&e=f", "a")

resty.ada

Contents

Modules

Classes

Module resty.ada

Constructors

Parameters:

Returns:

Raises:

See also:

Usage:

Parameters:

Returns:

Raises:

See also:

Usage:

Convert Functions

Parameters:

Returns:

Raises:

See also:

Usage:

Parameters:

Returns:

Raises:

See also:

Usage:

Validate Functions

Parameters:

Returns:

See also:

Usage:

Parameters:

Returns:

See also:

Usage:

Decode Functions

Returns:

Raises:

Usage:

Has Functions

Parameters:

Returns:

Raises:

See also:

Usage:

Parameters:

Returns:

Raises:

See also:

Usage:

Parameters:

Returns:

Raises:

See also:

Usage:

Parameters:

Returns:

Raises:

See also:

Usage:

Parameters:

Returns:

Raises:

See also:

Usage:

Parameters:

Returns:

Raises:

See also:

Usage:

Parameters:

Returns:

Raises:

See also:

Usage:

Parameters:

Returns:

Raises:

See also:

Module `resty.ada`