From 9df1aa0b07bf4de3bf6138e08030df6b044b8fee Mon Sep 17 00:00:00 2001 From: haithium <128622475+haithium@users.noreply.github.com> Date: Tue, 3 Mar 2026 22:31:21 +0000 Subject: [PATCH] chore(docs): auto-generate docs --- docs/src/modules/is.md | 34 ++++++++++---------- docs/src/modules/keyword.md | 20 ++++++------ docs/src/modules/runtime.md | 9 ++++++ docs/src/modules/str.md | 3 +- docs/src/modules/tbl.md | 24 --------------- docs/src/modules/template.md | 3 +- docs/src/modules/utils.md | 60 +++++++++++++++++++++++++++--------- docs/src/modules/validate.md | 4 +-- 8 files changed, 84 insertions(+), 73 deletions(-) diff --git a/docs/src/modules/is.md b/docs/src/modules/is.md index 2ce5488..f744c89 100644 --- a/docs/src/modules/is.md +++ b/docs/src/modules/is.md @@ -1,10 +1,10 @@ --- -desc: "Type predicates for Lua values and filesystem path kinds." +desc: "Type predicates for Lua values and filesystem path types." --- # `is` -Type predicates for Lua values and filesystem path kinds. +Type predicates for Lua values and filesystem path types. ## Usage @@ -65,16 +65,16 @@ is("hello", "STRING") --> true **Path Checks**: -| Function | Description | -| ------------------------- | ------------------------------------------------------- | -| [`block(v)`](#fn-block) | Returns `true` when `v` is a block device path. | -| [`char(v)`](#fn-char) | Returns `true` when `v` is a char device path. | -| [`device(v)`](#fn-device) | Returns `true` when `v` is a block or char device path. | -| [`dir(v)`](#fn-dir) | Returns `true` when `v` is a directory path. | -| [`fifo(v)`](#fn-fifo) | Returns `true` when `v` is a FIFO path. | -| [`file(v)`](#fn-file) | Returns `true` when `v` is a file path. | -| [`link(v)`](#fn-link) | Returns `true` when `v` is a symlink path. | -| [`socket(v)`](#fn-socket) | Returns `true` when `v` is a socket path. | +| Function | Description | +| ------------------------- | ------------------------------------------------------------ | +| [`block(v)`](#fn-block) | Returns `true` when `v` is a block device path. | +| [`char(v)`](#fn-char) | Returns `true` when `v` is a character device path. | +| [`device(v)`](#fn-device) | Returns `true` when `v` is a block or character device path. | +| [`dir(v)`](#fn-dir) | Returns `true` when `v` is a directory path. | +| [`fifo(v)`](#fn-fifo) | Returns `true` when `v` is a FIFO path. | +| [`file(v)`](#fn-file) | Returns `true` when `v` is a file path. | +| [`link(v)`](#fn-link) | Returns `true` when `v` is a symlink path. | +| [`socket(v)`](#fn-socket) | Returns `true` when `v` is a socket path. | ### Type Checks @@ -362,13 +362,13 @@ is.truthy("non-empty") ### Path Checks -Filesystem path kind checks. +Filesystem path type checks. > [!IMPORTANT] > > Path checks require **LuaFileSystem** -> ([`lfs`](https://github.com/lunarmodules/luafilesystem)) and raise an error it -> is not installed. +> ([`lfs`](https://github.com/lunarmodules/luafilesystem)) and raise an error if +> it is not installed. #### `block(v)` @@ -392,7 +392,7 @@ is.block("/dev/sda") #### `char(v)` -Returns `true` when `v` is a char device path. +Returns `true` when `v` is a character device path. **Parameters**: @@ -412,7 +412,7 @@ is.char("/dev/null") #### `device(v)` -Returns `true` when `v` is a block or char device path. +Returns `true` when `v` is a block or character device path. **Parameters**: diff --git a/docs/src/modules/keyword.md b/docs/src/modules/keyword.md index 600eab1..c4184c4 100644 --- a/docs/src/modules/keyword.md +++ b/docs/src/modules/keyword.md @@ -17,13 +17,13 @@ kw.isidentifier("hello_world") --> true ## Functions -| Function | Description | -| ----------------------------------------------------- | ----------------------------------------------------------------------------------- | -| [`iskeyword(v)`](#fn-iskeyword) | Return `true` when `v` is a reserved Lua keyword. | -| [`isidentifier(v)`](#fn-isidentifier) | Return `true` when `v` is a valid non-keyword Lua identifier. | -| [`kwlist()`](#fn-kwlist) | Return Lua keywords as a [`mods.List`](https://luamod.github.io/mods/modules/list). | -| [`kwset()`](#fn-kwset) | Return Lua keywords as a [`mods.Set`](https://luamod.github.io/mods/modules/set). | -| [`normalize_identifier(s)`](#fn-normalize-identifier) | Normalize an input into a safe Lua identifier. | +| Function | Description | +| ----------------------------------------------------- | ------------------------------------------------------------- | +| [`iskeyword(v)`](#fn-iskeyword) | Return `true` when `v` is a reserved Lua keyword. | +| [`isidentifier(v)`](#fn-isidentifier) | Return `true` when `v` is a valid non-keyword Lua identifier. | +| [`kwlist()`](#fn-kwlist) | Return Lua keywords as a [`mods.List`](/modules/list). | +| [`kwset()`](#fn-kwset) | Return Lua keywords as a [`mods.Set`](/modules/set). | +| [`normalize_identifier(s)`](#fn-normalize-identifier) | Normalize an input into a safe Lua identifier. | @@ -71,8 +71,7 @@ kw.isidentifier("local") --> false ### `kwlist()` -Return Lua keywords as a -[`mods.List`](https://luamod.github.io/mods/modules/list). +Return Lua keywords as a [`mods.List`](/modules/list). **Return**: @@ -88,8 +87,7 @@ kw.kwlist():contains("and") --> true ### `kwset()` -Return Lua keywords as a -[`mods.Set`](https://luamod.github.io/mods/modules/set). +Return Lua keywords as a [`mods.Set`](/modules/set). **Return**: diff --git a/docs/src/modules/runtime.md b/docs/src/modules/runtime.md index adfe43c..2d57209 100644 --- a/docs/src/modules/runtime.md +++ b/docs/src/modules/runtime.md @@ -25,6 +25,7 @@ print(runtime.is_lua54) --> true | false | [`minor`](#minor) | Minor version number parsed from `version`. | | [`version_num`](#version-num) | Numeric version encoded as `major * 100 + minor`. | | [`is_luajit`](#is-luajit) | True when running under LuaJIT. | +| [`is_windows`](#is-windows) | True when running on a Windows host. | | [`is_lua51`](#is-lua51) | True only on Lua 5.1 runtimes. | | [`is_lua52`](#is-lua52) | True only on Lua 5.2 runtimes. | | [`is_lua53`](#is-lua53) | True only on Lua 5.3 runtimes. | @@ -70,6 +71,14 @@ True when running under LuaJIT. print(runtime.is_luajit) --> true | false ``` +### `is_windows` + +True when running on a Windows host. + +```lua +print(runtime.is_windows) --> true | false +``` + ### `is_lua51` True only on Lua 5.1 runtimes. diff --git a/docs/src/modules/str.md b/docs/src/modules/str.md index 391a811..1d21cda 100644 --- a/docs/src/modules/str.md +++ b/docs/src/modules/str.md @@ -247,8 +247,7 @@ s = format_map("hi {name}", { name = "bob" }) --> "hi bob" > [!NOTE] > > `format_map` is a lightweight `{key}` replacement helper. For richer -> templating, use -> [`mods.template`](https://luamod.github.io/mods/modules/template). +> templating, use [`mods.template`](/modules/template). ### Predicates diff --git a/docs/src/modules/tbl.md b/docs/src/modules/tbl.md index 1e8128d..9e34758 100644 --- a/docs/src/modules/tbl.md +++ b/docs/src/modules/tbl.md @@ -39,7 +39,6 @@ print(tbl.count({ a = 1, b = 2 })) --> 2 | [`same(a, b)`](#fn-same) | Return `true` if two tables have the same keys and equal values. | | [`find_if(t, pred)`](#fn-find-if) | Find first value and key matching predicate. | | [`get(t, ...)`](#fn-get) | Safely get nested value by keys. | -| [`keypath(...)`](#fn-keypath) | Format a key chain as a Lua-like table access path. | **Transforms**: @@ -263,29 +262,6 @@ v2 = get(t) --> { a = { b = { c = 1 } } } > > If no keys are provided, returns the input table. - - -#### `keypath(...)` - -Format a key chain as a Lua-like table access path. - -**Parameters**: - -- `...` (`any`): Additional arguments. - -**Return**: - -- `path` (`string`): Rendered key path. - -**Example**: - -```lua -p1 = keypath("t", "a", "b", "c") --> "t.a.b.c" -p2 = keypath("ctx", "users", 1, "name") --> "ctx.users[1].name" -p3 = keypath("ctx", "invalid-key") --> 'ctx["invalid-key"]' -p4 = keypath() --> "" -``` - ### Transforms Table transformation and conversion utilities. diff --git a/docs/src/modules/template.md b/docs/src/modules/template.md index 407ffb3..ff9394e 100644 --- a/docs/src/modules/template.md +++ b/docs/src/modules/template.md @@ -85,8 +85,7 @@ template("Hi {{name_func}}", view) --> "Hi Ada" ## Table Values -Table placeholders are rendered using -[`mods.repr`](https://luamod.github.io/mods/modules/repr). +Table placeholders are rendered using `mods.repr`. ```lua view = { data = { a = 1, b = true } } diff --git a/docs/src/modules/utils.md b/docs/src/modules/utils.md index 4fa475d..cf2e051 100644 --- a/docs/src/modules/utils.md +++ b/docs/src/modules/utils.md @@ -24,11 +24,11 @@ Smart-quote a string for readable Lua-like output. **Parameters**: -- `v` (`string`) +- `v` (`string`): String to quote. **Return**: -- `out` (`string`) +- `out` (`string`): Quoted string. **Example**: @@ -37,30 +37,60 @@ print(utils.quote('He said "hi"')) -- 'He said "hi"' print(utils.quote('say "hi" and \\'bye\\'')) -- "say \"hi\" and 'bye'" ``` - + -### `repr(v)` +### `keypath(...)` -Render any Lua value as a string. +Format a key chain as a Lua-like table access path. -> [!NOTE] -> -> Uses [`inspect`](https://github.com/kikito/inspect.lua) when available, -> otherwise falls back to -> [`mods.repr`](https://luamod.github.io/mods/modules/repr). +**Parameters**: + +- `...` (`any`): Additional arguments. + +**Return**: + +- `path` (`string`): Rendered key path. + +**Example**: + +```lua +p1 = utils.keypath("t", "a", "b", "c") --> "t.a.b.c" +p2 = utils.keypath("ctx", "users", 1, "name") --> "ctx.users[1].name" +p3 = utils.keypath("ctx", "invalid-key") --> 'ctx["invalid-key"]' +p4 = utils.keypath() --> "" +``` + + + +### `assert_arg(argn, v, tp?, level?, msg?)` + +Assert argument value using [`mods.validate`](/modules/validate) and raise a Lua +error on failure. **Parameters**: -- `v` (`any`) +- `argn` (`integer`): Argument index for error context. +- `v` (`T`): Value to check. +- `tp?` (`modsIsType`): Validator name (defaults to `"truthy"`). +- `level?` (`integer`): Optional error level for `error(...)` (defaults to `2`). +- `msg?` (`string`): Optional override template passed to + [`mods.validate`](/modules/validate). **Return**: -- `out` (`string`) +- `v` (`T`): Same input value on success. **Example**: ```lua -print(utils.repr({ a = 1 })) --> { --- a = 1 --- } +utils.assert_arg(1, "ok", "string") --> "ok" +utils.assert_arg(2, 123, "string") +--> raises: bad argument #2 (expected string, got number) +utils.assert_arg(3, "x", "number", 2, "need {{expected}}, got {{got}}") +--> raises: bad argument #3 (need number, got string) ``` + +> [!NOTE] +> +> When the caller function name is available, error text includes +> `to ''` (Lua-style bad argument context). diff --git a/docs/src/modules/validate.md b/docs/src/modules/validate.md index d6dbf4a..56c1cec 100644 --- a/docs/src/modules/validate.md +++ b/docs/src/modules/validate.md @@ -667,8 +667,8 @@ ok, err = validate.number("x") --> false, "need number, got string" > validate.messages.truthy = "expected {{expected}} value, got {{value}}" > validate.truthy(nil) --> false, "expected truthy value, got no value" > ``` -> -> **Default Messages**: + +**Default Messages**: - Type checks: expected {{expected}}, got {{got}} - Value checks: expected {{expected}} value, got {{value}}