Skip to content

validate.md

Latest commit

 

History

History
675 lines (430 loc) · 16.3 KB

validate.md

File metadata and controls

675 lines (430 loc) · 16.3 KB
description Validation checks for values and filesystem path types.

validate

Validation checks for values and filesystem path types.

Usage

local validate = require "mods.validate"

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

validate()

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

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

Validator Names

Validator names are case-insensitive for field access.

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

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

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

Functions

Type Checks:

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

Value Checks:

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

Path Checks:

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

Validator API:

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

Type Checks

Basic Lua type validators (and their negated variants).

boolean(v)

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

Parameters:

  • v (any): Value to validate.

Return:

  • ok (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, "expected boolean, got number"

function(v)

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

Parameters:

  • v (any): Value to validate.

Return:

  • ok (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, "expected function, got number"

nil(v)

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

Parameters:

  • v (any): Value to validate.

Return:

  • ok (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, "expected nil, got number"

number(v)

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

Parameters:

  • v (any): Value to validate.

Return:

  • ok (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, "expected number, got string"

string(v)

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

Parameters:

  • v (any): Value to validate.

Return:

  • ok (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, "expected string, got number"

table(v)

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

Parameters:

  • v (any): Value to validate.

Return:

  • ok (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, "expected table, got number"

thread(v)

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

Parameters:

  • v (any): Value to validate.

Return:

  • ok (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, "expected thread, got number"

userdata(v)

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

Parameters:

  • v (any): Value to validate.

Return:

  • ok (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, "expected userdata, got number"

Value Checks

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

false(v)

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

Parameters:

  • v (any): Value to validate.

Return:

  • ok (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, "expected false, got true"

true(v)

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

Parameters:

  • v (any): Value to validate.

Return:

  • ok (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, "expected true, got false"

falsy(v)

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

Parameters:

  • v (any): Value to validate.

Return:

  • ok (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, "expected falsy, got number"

callable(v)

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

Parameters:

  • v (any): Value to validate.

Return:

  • ok (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, "expected callable, got number"

integer(v)

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

Parameters:

  • v (any): Value to validate.

Return:

  • ok (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, "expected integer, got 1.5"

truthy(v)

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

Parameters:

  • v (any): Value to validate.

Return:

  • ok (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, "expected truthy, got boolean"

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.

block(v)

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

Parameters:

  • v (any): Value to validate.

Return:

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

Example:

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

char(v)

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

Parameters:

  • v (any): Value to validate.

Return:

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

Example:

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

device(v)

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

Parameters:

  • v (any): Value to validate.

Return:

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

Example:

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

dir(v)

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

Parameters:

  • v (any): Value to validate.

Return:

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

Example:

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

fifo(v)

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

Parameters:

  • v (any): Value to validate.

Return:

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

Example:

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

file(v)

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

Parameters:

  • v (any): Value to validate.

Return:

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

Example:

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

link(v)

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

Parameters:

  • v (any): Value to validate.

Return:

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

Example:

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

socket(v)

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

Parameters:

  • v (any): Value to validate.

Return:

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

Example:

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

Validator API

register(name, check, msg?)

Register or override a validator function by name.

Parameters:

  • name (string): Validator name.
  • check (fun(v:any):(ok:boolean)): Validator function.
  • msg? (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 msg is provided, it becomes the default message template for that validator.
  • If msg is omitted, failures use: expected {{expected}}, got {{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 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 {{expected}} value, got {{value}}"
validate.truthy(nil) --> false, "expected truthy value, got no value"

Default Messages:

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