From b2e981ca40c16a8df3f605973c6da2664ce54bb4 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Lo=C3=AFc=20Hoguin?= <essen@ninenines.eu>
Date: Mon, 7 Nov 2016 01:11:56 +0200
Subject: Add man pages for parse_qs, match_qs and parse_header

[ci skip]
---
 doc/src/manual/cowboy_req.match_qs.asciidoc | 78 +++++++++++++++++++++++++++++
 1 file changed, 78 insertions(+)
 create mode 100644 doc/src/manual/cowboy_req.match_qs.asciidoc

(limited to 'doc/src/manual/cowboy_req.match_qs.asciidoc')

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)]
-- 
cgit v1.2.3

