diff options
Diffstat (limited to 'doc/src/manual/cowboy_req.match_qs.asciidoc')
-rw-r--r-- | doc/src/manual/cowboy_req.match_qs.asciidoc | 78 |
1 files changed, 78 insertions, 0 deletions
diff --git a/doc/src/manual/cowboy_req.match_qs.asciidoc b/doc/src/manual/cowboy_req.match_qs.asciidoc new file mode 100644 index 0000000..e66d311 --- /dev/null +++ b/doc/src/manual/cowboy_req.match_qs.asciidoc @@ -0,0 +1,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)] |