validate

Validation helpers for Lua values and filesystem path types.

Usage

local validate = require "mods.validate"

ok, err = validate.number("nope") --> false, "number expected, got string"
ok, err = validate(123, "number") --> true, nil

validate()

validate(v, validator) dispatches to the registered validator. If validator is omitted, it defaults to "truthy".

validate()         --> false, "truthy value expected, got no value"
validate(1)        --> true, nil
validate(1, "nil") --> false, "nil expected, got number"

Validator Names

Validator names are case-insensitive for field access.

validate.number(1) --> true, nil
validate.NumBer(1) --> true, nil

validator in validate(v, validator) is matched as-is (case-sensitive):

validate(1, "number") --> true, nil
validate(1, "NuMbEr") --> false, "NuMbEr expected, got number"

Custom Messages

Validator functions accept an optional template override as the second argument: validate.number(v, "need {{expected}}, got {{got}}")`.

You can also set validate.messages.<name> to define default templates per validator.

validate.string(123, "want {{expected}}, got {{got}}")
--> false, "want string, got number"

Functions

Type Checks:

Function	Description
boolean(v, msg?)	Returns true when v is a boolean. Otherwise returns false and an error message.
function(v, msg?)	Returns true when v is a function. Otherwise returns false and an error message.
nil(v, msg?)	Returns true when v is nil. Otherwise returns false and an error message.
number(v, msg?)	Returns true when v is a number. Otherwise returns false and an error message.
string(v, msg?)	Returns true when v is a string. Otherwise returns false and an error message.
table(v, msg?)	Returns true when v is a table. Otherwise returns false and an error message.
thread(v, msg?)	Returns true when v is a thread. Otherwise returns false and an error message.
userdata(v, msg?)	Returns true when v is a userdata value. Otherwise returns false and an error message.

Value Checks:

Function	Description
false(v, msg?)	Returns true when v is exactly false. Otherwise returns false and an error message.
true(v, msg?)	Returns true when v is exactly true. Otherwise returns false and an error message.
falsy(v, msg?)	Returns true when v is falsy. Otherwise returns false and an error message.
callable(v, msg?)	Returns true when v is callable. Otherwise returns false and an error message.
integer(v, msg?)	Returns true when v is an integer. Otherwise returns false and an error message.
truthy(v, msg?)	Returns true when v is truthy. Otherwise returns false and an error message.

Path Checks:

Function	Description
path(v, msg?)	Returns true when v is a valid filesystem path. Otherwise returns false and an error message.
block(v, msg?)	Returns true when v is a block device path. Otherwise returns false and an error message.
char(v, msg?)	Returns true when v is a char device path. Otherwise returns false and an error message.
device(v, msg?)	Returns true when v is a block or char device path. Otherwise returns false and an error message.
dir(v, msg?)	Returns true when v is a directory path. Otherwise returns false and an error message.
fifo(v, msg?)	Returns true when v is a FIFO path. Otherwise returns false and an error message.
file(v, msg?)	Returns true when v is a file path. Otherwise returns false and an error message.
link(v, msg?)	Returns true when v is a symlink path. Otherwise returns false and an error message.
socket(v, msg?)	Returns true when v is a socket path. Otherwise returns false and an error message.

Validator API:

Function	Description
register(name, validator, template?)	Register or override a validator function by name.

Type Checks

Basic Lua type validators (and their negated variants).

boolean(v, msg?)

Returns true when v is a boolean. Otherwise returns false and an error message.

Parameters:

• v (any): Value to validate.
• msg? (string): Optional override template.

Return:

• isValid (boolean): Whether the check succeeds.
• err (string?): Error message when the check fails.

Example:

ok, err = validate.boolean(true) --> true, nil
ok, err = validate.boolean(1)    --> false, "boolean expected, got number"

function(v, msg?)

Returns true when v is a function. Otherwise returns false and an error message.

Parameters:

• v (any): Value to validate.
• msg? (string): Optional override template.

Return:

• isValid (boolean): Whether the check succeeds.
• err (string?): Error message when the check fails.

Example:

ok, err = validate.Function(function() end) --> true, nil
ok, err = validate.Function(1)
--> false, "function expected, got number"

nil(v, msg?)

Returns true when v is nil. Otherwise returns false and an error message.

Parameters:

• v (any): Value to validate.
• msg? (string): Optional override template.

Return:

• isValid (boolean): Whether the check succeeds.
• err (string?): Error message when the check fails.

Example:

ok, err = validate.Nil(nil) --> true, nil
ok, err = validate.Nil(0)   --> false, "nil expected, got number"

number(v, msg?)

Returns true when v is a number. Otherwise returns false and an error message.

Parameters:

• v (any): Value to validate.
• msg? (string): Optional override template.

Return:

• isValid (boolean): Whether the check succeeds.
• err (string?): Error message when the check fails.

Example:

ok, err = validate.number(42)  --> true, nil
ok, err = validate.number("x") --> false, "number expected, got string"

string(v, msg?)

Returns true when v is a string. Otherwise returns false and an error message.

Parameters:

• v (any): Value to validate.
• msg? (string): Optional override template.

Return:

• isValid (boolean): Whether the check succeeds.
• err (string?): Error message when the check fails.

Example:

ok, err = validate.string("hello") --> true, nil
ok, err = validate.string(1)       --> false, "string expected, got number"

table(v, msg?)

Returns true when v is a table. Otherwise returns false and an error message.

Parameters:

• v (any): Value to validate.
• msg? (string): Optional override template.

Return:

• isValid (boolean): Whether the check succeeds.
• err (string?): Error message when the check fails.

Example:

ok, err = validate.table({}) --> true, nil
ok, err = validate.table(1)  --> false, "table expected, got number"

thread(v, msg?)

Returns true when v is a thread. Otherwise returns false and an error message.

Parameters:

• v (any): Value to validate.
• msg? (string): Optional override template.

Return:

• isValid (boolean): Whether the check succeeds.
• err (string?): Error message when the check fails.

Example:

co = coroutine.create(function() end)
ok, err = validate.thread(co) --> true, nil
ok, err = validate.thread(1)  --> false, "thread expected, got number"

userdata(v, msg?)

Returns true when v is a userdata value. Otherwise returns false and an error message.

Parameters:

• v (any): Value to validate.
• msg? (string): Optional override template.

Return:

• isValid (boolean): Whether the check succeeds.
• err (string?): Error message when the check fails.

Example:

ok, err = validate.userdata(io.stdout) --> true, nil
ok, err = validate.userdata(1)         --> false, "userdata expected, got number"

Value Checks

Value-state validators (exact true/false, truthy/falsy, callable, integer).

false(v, msg?)

Returns true when v is exactly false. Otherwise returns false and an error message.

Parameters:

• v (any): Value to validate.
• msg? (string): Optional override template.

Return:

• isValid (boolean): Whether the check succeeds.
• err (string?): Error message when the check fails.

Example:

ok, err = validate.False(false) --> true, nil
ok, err = validate.False(true)  --> false, "false value expected, got true"

true(v, msg?)

Returns true when v is exactly true. Otherwise returns false and an error message.

Parameters:

• v (any): Value to validate.
• msg? (string): Optional override template.

Return:

• isValid (boolean): Whether the check succeeds.
• err (string?): Error message when the check fails.

Example:

ok, err = validate.True(true)  --> true, nil
ok, err = validate.True(false) --> false, "true value expected, got false"

falsy(v, msg?)

Returns true when v is falsy. Otherwise returns false and an error message.

Parameters:

• v (any): Value to validate.
• msg? (string): Optional override template.

Return:

• isValid (boolean): Whether the check succeeds.
• err (string?): Error message when the check fails.

Example:

ok, err = validate.falsy(false) --> true, nil
ok, err = validate.falsy(1)     --> false, "falsy value expected, got 1"

callable(v, msg?)

Returns true when v is callable. Otherwise returns false and an error message.

Parameters:

• v (any): Value to validate.
• msg? (string): Optional override template.

Return:

• isValid (boolean): Whether the check succeeds.
• err (string?): Error message when the check fails.

Example:

ok, err = validate.callable(type) --> true, nil
ok, err = validate.callable(1)    --> false, "callable value expected, got 1"

integer(v, msg?)

Returns true when v is an integer. Otherwise returns false and an error message.

Parameters:

• v (any): Value to validate.
• msg? (string): Optional override template.

Return:

• isValid (boolean): Whether the check succeeds.
• err (string?): Error message when the check fails.

Example:

ok, err = validate.integer(1)   --> true, nil
ok, err = validate.integer(1.5) --> false, "integer value expected, got 1.5"

truthy(v, msg?)

Returns true when v is truthy. Otherwise returns false and an error message.

Parameters:

• v (any): Value to validate.
• msg? (string): Optional override template.

Return:

• isValid (boolean): Whether the check succeeds.
• err (string?): Error message when the check fails.

Example:

ok, err = validate.truthy(1)     --> true, nil
ok, err = validate.truthy(false) --> false, "truthy value expected, got false"

Path Checks

Filesystem path-kind validators backed by LuaFileSystem (lfs).

IMPORTANT

Path checks require LuaFileSystem (lfs) and raise an error if it is not installed.

path(v, msg?)

Returns true when v is a valid filesystem path. Otherwise returns false and an error message.

Parameters:

• v (any): Value to validate.
• msg? (string): Optional override template.

Return:

• isValid (boolean): Whether the check succeeds.
• err (string?): Error message when the check fails.

Example:

ok, err = validate.path("README.md")

block(v, msg?)

Returns true when v is a block device path. Otherwise returns false and an error message.

Parameters:

• v (any): Value to validate.
• msg? (string): Optional override template.

Return:

• isValid (boolean): Whether the check succeeds.
• err (string?): Error message when the check fails.

Example:

ok, err = validate.block(".")

char(v, msg?)

Returns true when v is a char device path. Otherwise returns false and an error message.

Parameters:

• v (any): Value to validate.
• msg? (string): Optional override template.

Return:

• isValid (boolean): Whether the check succeeds.
• err (string?): Error message when the check fails.

Example:

ok, err = validate.char(".")

device(v, msg?)

Returns true when v is a block or char device path. Otherwise returns false and an error message.

Parameters:

• v (any): Value to validate.
• msg? (string): Optional override template.

Return:

• isValid (boolean): Whether the check succeeds.
• err (string?): Error message when the check fails.

Example:

ok, err = validate.device(".")

dir(v, msg?)

Returns true when v is a directory path. Otherwise returns false and an error message.

Parameters:

• v (any): Value to validate.
• msg? (string): Optional override template.

Return:

• isValid (boolean): Whether the check succeeds.
• err (string?): Error message when the check fails.

Example:

ok, err = validate.dir(".")

fifo(v, msg?)

Returns true when v is a FIFO path. Otherwise returns false and an error message.

Parameters:

• v (any): Value to validate.
• msg? (string): Optional override template.

Return:

• isValid (boolean): Whether the check succeeds.
• err (string?): Error message when the check fails.

Example:

ok, err = validate.fifo(".")

file(v, msg?)

Returns true when v is a file path. Otherwise returns false and an error message.

Parameters:

• v (any): Value to validate.
• msg? (string): Optional override template.

Return:

• isValid (boolean): Whether the check succeeds.
• err (string?): Error message when the check fails.

Example:

ok, err = validate.file(".")

link(v, msg?)

Returns true when v is a symlink path. Otherwise returns false and an error message.

Parameters:

• v (any): Value to validate.
• msg? (string): Optional override template.

Return:

• isValid (boolean): Whether the check succeeds.
• err (string?): Error message when the check fails.

Example:

ok, err = validate.link(".")

socket(v, msg?)

Returns true when v is a socket path. Otherwise returns false and an error message.

Parameters:

• v (any): Value to validate.
• msg? (string): Optional override template.

Return:

• isValid (boolean): Whether the check succeeds.
• err (string?): Error message when the check fails.

Example:

ok, err = validate.socket(".")

Validator API

register(name, validator, template?)

Register or override a validator function by name.

Parameters:

• name (string): Validator name.
• validator (fun(v:any):(ok:boolean)): Validator function.
• template? (string): Optional default message template.

Return:

• none (nil)

Example:

validate.register("odd", function(v)
  return type(v) == "number" and v % 2 == 1
end, "{{value}} does not satisfy {{expected}}")

ok, err = validate.odd(3)     --> true, nil
ok, err = validate.odd("x")   --> false, '"x" does not satisfy odd'
ok, err = validate(2, "odd")  --> false, "2 does not satisfy odd"

NOTE

• If template is provided, it becomes the default message template for that validator.
• If template is omitted, failures use: expected, got .

Fields

messages

Custom error-message templates for validator failures.

Set validate.messages.<name>, where <name> is a validator name (for example: number, truthy, file).

The error-message template is used only when validation fails and an error message is returned.

validate.messages.number = "need {{expected}}, got {{got}}"
ok, err = validate.number("x") --> false, "need number, got string"

Placeholders:

• {{expected}}: The check target (for example number, string, truthy).
• {{got}}: The detected failure kind (usually a Lua type; path validators use invalid path).
• {{value}}: The passed value, formatted for display (strings are quoted).

NOTE

When the passed value is nil, rendered value text uses no value.

validate.messages.truthy = "{{expected}} value expected, got {{value}}"
validate.truthy(nil) --> false, "truthy value expected, got no value"

Default Messages:

• Type checks: {{expected}} expected, got {{got}}
• Value checks: {{expected}} value expected, got {{value}}
• Path checks: {{value}} is not a valid {{expected}} path (for path: {{value}} is not a valid path)

NOTE

For path checks, if the value is not a string, the message falls back to messages.string (as if validate.string was called).