mirror of
https://github.com/ninenines/cowboy.git
synced 2025-07-15 20:50:24 +00:00
89 lines
2 KiB
Text
89 lines
2 KiB
Text
|
= 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)]
|