Module corky.validator

Parameter validation for Corky.

This class provides methods for validating a value.

Usage example:

-- The module will return the constructor:
local validator = require "corky.validator"

-- Create a new validator instance for a value:
local instance = validator (some_value)

-- Validate it (the value must pass all tests):
instance.number       (   )
instance.less_than    ( 10)
instance.greater_than (-10)
instance.not_equals   (  0)

-- Get the value and the validation result:
local valid, value = instance.get ()

A short form exists, too. You can write the code above like this:

-- Get the constructor:
local v = require "corky.validator"

-- Same validations as above, plus getting the results, in one line:
local valid, value = v (some_value) . n . lt (10) . gt (-10) . ne (0) . get ()

-- Same as above, using the "constructor" instead of get():
local valid, value = v{v (some_value) . n . lt (10) . gt (-10) . ne (0) }

General information:

A validator instance basically contains a value and a validation result.

The first parameter passed to the constructor specifies the (initial) value of the value. The second (optional) parameter specifies the initial value of the validation result. If it is not specified, it defaults to true.

The validation methods may change both the value and the validation result, see the description of the individual methods for details.

If a validation fails (and thus the validation result is set to false), this validation result is final! Actual validation (or conversion) code will be skipped after that, no matter what methods are called. This also means that if the initial validation state is set to false via the constructor, no validation/conversion code will be run for that instance at all.

The final result (i.e. the final, possibly modified value), and the validation result (either true or false) may be retrieved using the get() method, or by calling the "constructor" function with one parameter, which must be an array with one element, which must be the validator instance:

local instance = validator (some_value)

-- Validation method calls omitted…

local valid, value = validator ({ instance })

Parentheses may be omitted in this case:

local valid, value = validator { instance }

Methods may be called one after the other as multiple statements, as shown in the very first example above. In that case, method notation, i.e. instance.<method> (), is required, no matter if a method expects parameters or not.

Validation and conversion methods return the instance, and thus methods may also be chained. For example:

instance.number ().less_than (10)

In that case, parentheses may be ommitted for methods that do not expect any parameters (unless the method is the last one in the statement):

instance.number.less_than (10)

For most methods there are short aliases defined, e.g. the number() method may also be called as num or n. All these features combined allow the short format mentioned above (with v being the "constructor"):

local valid, value = v{v (some_value) . n . lt (10) . gt (-10) . ne (0) }

Methods are named after the condition the value has to fulfill to pass the validation, e.g. the validation

instance.number.less_than (10).not_equal (0)

will only succeed if the value is a number (or a value that can be converted to a number), and if the value is less than 10, and if the value is not 0.

To only retrieve the (possibly modified) value or the validation result, the two properties value and valid may be used. These are not methods:

local value = instance.value
local valid = instance.valid

As a shortcut to get the validation result, the unary minus operator may be used:

local valid = - instance

This allows for omitting the outer "constructor" call, for example if the validation is done in an if statement:

if - v (some_value) . n . lt (10) . ne (0) then
   -- Do some stuff if some_value is valid…
end

