cowboy_req:match_cookies(3)

Name

cowboy_req:match_cookies - Match cookies against constraints

Description

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.

This function will crash on invalid cookie data. How to handle this is explained in details in the manual page for cowboy_req:parse_cookies(3).

Arguments

Fields

Cookies to retrieve.

See 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

%% ID and Lang are binaries.
#{id := ID, lang := Lang}
    = cowboy_req:match_cookies([id, lang], Req).

%% ID is an integer and Lang a non-empty binary.
#{id := ID, lang := Lang}
    = cowboy_req:match_cookies([{id, int}, {lang, nonempty}], Req).

#{lang := Lang}
    = cowboy_req:match_cookies([{lang, [], <<"en-US">>}], Req).

See also

cowboy_req(3), cowboy_req:filter_cookies(3), cowboy_req:parse_cookies(3)