Add man pages for the parse/match/binding cowboy_req functions

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

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

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, Req)          -> header(Name, Req, undefined)
-header(Name :: binary(), Req, Default) -> binary() | Default
+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.

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

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

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
+Cowboy will only return the query string values specified
-from the query string, validating and converting them
+in the fields list, and ignore all others. Fields can be
-in one call. In addition, the keys are converted to
+either the key requested; the key along with a list of
-atoms, making manipulation that much simpler.
+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
 

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

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