diff options
author | Loïc Hoguin <[email protected]> | 2017-10-03 13:39:41 +0200 |
---|---|---|
committer | Loïc Hoguin <[email protected]> | 2017-10-03 13:39:41 +0200 |
commit | b5d4cb91f80c833795a2d87050c3674bb7aecdc5 (patch) | |
tree | 62bf0ad8326006fcd3407fcb7c34c844c0dc0874 /docs/en/cowboy/2.0/manual/cowboy_req.parse_header | |
parent | 1f8d51dd2692fc3978080419987bbe4d49a41a90 (diff) | |
download | ninenines.eu-b5d4cb91f80c833795a2d87050c3674bb7aecdc5.tar.gz ninenines.eu-b5d4cb91f80c833795a2d87050c3674bb7aecdc5.tar.bz2 ninenines.eu-b5d4cb91f80c833795a2d87050c3674bb7aecdc5.zip |
Update Hugo, docs
Diffstat (limited to 'docs/en/cowboy/2.0/manual/cowboy_req.parse_header')
-rw-r--r-- | docs/en/cowboy/2.0/manual/cowboy_req.parse_header/index.html | 556 |
1 files changed, 278 insertions, 278 deletions
diff --git a/docs/en/cowboy/2.0/manual/cowboy_req.parse_header/index.html b/docs/en/cowboy/2.0/manual/cowboy_req.parse_header/index.html index aad1926f..7e22192a 100644 --- a/docs/en/cowboy/2.0/manual/cowboy_req.parse_header/index.html +++ b/docs/en/cowboy/2.0/manual/cowboy_req.parse_header/index.html @@ -7,7 +7,7 @@ <meta name="description" content=""> <meta name="author" content="Loïc Hoguin based on a design from (Soft10) Pol Cámara"> - <meta name="generator" content="Hugo 0.17" /> + <meta name="generator" content="Hugo 0.26" /> <title>Nine Nines: cowboy_req:parse_header(3)</title> @@ -67,283 +67,283 @@ <h1 class="lined-header"><span>cowboy_req:parse_header(3)</span></h1> -<div class="sect1">
-<h2 id="_name">Name</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>cowboy_req:parse_header - Parse the given HTTP header</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_description">Description</h2>
-<div class="sectionbody">
-<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight 3.1.8
-by Lorenzo Bettini
-http://www.lorenzobettini.it
-http://www.gnu.org/software/src-highlite -->
-<pre><tt><span style="font-weight: bold"><span style="color: #000000">parse_header</span></span>(<span style="color: #009900">Name</span>, <span style="color: #009900">Req</span>) <span style="color: #990000">-></span> <span style="color: #009900">ParsedValue</span> | <span style="color: #009900">Default</span>
-<span style="font-weight: bold"><span style="color: #000000">parse_header</span></span>(<span style="color: #009900">Name</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">Default</span>) <span style="color: #990000">-></span> <span style="color: #009900">ParsedValue</span> | <span style="color: #009900">Default</span>
-
-<span style="color: #009900">Name</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>()
-<span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>()
-<span style="color: #009900">ParsedValue</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">any</span></span>()
-<span style="color: #009900">Default</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">any</span></span>()</tt></pre></div></div>
-<div class="paragraph"><p>Parse the given HTTP header.</p></div>
-<div class="paragraph"><p>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.</p></div>
-<div class="paragraph"><p>The type of the parsed value varies depending on
-the header. Similarly, the default value when calling
-<code>cowboy_req:parse_header/2</code> differs depending on the
-header.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_arguments">Arguments</h2>
-<div class="sectionbody">
-<div class="dlist"><dl>
-<dt class="hdlist1">
-Name
-</dt>
-<dd>
-<p>
-Desired HTTP header name as a lowercase binary string.
-</p>
-</dd>
-<dt class="hdlist1">
-Req
-</dt>
-<dd>
-<p>
-The Req object.
-</p>
-</dd>
-<dt class="hdlist1">
-Default
-</dt>
-<dd>
-<p>
-Default value returned when the header is missing.
-</p>
-</dd>
-</dl></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_return_value">Return value</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The parsed header value varies depending on the header.
-When the header is missing, the default argument is returned.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_headers">Headers</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The following snippets detail the types returned by the
-different headers. Unless mentioned otherwise, the
-default value when the header is missing will be <code>undefined</code>:</p></div>
-<div class="listingblock">
-<div class="title">accept</div>
-<div class="content"><!-- Generator: GNU source-highlight 3.1.8
-by Lorenzo Bettini
-http://www.lorenzobettini.it
-http://www.gnu.org/software/src-highlite -->
-<pre><tt><span style="font-weight: bold"><span style="color: #000000">parse_header</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"accept"</span><span style="color: #990000">>></span>, <span style="color: #009900">Req</span>)
- <span style="color: #990000">-></span> [{{<span style="color: #009900">Type</span>, <span style="color: #009900">SubType</span>, <span style="color: #009900">Params</span>}, <span style="color: #009900">Quality</span>, <span style="color: #009900">AcceptExt</span>}]
-
-<span style="color: #009900">Type</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() <span style="font-style: italic"><span style="color: #9A1900">%% case insensitive</span></span>
-<span style="color: #009900">SubType</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() <span style="font-style: italic"><span style="color: #9A1900">%% case insensitive</span></span>
-<span style="color: #009900">Params</span> <span style="color: #990000">::</span> [{<span style="color: #009900">Key</span>, <span style="color: #009900">Value</span>}]
-<span style="color: #009900">Quality</span> <span style="color: #990000">::</span> <span style="color: #993399">0</span><span style="color: #990000">..</span><span style="color: #993399">1000</span>
-<span style="color: #009900">AcceptExt</span> <span style="color: #990000">::</span> [<span style="color: #009900">Key</span> | {<span style="color: #009900">Key</span>, <span style="color: #009900">Value</span>}]
-<span style="color: #009900">Key</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() <span style="font-style: italic"><span style="color: #9A1900">%% case insensitive</span></span>
-<span style="color: #009900">Value</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() <span style="font-style: italic"><span style="color: #9A1900">%% case sensitive</span></span></tt></pre></div></div>
-<div class="listingblock">
-<div class="title">accept-charset, accept-encoding and accept-language</div>
-<div class="content"><!-- Generator: GNU source-highlight 3.1.8
-by Lorenzo Bettini
-http://www.lorenzobettini.it
-http://www.gnu.org/software/src-highlite -->
-<pre><tt><span style="font-weight: bold"><span style="color: #000000">parse_header</span></span>(<span style="color: #009900">Name</span>, <span style="color: #009900">Req</span>) <span style="color: #990000">-></span> [{<span style="color: #009900">Value</span>, <span style="color: #009900">Quality</span>}]
-
-<span style="color: #009900">Name</span> <span style="color: #990000">::</span> <span style="color: #990000"><<</span><span style="color: #FF0000">"accept-charset"</span><span style="color: #990000">>></span>
- | <span style="color: #990000"><<</span><span style="color: #FF0000">"accept-encoding"</span><span style="color: #990000">>></span>
- | <span style="color: #990000"><<</span><span style="color: #FF0000">"accept-language"</span><span style="color: #990000">>></span>
-<span style="color: #009900">Value</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() <span style="font-style: italic"><span style="color: #9A1900">%% case insensitive</span></span>
-<span style="color: #009900">Quality</span> <span style="color: #990000">::</span> <span style="color: #993399">0</span><span style="color: #990000">..</span><span style="color: #993399">1000</span></tt></pre></div></div>
-<div class="listingblock">
-<div class="title">authorization</div>
-<div class="content"><!-- Generator: GNU source-highlight 3.1.8
-by Lorenzo Bettini
-http://www.lorenzobettini.it
-http://www.gnu.org/software/src-highlite -->
-<pre><tt><span style="font-weight: bold"><span style="color: #000000">parse_header</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"authorization"</span><span style="color: #990000">>></span>, <span style="color: #009900">Req</span>)
- <span style="color: #990000">-></span> {<span style="color: #FF6600">basic</span>, <span style="color: #009900">Username</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>(), <span style="color: #009900">Password</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>()}
- | {<span style="color: #FF6600">bearer</span>, <span style="color: #009900">Token</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>()}
- | {<span style="color: #FF6600">digest</span>, [{<span style="color: #009900">Key</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>(), <span style="color: #009900">Value</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>()}]}</tt></pre></div></div>
-<div class="listingblock">
-<div class="title">content-length</div>
-<div class="content"><!-- Generator: GNU source-highlight 3.1.8
-by Lorenzo Bettini
-http://www.lorenzobettini.it
-http://www.gnu.org/software/src-highlite -->
-<pre><tt><span style="font-weight: bold"><span style="color: #000000">parse_header</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"content-length"</span><span style="color: #990000">>></span>, <span style="color: #009900">Req</span>) <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>()</tt></pre></div></div>
-<div class="paragraph"><p>When the content-length header is missing, <code>0</code> is returned.</p></div>
-<div class="listingblock">
-<div class="title">content-type</div>
-<div class="content"><!-- Generator: GNU source-highlight 3.1.8
-by Lorenzo Bettini
-http://www.lorenzobettini.it
-http://www.gnu.org/software/src-highlite -->
-<pre><tt><span style="font-weight: bold"><span style="color: #000000">parse_header</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"content-type"</span><span style="color: #990000">>></span>, <span style="color: #009900">Req</span>)
- <span style="color: #990000">-></span> {<span style="color: #009900">Type</span>, <span style="color: #009900">SubType</span>, <span style="color: #009900">Params</span>}
-
-<span style="color: #009900">Type</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() <span style="font-style: italic"><span style="color: #9A1900">%% case insensitive</span></span>
-<span style="color: #009900">SubType</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() <span style="font-style: italic"><span style="color: #9A1900">%% case insensitive</span></span>
-<span style="color: #009900">Params</span> <span style="color: #990000">::</span> [{<span style="color: #009900">Key</span>, <span style="color: #009900">Value</span>}]
-<span style="color: #009900">Key</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() <span style="font-style: italic"><span style="color: #9A1900">%% case insensitive</span></span>
-<span style="color: #009900">Value</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() <span style="font-style: italic"><span style="color: #9A1900">%% case sensitive;</span></span></tt></pre></div></div>
-<div class="paragraph"><p>Note that the value for the charset parameter is case insensitive
-and returned as a lowercase binary string.</p></div>
-<div class="listingblock">
-<div class="title">cookie</div>
-<div class="content"><!-- Generator: GNU source-highlight 3.1.8
-by Lorenzo Bettini
-http://www.lorenzobettini.it
-http://www.gnu.org/software/src-highlite -->
-<pre><tt><span style="font-weight: bold"><span style="color: #000000">parse_header</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"cookie"</span><span style="color: #990000">>></span>, <span style="color: #009900">Req</span>) <span style="color: #990000">-></span> [{<span style="color: #009900">Name</span>, <span style="color: #009900">Value</span>}]
-
-<span style="color: #009900">Name</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() <span style="font-style: italic"><span style="color: #9A1900">%% case sensitive</span></span>
-<span style="color: #009900">Value</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() <span style="font-style: italic"><span style="color: #9A1900">%% case sensitive</span></span></tt></pre></div></div>
-<div class="paragraph"><p>When the cookie header is missing, <code>[]</code> is returned.</p></div>
-<div class="paragraph"><p>While an empty cookie header is not valid, some clients do
-send it. Cowboy will in this case also return <code>[]</code>.</p></div>
-<div class="listingblock">
-<div class="title">expect</div>
-<div class="content"><!-- Generator: GNU source-highlight 3.1.8
-by Lorenzo Bettini
-http://www.lorenzobettini.it
-http://www.gnu.org/software/src-highlite -->
-<pre><tt><span style="font-weight: bold"><span style="color: #000000">parse_header</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"expect"</span><span style="color: #990000">>></span>, <span style="color: #009900">Req</span>) <span style="color: #990000">-></span> <span style="color: #FF6600">continue</span></tt></pre></div></div>
-<div class="listingblock">
-<div class="title">if-match and if-none-match</div>
-<div class="content"><!-- Generator: GNU source-highlight 3.1.8
-by Lorenzo Bettini
-http://www.lorenzobettini.it
-http://www.gnu.org/software/src-highlite -->
-<pre><tt><span style="font-weight: bold"><span style="color: #000000">parse_header</span></span>(<span style="color: #009900">Name</span>, <span style="color: #009900">Req</span>)
- <span style="color: #990000">-></span> <span style="color: #FF6600">'*'</span> | [{<span style="color: #FF6600">weak</span> | <span style="color: #FF6600">strong</span>, <span style="color: #009900">OpaqueTag</span>}]
-
-<span style="color: #009900">Name</span> <span style="color: #990000">::</span> <span style="color: #990000"><<</span><span style="color: #FF0000">"if-match"</span><span style="color: #990000">>></span>
- | <span style="color: #990000"><<</span><span style="color: #FF0000">"if-none-match"</span><span style="color: #990000">>></span>
-<span style="color: #009900">OpaqueTag</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() <span style="font-style: italic"><span style="color: #9A1900">%% case sensitive</span></span></tt></pre></div></div>
-<div class="listingblock">
-<div class="title">if-modified-since and if-unmodified-since</div>
-<div class="content"><!-- Generator: GNU source-highlight 3.1.8
-by Lorenzo Bettini
-http://www.lorenzobettini.it
-http://www.gnu.org/software/src-highlite -->
-<pre><tt><span style="font-weight: bold"><span style="color: #000000">parse_header</span></span>(<span style="color: #009900">Name</span>, <span style="color: #009900">Req</span>) <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">calendar:datetime</span></span>()</tt></pre></div></div>
-<div class="listingblock">
-<div class="title">range</div>
-<div class="content"><!-- Generator: GNU source-highlight 3.1.8
-by Lorenzo Bettini
-http://www.lorenzobettini.it
-http://www.gnu.org/software/src-highlite -->
-<pre><tt><span style="font-weight: bold"><span style="color: #000000">parse_header</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"range"</span><span style="color: #990000">>></span>, <span style="color: #009900">Req</span>) <span style="color: #990000">-></span> {<span style="color: #009900">From</span>, <span style="color: #009900">To</span>} | <span style="color: #009900">Final</span>
-
-<span style="color: #009900">From</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>()
-<span style="color: #009900">To</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>() | <span style="color: #FF6600">infinity</span>
-<span style="color: #009900">Final</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">neg_integer</span></span>()</tt></pre></div></div>
-<div class="listingblock">
-<div class="title">sec-websocket-extensions</div>
-<div class="content"><!-- Generator: GNU source-highlight 3.1.8
-by Lorenzo Bettini
-http://www.lorenzobettini.it
-http://www.gnu.org/software/src-highlite -->
-<pre><tt><span style="font-weight: bold"><span style="color: #000000">parse_header</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"sec-websocket-extensions"</span><span style="color: #990000">>></span>, <span style="color: #009900">Req</span>)
- <span style="color: #990000">-></span> [{<span style="color: #009900">Extension</span>, <span style="color: #009900">Params</span>}]
-
-<span style="color: #009900">Extension</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() <span style="font-style: italic"><span style="color: #9A1900">%% case sensitive</span></span>
-<span style="color: #009900">Params</span> <span style="color: #990000">::</span> [<span style="color: #009900">Key</span> | {<span style="color: #009900">Key</span>, <span style="color: #009900">Value</span>}]
-<span style="color: #009900">Key</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() <span style="font-style: italic"><span style="color: #9A1900">%% case sensitive</span></span>
-<span style="color: #009900">Value</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() <span style="font-style: italic"><span style="color: #9A1900">%% case sensitive</span></span></tt></pre></div></div>
-<div class="listingblock">
-<div class="title">sec-websocket-protocol and upgrade</div>
-<div class="content"><!-- Generator: GNU source-highlight 3.1.8
-by Lorenzo Bettini
-http://www.lorenzobettini.it
-http://www.gnu.org/software/src-highlite -->
-<pre><tt><span style="font-weight: bold"><span style="color: #000000">parse_header</span></span>(<span style="color: #009900">Name</span>, <span style="color: #009900">Req</span>) <span style="color: #990000">-></span> [<span style="color: #009900">Token</span>]
-
-<span style="color: #009900">Name</span> <span style="color: #990000">::</span> <span style="color: #990000"><<</span><span style="color: #FF0000">"sec-websocket-protocol"</span><span style="color: #990000">>></span>
- | <span style="color: #990000"><<</span><span style="color: #FF0000">"upgrade"</span><span style="color: #990000">>></span>
-<span style="color: #009900">Token</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() <span style="font-style: italic"><span style="color: #9A1900">%% case insensitive</span></span></tt></pre></div></div>
-<div class="listingblock">
-<div class="title">x-forwarded-for</div>
-<div class="content"><!-- Generator: GNU source-highlight 3.1.8
-by Lorenzo Bettini
-http://www.lorenzobettini.it
-http://www.gnu.org/software/src-highlite -->
-<pre><tt><span style="font-weight: bold"><span style="color: #000000">parse_header</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"x-forwarded-for"</span><span style="color: #990000">>></span>, <span style="color: #009900">Req</span>) <span style="color: #990000">-></span> [<span style="color: #009900">Token</span>]
-
-<span style="color: #009900">Token</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() <span style="font-style: italic"><span style="color: #9A1900">%% case sensitive</span></span></tt></pre></div></div>
-<div class="listingblock">
-<div class="title">Unknown headers</div>
-<div class="content"><!-- Generator: GNU source-highlight 3.1.8
-by Lorenzo Bettini
-http://www.lorenzobettini.it
-http://www.gnu.org/software/src-highlite -->
-<pre><tt><span style="font-weight: bold"><span style="color: #000000">parse_header</span></span>(<span style="color: #990000">_</span>, <span style="color: #009900">Req</span>) <span style="color: #990000">-></span> {<span style="color: #000080">undefined</span>, <span style="color: #009900">RawValue</span>}</tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_changelog">Changelog</h2>
-<div class="sectionbody">
-<div class="ulist"><ul>
-<li>
-<p>
-<strong>2.0</strong>: Only the parsed header value is returned, it is no longer wrapped in a tuple.
-</p>
-</li>
-<li>
-<p>
-<strong>1.0</strong>: Function introduced.
-</p>
-</li>
-</ul></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_examples">Examples</h2>
-<div class="sectionbody">
-<div class="listingblock">
-<div class="title">Parse the accept header with a custom default value</div>
-<div class="content"><!-- Generator: GNU source-highlight 3.1.8
-by Lorenzo Bettini
-http://www.lorenzobettini.it
-http://www.gnu.org/software/src-highlite -->
-<pre><tt><span style="font-style: italic"><span style="color: #9A1900">%% Accept everything when header is missing.</span></span>
-<span style="color: #009900">Accept</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:parse_header</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"accept"</span><span style="color: #990000">>></span>, <span style="color: #009900">Req</span>,
- [{{ <span style="color: #990000"><<</span><span style="color: #FF0000">"*"</span><span style="color: #990000">>></span>, <span style="color: #990000"><<</span><span style="color: #FF0000">"*"</span><span style="color: #990000">>></span>, []}, <span style="color: #993399">1000</span>, []}])<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="listingblock">
-<div class="title">Parse the content-length header</div>
-<div class="content"><!-- Generator: GNU source-highlight 3.1.8
-by Lorenzo Bettini
-http://www.lorenzobettini.it
-http://www.gnu.org/software/src-highlite -->
-<pre><tt><span style="font-style: italic"><span style="color: #9A1900">%% Default content-length is 0.</span></span>
-<span style="color: #009900">Length</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:header</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"content-length"</span><span style="color: #990000">>></span>, <span style="color: #009900">Req</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_see_also">See also</h2>
-<div class="sectionbody">
-<div class="paragraph"><p><a href="../cowboy_req">cowboy_req(3)</a>,
-<a href="../cowboy_req.header">cowboy_req:header(3)</a>,
-<a href="../cowboy_req.headers">cowboy_req:headers(3)</a></p></div>
-</div>
-</div>
+<div class="sect1"> +<h2 id="_name">Name</h2> +<div class="sectionbody"> +<div class="paragraph"><p>cowboy_req:parse_header - Parse the given HTTP header</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_description">Description</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="content"><!-- Generator: GNU source-highlight 3.1.8 +by Lorenzo Bettini +http://www.lorenzobettini.it +http://www.gnu.org/software/src-highlite --> +<pre><tt><span style="font-weight: bold"><span style="color: #000000">parse_header</span></span>(<span style="color: #009900">Name</span>, <span style="color: #009900">Req</span>) <span style="color: #990000">-></span> <span style="color: #009900">ParsedValue</span> | <span style="color: #009900">Default</span> +<span style="font-weight: bold"><span style="color: #000000">parse_header</span></span>(<span style="color: #009900">Name</span>, <span style="color: #009900">Req</span>, <span style="color: #009900">Default</span>) <span style="color: #990000">-></span> <span style="color: #009900">ParsedValue</span> | <span style="color: #009900">Default</span> + +<span style="color: #009900">Name</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() +<span style="color: #009900">Req</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:req</span></span>() +<span style="color: #009900">ParsedValue</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">any</span></span>() +<span style="color: #009900">Default</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">any</span></span>()</tt></pre></div></div> +<div class="paragraph"><p>Parse the given HTTP header.</p></div> +<div class="paragraph"><p>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.</p></div> +<div class="paragraph"><p>The type of the parsed value varies depending on +the header. Similarly, the default value when calling +<code>cowboy_req:parse_header/2</code> differs depending on the +header.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_arguments">Arguments</h2> +<div class="sectionbody"> +<div class="dlist"><dl> +<dt class="hdlist1"> +Name +</dt> +<dd> +<p> +Desired HTTP header name as a lowercase binary string. +</p> +</dd> +<dt class="hdlist1"> +Req +</dt> +<dd> +<p> +The Req object. +</p> +</dd> +<dt class="hdlist1"> +Default +</dt> +<dd> +<p> +Default value returned when the header is missing. +</p> +</dd> +</dl></div> +</div> +</div> +<div class="sect1"> +<h2 id="_return_value">Return value</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The parsed header value varies depending on the header. +When the header is missing, the default argument is returned.</p></div> +</div> +</div> +<div class="sect1"> +<h2 id="_headers">Headers</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The following snippets detail the types returned by the +different headers. Unless mentioned otherwise, the +default value when the header is missing will be <code>undefined</code>:</p></div> +<div class="listingblock"> +<div class="title">accept</div> +<div class="content"><!-- Generator: GNU source-highlight 3.1.8 +by Lorenzo Bettini +http://www.lorenzobettini.it +http://www.gnu.org/software/src-highlite --> +<pre><tt><span style="font-weight: bold"><span style="color: #000000">parse_header</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"accept"</span><span style="color: #990000">>></span>, <span style="color: #009900">Req</span>) + <span style="color: #990000">-></span> [{{<span style="color: #009900">Type</span>, <span style="color: #009900">SubType</span>, <span style="color: #009900">Params</span>}, <span style="color: #009900">Quality</span>, <span style="color: #009900">AcceptExt</span>}] + +<span style="color: #009900">Type</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() <span style="font-style: italic"><span style="color: #9A1900">%% case insensitive</span></span> +<span style="color: #009900">SubType</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() <span style="font-style: italic"><span style="color: #9A1900">%% case insensitive</span></span> +<span style="color: #009900">Params</span> <span style="color: #990000">::</span> [{<span style="color: #009900">Key</span>, <span style="color: #009900">Value</span>}] +<span style="color: #009900">Quality</span> <span style="color: #990000">::</span> <span style="color: #993399">0</span><span style="color: #990000">..</span><span style="color: #993399">1000</span> +<span style="color: #009900">AcceptExt</span> <span style="color: #990000">::</span> [<span style="color: #009900">Key</span> | {<span style="color: #009900">Key</span>, <span style="color: #009900">Value</span>}] +<span style="color: #009900">Key</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() <span style="font-style: italic"><span style="color: #9A1900">%% case insensitive</span></span> +<span style="color: #009900">Value</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() <span style="font-style: italic"><span style="color: #9A1900">%% case sensitive</span></span></tt></pre></div></div> +<div class="listingblock"> +<div class="title">accept-charset, accept-encoding and accept-language</div> +<div class="content"><!-- Generator: GNU source-highlight 3.1.8 +by Lorenzo Bettini +http://www.lorenzobettini.it +http://www.gnu.org/software/src-highlite --> +<pre><tt><span style="font-weight: bold"><span style="color: #000000">parse_header</span></span>(<span style="color: #009900">Name</span>, <span style="color: #009900">Req</span>) <span style="color: #990000">-></span> [{<span style="color: #009900">Value</span>, <span style="color: #009900">Quality</span>}] + +<span style="color: #009900">Name</span> <span style="color: #990000">::</span> <span style="color: #990000"><<</span><span style="color: #FF0000">"accept-charset"</span><span style="color: #990000">>></span> + | <span style="color: #990000"><<</span><span style="color: #FF0000">"accept-encoding"</span><span style="color: #990000">>></span> + | <span style="color: #990000"><<</span><span style="color: #FF0000">"accept-language"</span><span style="color: #990000">>></span> +<span style="color: #009900">Value</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() <span style="font-style: italic"><span style="color: #9A1900">%% case insensitive</span></span> +<span style="color: #009900">Quality</span> <span style="color: #990000">::</span> <span style="color: #993399">0</span><span style="color: #990000">..</span><span style="color: #993399">1000</span></tt></pre></div></div> +<div class="listingblock"> +<div class="title">authorization</div> +<div class="content"><!-- Generator: GNU source-highlight 3.1.8 +by Lorenzo Bettini +http://www.lorenzobettini.it +http://www.gnu.org/software/src-highlite --> +<pre><tt><span style="font-weight: bold"><span style="color: #000000">parse_header</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"authorization"</span><span style="color: #990000">>></span>, <span style="color: #009900">Req</span>) + <span style="color: #990000">-></span> {<span style="color: #FF6600">basic</span>, <span style="color: #009900">Username</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>(), <span style="color: #009900">Password</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>()} + | {<span style="color: #FF6600">bearer</span>, <span style="color: #009900">Token</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>()} + | {<span style="color: #FF6600">digest</span>, [{<span style="color: #009900">Key</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>(), <span style="color: #009900">Value</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>()}]}</tt></pre></div></div> +<div class="listingblock"> +<div class="title">content-length</div> +<div class="content"><!-- Generator: GNU source-highlight 3.1.8 +by Lorenzo Bettini +http://www.lorenzobettini.it +http://www.gnu.org/software/src-highlite --> +<pre><tt><span style="font-weight: bold"><span style="color: #000000">parse_header</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"content-length"</span><span style="color: #990000">>></span>, <span style="color: #009900">Req</span>) <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>()</tt></pre></div></div> +<div class="paragraph"><p>When the content-length header is missing, <code>0</code> is returned.</p></div> +<div class="listingblock"> +<div class="title">content-type</div> +<div class="content"><!-- Generator: GNU source-highlight 3.1.8 +by Lorenzo Bettini +http://www.lorenzobettini.it +http://www.gnu.org/software/src-highlite --> +<pre><tt><span style="font-weight: bold"><span style="color: #000000">parse_header</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"content-type"</span><span style="color: #990000">>></span>, <span style="color: #009900">Req</span>) + <span style="color: #990000">-></span> {<span style="color: #009900">Type</span>, <span style="color: #009900">SubType</span>, <span style="color: #009900">Params</span>} + +<span style="color: #009900">Type</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() <span style="font-style: italic"><span style="color: #9A1900">%% case insensitive</span></span> +<span style="color: #009900">SubType</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() <span style="font-style: italic"><span style="color: #9A1900">%% case insensitive</span></span> +<span style="color: #009900">Params</span> <span style="color: #990000">::</span> [{<span style="color: #009900">Key</span>, <span style="color: #009900">Value</span>}] +<span style="color: #009900">Key</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() <span style="font-style: italic"><span style="color: #9A1900">%% case insensitive</span></span> +<span style="color: #009900">Value</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() <span style="font-style: italic"><span style="color: #9A1900">%% case sensitive;</span></span></tt></pre></div></div> +<div class="paragraph"><p>Note that the value for the charset parameter is case insensitive +and returned as a lowercase binary string.</p></div> +<div class="listingblock"> +<div class="title">cookie</div> +<div class="content"><!-- Generator: GNU source-highlight 3.1.8 +by Lorenzo Bettini +http://www.lorenzobettini.it +http://www.gnu.org/software/src-highlite --> +<pre><tt><span style="font-weight: bold"><span style="color: #000000">parse_header</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"cookie"</span><span style="color: #990000">>></span>, <span style="color: #009900">Req</span>) <span style="color: #990000">-></span> [{<span style="color: #009900">Name</span>, <span style="color: #009900">Value</span>}] + +<span style="color: #009900">Name</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() <span style="font-style: italic"><span style="color: #9A1900">%% case sensitive</span></span> +<span style="color: #009900">Value</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() <span style="font-style: italic"><span style="color: #9A1900">%% case sensitive</span></span></tt></pre></div></div> +<div class="paragraph"><p>When the cookie header is missing, <code>[]</code> is returned.</p></div> +<div class="paragraph"><p>While an empty cookie header is not valid, some clients do +send it. Cowboy will in this case also return <code>[]</code>.</p></div> +<div class="listingblock"> +<div class="title">expect</div> +<div class="content"><!-- Generator: GNU source-highlight 3.1.8 +by Lorenzo Bettini +http://www.lorenzobettini.it +http://www.gnu.org/software/src-highlite --> +<pre><tt><span style="font-weight: bold"><span style="color: #000000">parse_header</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"expect"</span><span style="color: #990000">>></span>, <span style="color: #009900">Req</span>) <span style="color: #990000">-></span> <span style="color: #FF6600">continue</span></tt></pre></div></div> +<div class="listingblock"> +<div class="title">if-match and if-none-match</div> +<div class="content"><!-- Generator: GNU source-highlight 3.1.8 +by Lorenzo Bettini +http://www.lorenzobettini.it +http://www.gnu.org/software/src-highlite --> +<pre><tt><span style="font-weight: bold"><span style="color: #000000">parse_header</span></span>(<span style="color: #009900">Name</span>, <span style="color: #009900">Req</span>) + <span style="color: #990000">-></span> <span style="color: #FF6600">'*'</span> | [{<span style="color: #FF6600">weak</span> | <span style="color: #FF6600">strong</span>, <span style="color: #009900">OpaqueTag</span>}] + +<span style="color: #009900">Name</span> <span style="color: #990000">::</span> <span style="color: #990000"><<</span><span style="color: #FF0000">"if-match"</span><span style="color: #990000">>></span> + | <span style="color: #990000"><<</span><span style="color: #FF0000">"if-none-match"</span><span style="color: #990000">>></span> +<span style="color: #009900">OpaqueTag</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() <span style="font-style: italic"><span style="color: #9A1900">%% case sensitive</span></span></tt></pre></div></div> +<div class="listingblock"> +<div class="title">if-modified-since and if-unmodified-since</div> +<div class="content"><!-- Generator: GNU source-highlight 3.1.8 +by Lorenzo Bettini +http://www.lorenzobettini.it +http://www.gnu.org/software/src-highlite --> +<pre><tt><span style="font-weight: bold"><span style="color: #000000">parse_header</span></span>(<span style="color: #009900">Name</span>, <span style="color: #009900">Req</span>) <span style="color: #990000">-></span> <span style="font-weight: bold"><span style="color: #000000">calendar:datetime</span></span>()</tt></pre></div></div> +<div class="listingblock"> +<div class="title">range</div> +<div class="content"><!-- Generator: GNU source-highlight 3.1.8 +by Lorenzo Bettini +http://www.lorenzobettini.it +http://www.gnu.org/software/src-highlite --> +<pre><tt><span style="font-weight: bold"><span style="color: #000000">parse_header</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"range"</span><span style="color: #990000">>></span>, <span style="color: #009900">Req</span>) <span style="color: #990000">-></span> {<span style="color: #009900">From</span>, <span style="color: #009900">To</span>} | <span style="color: #009900">Final</span> + +<span style="color: #009900">From</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>() +<span style="color: #009900">To</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">non_neg_integer</span></span>() | <span style="color: #FF6600">infinity</span> +<span style="color: #009900">Final</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000000">neg_integer</span></span>()</tt></pre></div></div> +<div class="listingblock"> +<div class="title">sec-websocket-extensions</div> +<div class="content"><!-- Generator: GNU source-highlight 3.1.8 +by Lorenzo Bettini +http://www.lorenzobettini.it +http://www.gnu.org/software/src-highlite --> +<pre><tt><span style="font-weight: bold"><span style="color: #000000">parse_header</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"sec-websocket-extensions"</span><span style="color: #990000">>></span>, <span style="color: #009900">Req</span>) + <span style="color: #990000">-></span> [{<span style="color: #009900">Extension</span>, <span style="color: #009900">Params</span>}] + +<span style="color: #009900">Extension</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() <span style="font-style: italic"><span style="color: #9A1900">%% case sensitive</span></span> +<span style="color: #009900">Params</span> <span style="color: #990000">::</span> [<span style="color: #009900">Key</span> | {<span style="color: #009900">Key</span>, <span style="color: #009900">Value</span>}] +<span style="color: #009900">Key</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() <span style="font-style: italic"><span style="color: #9A1900">%% case sensitive</span></span> +<span style="color: #009900">Value</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() <span style="font-style: italic"><span style="color: #9A1900">%% case sensitive</span></span></tt></pre></div></div> +<div class="listingblock"> +<div class="title">sec-websocket-protocol and upgrade</div> +<div class="content"><!-- Generator: GNU source-highlight 3.1.8 +by Lorenzo Bettini +http://www.lorenzobettini.it +http://www.gnu.org/software/src-highlite --> +<pre><tt><span style="font-weight: bold"><span style="color: #000000">parse_header</span></span>(<span style="color: #009900">Name</span>, <span style="color: #009900">Req</span>) <span style="color: #990000">-></span> [<span style="color: #009900">Token</span>] + +<span style="color: #009900">Name</span> <span style="color: #990000">::</span> <span style="color: #990000"><<</span><span style="color: #FF0000">"sec-websocket-protocol"</span><span style="color: #990000">>></span> + | <span style="color: #990000"><<</span><span style="color: #FF0000">"upgrade"</span><span style="color: #990000">>></span> +<span style="color: #009900">Token</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() <span style="font-style: italic"><span style="color: #9A1900">%% case insensitive</span></span></tt></pre></div></div> +<div class="listingblock"> +<div class="title">x-forwarded-for</div> +<div class="content"><!-- Generator: GNU source-highlight 3.1.8 +by Lorenzo Bettini +http://www.lorenzobettini.it +http://www.gnu.org/software/src-highlite --> +<pre><tt><span style="font-weight: bold"><span style="color: #000000">parse_header</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"x-forwarded-for"</span><span style="color: #990000">>></span>, <span style="color: #009900">Req</span>) <span style="color: #990000">-></span> [<span style="color: #009900">Token</span>] + +<span style="color: #009900">Token</span> <span style="color: #990000">::</span> <span style="font-weight: bold"><span style="color: #000080">binary</span></span>() <span style="font-style: italic"><span style="color: #9A1900">%% case sensitive</span></span></tt></pre></div></div> +<div class="listingblock"> +<div class="title">Unknown headers</div> +<div class="content"><!-- Generator: GNU source-highlight 3.1.8 +by Lorenzo Bettini +http://www.lorenzobettini.it +http://www.gnu.org/software/src-highlite --> +<pre><tt><span style="font-weight: bold"><span style="color: #000000">parse_header</span></span>(<span style="color: #990000">_</span>, <span style="color: #009900">Req</span>) <span style="color: #990000">-></span> {<span style="color: #000080">undefined</span>, <span style="color: #009900">RawValue</span>}</tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_changelog">Changelog</h2> +<div class="sectionbody"> +<div class="ulist"><ul> +<li> +<p> +<strong>2.0</strong>: Only the parsed header value is returned, it is no longer wrapped in a tuple. +</p> +</li> +<li> +<p> +<strong>1.0</strong>: Function introduced. +</p> +</li> +</ul></div> +</div> +</div> +<div class="sect1"> +<h2 id="_examples">Examples</h2> +<div class="sectionbody"> +<div class="listingblock"> +<div class="title">Parse the accept header with a custom default value</div> +<div class="content"><!-- Generator: GNU source-highlight 3.1.8 +by Lorenzo Bettini +http://www.lorenzobettini.it +http://www.gnu.org/software/src-highlite --> +<pre><tt><span style="font-style: italic"><span style="color: #9A1900">%% Accept everything when header is missing.</span></span> +<span style="color: #009900">Accept</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:parse_header</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"accept"</span><span style="color: #990000">>></span>, <span style="color: #009900">Req</span>, + [{{ <span style="color: #990000"><<</span><span style="color: #FF0000">"*"</span><span style="color: #990000">>></span>, <span style="color: #990000"><<</span><span style="color: #FF0000">"*"</span><span style="color: #990000">>></span>, []}, <span style="color: #993399">1000</span>, []}])<span style="color: #990000">.</span></tt></pre></div></div> +<div class="listingblock"> +<div class="title">Parse the content-length header</div> +<div class="content"><!-- Generator: GNU source-highlight 3.1.8 +by Lorenzo Bettini +http://www.lorenzobettini.it +http://www.gnu.org/software/src-highlite --> +<pre><tt><span style="font-style: italic"><span style="color: #9A1900">%% Default content-length is 0.</span></span> +<span style="color: #009900">Length</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:header</span></span>(<span style="color: #990000"><<</span><span style="color: #FF0000">"content-length"</span><span style="color: #990000">>></span>, <span style="color: #009900">Req</span>)<span style="color: #990000">.</span></tt></pre></div></div> +</div> +</div> +<div class="sect1"> +<h2 id="_see_also">See also</h2> +<div class="sectionbody"> +<div class="paragraph"><p><a href="../cowboy_req">cowboy_req(3)</a>, +<a href="../cowboy_req.header">cowboy_req:header(3)</a>, +<a href="../cowboy_req.headers">cowboy_req:headers(3)</a></p></div> +</div> +</div> |