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, otherwisefalse
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, otherwisefalse
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, otherwisefalse
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, otherwisefalse
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), otherwisefalse
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, otherwisefalse
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, otherwisefalse
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, otherwisefalse
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, otherwisefalse
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:
Raises:
error when href is not a stringUsage:
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:
Raises:
error when protocol is not a stringUsage:
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:
Raises:
error when username is not a stringUsage:
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:
Raises:
error when password is not a stringUsage:
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:
Raises:
error when host is not a stringUsage:
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:
Raises:
error when hostname is not a stringUsage:
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:
-
url or nil
self (except on errors
nil
) - nil or string error message (e.g. when port is out of acceptable range)
Raises:
error when port is not a number or a stringUsage:
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:
Raises:
error when pathname is not a stringUsage:
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 stringUsage:
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 stringUsage:
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, otherwisefalse
Raises:
error when key is not a stringUsage:
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:
Returns:
-
boolean
true
if search has the key with the value, otherwisefalse
Raises:
error when key or value is not a stringUsage:
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 stringUsage:
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 stringUsage:
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:
Returns:
-
url
self
Raises:
error when key or value is not a stringUsage:
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:
Returns:
-
url
self
Raises:
error when key or value is not a stringUsage:
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 stringUsage:
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:
Returns:
-
url
self
Raises:
error when key or value is not a stringUsage:
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:
- function iterator function
- 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:
- function iterator function
- 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:
- function iterator function
- 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:
- function iterator function
- 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:
- function iterator function
- 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()