Skip to content

chore(docs): auto-generate docs #12

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
haithium merged 1 commit into from
Feb 23, 2026
Merged

chore(docs): auto-generate docs #12

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 7 additions & 0 deletions docs/src/modules/is.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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**:
Expand Down
27 changes: 17 additions & 10 deletions docs/src/modules/keyword.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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`

Expand All @@ -46,16 +53,16 @@ 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
```

### `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
Expand Down
59 changes: 34 additions & 25 deletions docs/src/modules/list.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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**:
Expand Down Expand Up @@ -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

Expand Down Expand Up @@ -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)
Expand All @@ -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.
Expand Down Expand Up @@ -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).
Expand Down
2 changes: 1 addition & 1 deletion docs/src/modules/operator.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
20 changes: 10 additions & 10 deletions docs/src/modules/repr.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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"
-- }
-- }
-- }

```
38 changes: 22 additions & 16 deletions docs/src/modules/set.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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**:
Expand All @@ -27,21 +33,21 @@ 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). |
| [`update`](#update) | Add all elements from another set (in place). |

**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**:

Expand Down Expand Up @@ -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).
Expand Down Expand Up @@ -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.
Expand Down
52 changes: 31 additions & 21 deletions docs/src/modules/str.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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**:

Expand Down Expand Up @@ -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

Expand Down Expand Up @@ -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")
Expand Down Expand Up @@ -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")
Expand Down
Loading