Update the Cowboy 2.0 docs

1 files changed, 51 insertions, 21 deletions

diff --git a/docs/en/cowboy/2.0/guide/constraints/index.html b/docs/en/cowboy/2.0/guide/constraints/index.html
index 04171ebb..110adf07 100644
--- a/docs/en/cowboy/2.0/guide/constraints/index.html
+++ b/docs/en/cowboy/2.0/guide/constraints/index.html
@@ -70,7 +70,7 @@
 <div class="paragraph"><p>Constraints are validation and conversion functions applied

 to user input.</p></div>

 <div class="paragraph"><p>They are used in various places in Cowboy, including the

-router and the request match functions.</p></div>

+router and the <code>cowboy_req</code> match functions.</p></div>

 <div class="sect1">

 <h2 id="_syntax">Syntax</h2>

 <div class="sectionbody">

@@ -98,8 +98,15 @@ check that the integer is positive:</p></div>
 by Lorenzo Bettini

 http://www.lorenzobettini.it

 http://www.gnu.org/software/src-highlite -->

-<pre><tt><span style="color: #009900">PositiveFun</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #0000FF">fun</span></span>(<span style="color: #009900">V</span>) <span style="font-weight: bold"><span style="color: #0000FF">when</span></span> <span style="color: #009900">V</span> <span style="color: #990000">&gt;</span> <span style="color: #993399">0</span> <span style="color: #990000">-&gt;</span> <span style="color: #000080">true</span>; (<span style="color: #990000">_</span>) <span style="color: #990000">-&gt;</span> <span style="color: #000080">false</span> <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>,

+<pre><tt><span style="color: #009900">PositiveFun</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #0000FF">fun</span></span>

+    (<span style="color: #990000">_</span>, <span style="color: #009900">V</span>) <span style="font-weight: bold"><span style="color: #0000FF">when</span></span> <span style="color: #009900">V</span> <span style="color: #990000">&gt;</span> <span style="color: #993399">0</span> <span style="color: #990000">-&gt;</span>

+        {<span style="color: #FF6600">ok</span>, <span style="color: #009900">V</span>};

+    (<span style="color: #990000">_</span>, <span style="color: #990000">_</span>) <span style="color: #990000">-&gt;</span>

+        {<span style="color: #FF6600">error</span>, <span style="color: #FF6600">not_positive</span>}

+<span style="font-weight: bold"><span style="color: #0000FF">end</span></span>,

 {<span style="color: #FF6600">my_value</span>, [<span style="color: #FF6600">int</span>, <span style="color: #009900">PositiveFun</span>]}<span style="color: #990000">.</span></tt></pre></div></div>

+<div class="paragraph"><p>We ignore the first fun argument in this snippet. We shouldn&#8217;t.

+We will simply learn what it is later in this chapter.</p></div>

 <div class="paragraph"><p>When there&#8217;s only one constraint, it can be provided directly

 without wrapping it into a list:</p></div>

 <div class="listingblock">

@@ -145,31 +152,54 @@ cellspacing="0" cellpadding="4">
 <h2 id="_custom_constraints">Custom constraints</h2>

 <div class="sectionbody">

 <div class="paragraph"><p>Custom constraints are specified as a fun. This fun takes

-a single argument and must return one of <code>true</code>, <code>{true, NewValue}</code>

-or <code>false</code>.</p></div>

-<div class="paragraph"><p><code>true</code> indicates the input is valid, <code>false</code> otherwise.

-The <code>{true, NewValue}</code> tuple is returned when the input

-is valid and the value has been converted. For example,

-the following constraint will convert the binary input

-to an integer:</p></div>

+two arguments. The first argument indicates the operation

+to be performed, and the second is the value. What the

+value is and what must be returned depends on the operation.</p></div>

+<div class="paragraph"><p>Cowboy currently defines three operations. The operation

+used for validating and converting user input is the <code>forward</code>

