aboutsummaryrefslogtreecommitdiffstats
path: root/doc/src/manual/cowboy_req.match_qs.asciidoc
diff options
context:
space:
mode:
Diffstat (limited to 'doc/src/manual/cowboy_req.match_qs.asciidoc')
-rw-r--r--doc/src/manual/cowboy_req.match_qs.asciidoc78
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)]