Class url

Ada URL

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

Decode Methods

url:decode () Decodes URL and return its components in Lua table.

Has Methods

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

Get Methods

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

Set Methods

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

Clear Methods

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

Search Methods

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

Other Methods

url:tostring () Get URL in a normalized form.

Meta Methods

url:__tostring () Return search parameters as a string.
url:__len () Get length of the URL.

Destructor Method

url:free () Explicitly destroys the Ada URL instance and frees the memory.

Properties

url._VERSION


Decode Methods

url: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 following table: { scheme_type = 2, protocol = “https:”, username = “user”, password = “pass”, origin = “https://example.com:1234”, host_type = 0, host = “example.com:1234”, hostname = “example.com”, port = 1234, pathname = “/foo/bar”, search = “?baz”, hash = “#quux”, }

Returns:

    table table of URL components

Usage:

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

Has Methods

url:has_credentials ()
Checks whether the URL has credentials.

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

Returns:

    boolean true if URL has credentials, otherwise false

Usage:

    local url = require("resty.ada").parse("https://user:pass@host:1234/path?search#hash")
local res = url:has_credentials()
url:has_non_empty_username ()
Checks whether the URL has a non-empty username.

Returns:

    boolean true if URL has a non-empty username, otherwise false

Usage:

    local url = require("resty.ada").parse("https://user:pass@host:1234/path?search#hash")
local res = url:has_non_empty_username()
url:has_password ()
Checks whether the URL has a password.

Returns:

    boolean true if URL has a password, otherwise false

Usage:

    local url = require("resty.ada").parse("https://user:pass@host:1234/path?search#hash")
local res = url:has_password()
url:has_non_empty_password ()
Checks whether the URL has a non-empty password.

Returns:

    boolean true if URL has a non-empty password, otherwise false

Usage:

    local url = require("resty.ada").parse("https://user:pass@host:1234/path?search#hash")
local res = url:has_non_empty_password()
url:has_hostname ()
Checks whether the URL has a hostname (included an empty host).

Returns:

    boolean true if URL has a hostname (included an empty host), otherwise false

Usage:

    local url = require("resty.ada").parse("https://user:pass@host:1234/path?search#hash")
local res = url:has_hostname()
url:has_empty_hostname ()
Checks whether the URL has an host but it is the empty string.

Returns:

    boolean true if URL has an empty hostname, otherwise false

Usage:

    local url = require("resty.ada").parse("https://user:pass@host:1234/path?search#hash")
local res = url:has_empty_hostname()
url:has_port ()
Checks whether the URL has a (non default) port.

Returns:

    boolean true if URL has a (non default) port, otherwise false

Usage:

    local url = require("resty.ada").parse("https://user:pass@host:1234/path?search#hash")
local res = url:has_port()
url:has_search ()
Checks whether the URL has a search component.

Returns:

    boolean true if URL has a search, otherwise false

Usage:

    local url = require("resty.ada").parse("https://user:pass@host:1234/path?search#hash")
local res = url:has_search()
url:has_hash ()
Checks whether the URL has a hash component.

Returns:

    boolean true if URL has a hash, otherwise false

Usage:

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

Get Methods

url:get_components ()

Get URL component positions in a string (Lua 1-based indexing).

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,
}

Returns:

    table table of URL components (or their positions)

Usage:

    local url = require("resty.ada").parse("https://user:pass@host:1234/path?search#hash")
local res = url:get_components()
url:get_href ()
Get URL in a normalized form.

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

Returns:

    string URL in a normalized form

Usage:

    local url = require("resty.ada").parse("https://user:pass@host:1234/path?search#hash")
local res = url:get_href()
url:get_protocol ()
Get protocol from the URL.

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

Returns:

    string protocol part of the URL

Usage:

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

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

Returns:

    number scheme type of the URL

Usage:

    local url = require("resty.ada").parse("https://user:pass@host:1234/path?search#hash")
local res = url:get_scheme_type()
url:get_origin ()
Get origin of the URL.

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

Returns:

    string origin of the URL

Usage:

    local url = require("resty.ada").parse("https://user:pass@host:1234/path?search#hash")
