From 7b248e5163fd852d6defe967318da849433dadb1 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Lo=C3=AFc=20Hoguin?= <essen@ninenines.eu>
Date: Mon, 7 Nov 2016 18:03:47 +0200
Subject: Add man pages for the parse/match/binding cowboy_req functions

---
 doc/src/manual/cowboy_req.match_cookies.asciidoc | 88 ++++++++++++++++++++++++
 1 file changed, 88 insertions(+)
 create mode 100644 doc/src/manual/cowboy_req.match_cookies.asciidoc

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

diff --git a/doc/src/manual/cowboy_req.match_cookies.asciidoc b/doc/src/manual/cowboy_req.match_cookies.asciidoc
new file mode 100644
index 0000000..14f88d2
--- /dev/null
+++ b/doc/src/manual/cowboy_req.match_cookies.asciidoc
@@ -0,0 +1,88 @@
+= cowboy_req:match_cookies(3)
+
+== Name
+
+cowboy_req:match_cookies - Match cookies against constraints
+
+== Description
+
+[source,erlang]
+----
+match_cookies(Fields :: cowboy:fields(), Req :: cowboy_req:req())
+    -> #{atom() => any()}
+----
+
+Parse the cookies and match specific values against
+constraints.
+
+Cowboy will only return the cookie values specified in the
+fields list, and ignore all others. Fields can be either
+the name of the cookie requested; the name along with a
+list of constraints; or the name, a list of constraints
+and a default value in case the cookie is missing.
+
+This function will crash if the cookie is missing and no
+default value is provided. This function will also crash
+if a constraint fails.
+
+The name of the cookie must be provided as an atom. The
+key of the returned map will be that atom. The value may
+be converted through the use of constraints, making this
+function able to extract, validate and convert values all
+in one step.
+
+== Arguments
+
+Fields::
+
+Cookies to retrieve.
++
+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_cookies([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_cookies([{id, int}, {lang, nonempty}], Req).
+----
+
+.Match fields with default values
+[source,erlang]
+----
+#{lang := Lang}
+    = cowboy_req:match_cookies([{lang, [], <<"en-US">>}], Req).
+----
+
+== See also
+
+link:man:cowboy_req(3)[cowboy_req(3)],
+link:man:cowboy_req:parse_cookies(3)[cowboy_req:parse_cookies(3)]
-- 
cgit v1.2.3