resty.ada

• Index

Contents

• Constructors
• Has Functions
• Get Functions
• Set Functions
• Encode and Decode Functions
• Remove Functions
• Iterate Functions
• Other Functions

Modules

• resty.ada
• resty.ada.search

Classes

• url
• search

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 string

Usage:

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:

• search string search to parse
• key string search parameter name to check

Returns:

boolean true if search has the key, otherwise false

Raises:

error when search or key is not a string

Usage:

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, otherwise false

Raises:

error when search, key or value is not a string

Usage:

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:

• search string search to parse
• key string search parameter name

Returns:

string or nil parameter value or nil

Raises:

error when search or key is not a string

Usage:

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:

• search string search to parse
• key string search parameter name

Returns:

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

Raises:

error when search or key is not a string

Usage:

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:

• search string search to parse
• key string search parameter name
• value string search parameter value

Returns:

string string presentation of the search parameters

Raises:

error when search, key or value is not a string

Usage:

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:

• search string search to parse
• key string search parameter name
• value string search parameter value

Returns:

string string presentation of the search parameters

Raises:

error when search, key or value is not a string

Usage:

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 and number values are allowed or an array of them
• false value is treated as missing (same as nil)
• true returns "" (empty string)
• negative and positive inf and NaN 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:

• params table or string search parameters to encode (either a table or string)

Returns:

string encoded query string

Raises:

error when search or key is not a table or string, or when the rules above are not followed

Usage:

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 string

Usage:

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 string

Usage:

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:

• search string search to parse
• key string search parameter name

Returns:

string string presentation of the search parameters

Raises:

error when search or key is not a string

Usage:

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 string

Usage:

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:

1. function iterator function
2. cdata state

Raises:

error when search is not a string

Usage:

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:

1. function iterator function
2. cdata state

Raises:

error when search is not a string

Usage:

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:

1. function iterator function
2. cdata state

Raises:

error when search is not a string

Usage:

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:

1. function iterator function
2. cdata state

Raises:

error when search is not a string

Usage:

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:

1. function iterator function
2. cdata state

Raises:

error when search is not a string

Usage:

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 string

Usage:

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 string

Usage:

local search = require("resty.ada.search")
local result = search.size("a=b&c=d&e=f")