~mna/tulip-wiki

a2757edf4b694549b95e27eefa1b94d192e9bd42 — Martin Angers 1 year, 8 months ago 88c5ab2 v0.2.0-1
Document the validator package
2 files changed, 89 insertions(+), 0 deletions(-)

M index.md
A pkg.validator.md
M index.md => index.md +1 -0
@@ 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)

A pkg.validator.md => pkg.validator.md +88 -0
@@ 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)