diff --git a/docs/src/modules/is.md b/docs/src/modules/is.md index 2ce5488..abcb908 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." +description: "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..502eee8 100644 --- a/docs/src/modules/keyword.md +++ b/docs/src/modules/keyword.md @@ -1,5 +1,5 @@ --- -desc: "Lua keyword helpers." +description: "Lua keyword helpers." --- # `keyword` @@ -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/list.md b/docs/src/modules/list.md index 0071d9c..3e0f300 100644 --- a/docs/src/modules/list.md +++ b/docs/src/modules/list.md @@ -1,5 +1,5 @@ --- -desc: +description: "A list class providing common operations to create, modify, and query sequences of values." --- diff --git a/docs/src/modules/operator.md b/docs/src/modules/operator.md index a836ca8..ae780ac 100644 --- a/docs/src/modules/operator.md +++ b/docs/src/modules/operator.md @@ -1,5 +1,5 @@ --- -desc: "Operator helpers as functions." +description: "Operator helpers as functions." --- # `operator` diff --git a/docs/src/modules/repr.md b/docs/src/modules/repr.md index 2590049..e0ffceb 100644 --- a/docs/src/modules/repr.md +++ b/docs/src/modules/repr.md @@ -1,5 +1,5 @@ --- -desc: "Render any Lua value as a readable string." +description: "Render any Lua value as a readable string." --- # `repr` diff --git a/docs/src/modules/runtime.md b/docs/src/modules/runtime.md index adfe43c..e8c2b99 100644 --- a/docs/src/modules/runtime.md +++ b/docs/src/modules/runtime.md @@ -1,5 +1,5 @@ --- -desc: "Exposes Lua runtime metadata and version compatibility flags." +description: "Exposes Lua runtime metadata and version compatibility flags." --- # `runtime` @@ -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/set.md b/docs/src/modules/set.md index 1c6768d..ad774bf 100644 --- a/docs/src/modules/set.md +++ b/docs/src/modules/set.md @@ -1,5 +1,5 @@ --- -desc: +description: "A set class providing common operations to create, modify, and query collections of unique values." --- diff --git a/docs/src/modules/str.md b/docs/src/modules/str.md index 391a811..6ed0bc6 100644 --- a/docs/src/modules/str.md +++ b/docs/src/modules/str.md @@ -1,5 +1,5 @@ --- -desc: "String utility helpers modeled after Python's `str`." +description: "String utility helpers modeled after Python's `str`." --- # `str` @@ -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/stringcase.md b/docs/src/modules/stringcase.md index 69c02ed..d073e0f 100644 --- a/docs/src/modules/stringcase.md +++ b/docs/src/modules/stringcase.md @@ -1,5 +1,5 @@ --- -desc: "String case conversion helpers." +description: "String case conversion helpers." --- # `stringcase` diff --git a/docs/src/modules/tbl.md b/docs/src/modules/tbl.md index 1e8128d..17590a0 100644 --- a/docs/src/modules/tbl.md +++ b/docs/src/modules/tbl.md @@ -1,5 +1,5 @@ --- -desc: "Utility functions for working with Lua tables." +description: "Utility functions for working with Lua tables." --- # `tbl` @@ -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..6488c2d 100644 --- a/docs/src/modules/template.md +++ b/docs/src/modules/template.md @@ -1,5 +1,5 @@ --- -desc: "Interpolate string placeholders of the form {{." +description: "Interpolate string placeholders of the form {{." --- # `template` @@ -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..9bdd03c 100644 --- a/docs/src/modules/utils.md +++ b/docs/src/modules/utils.md @@ -1,5 +1,5 @@ --- -desc: "Small shared utility helpers used by modules in this library." +description: "Small shared utility helpers used by modules in this library." --- # `utils` @@ -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..53e3d36 100644 --- a/docs/src/modules/validate.md +++ b/docs/src/modules/validate.md @@ -1,5 +1,5 @@ --- -desc: "Validation checks for values and filesystem path types." +description: "Validation checks for values and filesystem path types." --- # `validate` @@ -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}}