From 2599c1874f16ade34e95d6b2a23a873d84b5a1b2 Mon Sep 17 00:00:00 2001 From: haithium <128622475+haithium@users.noreply.github.com> Date: Mon, 23 Feb 2026 23:50:37 +0000 Subject: [PATCH] chore(docs): auto-generate docs --- docs/src/modules/is.md | 7 +++++ docs/src/modules/keyword.md | 27 +++++++++++------ docs/src/modules/list.md | 59 +++++++++++++++++++++--------------- docs/src/modules/operator.md | 2 +- docs/src/modules/repr.md | 20 ++++++------ docs/src/modules/set.md | 38 +++++++++++++---------- docs/src/modules/str.md | 52 ++++++++++++++++++------------- docs/src/modules/tbl.md | 56 ++++++++++++++++++---------------- docs/src/modules/utils.md | 14 +++++++++ docs/src/modules/validate.md | 18 +++++++++++ 10 files changed, 184 insertions(+), 109 deletions(-) diff --git a/docs/src/modules/is.md b/docs/src/modules/is.md index 2496421..cfd5dd7 100644 --- a/docs/src/modules/is.md +++ b/docs/src/modules/is.md @@ -26,6 +26,13 @@ ok = is.table({}) --> true > is("hello", "String") --> true > ``` +## Dependencies + +Dependencies below are lazy-loaded 💤 on first access. + +- [`lfs`](https://github.com/lunarmodules/luafilesystem) (optional; required + only for filesystem/path checks) + ## Functions **Type Checks**: diff --git a/docs/src/modules/keyword.md b/docs/src/modules/keyword.md index ec35aff..5131e5c 100644 --- a/docs/src/modules/keyword.md +++ b/docs/src/modules/keyword.md @@ -15,15 +15,22 @@ kw.iskeyword("local")) --> true kw.isidentifier("hello_world") --> true ``` +## Dependencies + +Dependencies below are lazy-loaded 💤 on first access. + +- [`mods.Set`](https://luamod.github.io/mods/modules/set) +- [`mods.List`](https://luamod.github.io/mods/modules/list) + ## Functions -| Function | Description | -| ----------------------------------------------- | ---------------------------------------------------------------------------------------------- | -| [`iskeyword`](#iskeyword) | Return `true` when `s` is a reserved Lua keyword. | -| [`isidentifier`](#isidentifier) | Return `true` when `s` is a valid non-keyword Lua identifier. | -| [`kwlist`](#kwlist) | Return Lua keywords as a [`mods.List`](https://luamod.github.io/mods/modules/list) of strings. | -| [`kwset`](#kwset) | Return Lua keywords as a [`mods.Set`](https://luamod.github.io/mods/modules/set) of strings. | -| [`normalize_identifier`](#normalize-identifier) | Normalize an input into a safe Lua identifier. | +| Function | Description | +| ----------------------------------------------- | ----------------------------------------------------------------------------------- | +| [`iskeyword`](#iskeyword) | Return `true` when `s` is a reserved Lua keyword. | +| [`isidentifier`](#isidentifier) | Return `true` when `s` is a valid non-keyword Lua identifier. | +| [`kwlist`](#kwlist) | Return Lua keywords as a [`mods.List`](https://luamod.github.io/mods/modules/list). | +| [`kwset`](#kwset) | Return Lua keywords as a [`mods.Set`](https://luamod.github.io/mods/modules/set). | +| [`normalize_identifier`](#normalize-identifier) | Normalize an input into a safe Lua identifier. | ### `iskeyword` @@ -46,7 +53,7 @@ kw.isidentifier("local") --> false ### `kwlist` Return Lua keywords as a -[`mods.List`](https://luamod.github.io/mods/modules/list) of strings. +[`mods.List`](https://luamod.github.io/mods/modules/list). ```lua kw.kwlist():contains("and") --> true @@ -54,8 +61,8 @@ kw.kwlist():contains("and") --> true ### `kwset` -Return Lua keywords as a [`mods.Set`](https://luamod.github.io/mods/modules/set) -of strings. +Return Lua keywords as a +[`mods.Set`](https://luamod.github.io/mods/modules/set). ```lua kw.kwlset():contains("and") --> true diff --git a/docs/src/modules/list.md b/docs/src/modules/list.md index 0f5c2a6..c02d2a5 100644 --- a/docs/src/modules/list.md +++ b/docs/src/modules/list.md @@ -12,13 +12,19 @@ query sequences of values. ## Usage ```lua -lsist = require "mods.List" +List = require "mods.List" ls = List({ "a" }):append("b") print(ls:contains("b")) --> true print(ls:index("b")) --> 2 ``` +## Dependencies + +Dependencies below are lazy-loaded 💤 on first access. + +- [`mods.Set`](https://luamod.github.io/mods/modules/set) + ## Functions **Predicates**: @@ -69,25 +75,25 @@ print(ls:index("b")) --> 2 **Transform**: -| Function | Description | -| ------------------------------- | ------------------------------------------------------------------------------------------------- | -| [`difference`](#difference) | Return a new list with values not in the given list. | -| [`drop`](#drop) | Return a new list without the first n elements. | -| [`filter`](#filter) | Return a new list with values matching the predicate. | -| [`flatten`](#flatten) | Flatten one level of nested lists. | -| [`foreach`](#foreach) | Apply a function to each element (for side effects). Returns nil. | -| [`group_by`](#group-by) | Group list values by a computed key. | -| [`intersection`](#intersection) | Return values that are also present in the given list. Order is preserved from the original list. | -| [`invert`](#invert) | Invert values to indices in a new table. | -| [`join`](#join) | Join list values into a string. | -| [`map`](#map) | Return a new list by mapping each value. | -| [`reduce`](#reduce) | Reduce the list to a single value using an accumulator. | -| [`reverse`](#reverse) | Return a new list with items reversed. | -| [`setify`](#setify) | Convert the list to a set. | -| [`slice`](#slice) | Return a new list containing items from i to j (inclusive). | -| [`take`](#take) | Return the first n elements as a new list. | -| [`uniq`](#uniq) | Return a new list with duplicates removed (first occurrence kept). | -| [`zip`](#zip) | Zip two lists into a list of 2-element tables. | +| Function | Description | +| ------------------------------- | ------------------------------------------------------------------ | +| [`difference`](#difference) | Return a new list with values not in the given list. | +| [`drop`](#drop) | Return a new list without the first n elements. | +| [`filter`](#filter) | Return a new list with values matching the predicate. | +| [`flatten`](#flatten) | Flatten one level of nested lists. | +| [`foreach`](#foreach) | Apply a function to each element (for side effects). | +| [`group_by`](#group-by) | Group list values by a computed key. | +| [`intersection`](#intersection) | Return values that are also present in the given list. | +| [`invert`](#invert) | Invert values to indices in a new table. | +| [`join`](#join) | Join list values into a string. | +| [`map`](#map) | Return a new list by mapping each value. | +| [`reduce`](#reduce) | Reduce the list to a single value using an accumulator. | +| [`reverse`](#reverse) | Return a new list with items reversed. | +| [`toset`](#toset) | Convert the list to a set. | +| [`slice`](#slice) | Return a new list containing items from i to j (inclusive). | +| [`take`](#take) | Return the first n elements as a new list. | +| [`uniq`](#uniq) | Return a new list with duplicates removed (first occurrence kept). | +| [`zip`](#zip) | Zip two lists into a list of 2-element tables. | ### Predicates @@ -331,7 +337,7 @@ f = List({ { "a", "b" }, { "c" } }):flatten() --> { "a", "b", "c" } #### `foreach` -Apply a function to each element (for side effects). Returns nil. +Apply a function to each element (for side effects). ```lua List({ "a", "b" }):foreach(print) @@ -350,14 +356,15 @@ g = List(words):group_by(string.len) --> { {"b"}, { "aa", "dd" }, { "ccc" } } #### `intersection` -Return values that are also present in the given list. Order is preserved from -the original list. +Return values that are also present in the given list. ```lua i = List({ "a", "b", "a", "c" }):intersection({ "a", "c" }) --> { "a", "a", "c" } ``` +> [!NOTE] Order is preserved from the original list. + #### `invert` Invert values to indices in a new table. @@ -406,14 +413,16 @@ Return a new list with items reversed. r = List({ "a", "b", "c" }):reverse() --> { "c", "b", "a" } ``` -#### `setify` +#### `toset` Convert the list to a set. ```lua -s = List({ "a", "b", "a" }):setify() --> { a = true, b = true } +s = List({ "a", "b", "a" }):toset() --> { a = true, b = true } ``` +> [!NOTE] Order is preserved from the original list. + #### `slice` Return a new list containing items from i to j (inclusive). diff --git a/docs/src/modules/operator.md b/docs/src/modules/operator.md index fd10c46..0b07355 100644 --- a/docs/src/modules/operator.md +++ b/docs/src/modules/operator.md @@ -11,7 +11,7 @@ Operator helpers as functions. ```lua operator = require "mods.operator" -print(operator.add(1, 2)) -->> 3 +print(operator.add(1, 2)) --> 3 ``` ## Functions diff --git a/docs/src/modules/repr.md b/docs/src/modules/repr.md index 3e59146..2970fe5 100644 --- a/docs/src/modules/repr.md +++ b/docs/src/modules/repr.md @@ -13,15 +13,15 @@ repr = require "mods.repr" print(repr("Hello world!")) --> "Hello world!" -print(repr({ user = { name = "Ada", tags = { "lua", "docs" } } })) ---> { --- user = { --- name = "Ada", --- tags = { --- [1] = "lua", --- [2] = "docs" --- } --- } --- } +view = { user = { name = "Ada", tags = { "lua", "docs" } } } +print(repr(view)) --> { +-- user = { +-- name = "Ada", +-- tags = { +-- [1] = "lua", +-- [2] = "docs" +-- } +-- } +-- } ``` diff --git a/docs/src/modules/set.md b/docs/src/modules/set.md index d7fc972..b2595b7 100644 --- a/docs/src/modules/set.md +++ b/docs/src/modules/set.md @@ -18,6 +18,12 @@ s = Set({ "a" }) print(s:contains("a")) --> true ``` +## Dependencies + +Dependencies below are lazy-loaded 💤 on first access. + +- [`mods.tbl`](https://luamod.github.io/mods/modules/tbl) + ## Functions **Mutation**: @@ -27,7 +33,6 @@ print(s:contains("a")) --> true | [`add`](#add) | Add an element to the set. | | [`clear`](#clear) | Remove all elements from the set. | | [`difference_update`](#difference-update) | Remove elements found in another set (in place). | -| [`discard`](#discard) | Remove an element if present, do nothing otherwise. | | [`intersection_update`](#intersection-update) | Keep only elements common to both sets (in place). | | [`pop`](#pop) | Remove and return an arbitrary element. | | [`symmetric_difference_update`](#symmetric-difference-update) | Update the set with elements not shared by both (in place). | @@ -35,13 +40,14 @@ print(s:contains("a")) --> true **Copying**: -| Function | Description | -| ----------------------------------------------- | ----------------------------------------------- | -| [`copy`](#copy) | Return a shallow copy of the set. | -| [`difference`](#difference) | Return elements in this set but not in another. | -| [`intersection`](#intersection) | Return elements common to both sets. | -| [`symmetric_difference`](#symmetric-difference) | Return elements not shared by both sets. | -| [`union`](#union) | Return a new set with all elements from both. | +| Function | Description | +| ----------------------------------------------- | --------------------------------------------------- | +| [`copy`](#copy) | Return a shallow copy of the set. | +| [`difference`](#difference) | Return elements in this set but not in another. | +| [`intersection`](#intersection) | Return elements common to both sets. | +| [`remove`](#remove) | Remove an element if present, do nothing otherwise. | +| [`symmetric_difference`](#symmetric-difference) | Return elements not shared by both sets. | +| [`union`](#union) | Return a new set with all elements from both. | **Predicates**: @@ -94,14 +100,6 @@ Remove elements found in another set (in place). s = Set({ "a", "b" }):difference_update(Set({ "b" })) --> s contains "a" ``` -#### `discard` - -Remove an element if present, do nothing otherwise. - -```lua -s = Set({ "a", "b" }):discard("b") --> s contains "a" -``` - #### `intersection_update` Keep only elements common to both sets (in place). @@ -164,6 +162,14 @@ Return elements common to both sets. i = Set({ "a", "b" }):intersection(Set({ "b", "c" })) --> i contains "b" ``` +#### `remove` + +Remove an element if present, do nothing otherwise. + +```lua +s = Set({ "a", "b" }):remove("b") --> s contains "a" +``` + #### `symmetric_difference` Return elements not shared by both sets. diff --git a/docs/src/modules/str.md b/docs/src/modules/str.md index 69af7be..7ed035d 100644 --- a/docs/src/modules/str.md +++ b/docs/src/modules/str.md @@ -14,19 +14,27 @@ str = require "mods.str" print(str.capitalize("hello world")) --> "Hello world" ``` +## Dependencies + +Dependencies below are lazy-loaded 💤 on first access. + +- [`mods.keyword`](https://luamod.github.io/mods/modules/keyword) +- [`mods.List`](https://luamod.github.io/mods/modules/list) +- [`mods.stringcase`](https://luamod.github.io/mods/modules/stringcase) + ## Functions **Formatting**: -| Function | Description | -| --------------------------- | ----------------------------------------------------------------------------------------------- | -| [`capitalize`](#capitalize) | Return copy with first character capitalized and the rest lowercased. | -| [`center`](#center) | Center string within width, padded with fill characters. | -| [`count`](#count) | Count non-overlapping occurrences of a substring. | -| [`endswith`](#endswith) | Return true if string ends with suffix. If suffix is a list, return true if any suffix matches. | -| [`expandtabs`](#expandtabs) | Expand tabs to spaces using given tabsize. | -| [`find`](#find) | Return lowest index of substring or nil if not found. | -| [`format_map`](#format-map) | Format string with mapping (key-based) replacement. | +| Function | Description | +| --------------------------- | --------------------------------------------------------------------- | +| [`capitalize`](#capitalize) | Return copy with first character capitalized and the rest lowercased. | +| [`center`](#center) | Center string within width, padded with fill characters. | +| [`count`](#count) | Count non-overlapping occurrences of a substring. | +| [`endswith`](#endswith) | Return true if string ends with suffix. | +| [`expandtabs`](#expandtabs) | Expand tabs to spaces using given tabsize. | +| [`find`](#find) | Return lowest index of substring or nil if not found. | +| [`format_map`](#format-map) | Format string with mapping (key-based) replacement. | **Predicates**: @@ -74,14 +82,14 @@ print(str.capitalize("hello world")) --> "Hello world" **Casing & Transform**: -| Function | Description | -| --------------------------- | ------------------------------------------------------------------------------------------------- | -| [`swapcase`](#swapcase) | Return a copy with case of alphabetic characters swapped. | -| [`startswith`](#startswith) | Return true if string starts with prefix. If prefix is a list, return true if any prefix matches. | -| [`title`](#title) | Return titlecased copy. | -| [`translate`](#translate) | Translate characters using a mapping table. | -| [`upper`](#upper) | Return uppercased copy. | -| [`zfill`](#zfill) | Pad numeric string on the left with zeros. | +| Function | Description | +| --------------------------- | --------------------------------------------------------- | +| [`swapcase`](#swapcase) | Return a copy with case of alphabetic characters swapped. | +| [`startswith`](#startswith) | Return true if string starts with prefix. | +| [`title`](#title) | Return titlecased copy. | +| [`translate`](#translate) | Translate characters using a mapping table. | +| [`upper`](#upper) | Return uppercased copy. | +| [`zfill`](#zfill) | Pad numeric string on the left with zeros. | ### Formatting @@ -120,8 +128,9 @@ n = count("abcd", "") #### `endswith` -Return true if string ends with suffix. If suffix is a list, return true if any -suffix matches. +Return true if string ends with suffix. + +> [!NOTE] If suffix is a list, returns `true` when any suffix matches. ```lua ok = endswith("hello.lua", ".lua") @@ -461,8 +470,9 @@ s = swapcase("AbC") #### `startswith` -Return true if string starts with prefix. If prefix is a list, return true if -any prefix matches. +Return true if string starts with prefix. + +> [!NOTE] If prefix is a list, returns `true` when any prefix matches. ```lua ok = startswith("hello.lua", "he") diff --git a/docs/src/modules/tbl.md b/docs/src/modules/tbl.md index f86ac0e..a9f3ddf 100644 --- a/docs/src/modules/tbl.md +++ b/docs/src/modules/tbl.md @@ -25,31 +25,31 @@ print(tbl.count({ a = 1, b = 2 })) --> 2 **Copying**: -| Function | Description | -| ----------------------- | --------------------------------------------------------------------------------------------------------------------------- | -| [`copy`](#copy) | Create a shallow copy of the table. | -| [`deepcopy`](#deepcopy) | Create a deep copy of a value. If `v` is a table, all nested tables are copied recursively; other types are returned as-is. | +| Function | Description | +| ----------------------- | ----------------------------------- | +| [`copy`](#copy) | Create a shallow copy of the table. | +| [`deepcopy`](#deepcopy) | Create a deep copy of a value. | **Query**: -| Function | Description | -| --------------------- | ---------------------------------------------------------------------------------- | -| [`filter`](#filter) | Filter entries by a value predicate. | -| [`find`](#find) | Find the first key whose value equals the given value. | -| [`find_if`](#find-if) | Find first value and key matching predicate. | -| [`get`](#get) | Safely get nested value by keys. If no keys are provided, returns the input table. | +| Function | Description | +| --------------------- | ------------------------------------------------------ | +| [`filter`](#filter) | Filter entries by a value predicate. | +| [`find`](#find) | Find the first key whose value equals the given value. | +| [`find_if`](#find-if) | Find first value and key matching predicate. | +| [`get`](#get) | Safely get nested value by keys. | **Transforms**: -| Function | Description | -| --------------------- | ---------------------------------------------------------------------------------------------------------------------------- | -| [`invert`](#invert) | Invert keys/values into new table. | -| [`isempty`](#isempty) | Return true if table has no entries. | -| [`keys`](#keys) | Return a list of all keys in the table. | -| [`map`](#map) | Return a new table by mapping each value (keys preserved). | -| [`pairmap`](#pairmap) | Return a new table by mapping each key-value pair. The resulting table keeps the same keys, with values transformed by `fn`. | -| [`update`](#update) | Merge entries from t2 into t1 and return t1. | -| [`values`](#values) | Return a list of all values in the table. | +| Function | Description | +| --------------------- | ---------------------------------------------------------- | +| [`invert`](#invert) | Invert keys/values into new table. | +| [`isempty`](#isempty) | Return true if table has no entries. | +| [`keys`](#keys) | Return a list of all keys in the table. | +| [`map`](#map) | Return a new table by mapping each value (keys preserved). | +| [`pairmap`](#pairmap) | Return a new table by mapping each key-value pair. | +| [`update`](#update) | Merge entries from `t2` into `t1` and return `t1`. | +| [`values`](#values) | Return a list of all values in the table. | ### Basics @@ -86,8 +86,10 @@ t = copy({ a = 1, b = 2 }) --> { a = 1, b = 2 } #### `deepcopy` -Create a deep copy of a value. If `v` is a table, all nested tables are copied -recursively; other types are returned as-is. +Create a deep copy of a value. + +> [!NOTE] If `v` is a table, all nested tables are copied recursively; other +> types are returned as-is. ```lua t = deepcopy({ a = { b = 1 } }) --> { a = { b = 1 } } @@ -128,8 +130,7 @@ end) --> 2, "b" #### `get` -Safely get nested value by keys. If no keys are provided, returns the input -table. +Safely get nested value by keys. ```lua t = { a = { b = { c = 1 } } } @@ -137,6 +138,8 @@ v1 = get(t, "a", "b", "c") --> 1 v2 = get(t) --> { a = { b = { c = 1 } } } ``` +> [!NOTE] If no keys are provided, returns the input table. + ### Transforms Table transformation and conversion utilities. @@ -177,8 +180,9 @@ end) --> { a = 10, b = 20 } #### `pairmap` -Return a new table by mapping each key-value pair. The resulting table keeps the -same keys, with values transformed by `fn`. +Return a new table by mapping each key-value pair. + +> [!NOTE] Output keeps original keys; only values are transformed by `fn`. ```lua t = pairmap({ a = 1, b = 2 }, function(k, v) @@ -188,7 +192,7 @@ end) --> { a = "a1", b = "b2" } #### `update` -Merge entries from t2 into t1 and return t1. +Merge entries from `t2` into `t1` and return `t1`. ```lua t1 = { a = 1, b = 2 } diff --git a/docs/src/modules/utils.md b/docs/src/modules/utils.md index 65d38bd..7ce1af2 100644 --- a/docs/src/modules/utils.md +++ b/docs/src/modules/utils.md @@ -24,3 +24,17 @@ Smart-quote a string for readable Lua-like output. print(utils.quote('He said "hi"')) -- 'He said "hi"' print(utils.quote('say "hi" and \\'bye\\'')) -- "say \"hi\" and 'bye'" ``` + +### `repr` + +Render any Lua value as a string. + +> [!NOTE] Uses [`inspect`](https://github.com/kikito/inspect.lua) when +> available, otherwise falls back to +> [`mods.repr`](https://luamod.github.io/mods/modules/repr). + +```lua +print(utils.repr({ a = 1 })) --> { +-- a = 1 +-- } +``` diff --git a/docs/src/modules/validate.md b/docs/src/modules/validate.md index 8da88fd..33d7f18 100644 --- a/docs/src/modules/validate.md +++ b/docs/src/modules/validate.md @@ -35,6 +35,14 @@ ok, err = validate.is_not.number(3.14) > `Not`, including underscore-insensitive top-level aliases (for example, > `validate.is_not_number` and `validate.isnotnumber`). +## Dependencies + +Dependencies below are lazy-loaded 💤 on first access. + +- [`lfs`](https://github.com/lunarmodules/luafilesystem) (optional; required + only for filesystem/path checks) +- [`mods.is`](https://luamod.github.io/mods/modules/is) + ## Callable Forms `validate`, `validate.is`, and `validate.is_not` are all callable. @@ -481,6 +489,16 @@ ok, err = validate.is_not.truthy(1) --> false, "expected not truthy" ### Path Checks +Filesystem path-kind validators backed by LuaFileSystem (`lfs`). + +Filesystem path kind checks. + +> [!IMPORTANT] +> +> Path checks require **LuaFileSystem** +> ([`lfs`](https://github.com/lunarmodules/luafilesystem)) and raise an error it +> is not installed. + #### `block` Returns `true` when `v` is a block device path. Otherwise returns `false` and an