1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
|
= cowboy_req:match_qs(3)
== Name
cowboy_req:match_qs - Match the query string against constraints
== Description
[source,erlang]
----
match_qs(Fields :: cowboy:fields(), Req :: cowboy_req:req())
-> #{atom() => any()}
----
Parse the query string and match specific values against
constraints.
This function allows easily retrieving expected values
from the query string, validating and converting them
in one call. In addition, the keys are converted to
atoms, making manipulation that much simpler.
== Arguments
Fields::
Fields to retrieve from the query string.
+
See link:man:cowboy(3)[cowboy(3)] for a complete description.
Req::
The Req object.
== Return value
Desired values are returned as a map. The key is the atom
that was given in the list of fields, and the value is the
optionally converted value after applying constraints.
The map contains the same keys that were given in the fields.
An exception is triggered when the match fails.
== Changelog
* *2.0*: Function introduced.
== Examples
.Match fields
[source,erlang]
----
%% ID and Lang are binaries.
#{id := ID, lang := Lang}
= cowboy_req:match_qs([id, lang], Req).
----
.Match fields and apply constraints
[source,erlang]
----
%% ID is an integer and Lang a non-empty binary.
#{id := ID, lang := Lang}
= cowboy_req:match_qs([{id, int}, {lang, nonempty}], Req).
----
.Match fields with default values
[source,erlang]
----
#{lang := Lang}
= cowboy_req:match_qs([{lang, [], <<"en-US">>}], Req).
----
== See also
link:man:cowboy_req(3)[cowboy_req(3)],
link:man:cowboy_req:qs(3)[cowboy_req:qs(3)],
link:man:cowboy_req:parse_qs(3)[cowboy_req:parse_qs(3)]
|
