From 4023e7f4e429179fd9c2cce4487c33646c6bd327 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Lo=C3=AFc=20Hoguin?= <essen@ninenines.eu>
Date: Thu, 14 Jan 2016 13:35:25 +0100
Subject: Convert the documentation to Asciidoc

A few small revisions were made, and Erlang.mk has been updated.
---
 doc/src/guide/constraints.asciidoc | 54 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 54 insertions(+)
 create mode 100644 doc/src/guide/constraints.asciidoc

(limited to 'doc/src/guide/constraints.asciidoc')

diff --git a/doc/src/guide/constraints.asciidoc b/doc/src/guide/constraints.asciidoc
new file mode 100644
index 0000000..0ae01d5
--- /dev/null
+++ b/doc/src/guide/constraints.asciidoc
@@ -0,0 +1,54 @@
+[[constraints]]
+== 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.
+
+=== Structure
+
+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.
+
+=== Built-in constraints
+
+[cols="<,<",options="header"]
+|===
+| Constraint | Description
+| int        | Convert binary value to integer.
+| nonempty   | Ensures the binary value is non-empty.
+|===
+
+=== Custom constraint
+
+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.
-- 
cgit v1.2.3

