From 57b5a67bf6d845322d8365e54c18e0d66fdad4d6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lo=C3=AFc=20Hoguin?= Date: Sun, 4 Sep 2016 19:11:12 +0200 Subject: Update documentation --- docs/en/cowboy/2.0/guide/constraints/index.html | 100 ++++++++++++++++-------- 1 file changed, 68 insertions(+), 32 deletions(-) (limited to 'docs/en/cowboy/2.0/guide/constraints/index.html') diff --git a/docs/en/cowboy/2.0/guide/constraints/index.html b/docs/en/cowboy/2.0/guide/constraints/index.html index 2428e8d4..f2904152 100644 --- a/docs/en/cowboy/2.0/guide/constraints/index.html +++ b/docs/en/cowboy/2.0/guide/constraints/index.html @@ -69,36 +69,53 @@

Constraints

-

Cowboy provides an optional constraints based validation feature -when interacting with user input.

-

Constraints are first used during routing. The router uses -constraints to more accurately match bound values, allowing -to create routes where a segment is an integer for example, -and rejecting the others.

-

Constraints are also used when performing a match operation -on input data, like the query string or cookies. There, a -default value can also be provided for optional values.

-

Finally, constraints can be used to not only validate input, -but also convert said input into proper Erlang terms, all in -one step.

+

Constraints are validation and conversion functions applied +to user input.

+

They are used in various places in Cowboy, including the +router and the request match functions.

-

Structure

+

Syntax

-

Constraints are provided as a list of fields and for each -field a list of constraints for that field can be provided.

-

Fields are either the name of the field; the name and -one or more constraints; or the name, one or more constraints -and a default value.

-

When no default value is provided then the field is required. -Otherwise the default value is used.

-

All constraints for a field will be used to match its value -in the order they are given. If the value is modified by a -constraint, the next constraint receives the updated value.

+

Constraints are provided as a list of fields. For each field +in the list, specific constraints can be applied, as well as +a default value if the field is missing.

+

A field can take the form of an atom field, a tuple with +constraints {field, Constraints} or a tuple with constraints +and a default value {field, Constraints, Default}. +The field form indicates the field is mandatory.

+

Note that when used with the router, only the second form +makes sense, as it does not use the default and the field +is always defined.

+

Constraints for each field are provided as an ordered list +of atoms or funs to apply. Built-in constraints are provided +as atoms, while custom constraints are provided as funs.

+

When multiple constraints are provided, they are applied in +the order given. If the value has been modified by a constraint +then the next one receives the new value.

+

For example, the following constraints will first validate +and convert the field my_value to an integer, and then +check that the integer is positive:

+
+
+
PositiveFun = fun(V) when V > 0 -> true; (_) -> false end,
+{my_value, [int, PositiveFun]}.
+

When there’s only one constraint, it can be provided directly +without wrapping it into a list:

+
+
+
{my_value, int}

Built-in constraints

+

Built-in constraints are specified as an atom:

- + @@ -127,15 +144,34 @@ cellspacing="0" cellpadding="4">
-

Custom constraint

+

Custom constraints

-

In addition to the predefined constraints, Cowboy will accept -a fun. This fun must accept one argument and return one of -true, {true, NewValue} or false. The result indicates -whether the value matches the constraint, and if it does it -can optionally be modified. This allows converting the value -to a more appropriate Erlang term.

-

Note that constraint functions SHOULD be pure and MUST NOT crash.

+

Custom constraints are specified as a fun. This fun takes +a single argument and must return one of true, {true, NewValue} +or false.

+

true indicates the input is valid, false otherwise. +The {true, NewValue} 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:

+
+
+
fun (Value0) when is_binary(Value0) ->
+        try binary_to_integer(Value0) of
+                Value -> {true, Value}
+        catch _:_ ->
+                false
+        end.
+

Constraint functions should only crash because the programmer +made an error when chaining constraints incorrectly (for example +if the constraints were [int, int], and not because of input. +If the input is invalid then false must be returned.

+

In our snippet, the is_binary/1 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.

-- cgit v1.2.3

int

Convert binary value to integer.

Converts binary value to integer.

nonempty