From f34ef2ceae4bccd49f3a655e311c310b7570e64f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lo=C3=AFc=20Hoguin?= Date: Wed, 4 Jan 2017 19:21:23 +0100 Subject: Improve the manual for the new resp_header functions --- doc/src/manual/cowboy_req.asciidoc | 4 +- .../manual/cowboy_req.delete_resp_header.asciidoc | 5 ++- doc/src/manual/cowboy_req.has_resp_header.asciidoc | 3 ++ doc/src/manual/cowboy_req.reply.asciidoc | 4 +- doc/src/manual/cowboy_req.resp_header.asciidoc | 32 +++++++++------ doc/src/manual/cowboy_req.resp_headers.asciidoc | 13 +++---- doc/src/manual/cowboy_req.set_resp_body.asciidoc | 1 + doc/src/manual/cowboy_req.set_resp_cookie.asciidoc | 1 + doc/src/manual/cowboy_req.set_resp_header.asciidoc | 3 ++ .../manual/cowboy_req.set_resp_headers.asciidoc | 45 ++++++++++++++++------ doc/src/manual/cowboy_req.stream_reply.asciidoc | 1 + 11 files changed, 79 insertions(+), 33 deletions(-) (limited to 'doc/src') diff --git a/doc/src/manual/cowboy_req.asciidoc b/doc/src/manual/cowboy_req.asciidoc index b2ddbc1..2cac8d5 100644 --- a/doc/src/manual/cowboy_req.asciidoc +++ b/doc/src/manual/cowboy_req.asciidoc @@ -67,11 +67,11 @@ Request body: Response: * link:man:cowboy_req:set_resp_cookie(3)[cowboy_req:set_resp_cookie(3)] - Set a cookie -* link:man:cowboy_req:resp_header(3)[cowboy_req:resp_header(3)] - Access the named HTTP header set for the response -* link:man:cowboy_req:resp_headers(3)[cowboy_req:resp_headers(3)] - Access HTTP headers set for the response * link:man:cowboy_req:set_resp_header(3)[cowboy_req:set_resp_header(3)] - Set a response header * link:man:cowboy_req:set_resp_headers(3)[cowboy_req:set_resp_headers(3)] - Set several response headers * link:man:cowboy_req:has_resp_header(3)[cowboy_req:has_resp_header(3)] - Is the given response header set? +* link:man:cowboy_req:resp_header(3)[cowboy_req:resp_header(3)] - Response header +* link:man:cowboy_req:resp_headers(3)[cowboy_req:resp_headers(3)] - Response headers * link:man:cowboy_req:delete_resp_header(3)[cowboy_req:delete_resp_header(3)] - Delete a response header * link:man:cowboy_req:set_resp_body(3)[cowboy_req:set_resp_body(3)] - Set the response body * link:man:cowboy_req:has_resp_body(3)[cowboy_req:has_resp_body(3)] - Is there a response body? diff --git a/doc/src/manual/cowboy_req.delete_resp_header.asciidoc b/doc/src/manual/cowboy_req.delete_resp_header.asciidoc index 7a32d70..0b530be 100644 --- a/doc/src/manual/cowboy_req.delete_resp_header.asciidoc +++ b/doc/src/manual/cowboy_req.delete_resp_header.asciidoc @@ -52,4 +52,7 @@ Req = cowboy_req:delete_resp_header(<<"content-type">>, Req0), link:man:cowboy_req(3)[cowboy_req(3)], link:man:cowboy_req:set_resp_header(3)[cowboy_req:set_resp_header(3)], -link:man:cowboy_req:has_resp_header(3)[cowboy_req:has_resp_header(3)] +link:man:cowboy_req:set_resp_headers(3)[cowboy_req:set_resp_headers(3)], +link:man:cowboy_req:has_resp_header(3)[cowboy_req:has_resp_header(3)], +link:man:cowboy_req:resp_header(3)[cowboy_req:resp_header(3)], +link:man:cowboy_req:resp_headers(3)[cowboy_req:resp_headers(3)] diff --git a/doc/src/manual/cowboy_req.has_resp_header.asciidoc b/doc/src/manual/cowboy_req.has_resp_header.asciidoc index d6ada37..b8f1ece 100644 --- a/doc/src/manual/cowboy_req.has_resp_header.asciidoc +++ b/doc/src/manual/cowboy_req.has_resp_header.asciidoc @@ -51,4 +51,7 @@ true = cowboy_req:has_resp_header(<<"content-type">>, Req). link:man:cowboy_req(3)[cowboy_req(3)], link:man:cowboy_req:set_resp_header(3)[cowboy_req:set_resp_header(3)], +link:man:cowboy_req:set_resp_headers(3)[cowboy_req:set_resp_headers(3)], +link:man:cowboy_req:resp_header(3)[cowboy_req:resp_header(3)], +link:man:cowboy_req:resp_headers(3)[cowboy_req:resp_headers(3)], link:man:cowboy_req:delete_resp_header(3)[cowboy_req:delete_resp_header(3)] diff --git a/doc/src/manual/cowboy_req.reply.asciidoc b/doc/src/manual/cowboy_req.reply.asciidoc index 35403f8..37e32c9 100644 --- a/doc/src/manual/cowboy_req.reply.asciidoc +++ b/doc/src/manual/cowboy_req.reply.asciidoc @@ -29,7 +29,8 @@ While header names are case insensitive, Cowboy requires them to be given as lowercase to function properly. Cowboy does not allow duplicate header names. Headers set -by this function may overwrite those set by `set_resp_header/3`. +by this function may overwrite those set by `set_resp_header/3` +and `set_resp_headers/2`. Use link:man:cowboy_req:set_resp_cookie(3)[cowboy_req:set_resp_cookie(3)] instead of this function to set cookies. @@ -110,6 +111,7 @@ Req = cowboy_req:reply(200, #{ link:man:cowboy_req(3)[cowboy_req(3)], link:man:cowboy_req:set_resp_cookie(3)[cowboy_req:set_resp_cookie(3)], link:man:cowboy_req:set_resp_header(3)[cowboy_req:set_resp_header(3)], +link:man:cowboy_req:set_resp_headers(3)[cowboy_req:set_resp_headers(3)], link:man:cowboy_req:set_resp_body(3)[cowboy_req:set_resp_body(3)], link:man:cowboy_req:stream_reply(3)[cowboy_req:stream_reply(3)], link:man:cowboy_req:push(3)[cowboy_req:push(3)] diff --git a/doc/src/manual/cowboy_req.resp_header.asciidoc b/doc/src/manual/cowboy_req.resp_header.asciidoc index 84713ef..52f95d6 100644 --- a/doc/src/manual/cowboy_req.resp_header.asciidoc +++ b/doc/src/manual/cowboy_req.resp_header.asciidoc @@ -2,7 +2,7 @@ == Name -cowboy_req:resp_header - Access the named HTTP header set for the response +cowboy_req:resp_header - Response header == Description @@ -11,18 +11,26 @@ cowboy_req:resp_header - Access the named HTTP header set for the response resp_header(Name, Req) -> resp_header(Name, Req, undefined) resp_header(Name, Req, Default) -> binary() | Default -Name :: binary() +Name :: binary() %% lowercase; case insensitive Req :: cowboy_req:req() Default :: any() ---- -Return the currently set response header value for the given HTTP header. +Return the value for the given response header. + +The response header must have been set previously using +link:man:cowboy_req:set_resp_header(3)[cowboy_req:set_resp_header(3)] or +link:man:cowboy_req:set_resp_headers(3)[cowboy_req:set_resp_headers(3)]. + +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. == Arguments Name:: -Desired response HTTP header name as a binary. +Desired response header name as a lowercase binary string. Req:: @@ -34,7 +42,8 @@ Default value returned when the header is missing. == Return value -The binary value for the given HTTP header name. +The header value is returned as a binary string. When the +header is missing, the default argument is returned. == Changelog @@ -42,20 +51,21 @@ The binary value for the given HTTP header name. == Examples -.Get the response header with the given name +.Get the content-type response header [source,erlang] ---- -HeaderValue = cowboy_req:resp_header(<<"x-test-header">>, Req). +Type = cowboy_req:resp_header(<<"content-type">>, Req). ---- -.Get the response header with the given name and a default +.Get the content-type response header with a default value [source,erlang] ---- -HeaderValue = cowboy_req:resp_header(<<"x-test-header">>, Req, <<"bar">>). +Type = cowboy_req:resp_header(<<"content-type">>, Req, <<"text/html">>). ---- == See also link:man:cowboy_req(3)[cowboy_req(3)], -link:man:cowboy_req:set_resp_headers(3)[cowboy_req:resp_headers(3)] -link:man:cowboy_req:set_resp_header(3)[cowboy_req:set_resp_header(3)] +link:man:cowboy_req:resp_headers(3)[cowboy_req:resp_headers(3)], +link:man:cowboy_req:set_resp_header(3)[cowboy_req:set_resp_header(3)], +link:man:cowboy_req:set_resp_headers(3)[cowboy_req:set_resp_headers(3)] diff --git a/doc/src/manual/cowboy_req.resp_headers.asciidoc b/doc/src/manual/cowboy_req.resp_headers.asciidoc index 804c0d0..a3b8f0e 100644 --- a/doc/src/manual/cowboy_req.resp_headers.asciidoc +++ b/doc/src/manual/cowboy_req.resp_headers.asciidoc @@ -2,18 +2,16 @@ == Name -cowboy_req:resp_headers - Access HTTP headers set for the response +cowboy_req:resp_headers - Response headers == Description [source,erlang] ---- -resp_headers(Req) -> cowboy:http_headers() - -Req :: cowboy_req:req() +resp_headers(Req :: cowboy_req:req()) -> cowboy:http_headers() ---- -Return all HTTP response headers. +Return all response headers. == Arguments @@ -25,7 +23,6 @@ The Req object. Headers are returned as a map with keys being lowercase binary strings, and values as binary strings. -If no response headers have been added the empty map is returned. == Changelog @@ -42,4 +39,6 @@ Headers = cowboy_req:resp_headers(Req). == See also link:man:cowboy_req(3)[cowboy_req(3)], -link:man:cowboy_req:set_resp_headers(3)[cowboy_req:set_resp_headers(3)] \ No newline at end of file +link:man:cowboy_req:resp_header(3)[cowboy_req:resp_header(3)], +link:man:cowboy_req:set_resp_header(3)[cowboy_req:set_resp_header(3)], +link:man:cowboy_req:set_resp_headers(3)[cowboy_req:set_resp_headers(3)] diff --git a/doc/src/manual/cowboy_req.set_resp_body.asciidoc b/doc/src/manual/cowboy_req.set_resp_body.asciidoc index 5537dae..023b8bb 100644 --- a/doc/src/manual/cowboy_req.set_resp_body.asciidoc +++ b/doc/src/manual/cowboy_req.set_resp_body.asciidoc @@ -86,5 +86,6 @@ Req = cowboy_req:set_resp_body(<<>>, Req0). link:man:cowboy_req(3)[cowboy_req(3)], link:man:cowboy_req:set_resp_header(3)[cowboy_req:set_resp_header(3)], +link:man:cowboy_req:set_resp_headers(3)[cowboy_req:set_resp_headers(3)], link:man:cowboy_req:reply(3)[cowboy_req:reply(3)], link:man:cowboy_req:stream_reply(3)[cowboy_req:stream_reply(3)] diff --git a/doc/src/manual/cowboy_req.set_resp_cookie.asciidoc b/doc/src/manual/cowboy_req.set_resp_cookie.asciidoc index 75126b1..56f308e 100644 --- a/doc/src/manual/cowboy_req.set_resp_cookie.asciidoc +++ b/doc/src/manual/cowboy_req.set_resp_cookie.asciidoc @@ -111,5 +111,6 @@ Req = cowboy_req:set_resp_cookie(<<"sessionid">>, SessionID, [ link:man:cowboy_req(3)[cowboy_req(3)], link:man:cowboy_req:set_resp_header(3)[cowboy_req:set_resp_header(3)], +link:man:cowboy_req:set_resp_headers(3)[cowboy_req:set_resp_headers(3)], link:man:cowboy_req:reply(3)[cowboy_req:reply(3)], link:man:cowboy_req:stream_reply(3)[cowboy_req:stream_reply(3)] diff --git a/doc/src/manual/cowboy_req.set_resp_header.asciidoc b/doc/src/manual/cowboy_req.set_resp_header.asciidoc index 8540187..86d29a1 100644 --- a/doc/src/manual/cowboy_req.set_resp_header.asciidoc +++ b/doc/src/manual/cowboy_req.set_resp_header.asciidoc @@ -72,7 +72,10 @@ Req = cowboy_req:set_resp_header(<<"allow">>, link:man:cowboy_req(3)[cowboy_req(3)], link:man:cowboy_req:set_resp_cookie(3)[cowboy_req:set_resp_cookie(3)], +link:man:cowboy_req:set_resp_headers(3)[cowboy_req:set_resp_headers(3)], link:man:cowboy_req:has_resp_header(3)[cowboy_req:has_resp_header(3)], +link:man:cowboy_req:resp_header(3)[cowboy_req:resp_header(3)], +link:man:cowboy_req:resp_headers(3)[cowboy_req:resp_headers(3)], link:man:cowboy_req:delete_resp_header(3)[cowboy_req:delete_resp_header(3)], link:man:cowboy_req:reply(3)[cowboy_req:reply(3)], link:man:cowboy_req:stream_reply(3)[cowboy_req:stream_reply(3)] diff --git a/doc/src/manual/cowboy_req.set_resp_headers.asciidoc b/doc/src/manual/cowboy_req.set_resp_headers.asciidoc index e5a0fcb..63fe424 100644 --- a/doc/src/manual/cowboy_req.set_resp_headers.asciidoc +++ b/doc/src/manual/cowboy_req.set_resp_headers.asciidoc @@ -8,22 +8,32 @@ cowboy_req:set_resp_headers - Set several response headers [source,erlang] ---- -set_resp_headers(Headers, Req) -> cowboy_req:req() +set_resp_headers(Headers, Req :: cowboy_req:req()) + -> Req Headers :: cowboy:http_headers() -Req :: cowboy_req:req() ---- -Add all given headers to the response headers. -If a given header key already exists in the currently set -response-header map the given value will overwrite the old. +Set several headers to be sent with the response. + +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. + +Cowboy does not allow duplicate header names. Headers set +by this function may be overwritten by those set from the +reply functions. Likewise, headers set by this function may +overwrite headers that were set previously. + +Use link:man:cowboy_req:set_resp_cookie(3)[cowboy_req:set_resp_cookie(3)] +instead of this function to set cookies. == Arguments Headers:: -A map with keys and values as binary strings. -Key values should be lowercase to function properly. +Headers as a map with keys being lowercase binary strings, +and values as binary strings. Req:: @@ -31,7 +41,10 @@ The Req object. == Return value -A request object updated with the given response headers. +A new Req object is returned. + +The returned Req object must be used from that point onward, +otherwise the headers will not be sent in the response. == Changelog @@ -39,13 +52,23 @@ A request object updated with the given response headers. == Examples -.Get all response headers +.Set several response headers [source,erlang] ---- -Req1 = cowboy_req:set_resp_headers(#{<<"x-header-test">> => <<"1">>}, Req0). +Req = cowboy_req:set_resp_headers(#{ + <<"content-type">> => <<"text/html">>, + <<"content-encoding">> => <<"gzip">> +}, Req0). ---- == See also link:man:cowboy_req(3)[cowboy_req(3)], -link:man:cowboy_req:resp_headers(3)[cowboy_req:resp_headers(3)] \ No newline at end of file +link:man:cowboy_req:set_resp_cookie(3)[cowboy_req:set_resp_cookie(3)], +link:man:cowboy_req:set_resp_header(3)[cowboy_req:set_resp_header(3)], +link:man:cowboy_req:has_resp_header(3)[cowboy_req:has_resp_header(3)], +link:man:cowboy_req:resp_header(3)[cowboy_req:resp_header(3)], +link:man:cowboy_req:resp_headers(3)[cowboy_req:resp_headers(3)], +link:man:cowboy_req:delete_resp_header(3)[cowboy_req:delete_resp_header(3)], +link:man:cowboy_req:reply(3)[cowboy_req:reply(3)], +link:man:cowboy_req:stream_reply(3)[cowboy_req:stream_reply(3)] diff --git a/doc/src/manual/cowboy_req.stream_reply.asciidoc b/doc/src/manual/cowboy_req.stream_reply.asciidoc index 9d3ef92..8c4a7ae 100644 --- a/doc/src/manual/cowboy_req.stream_reply.asciidoc +++ b/doc/src/manual/cowboy_req.stream_reply.asciidoc @@ -102,6 +102,7 @@ cowboy_req:stream_body(<<"World!\n">>, fin, Req). link:man:cowboy_req(3)[cowboy_req(3)], link:man:cowboy_req:set_resp_cookie(3)[cowboy_req:set_resp_cookie(3)], link:man:cowboy_req:set_resp_header(3)[cowboy_req:set_resp_header(3)], +link:man:cowboy_req:set_resp_headers(3)[cowboy_req:set_resp_headers(3)], link:man:cowboy_req:reply(3)[cowboy_req:reply(3)], link:man:cowboy_req:stream_body(3)[cowboy_req:stream_body(3)], link:man:cowboy_req:push(3)[cowboy_req:push(3)] -- cgit v1.2.3