local res = url:get_origin()
url:get_username ()
Get URL’s username.

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

Returns:

    string URL’s username

Usage:

    local url = require("resty.ada").parse("https://user:pass@host:1234/path?search#hash")
local res = url:get_username()
url:get_password ()
Get URL’s password.

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

Returns:

    string URL’s password

Usage:

    local url = require("resty.ada").parse("https://user:pass@host:1234/path?search#hash")
local res = url:get_password()
url:get_host ()
Get URL’s host, serialized, followed by U+003A (:) and url’s port, serialized.

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

Returns:

    string URL’s host

Usage:

    local url = require("resty.ada").parse("https://user:pass@host:1234/path?search#hash")
local res = url:get_host()
url:get_hostname ()
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

Returns:

    string URL’s host (name only)

Usage:

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

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

Returns:

    number scheme type of the URL

Usage:

    local url = require("resty.ada").parse("https://user:pass@host:1234/path?search#hash")
local res = url:get_host_type()
url:get_port ()
Get URL’s port.

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

Returns:

    number or string URL’s port

Usage:

    local url = require("resty.ada").parse("https://user:pass@host:1234/path?search#hash")
local res = url:get_port()
url:get_pathname ()
Get URL’s path.

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

Returns:

    string URL’s path

Usage:

    local url = require("resty.ada").parse("https://user:pass@host:1234/path?search#hash")
local res = url:get_pathname()
url:get_search ()
Get URL’s search (query).

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

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

Returns:

    string URL’s query

Usage:

    local url = require("resty.ada").parse("https://user:pass@host:1234/path?search#hash")
local res = url:get_search()
url:get_hash ()
Get URL’s hash (fragment).

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

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

Returns:

    string URL’s fragment (except on errors nil)

Usage:

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

Set Methods

url:set_href (href)
Sets HREF (aka url) to the URL.

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

Parameters:

  • href string the HREF to set to the URL

Returns:

  1. url or nil self (except on errors nil)
  2. nil or string error message

Raises:

error when href is not a string

Usage:

    local url = require("resty.ada").parse("https://user:pass@host:1234/path?search#hash")
local res = url:set_protocol("wss"):get_href()
url:set_protocol (protocol)
Sets protocol to the URL.

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

Parameters:

  • protocol string the protocol to set to the URL

Returns:

  1. url or nil self (except on errors nil)
  2. nil or string error message

Raises:

error when protocol is not a string

Usage:

    local url = require("resty.ada").parse("https://user:pass@host:1234/path?search#hash")
local res = url:set_protocol("wss"):get_href()
url:set_username (username)
Sets username to the URL.

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

Parameters:

  • username string the username to set to the URL

Returns:

  1. url or nil self (except on errors nil)
  2. nil or string error message

Raises:

error when username is not a string

Usage:

    local url = require("resty.ada").parse("https://user:pass@host:1234/path?search#hash")
local res = url:set_username("guest"):get_href()
url:set_password (password)
Sets password to the URL.

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

Parameters:

  • password string the password to set to the URL

Returns:

  1. url or nil self (except on errors nil)
  2. nil or string error message

Raises:

error when password is not a string

Usage:

    local url = require("resty.ada").parse("https://user:pass@host:1234/path?search#hash")
local res = url:ada_set_password("secret"):get_href()
url:set_host (host)
Sets host to the URL.

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

Parameters:

  • host string the host to set to the URL

Returns:

  1. url or nil self (except on errors nil)
  2. nil or string error message

Raises:

error when host is not a string

Usage:

    local url = require("resty.ada").parse("https://user:pass@host:1234/path?search#hash")
local res = url:set_host("test:4321"):get_href()
url:set_hostname (hostname)
Sets host (name only) to the URL.

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

Parameters:

  • hostname string the host (name only) to set to the URL

Returns:

  1. url or nil self (except on errors nil)
  2. nil or string error message

Raises:

error when hostname is not a string

Usage:

    local url = require("resty.ada").parse("https://user:pass@host:1234/path?search#hash")
