Module resty.ada.search
Provides URL search parameter parsing and manipulation functionality.
See: https://url.spec.whatwg.org/#interface-urlsearchparams
Constructors
parse (search) | Parses search and returns an instance of Ada URL Search. |
Has Functions
has (search, key) | Checks whether the search has a key. |
has_value (search, key, value) | Checks whether the search has a key with a specific value. |
Get Functions
get (search, key) | Get search parameter’s value. |
get_all (search, key) | Get all the search parameter’s values. |
Set Functions
set (search, key, value) | Set the search parameter’s value. |
append (search, key, value) | Append value to the the search parameter. |
Encode and Decode Functions
encode (params) | Encodes search parameters and returns an query string. |
decode (search) | Decodes search parameters and returns a Lua table of them. |
decode_all (search) | Decodes all search parameters and returns a Lua table of them. |
Remove Functions
remove (search, key) | Remove search parameter. |
remove_value (search, key, value) | Remove search parameter’s value. |
Iterate Functions
each (search) | Iterate over search parameters. |
each_key (search) | Iterate over each key in search parameters. |
each_value (search) | Iterate over each value in search parameters. |
pairs (search) | Iterate over each key and value in search parameters. |
ipairs (search) | Iterate over each parameter in search parameters. |
Other Functions
sort (search) | Sort search parameters. |
size (search) | Count search parameters. |
Constructors
- parse (search)
-
Parses search and returns an instance of Ada URL Search.
See: https://url.spec.whatwg.org/#interface-urlsearchparams
Parameters:
- search string search to parse
Returns:
-
search
Ada URL Search instance
Raises:
error when search is not a stringUsage:
local search = require("resty.ada.search").parse("a=b&c=d&e=f")
Has Functions
- has (search, key)
-
Checks whether the search has a key.
See: https://url.spec.whatwg.org/#dom-urlsearchparams-has
Parameters:
Returns:
-
boolean
true
if search has the key, otherwisefalse
Raises:
error when search or key is not a stringUsage:
local search = require("resty.ada.search") local result = search.has("a=b&c=d&e=f", "a")
- has_value (search, key, value)
-
Checks whether the search has a key with a specific value.
See: https://url.spec.whatwg.org/#dom-urlsearchparams-has
Parameters:
- search string 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, otherwisefalse
Raises:
error when search, key or value is not a stringUsage:
local search = require("resty.ada.search") local result = search.has_value("a=b&c=d&e=f", "a", "b")
Get Functions
- get (search, key)
-
Get search parameter’s value.
See: https://url.spec.whatwg.org/#dom-urlsearchparams-get
Parameters:
Returns:
-
string or nil
parameter value or
nil
Raises:
error when search or key is not a stringUsage:
local search = require("resty.ada.search") local result = search.get("a=b&c=d&e=f", "a")
- get_all (search, key)
-
Get all the search parameter’s values.
See: https://url.spec.whatwg.org/#dom-urlsearchparams-getall
Parameters:
Returns:
-
table
array of all the values (or an empty array)
Raises:
error when search or key is not a stringUsage:
local search = require("resty.ada.search") local result = search.get_all("a=b&c=d&e=f", "a")
Set Functions
- set (search, key, value)
-
Set the search parameter’s value.
See: https://url.spec.whatwg.org/#dom-urlsearchparams-set
Parameters:
Returns:
-
string
string presentation of the search parameters
Raises:
error when search, key or value is not a stringUsage:
local search = require("resty.ada.search") local result = search.set("a=b&c=d&e=f", "a", "g")
- append (search, key, value)
-
Append value to the the search parameter.
See: https://url.spec.whatwg.org/#dom-urlsearchparams-append
Parameters:
Returns:
-
string
string presentation of the search parameters
Raises:
error when search, key or value is not a stringUsage:
local search = require("resty.ada.search") local result = search.append("a=b&c=d&e=f", "a", "g")
Encode and Decode Functions
- encode (params)
-
Encodes search parameters and returns an query string.
- only string keys are allowed.
- only string,
boolean
andnumber
values are allowed or an array of them false
value is treated as missing (same asnil
)true
returns""
(empty string)- negative and positive
inf
andNaN
are not allowed as numbers in values
When passing a table the keys will be sorted and with string the given order is preserved.
Parameters:
Returns:
-
string
encoded query string
Raises:
error when search or key is not a table or string, or when the rules above are not followedUsage:
local search = require("resty.ada.search") local result = search.encode({ g = "h", a = { "f", "b", }, c = "d", })
- decode (search)
-
Decodes search parameters and returns a Lua table of them.
If same parameter appears multiple times, only the value of the first is returned.
Given the following query string: “a=b&c=d&e=f&a=g”
The following table is returned: { a = “b”, c = “d”, e = “f”, }
Parameters:
- search string search to parse
Returns:
-
table
a table of all search parameters (a string:string map).
Raises:
error when search or key is not a stringUsage:
local search = require("resty.ada.search") local result = search.decode("a=b&c=d&e=f&a=g")
- decode_all (search)
-
Decodes all search parameters and returns a Lua table of them.
Given the following query string: “a=b&a=c&d=e”"
The following table is returned: { a = { “b”, “c” }, d = { “e” }, }
Parameters:
- search string search to parse
Returns:
-
table
a table of all search parameters (a string:table [array] map).
Raises:
error when search or key is not a stringUsage:
local search = require("resty.ada.search") local result = search.decode_all("a=b&a=c&d=e")
Remove Functions
- remove (search, key)
-
Remove search parameter.
See: https://url.spec.whatwg.org/#dom-urlsearchparams-delete
Parameters:
Returns:
-
string
string presentation of the search parameters
Raises:
error when search or key is not a stringUsage:
local search = require("resty.ada.search") local result = search.remove("a=b&c=d&e=f", "a")
- remove_value (search, key, value)
-
Remove search parameter’s value.
See: https://url.spec.whatwg.org/#dom-urlsearchparams-delete
Parameters:
- search string search to parse
- key string search parameter name
- value string search parameter’s value
Returns:
-
string
string presentation of the search parameters
Raises:
error when search, key or value is not a stringUsage:
local search = require("resty.ada.search") local result = search.remove_value("a=b&c=d&e=f", "a", "b")
Iterate Functions
- each (search)
-
Iterate over search parameters.
Parameters:
- search string search to parse
Returns:
- function iterator function
- cdata state
Raises:
error when search is not a stringUsage:
local search = require("resty.ada.search") for param in search.each("a=b&c=d&e=f") do print(param.key, " = ", param.value) end
- each_key (search)
-
Iterate over each key in search parameters.
Parameters:
- search string search to parse
Returns:
- function iterator function
- cdata state
Raises:
error when search is not a stringUsage:
local search = require("resty.ada.search") for key in search.each_key("a=b&c=d&e=f") do print("key: ", key) end
- each_value (search)
-
Iterate over each value in search parameters.
Parameters:
- search string search to parse
Returns:
- function iterator function
- cdata state
Raises:
error when search is not a stringUsage:
local search = require("resty.ada.search") for value in search.each_value("a=b&c=d&e=f") do print("value: ", value) end
- pairs (search)
-
Iterate over each key and value in search parameters.
Parameters:
- search string search to parse
Returns:
- function iterator function
- cdata state
Raises:
error when search is not a stringUsage:
local search = require("resty.ada.search") for key, value in search.pairs("a=b&c=d&e=f") do print(key, " = ", value) end
- ipairs (search)
-
Iterate over each parameter in search parameters.
Parameters:
- search string search to parse
Returns:
- function iterator function
- cdata state
Raises:
error when search is not a stringUsage:
for i, param in search.ipairs("a=b&c=d&e=f") do print(i, ". ", param.key, " = ", param.value) end
Other Functions
- sort (search)
-
Sort search parameters.
See: https://url.spec.whatwg.org/#dom-urlsearchparams-sort
Parameters:
- search string search to parse
Returns:
-
string
string presentation of the search parameters
Raises:
error when search is not a stringUsage:
local search = require("resty.ada.search") local result = search.sort("e=f&c=d&a=b")
- size (search)
-
Count search parameters.
Parameters:
- search string search to parse
Returns:
-
number
search parameters count
Raises:
error when search is not a stringUsage:
local search = require("resty.ada.search") local result = search.size("a=b&c=d&e=f")