With Lua 5.2 or later, the length operator (#) may be used as a shortcut to get the value:

local value = # instance

Info:

  • Copyright: © 2015-2017 Stefan Göbel
  • Release: 2017033001
  • License: GPLv3
  • Author: Stefan Göbel [⌂] [✉]

Functions

validator (value[, valid]) Constructor, or getter.

Properties

instance The following list shows the instance properties that are available.

Methods

get () Get the validation status and the value.

General

required () Check if a required value is nil.
optional () Check if an optional value is nil.
default_value (default) Set a default value.
change_value (new_value) Changes the value.
type (...) Check the type of the value.
external (func, ...) Call an external validation function.
equal (...) Check if the value equals one of the parameters.
not_equal (match) Check if the value does not equal the parameter.

Numbers

number ([base]) Check if the value can be converted to a number.
in_range (min, max) Check if the value is in the specified range.
greater_than (number) Check if the value is greater than the parameter.
less_than (number) Check if the value is less than the parameter.
greater_or_equal (number) Check if the value is greater than or equal to the parameter.
less_or_equal (number) Check if the value is less than or equal to the parameter.
divisible (...) Check if the value is divisible by one of the parameters.

Strings

string () Check if the value can be converted to a string.
optional_empty () Check if an optional value is an empty string.
not_empty () Check for an empty string.
empty_to_nil () Set the value to nil if it is an empty string.
length () Change the value to its string length.

Conditional

next_if (condition[, number]) Skip the next check(s) if a condition is met.


Functions

validator (value[, valid]) line 740
Constructor, or getter.

This function is returned by the module:

local validator = require "corky.validator"

If the first parameter of this function is an array with one element (at position 1), and this one element is a validator instance, the function will return the current validation result and the current value of that instance, in that order. This is just syntactic sugar, it may be used instead of the get() method. Please see above for usage examples.

In all other cases, this function will return a new validator instance, with the current value set to the value specified as the first parameter. The optional second parameter may be used to set the initial validation result, it must be either true or false.

Parameters:

  • value The initial value of a new validator instance, or an array containing an existing instance when used as a getter.
  • valid bool The initial validation result. (optional)

Returns:

  1. Either the new validator instance, or the instance's validation result and value when used as a getter.

Properties

instance line 189
The following list shows the instance properties that are available. Note that these are read-only, trying to set them will be silently ignored.

Fields:

  • valid The current validation result, either true or false.
  • value The current validation value.

Methods

get () line 201
Get the validation status and the value.

Returns:

  1. The validation result, either true or false.
  2. The current value.

General

required () line 258
Check if a required value is nil.

If the value is nil, it will be marked as invalid.

Aliases: r, req

optional () line 276
Check if an optional value is nil.

If the value is nil, it will be considered valid, but all following validation methods will be skipped (the result is final).

Aliases: o, opt

default_value (default) line 298
Set a default value.

This method will modify the value!

If the value is nil, it will be set to the specified default value. This will be considered valid. All following validation methods will be skipped (the result is final).

Aliases: dv, def

Parameters:

  • default The default value.
change_value (new_value) line 322
Changes the value.

This method will modify the value!

This method will not modify the validation result.

Changes the value to the value specified by the parameter.

Aliases: ch

Parameters:

  • new_value The new value.
type (...) line 340
Check the type of the value.

If the type of the value matches one of the parameters, the validation passes. Else the value will be marked as invalid.

Aliases: t

Parameters:

  • ... An arbitrary number of strings specifying the allowed types for the value. Valid type names are "nil", "boolean", "number", "string", "userdata", "function", "thread", and "table".
external (func, ...) line 367
Call an external validation function.

The first parameter must be a function. It will be called with the value as the first parameter, all remaining parameters will be passed to the function after the value. The return value of the function will be used in boolean context, if it evaluates to false, e.g. if it is false or nil, the value will be marked as invalid.

Aliases: x, ext

Parameters:

  • func function The function to call.
  • ... Additional parameters to pass to the function.
equal (...) line 389
Check if the value equals one of the parameters.

An arbitrary number of parameters may be specified. If the value matches one of these, the validation passes, if it does not match one of the parameters, it will be marked as invalid.

Note: If called without any parameters the value will be marked as invalid!

Aliases: e, eq

Parameters:

  • ... An arbitrary number of arbitrary values against which the value will be checked.
not_equal (match) line 412
Check if the value does not equal the parameter.

If the value equals the parameter, it will be marked as invalid.

Aliases: ne, neq

Parameters:

  • match An arbitrary value to check against.

Numbers

number ([base]) line 444
Check if the value can be converted to a number.

This method will modify the value!

This method will convert the value to a number (by calling tonumber()). If this fails, the value will be marked as invalid.

Note: For a type check without conversion the type() method may be used. To check if the value can be converted to a number without converting it the external() method may be used with tonumber as parameter.

Aliases: n, num

Parameters:

  • base number Will be passed to tonumber(), see there for more details. (optional)
in_range (min, max) line 466
Check if the value is in the specified range.

This method will mark the value as invalid if it is less than the specified minimum or greater than the specified maximum value.

Aliases: ir, range

Parameters:

  • min number The minimum value.
  • max number The maximum value.
greater_than (number) line 485
Check if the value is greater than the parameter.

If the value is greater than the parameter, the validation passes, else it will be marked as invalid.

Aliases: gt

Parameters:

  • number number The value to compare.
less_than (number) line 503
Check if the value is less than the parameter.

If the value is less than the parameter, the validation passes, else it will be marked as invalid.

Aliases: lt

Parameters:

  • number number The value to compare.
greater_or_equal (number) line 522
Check if the value is greater than or equal to the parameter.

If the value is greater than or equal to the parameter, the validation passes, else it will be marked as invalid.

Aliases: ge

Parameters:

  • number number The value to compare.
less_or_equal (number) line 541
Check if the value is less than or equal to the parameter.

If the value is less than or equal to the parameter, the validation passes, else it will be marked as invalid.

Aliases: le

Parameters:

  • number number The value to compare.
divisible (...) line 559
Check if the value is divisible by one of the parameters.

If the value is divisible by one of the parameters, the check passes, else it will be marked as invalid.

Aliases: d, div

Parameters:

  • ... An arbitrary number of numbers to check against.

Strings

string () line 589
Check if the value can be converted to a string.

This method will modify the value!

This method will convert the value to a string (by calling tostring()). If this fails, the value will be marked as invalid [not sure if this can happen].

Note: For a type check without conversion the type() method may be used.

optional_empty () line 608
Check if an optional value is an empty string.

If the value is an empty string (""), it will be considered valid, and all following validation methods will be skipped (the result is final).

Aliases: oe, oem

not_empty () line 625
Check for an empty string.

If the value (which must be a string, this is not checked by this method) is empty (i.e. ""), it will be marked as invalid.

Aliases: nm, nem

empty_to_nil () line 644
Set the value to nil if it is an empty string.

This method will modify the value!

This method will not modify the validation result.

Aliases: en, etn

length () line 666
Change the value to its string length.

This method will modify the value!

This method will not modify the validation result.

string.len() will be called for the current value, and the value will be changed to the result.

Aliases: l, len

Conditional

next_if (condition[, number]) line 696
Skip the next check(s) if a condition is met.

This method will not modify the validation result.

The first parameter will be evaluated in boolean context. If it is a false value, the following validation methods will be skipped, if it is a true value nothing will be done and processing continues with the next method. The number of methods to skip may be specified using the second parameter, it must be an integer greater than or equal to 1. It defaults to 1 if not specified. The next_if() method itself does not modify the validation result or the value.

Aliases: ni, nif

Parameters:

  • condition bool The condition, its value will be evaluated in boolean context.
  • number int The number of validations to skip. (optional)
generated by LDoc 1.4.6 Last updated 2019-02-14 20:51:07