local res = url:set_hostname("test"):get_href()
url:set_port (port)
Sets port to the URL.

Note: inf, -inf and NaN are considered invalid and they raise an error.

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

Parameters:

  • port number or string the port to set to the URL

Returns:

  1. url or nil self (except on errors nil)
  2. nil or string error message (e.g. when port is out of acceptable range)

Raises:

error when port is not a number or a string

Usage:

    local url = require("resty.ada").parse("https://user:pass@host:1234/path?search#hash")
local res = url:set_port(4321):get_href()
url:set_pathname (path)
Sets path to the URL.

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

Parameters:

  • path string the path to set to the URL

Returns:

  1. url or nil self (except on errors nil)
  2. nil or string error message

Raises:

error when pathname is not a string

Usage:

    local url = require("resty.ada").parse("https://user:pass@host:1234/path?search#hash")
local res = url:set_pathname("foo"):get_href()
url:set_search (query)
Sets search (query) to the URL.

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

Parameters:

  • query string the query string to set to the URL

Returns:

    url self

Raises:

error when query is not a string

Usage:

    local url = require("resty.ada").parse("https://user:pass@host:1234/path?search#hash")
local res = url:set_search("q=1&done"):get_href()
url:set_hash (hash)
Sets hash (fragment) to the URL.

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

Parameters:

  • hash string the fragment to set to the URL

Returns:

    url self

Raises:

error when hash is not a string

Usage:

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

Clear Methods

url:clear_port ()
Clear URL’s port.

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

Returns:

    url self

Usage:

    local url = require("resty.ada").parse("https://user:pass@host:1234/path?search#hash")
local res = url:clear_port():get_href()
url:clear_search ()
Clear URL’s search (query string).

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

Returns:

    url self

Usage:

    local url = require("resty.ada").parse("https://user:pass@host:1234/path?search#hash")
local res = url:clear_search():get_href()
url:clear_hash ()
Clear URL’s hash (fragment).

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

Returns:

    url self

Usage:

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

Search Methods

url:search_parse ()
Parses search from URL and returns an instance of Ada URL Search.

Returns:

    search Ada URL Search instance

Usage:

    local url = require("resty.ada").parse("https://user:pass@host:1234/?a=b&c=d&e=f")
local search = url:search_parse()
url:search_decode ()
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.

An example return value: { key1 = “value”, key2 = “value2”, }

Returns:

    table a table of all search parameters (a string:string map).

Usage:

    local url = require("resty.ada").parse("http://host/?a=b&c=d&e=f&a=g")
local result = url:search_decode()
url:search_decode_all (url)
Decodes all search parameters from URL and returns a Lua table of them.

An example return value: { key1 = { “first”, “second”, }, key2 = { “value” }, }

Parameters:

  • url string url (with search) to parse

Returns:

    table a table of all search parameters (a string:table [array] map).

Usage:

    local url = require("resty.ada").parse("http://host/?a=b&a=c&d=e")
local result = url:search_decode_all()
url:search_has (key)
Checks whether the url has a search with a key.

Parameters:

  • key string search parameter name to check

Returns:

    boolean true if search has the key, otherwise false

Raises:

error when key is not a string

Usage:

    local url = require("resty.ada").parse("https://user:pass@host:1234/?a=b&c=d&e=f")
local res = url:search_has("a")
url:search_has_value (key, value)
Checks whether the url has a search with a key with a specific value.

Parameters:

  • 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

Raises:

error when key or value is not a string

Usage:

    local url = require("resty.ada").parse("https://user:pass@host:1234/?a=b&c=d&e=f")
local res = url:search_has_value("a", "b")
url:search_get (key)
Get URL’s search parameter’s value.

Parameters:

  • key string search parameter name

Returns:

    string or nil parameter value or nil

Raises:

error when key is not a string

Usage:

    local url = require("resty.ada").parse("https://user:pass@host:1234/?a=b&c=d&e=f")
local res = url:search_get("a")
url:search_get_all (key)
Get all the URL’s search parameter’s values.

Parameters:

  • key string search parameter name

Returns:

    table array of all the values (or an empty array)

