From 8151ea9815afea8264ebabc69bcc96f9b0d3f228 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lo=C3=AFc=20Hoguin?= Date: Mon, 7 Nov 2016 01:15:04 +0200 Subject: Update docs --- .../cowboy/2.0/manual/cowboy_req.header/index.html | 2 +- .../2.0/manual/cowboy_req.match_qs/index.html | 253 +++++++++++++ .../2.0/manual/cowboy_req.parse_header/index.html | 405 +++++++++++++++++++++ .../2.0/manual/cowboy_req.parse_qs/index.html | 255 +++++++++++++ docs/en/cowboy/2.0/manual/index.html | 15 + 5 files changed, 929 insertions(+), 1 deletion(-) create mode 100644 docs/en/cowboy/2.0/manual/cowboy_req.match_qs/index.html create mode 100644 docs/en/cowboy/2.0/manual/cowboy_req.parse_header/index.html create mode 100644 docs/en/cowboy/2.0/manual/cowboy_req.parse_qs/index.html (limited to 'docs/en') diff --git a/docs/en/cowboy/2.0/manual/cowboy_req.header/index.html b/docs/en/cowboy/2.0/manual/cowboy_req.header/index.html index cc2aa12e..f4fb9809 100644 --- a/docs/en/cowboy/2.0/manual/cowboy_req.header/index.html +++ b/docs/en/cowboy/2.0/manual/cowboy_req.header/index.html @@ -110,7 +110,7 @@ Name

-Desired HTTP header name as a binary string. +Desired HTTP header name as a lowercase binary string.

diff --git a/docs/en/cowboy/2.0/manual/cowboy_req.match_qs/index.html b/docs/en/cowboy/2.0/manual/cowboy_req.match_qs/index.html new file mode 100644 index 00000000..4f58bef7 --- /dev/null +++ b/docs/en/cowboy/2.0/manual/cowboy_req.match_qs/index.html @@ -0,0 +1,253 @@ + + + + + + + + + + + + Nine Nines: cowboy_req:match_qs(3) + + + + + + + + + + + + + + + + +

+ + + +

+ +

cowboy_req:match_qs(3)

+ +

Name

cowboy_req:match_qs - Match the query string against constraints

Description

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

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

Match fields and apply constraints

%% 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

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

cowboy_req:parse_header(3)

+ +

Name

cowboy_req:parse_header - Parse the given HTTP header

Description

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:

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

parse_header(Name, Req) -> [{Value, Quality}]
+
+Name    :: <<"accept-charset">>
+         | <<"accept-encoding">>
+         | <<"accept-language">>
+Value   :: binary()                 %% case insensitive
+Quality :: 0..1000

authorization

parse_header(<<"authorization">>, Req)
+    -> {basic, Username :: binary(), Password :: binary()}
+     | {bearer, Token :: binary()}
+     | {digest, [{Key :: binary(), Value :: binary()}]}

content-length

parse_header(<<"content-length">>, Req) -> non_neg_integer()

When the content-length header is missing, 0 is returned.

content-type

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.

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

parse_header(<<"expect">>, Req) -> continue

if-match and if-none-match

parse_header(Name, Req)
+    -> '*' | [{weak | strong, OpaqueTag}]
+
+Name      :: <<"if-match">>
+           | <<"if-none-match">>
+OpaqueTag :: binary()               %% case sensitive

if-modified-since and if-unmodified-since

parse_header(Name, Req) -> calendar:datetime()

range

parse_header(<<"range">>, Req) -> {From, To} | Final
+
+From  :: non_neg_integer()
+To    :: non_neg_integer() | infinity
+Final :: neg_integer()

sec-websocket-extensions

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

parse_header(Name, Req) -> [Token]
+
+Name  :: <<"sec-websocket-protocol">>
+       | <<"upgrade">>
+Token :: binary()                   %% case insensitive

x-forwarded-for

parse_header(<<"x-forwarded-for">>, Req) -> [Token]
+
+Token :: binary()                   %% case sensitive

Unknown headers

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

%% Accept everything when header is missing.
+Accept = cowboy_req:parse_header(<<"accept">>, Req,
+        [{#{#HUGOSHORTCODE-1#}#}

+ + + + + +

+ +

+ + +

+ Cowboy + 2.0 + Function Reference + +

+ +

User Guide
Function Reference

+ +

Navigation

+ +

Version select

+ +

+ + + + + + + + + + + + diff --git a/docs/en/cowboy/2.0/manual/cowboy_req.parse_qs/index.html b/docs/en/cowboy/2.0/manual/cowboy_req.parse_qs/index.html new file mode 100644 index 00000000..7e091405 --- /dev/null +++ b/docs/en/cowboy/2.0/manual/cowboy_req.parse_qs/index.html @@ -0,0 +1,255 @@ + + + + + + + + + + + + Nine Nines: cowboy_req:parse_qs(3) + + + + + + + + + + + + + + + + +

+ + + +

+ +

cowboy_req:parse_qs(3)

+ +

Name

cowboy_req:parse_qs - Parse the query string

Description

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

ParsedQs = cowboy_req:parse_qs(Req),
+AtomsQs = [{binary_to_existing_atom(K, latin1), V}
+    || {K, V} <- ParsedQs].

99s

cowboy_req:match_qs(3)

Name

Description

Arguments

Return value

Changelog

Examples

See also

+ Cowboy + 2.0 + Function Reference + +

Navigation

Version select

99s

cowboy_req:parse_header(3)

Name

Description

Arguments

Return value

Headers

Changelog

Examples

+ Cowboy + 2.0 + Function Reference + +

Navigation

Version select

99s

cowboy_req:parse_qs(3)

Name

Description

Arguments

Return value

Changelog

Examples

See also

+ Cowboy + 2.0 + Function Reference + +

Navigation

Version select