diff options
Diffstat (limited to 'doc/src')
| -rw-r--r-- | doc/src/manual/cowboy_req.header.asciidoc | 2 | ||||
| -rw-r--r-- | doc/src/manual/cowboy_req.match_qs.asciidoc | 78 | ||||
| -rw-r--r-- | doc/src/manual/cowboy_req.parse_header.asciidoc | 229 | ||||
| -rw-r--r-- | doc/src/manual/cowboy_req.parse_qs.asciidoc | 58 |
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)] |