Raises:

error when key is not a string

Usage:

    local url = require("resty.ada").parse("https://user:pass@host:1234/?a=b&c=d&e=f")
local res = url:search_get_all("a")
url:search_set (key, value)
Set the URL’s search parameter’s value.

Parameters:

  • key string search parameter name
  • value string search parameter value

Returns:

    url self

Raises:

error when key or value is not a string

Usage:

    local url = require("resty.ada").parse("https://user:pass@host:1234/?a=b&c=d&e=f")
local res = url:search_set("a", "g"):get_href()
url:search_append (key, value)
Append value to the the URL’s search parameter.

Parameters:

  • key string search parameter name
  • value string search parameter value

Returns:

    url self

Raises:

error when key or value is not a string

Usage:

    local url = require("resty.ada").parse("https://user:pass@host:1234/?a=b&c=d&e=f")
local res = url:search_append("a", "g"):get_href()
url:search_remove (key)
Remove search parameter from URL.

Parameters:

  • key string search parameter name

Returns:

    url self

Raises:

error when key is not a string

Usage:

    local url = require("resty.ada").parse("https://user:pass@host:1234/?a=b&c=d&e=f")
local res = url:search_remove("a"):get_href()
url:search_remove_value (key, value)
Remove search parameter’s value from URL.

Parameters:

  • key string search parameter name
  • value string search parameter’s value

Returns:

    url self

Raises:

error when key or value is not a string

Usage:

    local url = require("resty.ada").parse("https://user:pass@host:1234/?a=b&c=d&e=f")
local res = url:search_remove_value("a", "b"):get_href()
url:search_sort ()
Sort the URL’s search parameters.

Returns:

    url self

Usage:

    local url = require("resty.ada").parse("https://user:pass@host:1234/?e=f&c=d&a=b")
local res = url:search_sort():get_href()
url:search_size ()
Count search parameters in URL.

Returns:

    number search parameters count

Usage:

    local url = require("resty.ada").parse("https://user:pass@host:1234/?a=b&c=d&e=f")
local res = url:search_size()
url:search_each ()
Iterate over search parameters in URL.

Returns:

  1. function iterator function
  2. cdata state

Usage:

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

Returns:

  1. function iterator function
  2. cdata state

Usage:

    local url = require("resty.ada").parse("https://user:pass@host:1234/?a=b&c=d&e=f")
for key in url:search_each_key() do
  print("key: ", key)
end
url:search_each_value ()
Iterate over each value in search parameters in URL.

Returns:

  1. function iterator function
  2. cdata state

Usage:

    local url = require("resty.ada").parse("https://user:pass@host:1234/?a=b&c=d&e=f")
for value in url:search_each_value() do
  print("value: ", value)
end
url:search_pairs ()
Iterate over each key and value in search parameters in URL.

Returns:

  1. function iterator function
  2. cdata state

Usage:

    local url = require("resty.ada").parse("https://user:pass@host:1234/?a=b&c=d&e=f")
for key, value  in url:search_pairs() do
  print(key, " = ", value)
end
url:search_pairs ()
Iterate over each parameter in search parameters in URL.

Returns:

  1. function iterator function
  2. cdata state

Usage:

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

Other Methods

url:tostring ()
Get URL in a normalized form.

Returns:

    string URL in a normalized form

Usage:

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

Meta Methods

url:__tostring ()
Return search parameters as a string.

See: https://url.spec.whatwg.org/#urlsearchparams-stringification-behavior

Returns:

    string string presentation of the search parameters

Usage:

    local search = require("resty.ada.search").parse("a=b&c=d&e=f")
local result = tostring(search)
url:__len ()
Get length of the URL.

Returns:

    number length of the URL

Usage:

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

Destructor Method

url:free ()
Explicitly destroys the Ada URL instance and frees the memory.

After calling this function, further calls will result runtime error. If this is not explicitly called, the memory is freed with garbage collector.

Usage:

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

Properties

url._VERSION
  • _VERSION resty.ada version
generated by LDoc 1.5.0 Last updated 2024-09-03 15:49:45