2 files changed, 89 insertions(+), 0 deletions(-)

M index.md
A pkg.validator.md

@@ 222,6 222,7 @@ To summarize, the app and packages "startup" lifecycle goes like this:
 * [tulip.pkg.template](pkg.template.md)
 * [tulip.pkg.token](pkg.token.md)
 * [tulip.pkg.urlenc](pkg.urlenc.md)
+* [tulip.pkg.validator](pkg.validator.md)
 * [tulip.pkg.wmiddleware](pkg.wmiddleware.md)
 * [tulip.pkg.worker](pkg.worker.md)
 * [tulip.pkg.wroutes](pkg.wroutes.md)

@@ 0,0 1,88 @@
+The `tulip.pkg.validator` module exports the `validator` package.
+
+# Configuration
+
+None.
+
+# API Extensions
+
+Registering this package provides the following method and field extensions.
+
+## `ok, err|vt = App:validate(t, schema)`
+
+Validates the table t based on the schema definition.
+
+Args:
+* t: table = the table to validate
+* schema: table = the schema definition, see below for details.
+
+Returns:
+* ok: boolean = true on success
+* err: Error|nil = if ok is falsy, the EINVAL error, with the field
+  and value set to the field that failed validation.
+* vt: table = if ok is true, vt contains the flattened validated
+  values under the same keys as the keys or paths in schema. E.g.
+  if schema as "name" and "user.birth.country" as keys, then vt
+  would have their validated values under vt["name"] and
+  vt["user.birth.country"] (flattened under that exact key).
+  Validated values can be slightly different from the raw ones
+  (e.g. converted to another type, normalized).
+
+The schema is a dictionary where the key is a key name or path in t
+(e.g. "email" or "user.age"), and the value is a table that defines
+the validations to apply to that field. Possible fields on that
+validations table are:
+
+* type: string = the type of that value, fails if it is not of that
+  type if present ('integer', 'string', 'boolean')
+* min, max: number = the minimum and maximum value for integers, or
+  the minimum and maximum length in bytes for strings.
+* mincp, maxcp: number = the minimum and maximum number of codepoints
+  for utf-8 strings. Fails if the string is not valid utf8.
+* trim\_ws: boolean = for strings, if true, trims leading and trailing
+  whitespace. This happens after the validation for min/max bytes,
+  but before validation of min/max codepoints, so that a trim is not
+  attempted on an exaggerately long string (via the bytes validation), but
+  one can still require a minimum number of code points to be present
+  after trim.
+* normalize\_ws: boolean = for strings, if true, all spaces are normalized
+  prior to validation for control characters, so that tabs and newlines
+  are turned into standard spaces.
+* allow\_cc: boolean = for strings, if true, allows control characters.
+  By default, control characters raise an error.
+* required: boolean = fails if the value is not present (nil).
+* pattern: string = if set, strings must match this pattern.
+* enum: array = if set, value must match one of those values (can be
+  of any type, must match the type of the field to possibly succeed).
+
+Booleans are a bit different, none of the previous schema validations
+apply to them. By default, they follow Lua's definition of true/false,
+so unless the value is nil or false, it is true. But the following
+schema fields can alter the result of the validation:
+* true\_value: any = if set, only this value is considered true,
+  everything else is false unless false\_value is set.
+* false\_value: any = if set, only this value is considered false,
+  everything else is true unless true\_value is set.
+If both are set, then any value that isn't one of those two is
+considered invalid (basically, this is like an enum for booleans,
+with the added semantics that one means true, the other false).
+
+## `ok, err|vt = Request:validate(schema[, force_ct])`
+
+Validates the decoded body of the Request based on schema. The
+behaviour is the same as App:validate. This is registered by the
+middleware, which must be enabled for that extension to be installed.
+If force\_ct is provided, it is passed to the call to Request:decode\_body.
+
+# Registered Middleware
+
+The following middleware are registered and can be referenced by name in the configuration.
+
+## tulip.pkg.validator
+
+Must be added before any handler that needs to call Request:validate,
+as it registers that extension. Not registered if the middleware
+package is not registered (does not raise an error, as some apps may
+use App:validator without the need for the middleware).
+
+[Back to index](index.md#reference)