From 7b248e5163fd852d6defe967318da849433dadb1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lo=C3=AFc=20Hoguin?= 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.binding.asciidoc | 67 ++++++++++++++++++ doc/src/manual/cowboy_req.bindings.asciidoc | 46 +++++++++++++ doc/src/manual/cowboy_req.header.asciidoc | 8 ++- doc/src/manual/cowboy_req.host_info.asciidoc | 48 +++++++++++++ doc/src/manual/cowboy_req.match_cookies.asciidoc | 88 ++++++++++++++++++++++++ doc/src/manual/cowboy_req.match_qs.asciidoc | 18 +++-- doc/src/manual/cowboy_req.parse_cookies.asciidoc | 55 +++++++++++++++ doc/src/manual/cowboy_req.path_info.asciidoc | 48 +++++++++++++ 8 files changed, 371 insertions(+), 7 deletions(-) create mode 100644 doc/src/manual/cowboy_req.binding.asciidoc create mode 100644 doc/src/manual/cowboy_req.bindings.asciidoc create mode 100644 doc/src/manual/cowboy_req.host_info.asciidoc create mode 100644 doc/src/manual/cowboy_req.match_cookies.asciidoc create mode 100644 doc/src/manual/cowboy_req.parse_cookies.asciidoc create mode 100644 doc/src/manual/cowboy_req.path_info.asciidoc (limited to 'doc/src/manual') diff --git a/doc/src/manual/cowboy_req.binding.asciidoc b/doc/src/manual/cowboy_req.binding.asciidoc new file mode 100644 index 0000000..4e27f31 --- /dev/null +++ b/doc/src/manual/cowboy_req.binding.asciidoc @@ -0,0 +1,67 @@ += cowboy_req:binding(3) + +== Name + +cowboy_req:binding - Access a value bound from the route + +== Description + +[source,erlang] +---- +binding(Name, Req) -> binding(Name, Req, undefined) +binding(Name, Req, Default) -> any() | Default + +Name :: atom() +Req :: cowboy_req:req() +Default :: any() +---- + +Return the value for the given binding. + +== Arguments + +Name:: + +Desired binding name as an atom. + +Req:: + +The Req object. + +Default:: + +Default value returned when the binding is missing. + +== Return value + +By default the value is a case sensitive binary string, however +constraints may change the type of this value (for example +automatically converting numbers to integer). + +== Changelog + +* *2.0*: Only the value is returned, it is no longer wrapped in a tuple. +* *1.0*: Function introduced. + +== Examples + +.Get the username from the path +[source,erlang] +---- +%% Route is "/users/:user" +Username = cowboy_req:binding(user, Req). +---- + +.Get the branch name, with a default +[source,erlang] +---- +%% Route is "/log[/:branch]" +Branch = cowboy_req:binding(branch, Req, <<"master">>) +---- + +== See also + +link:man:cowboy_req(3)[cowboy_req(3)], +link:man:cowboy_req:bindings(3)[cowboy_req:bindings(3)], +link:man:cowboy_req:host_info(3)[cowboy_req:host_info(3)], +link:man:cowboy_req:path_info(3)[cowboy_req:path_info(3)] diff --git a/doc/src/manual/cowboy_req.bindings.asciidoc b/doc/src/manual/cowboy_req.bindings.asciidoc new file mode 100644 index 0000000..3e89859 --- /dev/null +++ b/doc/src/manual/cowboy_req.bindings.asciidoc @@ -0,0 +1,46 @@ += cowboy_req:bindings(3) + +== Name + +cowboy_req:bindings - Access all values bound from the route + +== Description + +[source,erlang] +---- +bindings(Req :: cowboy_req:req()) -> [{Name :: atom(), any()}] +---- + +Return all bindings as a list of key/value pairs. + +== Arguments + +Req:: + +The Req object. + +== Return value + +By default values are case sensitive binary strings, however +constraints may change the type of this value (for example +automatically converting numbers to integer). + +== Changelog + +* *2.0*: Only the values are returned, it is no longer wrapped in a tuple. +* *1.0*: Function introduced. + +== Examples + +.Get all bindings +[source,erlang] +---- +Bindings = cowboy_req:bindings(Req). +---- + +== See also + +link:man:cowboy_req(3)[cowboy_req(3)], +link:man:cowboy_req:binding(3)[cowboy_req:binding(3)], +link:man:cowboy_req:host_info(3)[cowboy_req:host_info(3)], +link:man:cowboy_req:path_info(3)[cowboy_req:path_info(3)] diff --git a/doc/src/manual/cowboy_req.header.asciidoc b/doc/src/manual/cowboy_req.header.asciidoc index a4d7007..d0d2052 100644 --- a/doc/src/manual/cowboy_req.header.asciidoc +++ b/doc/src/manual/cowboy_req.header.asciidoc @@ -8,10 +8,12 @@ cowboy_req:header - HTTP header [source,erlang] ---- -header(Name :: binary(), Req) -> header(Name, Req, undefined) -header(Name :: binary(), Req, Default) -> binary() | Default +header(Name, Req) -> header(Name, Req, undefined) +header(Name, Req, Default) -> binary() | Default -Req :: cowboy_req:req() +Name :: binary() +Req :: cowboy_req:req() +Default :: any() ---- Return the value for the given HTTP header. diff --git a/doc/src/manual/cowboy_req.host_info.asciidoc b/doc/src/manual/cowboy_req.host_info.asciidoc new file mode 100644 index 0000000..77a4c11 --- /dev/null +++ b/doc/src/manual/cowboy_req.host_info.asciidoc @@ -0,0 +1,48 @@ += cowboy_req:host_info(3) + +== Name + +cowboy_req:host_info - Access the route's heading host segments + +== Description + +[source,erlang] +---- +host_info(Req :: cowboy_req:req()) -> cowboy_router:tokens() +---- + +Return the tokens for the heading host segments. + +This is the part of the host name that was matched using +the `...` notation. + +== Arguments + +Req:: + +The Req object. + +== Return value + +The tokens are returned as a list of case insensitive +binary strings. + +== Changelog + +* *2.0*: Only the tokens are returned, they are no longer wrapped in a tuple. +* *1.0*: Function introduced. + +== Examples + +.Get the host_info tokens +[source,erlang] +---- +HostInfo = cowboy_req:host_info(Req). +---- + +== See also + +link:man:cowboy_req(3)[cowboy_req(3)], +link:man:cowboy_req:binding(3)[cowboy_req:binding(3)], +link:man:cowboy_req:bindings(3)[cowboy_req:bindings(3)], +link:man:cowboy_req:path_info(3)[cowboy_req:path_info(3)] 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)] diff --git a/doc/src/manual/cowboy_req.match_qs.asciidoc b/doc/src/manual/cowboy_req.match_qs.asciidoc index e66d311..845d09a 100644 --- a/doc/src/manual/cowboy_req.match_qs.asciidoc +++ b/doc/src/manual/cowboy_req.match_qs.asciidoc @@ -15,10 +15,20 @@ match_qs(Fields :: cowboy:fields(), Req :: cowboy_req:req()) 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. +Cowboy will only return the query string values specified +in the fields list, and ignore all others. Fields can be +either the key requested; the key along with a list of +constraints; or the key, a list of constraints and a +default value in case the key is missing. + +This function will crash if the key is missing and no +default value is provided. This function will also crash +if a constraint fails. + +The key 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 diff --git a/doc/src/manual/cowboy_req.parse_cookies.asciidoc b/doc/src/manual/cowboy_req.parse_cookies.asciidoc new file mode 100644 index 0000000..c174da4 --- /dev/null +++ b/doc/src/manual/cowboy_req.parse_cookies.asciidoc @@ -0,0 +1,55 @@ += cowboy_req:parse_cookies(3) + +== Name + +cowboy_req:parse_cookies - Parse cookie headers + +== Description + +[source,erlang] +---- +parse_cookies(Req) -> [{Name, Value}] + +Name :: binary() %% case sensitive +Value :: binary() %% case sensitive +---- + +Parse cookie headers. + +Alias for link:man:cowboy_req:parse_header(3)[cowboy_req:parse_header(<<"cookie">>, Req)]. + +When the cookie header is missing, `[]` is returned. + +While an empty cookie header is not valid, some clients do +send it. Cowboy will in this case also return `[]`. + +== Arguments + +Req:: + +The Req object. + +== Return value + +The cookies are returned as a list of key/values. Keys and +values are case sensitive binary strings. + +== Changelog + +* *2.0*: Only the parsed header value is returned, it is no longer wrapped in a tuple. +* *2.0*: Function introduced. Replaces `cookie/2,3` and `cookies/1`. + +== Examples + +.Look for a specific cookie +[source,erlang] +---- +Cookies = cowboy_req:parse_cookies(Req), +{_, Token} = lists:keyfind(token, 1, Cookies). +---- + +== See also + +link:man:cowboy_req(3)[cowboy_req(3)], +link:man:cowboy_req:parse_header(3)[cowboy_req:parse_header(3)], +link:man:cowboy_req:match_cookies(3)[cowboy_req:match_cookies(3)] diff --git a/doc/src/manual/cowboy_req.path_info.asciidoc b/doc/src/manual/cowboy_req.path_info.asciidoc new file mode 100644 index 0000000..d114640 --- /dev/null +++ b/doc/src/manual/cowboy_req.path_info.asciidoc @@ -0,0 +1,48 @@ += cowboy_req:path_info(3) + +== Name + +cowboy_req:path_info - Access the route's trailing path segments + +== Description + +[source,erlang] +---- +path_info(Req :: cowboy_req:req()) -> cowboy_router:tokens() +---- + +Return the tokens for the trailing path segments. + +This is the part of the host name that was matched using +the `...` notation. + +== Arguments + +Req:: + +The Req object. + +== Return value + +The tokens are returned as a list of case sensitive +binary strings. + +== Changelog + +* *2.0*: Only the tokens are returned, they are no longer wrapped in a tuple. +* *1.0*: Function introduced. + +== Examples + +.Get the path_info tokens +[source,erlang] +---- +PathInfo = cowboy_req:path_info(Req). +---- + +== See also + +link:man:cowboy_req(3)[cowboy_req(3)], +link:man:cowboy_req:binding(3)[cowboy_req:binding(3)], +link:man:cowboy_req:bindings(3)[cowboy_req:bindings(3)], +link:man:cowboy_req:host_info(3)[cowboy_req:host_info(3)] -- cgit v1.2.3