+operation.</p></div>

 <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: #0000FF">fun</span></span> (<span style="color: #009900">Value0</span>) <span style="font-weight: bold"><span style="color: #0000FF">when</span></span> <span style="font-weight: bold"><span style="color: #000080">is_binary</span></span>(<span style="color: #009900">Value0</span>) <span style="color: #990000">-&gt;</span>

-    <span style="font-weight: bold"><span style="color: #0000FF">try</span></span> <span style="font-weight: bold"><span style="color: #000000">binary_to_integer</span></span>(<span style="color: #009900">Value0</span>) <span style="font-weight: bold"><span style="color: #0000FF">of</span></span>

-        <span style="color: #009900">Value</span> <span style="color: #990000">-&gt;</span> {<span style="color: #000080">true</span>, <span style="color: #009900">Value</span>}

+<pre><tt><span style="font-weight: bold"><span style="color: #000000">int</span></span>(<span style="color: #FF6600">forward</span>, <span style="color: #009900">Value</span>) <span style="color: #990000">-&gt;</span>

+    <span style="font-weight: bold"><span style="color: #0000FF">try</span></span>

+        {<span style="color: #FF6600">ok</span>, <span style="font-weight: bold"><span style="color: #000000">binary_to_integer</span></span>(<span style="color: #009900">Value</span>)}

     <span style="font-weight: bold"><span style="color: #0000FF">catch</span></span> <span style="color: #990000">_:_</span> <span style="color: #990000">-&gt;</span>

-        <span style="color: #000080">false</span>

-    <span style="font-weight: bold"><span style="color: #0000FF">end</span></span><span style="color: #990000">.</span></tt></pre></div></div>

-<div class="paragraph"><p>Constraint functions should only crash because the programmer

-made an error when chaining constraints incorrectly (for example

-if the constraints were <code>[int, int]</code>, and not because of input.

-If the input is invalid then <code>false</code> must be returned.</p></div>

-<div class="paragraph"><p>In our snippet, the <code>is_binary/1</code> guard will crash only

-because of a programmer error, and the try block is there

-to ensure that we do not crash when the input is invalid.</p></div>

+        {<span style="color: #FF6600">error</span>, <span style="color: #FF6600">not_an_integer</span>}

+    <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>;</tt></pre></div></div>

+<div class="paragraph"><p>The value must be returned even if it is not converted

+by the constraint.</p></div>

+<div class="paragraph"><p>The <code>reverse</code> operation does the opposite: it

+takes a converted value and changes it back to what the

+user input would have been.</p></div>

+<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">int</span></span>(<span style="color: #FF6600">reverse</span>, <span style="color: #009900">Value</span>) <span style="color: #990000">-&gt;</span>

+        <span style="font-weight: bold"><span style="color: #0000FF">try</span></span>

+                {<span style="color: #FF6600">ok</span>, <span style="font-weight: bold"><span style="color: #000000">integer_to_binary</span></span>(<span style="color: #009900">Value</span>)}

+        <span style="font-weight: bold"><span style="color: #0000FF">catch</span></span> <span style="color: #990000">_:_</span> <span style="color: #990000">-&gt;</span>

+                {<span style="color: #FF6600">error</span>, <span style="color: #FF6600">not_an_integer</span>}

+        <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>;</tt></pre></div></div>

+<div class="paragraph"><p>Finally, the <code>format_error</code> operation takes an error

+returned by any other operation and returns a formatted

+human-readable error message.</p></div>

+<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">int</span></span>(<span style="color: #FF6600">format_error</span>, {<span style="color: #FF6600">not_an_integer</span>, <span style="color: #009900">Value</span>}) <span style="color: #990000">-&gt;</span>

+        <span style="font-weight: bold"><span style="color: #000000">io_lib:format</span></span>(<span style="color: #FF0000">"The value ~p is not an integer."</span>, [<span style="color: #009900">Value</span>])<span style="color: #990000">.</span></tt></pre></div></div>

+<div class="paragraph"><p>Notice that for this case you get both the error and

+the value that was given to the constraint that produced

+this error.</p></div>

+<div class="paragraph"><p>Cowboy will not catch exceptions coming from constraint

+functions. They should be written to not emit any exceptions.</p></div>

 </div>

 </div>