Skip to content

Commit 30c1d23

Browse files
github-actions[bot]haithium
github-actions[bot]
and
haithium
authored
chore(docs): auto-generate docs (#12)
Co-authored-by: haithium <128622475+haithium@users.noreply.github.com>
1 parent ba2e9a6 commit 30c1d23

10 files changed

Lines changed: 184 additions & 109 deletions

File tree

‎docs/src/modules/is.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,13 @@ ok = is.table({}) --> true
2626
> is("hello", "String") --> true
2727
> ```
2828
29+
## Dependencies
30+
31+
Dependencies below are lazy-loaded 💤 on first access.
32+
33+
- [`lfs`](https://github.com/lunarmodules/luafilesystem) (optional; required
34+
only for filesystem/path checks)
35+
2936
## Functions
3037
3138
**Type Checks**:

‎docs/src/modules/keyword.md‎

Lines changed: 17 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -15,15 +15,22 @@ kw.iskeyword("local")) --> true
1515
kw.isidentifier("hello_world") --> true
1616
```
1717

18+
## Dependencies
19+
20+
Dependencies below are lazy-loaded 💤 on first access.
21+
22+
- [`mods.Set`](https://luamod.github.io/mods/modules/set)
23+
- [`mods.List`](https://luamod.github.io/mods/modules/list)
24+
1825
## Functions
1926

20-
| Function | Description |
21-
| ----------------------------------------------- | ---------------------------------------------------------------------------------------------- |
22-
| [`iskeyword`](#iskeyword) | Return `true` when `s` is a reserved Lua keyword. |
23-
| [`isidentifier`](#isidentifier) | Return `true` when `s` is a valid non-keyword Lua identifier. |
24-
| [`kwlist`](#kwlist) | Return Lua keywords as a [`mods.List`](https://luamod.github.io/mods/modules/list) of strings. |
25-
| [`kwset`](#kwset) | Return Lua keywords as a [`mods.Set`](https://luamod.github.io/mods/modules/set) of strings. |
26-
| [`normalize_identifier`](#normalize-identifier) | Normalize an input into a safe Lua identifier. |
27+
| Function | Description |
28+
| ----------------------------------------------- | ----------------------------------------------------------------------------------- |
29+
| [`iskeyword`](#iskeyword) | Return `true` when `s` is a reserved Lua keyword. |
30+
| [`isidentifier`](#isidentifier) | Return `true` when `s` is a valid non-keyword Lua identifier. |
31+
| [`kwlist`](#kwlist) | Return Lua keywords as a [`mods.List`](https://luamod.github.io/mods/modules/list). |
32+
| [`kwset`](#kwset) | Return Lua keywords as a [`mods.Set`](https://luamod.github.io/mods/modules/set). |
33+
| [`normalize_identifier`](#normalize-identifier) | Normalize an input into a safe Lua identifier. |
2734

2835
### `iskeyword`
2936

@@ -46,16 +53,16 @@ kw.isidentifier("local") --> false
4653
### `kwlist`
4754

4855
Return Lua keywords as a
49-
[`mods.List`](https://luamod.github.io/mods/modules/list) of strings.
56+
[`mods.List`](https://luamod.github.io/mods/modules/list).
5057

5158
```lua
5259
kw.kwlist():contains("and") --> true
5360
```
5461

5562
### `kwset`
5663

57-
Return Lua keywords as a [`mods.Set`](https://luamod.github.io/mods/modules/set)
58-
of strings.
64+
Return Lua keywords as a
65+
[`mods.Set`](https://luamod.github.io/mods/modules/set).
5966

6067
```lua
6168
kw.kwlset():contains("and") --> true

‎docs/src/modules/list.md‎

Lines changed: 34 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -12,13 +12,19 @@ query sequences of values.
1212
## Usage
1313

1414
```lua
15-
lsist = require "mods.List"
15+
List = require "mods.List"
1616

1717
ls = List({ "a" }):append("b")
1818
print(ls:contains("b")) --> true
1919
print(ls:index("b")) --> 2
2020
```
2121

22+
## Dependencies
23+
24+
Dependencies below are lazy-loaded 💤 on first access.
25+
26+
- [`mods.Set`](https://luamod.github.io/mods/modules/set)
27+
2228
## Functions
2329

2430
**Predicates**:
@@ -69,25 +75,25 @@ print(ls:index("b")) --> 2
6975

7076
**Transform**:
7177

72-
| Function | Description |
73-
| ------------------------------- | ------------------------------------------------------------------------------------------------- |
74-
| [`difference`](#difference) | Return a new list with values not in the given list. |
75-
| [`drop`](#drop) | Return a new list without the first n elements. |
76-
| [`filter`](#filter) | Return a new list with values matching the predicate. |
77-
| [`flatten`](#flatten) | Flatten one level of nested lists. |
78-
| [`foreach`](#foreach) | Apply a function to each element (for side effects). Returns nil. |
79-
| [`group_by`](#group-by) | Group list values by a computed key. |
80-
| [`intersection`](#intersection) | Return values that are also present in the given list. Order is preserved from the original list. |
81-
| [`invert`](#invert) | Invert values to indices in a new table. |
82-
| [`join`](#join) | Join list values into a string. |
83-
| [`map`](#map) | Return a new list by mapping each value. |
84-
| [`reduce`](#reduce) | Reduce the list to a single value using an accumulator. |
85-
| [`reverse`](#reverse) | Return a new list with items reversed. |
86-
| [`setify`](#setify) | Convert the list to a set. |
87-
| [`slice`](#slice) | Return a new list containing items from i to j (inclusive). |
88-
| [`take`](#take) | Return the first n elements as a new list. |
89-
| [`uniq`](#uniq) | Return a new list with duplicates removed (first occurrence kept). |
90-
| [`zip`](#zip) | Zip two lists into a list of 2-element tables. |
78+
| Function | Description |
79+
| ------------------------------- | ------------------------------------------------------------------ |
80+
| [`difference`](#difference) | Return a new list with values not in the given list. |
81+
| [`drop`](#drop) | Return a new list without the first n elements. |
82+
| [`filter`](#filter) | Return a new list with values matching the predicate. |
83+
| [`flatten`](#flatten) | Flatten one level of nested lists. |
84+
| [`foreach`](#foreach) | Apply a function to each element (for side effects). |
85+
| [`group_by`](#group-by) | Group list values by a computed key. |
86+
| [`intersection`](#intersection) | Return values that are also present in the given list. |
87+
| [`invert`](#invert) | Invert values to indices in a new table. |
88+
| [`join`](#join) | Join list values into a string. |
89+
| [`map`](#map) | Return a new list by mapping each value. |
90+
| [`reduce`](#reduce) | Reduce the list to a single value using an accumulator. |
91+
| [`reverse`](#reverse) | Return a new list with items reversed. |
92+
| [`toset`](#toset) | Convert the list to a set. |
93+
| [`slice`](#slice) | Return a new list containing items from i to j (inclusive). |
94+
| [`take`](#take) | Return the first n elements as a new list. |
95+
| [`uniq`](#uniq) | Return a new list with duplicates removed (first occurrence kept). |
96+
| [`zip`](#zip) | Zip two lists into a list of 2-element tables. |
9197

9298
### Predicates
9399

@@ -331,7 +337,7 @@ f = List({ { "a", "b" }, { "c" } }):flatten() --> { "a", "b", "c" }
331337

332338
#### `foreach`
333339

334-
Apply a function to each element (for side effects). Returns nil.
340+
Apply a function to each element (for side effects).
335341

336342
```lua
337343
List({ "a", "b" }):foreach(print)
@@ -350,14 +356,15 @@ g = List(words):group_by(string.len) --> { {"b"}, { "aa", "dd" }, { "ccc" } }
350356

351357
#### `intersection`
352358

353-
Return values that are also present in the given list. Order is preserved from
354-
the original list.
359+
Return values that are also present in the given list.
355360

356361
```lua
357362
i = List({ "a", "b", "a", "c" }):intersection({ "a", "c" })
358363
--> { "a", "a", "c" }
359364
```
360365

366+
> [!NOTE] Order is preserved from the original list.
367+
361368
#### `invert`
362369

363370
Invert values to indices in a new table.
@@ -406,14 +413,16 @@ Return a new list with items reversed.
406413
r = List({ "a", "b", "c" }):reverse() --> { "c", "b", "a" }
407414
```
408415

409-
#### `setify`
416+
#### `toset`
410417

411418
Convert the list to a set.
412419

413420
```lua
414-
s = List({ "a", "b", "a" }):setify() --> { a = true, b = true }
421+
s = List({ "a", "b", "a" }):toset() --> { a = true, b = true }
415422
```
416423

424+
> [!NOTE] Order is preserved from the original list.
425+
417426
#### `slice`
418427

419428
Return a new list containing items from i to j (inclusive).

‎docs/src/modules/operator.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,7 @@ Operator helpers as functions.
1111
```lua
1212
operator = require "mods.operator"
1313

14-
print(operator.add(1, 2)) -->> 3
14+
print(operator.add(1, 2)) --> 3
1515
```
1616

1717
## Functions

‎docs/src/modules/repr.md‎

Lines changed: 10 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -13,15 +13,15 @@ repr = require "mods.repr"
1313

1414
print(repr("Hello world!")) --> "Hello world!"
1515

16-
print(repr({ user = { name = "Ada", tags = { "lua", "docs" } } }))
17-
--> {
18-
-- user = {
19-
-- name = "Ada",
20-
-- tags = {
21-
-- [1] = "lua",
22-
-- [2] = "docs"
23-
-- }
24-
-- }
25-
-- }
16+
view = { user = { name = "Ada", tags = { "lua", "docs" } } }
17+
print(repr(view)) --> {
18+
-- user = {
19+
-- name = "Ada",
20+
-- tags = {
21+
-- [1] = "lua",
22+
-- [2] = "docs"
23+
-- }
24+
-- }
25+
-- }
2626

2727
```

‎docs/src/modules/set.md‎

Lines changed: 22 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,12 @@ s = Set({ "a" })
1818
print(s:contains("a")) --> true
1919
```
2020

21+
## Dependencies
22+
23+
Dependencies below are lazy-loaded 💤 on first access.
24+
25+
- [`mods.tbl`](https://luamod.github.io/mods/modules/tbl)
26+
2127
## Functions
2228

2329
**Mutation**:
@@ -27,21 +33,21 @@ print(s:contains("a")) --> true
2733
| [`add`](#add) | Add an element to the set. |
2834
| [`clear`](#clear) | Remove all elements from the set. |
2935
| [`difference_update`](#difference-update) | Remove elements found in another set (in place). |
30-
| [`discard`](#discard) | Remove an element if present, do nothing otherwise. |
3136
| [`intersection_update`](#intersection-update) | Keep only elements common to both sets (in place). |
3237
| [`pop`](#pop) | Remove and return an arbitrary element. |
3338
| [`symmetric_difference_update`](#symmetric-difference-update) | Update the set with elements not shared by both (in place). |
3439
| [`update`](#update) | Add all elements from another set (in place). |
3540

3641
**Copying**:
3742

38-
| Function | Description |
39-
| ----------------------------------------------- | ----------------------------------------------- |
40-
| [`copy`](#copy) | Return a shallow copy of the set. |
41-
| [`difference`](#difference) | Return elements in this set but not in another. |
42-
| [`intersection`](#intersection) | Return elements common to both sets. |
43-
| [`symmetric_difference`](#symmetric-difference) | Return elements not shared by both sets. |
44-
| [`union`](#union) | Return a new set with all elements from both. |
43+
| Function | Description |
44+
| ----------------------------------------------- | --------------------------------------------------- |
45+
| [`copy`](#copy) | Return a shallow copy of the set. |
46+
| [`difference`](#difference) | Return elements in this set but not in another. |
47+
| [`intersection`](#intersection) | Return elements common to both sets. |
48+
| [`remove`](#remove) | Remove an element if present, do nothing otherwise. |
49+
| [`symmetric_difference`](#symmetric-difference) | Return elements not shared by both sets. |
50+
| [`union`](#union) | Return a new set with all elements from both. |
4551

4652
**Predicates**:
4753

@@ -94,14 +100,6 @@ Remove elements found in another set (in place).
94100
s = Set({ "a", "b" }):difference_update(Set({ "b" })) --> s contains "a"
95101
```
96102

97-
#### `discard`
98-
99-
Remove an element if present, do nothing otherwise.
100-
101-
```lua
102-
s = Set({ "a", "b" }):discard("b") --> s contains "a"
103-
```
104-
105103
#### `intersection_update`
106104

107105
Keep only elements common to both sets (in place).
@@ -164,6 +162,14 @@ Return elements common to both sets.
164162
i = Set({ "a", "b" }):intersection(Set({ "b", "c" })) --> i contains "b"
165163
```
166164

165+
#### `remove`
166+
167+
Remove an element if present, do nothing otherwise.
168+
169+
```lua
170+
s = Set({ "a", "b" }):remove("b") --> s contains "a"
171+
```
172+
167173
#### `symmetric_difference`
168174

169175
Return elements not shared by both sets.

‎docs/src/modules/str.md‎

Lines changed: 31 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -14,19 +14,27 @@ str = require "mods.str"
1414
print(str.capitalize("hello world")) --> "Hello world"
1515
```
1616

17+
## Dependencies
18+
19+
Dependencies below are lazy-loaded 💤 on first access.
20+
21+
- [`mods.keyword`](https://luamod.github.io/mods/modules/keyword)
22+
- [`mods.List`](https://luamod.github.io/mods/modules/list)
23+
- [`mods.stringcase`](https://luamod.github.io/mods/modules/stringcase)
24+
1725
## Functions
1826

1927
**Formatting**:
2028

21-
| Function | Description |
22-
| --------------------------- | ----------------------------------------------------------------------------------------------- |
23-
| [`capitalize`](#capitalize) | Return copy with first character capitalized and the rest lowercased. |
24-
| [`center`](#center) | Center string within width, padded with fill characters. |
25-
| [`count`](#count) | Count non-overlapping occurrences of a substring. |
26-
| [`endswith`](#endswith) | Return true if string ends with suffix. If suffix is a list, return true if any suffix matches. |
27-
| [`expandtabs`](#expandtabs) | Expand tabs to spaces using given tabsize. |
28-
| [`find`](#find) | Return lowest index of substring or nil if not found. |
29-
| [`format_map`](#format-map) | Format string with mapping (key-based) replacement. |
29+
| Function | Description |
30+
| --------------------------- | --------------------------------------------------------------------- |
31+
| [`capitalize`](#capitalize) | Return copy with first character capitalized and the rest lowercased. |
32+
| [`center`](#center) | Center string within width, padded with fill characters. |
33+
| [`count`](#count) | Count non-overlapping occurrences of a substring. |
34+
| [`endswith`](#endswith) | Return true if string ends with suffix. |
35+
| [`expandtabs`](#expandtabs) | Expand tabs to spaces using given tabsize. |
36+
| [`find`](#find) | Return lowest index of substring or nil if not found. |
37+
| [`format_map`](#format-map) | Format string with mapping (key-based) replacement. |
3038

3139
**Predicates**:
3240

@@ -74,14 +82,14 @@ print(str.capitalize("hello world")) --> "Hello world"
7482

7583
**Casing & Transform**:
7684

77-
| Function | Description |
78-
| --------------------------- | ------------------------------------------------------------------------------------------------- |
79-
| [`swapcase`](#swapcase) | Return a copy with case of alphabetic characters swapped. |
80-
| [`startswith`](#startswith) | Return true if string starts with prefix. If prefix is a list, return true if any prefix matches. |
81-
| [`title`](#title) | Return titlecased copy. |
82-
| [`translate`](#translate) | Translate characters using a mapping table. |
83-
| [`upper`](#upper) | Return uppercased copy. |
84-
| [`zfill`](#zfill) | Pad numeric string on the left with zeros. |
85+
| Function | Description |
86+
| --------------------------- | --------------------------------------------------------- |
87+
| [`swapcase`](#swapcase) | Return a copy with case of alphabetic characters swapped. |
88+
| [`startswith`](#startswith) | Return true if string starts with prefix. |
89+
| [`title`](#title) | Return titlecased copy. |
90+
| [`translate`](#translate) | Translate characters using a mapping table. |
91+
| [`upper`](#upper) | Return uppercased copy. |
92+
| [`zfill`](#zfill) | Pad numeric string on the left with zeros. |
8593

8694
### Formatting
8795

@@ -120,8 +128,9 @@ n = count("abcd", "")
120128

121129
#### `endswith`
122130

123-
Return true if string ends with suffix. If suffix is a list, return true if any
124-
suffix matches.
131+
Return true if string ends with suffix.
132+
133+
> [!NOTE] If suffix is a list, returns `true` when any suffix matches.
125134
126135
```lua
127136
ok = endswith("hello.lua", ".lua")
@@ -461,8 +470,9 @@ s = swapcase("AbC")
461470

462471
#### `startswith`
463472

464-
Return true if string starts with prefix. If prefix is a list, return true if
465-
any prefix matches.
473+
Return true if string starts with prefix.
474+
475+
> [!NOTE] If prefix is a list, returns `true` when any prefix matches.
466476
467477
```lua
468478
ok = startswith("hello.lua", "he")

0 commit comments

Comments
 (0)