cowboy/doc/src/manual/cowboy_req.match_cookies.asciidoc

= 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)]