Add man pages for parse_qs, match_qs and parse_header

[ci skip]

4 files changed, 366 insertions, 1 deletions

diff --git a/doc/src/manual/cowboy_req.header.asciidoc b/doc/src/manual/cowboy_req.header.asciidoc
index e16b902..a4d7007 100644
--- a/doc/src/manual/cowboy_req.header.asciidoc
+++ b/doc/src/manual/cowboy_req.header.asciidoc
@@ -33,7 +33,7 @@ Note that this snippet will crash if the header is missing.
 
 Name::
 
-Desired HTTP header name as a binary string.
+Desired HTTP header name as a lowercase binary string.
 
 Req::
 
diff --git a/doc/src/manual/cowboy_req.match_qs.asciidoc b/doc/src/manual/cowboy_req.match_qs.asciidoc
new file mode 100644
index 0000000..e66d311
--- /dev/null
+++ b/doc/src/manual/cowboy_req.match_qs.asciidoc
@@ -0,0 +1,78 @@
+= cowboy_req:match_qs(3)
+
+== Name
+
+cowboy_req:match_qs - Match the query string against constraints
+
+== Description
+
+[source,erlang]
+----
+match_qs(Fields :: cowboy:fields(), Req :: cowboy_req:req())
+    -> #{atom() => any()}
+----
+
+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.
+
+== Arguments
+
+Fields::
+
+Fields to retrieve from the query string.
++
+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_qs([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_qs([{id, int}, {lang, nonempty}], Req).
+----
+
+.Match fields with default values
+[source,erlang]
+----
+#{lang := Lang}
+    = cowboy_req:match_qs([{lang, [], <<"en-US">>}], Req).
+----
+
+== See also
+
+link:man:cowboy_req(3)[cowboy_req(3)],
+link:man:cowboy_req:qs(3)[cowboy_req:qs(3)],
+link:man:cowboy_req:parse_qs(3)[cowboy_req:parse_qs(3)]
diff --git a/doc/src/manual/cowboy_req.parse_header.asciidoc b/doc/src/manual/cowboy_req.parse_header.asciidoc
new file mode 100644
index 0000000..14e640d
--- /dev/null
+++ b/doc/src/manual/cowboy_req.parse_header.asciidoc
@@ -0,0 +1,229 @@
+= cowboy_req:parse_header(3)
+
+== Name
+
+cowboy_req:parse_header - Parse the given HTTP header
+
+== Description
+
+[source,erlang]
+----
+parse_header(Name, Req)          -> ParsedValue | Default
+parse_header(Name, Req, Default) -> ParsedValue | Default
+
+Name        :: binary()
+Req         :: cowboy_req:req()
+ParsedValue :: any()
+Default     :: any()
+----
+
+Parse the given HTTP header.
+
+The header name must be given as a lowercase binary string.
+While header names are case insensitive, Cowboy requires them
+to be given as lowercase to function properly.
+
+The type of the parsed value varies depending on
+the header. Similarly, the default value when calling
+`cowboy_req:parse_header/2` differs depending on the
+header.
+
+== Arguments
+
+Name::
+
+Desired HTTP header name as a lowercase binary string.
+
+Req::
+
+The Req object.
+
+Default::
+
+Default value returned when the header is missing.
+
+== Return value
+
+The parsed header value varies depending on the header.
+When the header is missing, the default argument is returned.
+
+== Headers
+
+The following snippets detail the types returned by the
+different headers. Unless mentioned otherwise, the
+default value when the header is missing will be `undefined`:
+
+.accept
+[source,erlang]
+----
+parse_header(<<"accept">>, Req)
+    -> [{{Type, SubType, Params}, Quality, AcceptExt}]
+
+Type      :: binary()               %% case insensitive
+SubType   :: binary()               %% case insensitive
+Params    :: [{Key, Value}]
+Quality   :: 0..1000
+AcceptExt :: [Key | {Key, Value}]
+Key       :: binary()               %% case insensitive
+Value     :: binary()               %% case sensitive
+----
+
+.accept-charset, accept-encoding and accept-language
+[source,erlang]
+----
+parse_header(Name, Req) -> [{Value, Quality}]
+
+Name    :: <<"accept-charset">>
+         | <<"accept-encoding">>
+         | <<"accept-language">>
+Value   :: binary()                 %% case insensitive
+Quality :: 0..1000
+----
+
+.authorization
+[source,erlang]
+----
+parse_header(<<"authorization">>, Req)
+    -> {basic, Username :: binary(), Password :: binary()}
+     | {bearer, Token :: binary()}
+     | {digest, [{Key :: binary(), Value :: binary()}]}
+----
+
+// @todo Currently also parses connection. Do we want this? Should it be documented? Use case?
+
+.content-length
+[source,erlang]
+----
+parse_header(<<"content-length">>, Req) -> non_neg_integer()
+----
+
+When the content-length header is missing, `0` is returned.
+
+.content-type
+[source,erlang]
+----
+parse_header(<<"content-type">>, Req)
+    -> {Type, SubType, Params}
+
+Type      :: binary()               %% case insensitive
+SubType   :: binary()               %% case insensitive
+Params    :: [{Key, Value}]
+Key       :: binary()               %% case insensitive
+Value     :: binary()               %% case sensitive;
+----
+
+Note that the value for the charset parameter is case insensitive
+and returned as a lowercase binary string.
+
+.cookie
+[source,erlang]
+----
+parse_header(<<"cookie">>, Req) -> [{Name, Value}]
+
+Name  :: binary()                   %% case sensitive
+Value :: binary()                   %% case sensitive
+----
+
+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 `[]`.
+
+.expect
+[source,erlang]
+----
+parse_header(<<"expect">>, Req) -> continue
+----
+
+.if-match and if-none-match
+[source,erlang]
+----
+parse_header(Name, Req)
+    -> '*' | [{weak | strong, OpaqueTag}]
+
+Name      :: <<"if-match">>
+           | <<"if-none-match">>
+OpaqueTag :: binary()               %% case sensitive
+----
+
+.if-modified-since and if-unmodified-since
+[source,erlang]
+----
+parse_header(Name, Req) -> calendar:datetime()
+----
+
+.range
+[source,erlang]
+----
+parse_header(<<"range">>, Req) -> {From, To} | Final
+
+From  :: non_neg_integer()
+To    :: non_neg_integer() | infinity
+Final :: neg_integer()
+----
+
+// @todo Remove transfer-encoding from the headers parsed by this function.
+
+.sec-websocket-extensions
+[source,erlang]
+----
+parse_header(<<"sec-websocket-extensions">>, Req)
+    -> [{Extension, Params}]
+
+Extension :: binary()               %% case sensitive
+Params    :: [Key | {Key, Value}]
+Key       :: binary()               %% case sensitive
+Value     :: binary()               %% case sensitive
+----
+
+.sec-websocket-protocol and upgrade
+[source,erlang]
+----
+parse_header(Name, Req) -> [Token]
+
+Name  :: <<"sec-websocket-protocol">>
+       | <<"upgrade">>
+Token :: binary()                   %% case insensitive
+----
+
+.x-forwarded-for
+[source,erlang]
+----
+parse_header(<<"x-forwarded-for">>, Req) -> [Token]
+
+Token :: binary()                   %% case sensitive
+----
+
+.Unknown headers
+[source,erlang]
+----
+parse_header(_, Req) -> {undefined, RawValue}
+----
+
+== Changelog
+
+* *2.0*: Only the parsed header value is returned, it is no longer wrapped in a tuple.
+* *1.0*: Function introduced.
+
+== Examples
+
+.Parse the accept header with a custom default value
+[source,erlang]
+----
+%% Accept everything when header is missing.
+Accept = cowboy_req:parse_header(<<"accept">>, Req,
+	[{{<<"*">>, <<"*">>, []}, 1000, []}]).
+----
+
+.Parse the content-length header
+[source,erlang]
+----
+%% Default content-length is 0.
+Length = cowboy_req:header(<<"content-length">>, Req).
+----
+
+== See also
+
+link:man:cowboy_req(3)[cowboy_req(3)],
+link:man:cowboy_req:header(3)[cowboy_req:header(3)],
+link:man:cowboy_req:headers(3)[cowboy_req:headers(3)]
diff --git a/doc/src/manual/cowboy_req.parse_qs.asciidoc b/doc/src/manual/cowboy_req.parse_qs.asciidoc
new file mode 100644
index 0000000..907bc7b
--- /dev/null
+++ b/doc/src/manual/cowboy_req.parse_qs.asciidoc
@@ -0,0 +1,58 @@
+= cowboy_req:parse_qs(3)
+
+== Name
+
+cowboy_req:parse_qs - Parse the query string
+
+== Description
+
+[source,erlang]
+----
+parse_qs(Req :: cowboy_req:req())
+    -> [{Key :: binary(), Value :: binary() | true}]
+----
+
+Parse the query string as a list of key/value pairs.
+
+== Arguments
+
+Req::
+
+The Req object.
+
+== Return value
+
+The parsed query string is returned as a list of key/value pairs.
+The key is a binary string. The value is either a binary string,
+or the atom `true`. Both key and value are case sensitive.
+
+The atom `true` is returned when a key is present in the query
+string without a value. For example, in the following URIs
+the key `<<"edit">>` will always have the value `true`:
+
+* `/posts/42?edit`
+* `/posts/42?edit&exclusive=1`
+* `/posts/42?exclusive=1&edit`
+* `/posts/42?exclusive=1&edit&from=web`
+
+== Changelog
+
+* *2.0*: The parsed value is not longer cached in the Req object.
+* *2.0*: Only the parsed query string is returned, it is no longer wrapped in a tuple.
+* *2.0*: Function introduced. Replaces `qs_val/1` and `qs_vals/1`.
+
+== Examples
+
+.Parse the query string and convert the keys to atoms
+[source,erlang]
+----
+ParsedQs = cowboy_req:parse_qs(Req),
+AtomsQs = [{binary_to_existing_atom(K, latin1), V}
+    || {K, V} <- ParsedQs].
+----
+
+== See also
+
+link:man:cowboy_req(3)[cowboy_req(3)],
+link:man:cowboy_req:qs(3)[cowboy_req:qs(3)],
+link:man:cowboy_req:match_qs(3)[cowboy_req:match_qs(3)]