libraries.lua

-- Structured documentation for the libraries, tools and ZLI-specific topics
-- bundled with ZLI.
--
-- This file is the source of truth for doc/libraries.md and for the library
-- part of the @manual page.  It is also loaded by `require "docs"`, which
-- powers `zli @help` and the REPL's `:help` command.
--
-- Entries use GitHub-flavored Markdown (rendered by the bundled md4c binding
-- through src/docs_markdown.lua).  The Lua standard library documentation is
-- generated from the Lua 5.5 manual at build time and lives in docs_manual.lua.

local function entry(name, signature, kind, summary, doc, aliases)
    return {
        name = name,
        signature = signature,
        kind = kind,
        summary = summary,
        markdown = doc,
        aliases = aliases,
    }
end

local function module(name, title, summary, doc, entries, options)
    options = options or {}
    return {
        name = name,
        title = title,
        summary = summary,
        markdown = doc,
        entries = entries,
        upstream = options.upstream,
        license = options.license,
        aliases = options.aliases,
    }
end

return {
    schema = 1,
    groups = {
        {
            id = "zli",
            title = "ZLI libraries",
            source = "zli",
            modules = {
                module("auxiliary", "auxiliary", "Extra string, table, file and OS helpers.", [==[
The `auxiliary` module is loaded automatically.  It extends the standard
`string`, `table`, `io`, `os` and `math` tables and adds a few global helpers.
]==], {
                    entry("arg_error", "arg_error(func, narg, message [, level])", "function",
                        "Raise a Lua argument error.",
                        "Raises `message` as a bad-argument error for argument `narg` of `func`.  `level` is passed to `error`."),
                    entry("arg_check", "arg_check(func, narg, test, message)", "function",
                        "Raise an argument error when `test` is false.",
                        "Convenience wrapper around `arg_error`.  `func` and `narg` identify the offending argument."),
                    entry("arg_check_type", "arg_check_type(func, narg, value, level, ...)", "function",
                        "Validate the type of an argument.",
                        "Accepts the value when its type is one of the types passed in `...`; otherwise raises an argument error."),
                    entry("sorted_pairs", "sorted_pairs(tbl [, comparator])", "function",
                        "Iterate a table in sorted key order.",
                        "Returns an iterator like `pairs`, sorted by key.  An optional comparator is passed to `table.sort`."),
                    entry("lambda", "lambda(source) / L(source)", "function",
                        "Create a Lua function from a short expression.",
                        [==[
Compile `source` into a callable Lua function.  The global helpers `lambda` and
`L`, and the string method `string.L`, are equivalent.  The source may read
local variables and upvalues visible where the lambda is created, even after
the creating scope has returned.

The first characters of `source` select one of these styles:

| Source style                            | Example                | Equivalent Lua function                |
| --------------------------------------- | ---------------------- | -------------------------------------- |
| Method call                             | `L(":hello")`          | `function(it) return it:hello() end`   |
| Method call with arguments (arrow form) | `L("-> it:add(2, 3)")` | `function(it) return it:add(2, 3) end` |
| Field access                            | `L(".name")`           | `function(it) return it.name end`      |
| Field call                              | `L(".hello()")`        | `function(it) return it.hello() end`   |
| Arrow expression                        | `L("-> it * 2")`       | `function(it) return it * 2 end`       |
| Bare expression                         | `L("it * 2")`          | `function(it) return it * 2 end`       |
| Parameter list                          | `L("(a, b) -> a + b")` | `function(a, b) return a + b end`      |
| No parameters                           | `L("() -> 42")`        | `function() return 42 end`             |

The method shorthand appends `()` to the rest of the source: `":hello"` becomes
`it:hello()`.  Use it for zero-argument methods, and do not include the
parentheses in the source.  Pass arguments with the arrow form, for example
`L("-> it:add(2, 3)")`.

The field shorthand appends the rest of the source to `it` without adding
parentheses: `".name"` becomes `it.name`, and `".hello()"` becomes
`it.hello()` (a plain function call, not a method call).  The arrow and bare
forms provide exactly one parameter named `it`.  The parenthesised form is the
only style that chooses its own parameter list.

A source beginning with `(` is always parsed as a parameter list and must
contain `->`.  To use an expression that starts with a parenthesis, use the
arrow form: `L("-> (it + 1) * 2")`.

For example, `L("(a, b) -> a + b")` loads a chunk equivalent to this one (with
the captured scope as its environment) and calls it to produce the lambda:

```lua
return function(a, b) return a + b end
```

The aliases can be written in several ways:

```lua
local double = L("it * 2")        -- global L
local triple = lambda("it * 3")   -- global lambda
local upper = (":upper"):L()      -- string method
local negate = L "-> -it"         -- function call sugar
```

Typical uses:

```lua
local double = L("it * 2")
print(double(21)) --> 42

local add = L("(a, b) -> a + b")
print(add(20, 22)) --> 42

local user = {
    name = "Ada",
    hello = function(self) return "Hello " .. self.name end,
}
print(L(":hello")(user)) --> Hello Ada
print(L(".name")(user))  --> Ada
```

Lambdas are also accepted as strings by helpers such as `stream:map`:

```lua
local stream = require "stream"
local multiplier = 3
local result = stream({ 1, 2, 3 }):map("it * multiplier"):toarray()
print(table.concat(result, ",")) --> 3,6,9
```

Because the source is compiled when the lambda is created, a lambda created in
a tail-call position cannot see locals from the discarded caller frame.  This
is the same limitation as the f-strings library.
]==]),
                    entry("string.starts_with", "string.starts_with(value, prefix)", "method",
                        "Return true when a string starts with `prefix`.",
                        [[
Return true when the string begins with `prefix`.

The comparison is case-sensitive and literal, not a Lua pattern match. An empty prefix always matches.

```lua
print(("hello"):starts_with("he")) --> true
print(("hello"):starts_with("lo")) --> false
```
]]),
                    entry("string.ends_with", "string.ends_with(value, suffix)", "method",
                        "Return true when a string ends with `suffix`.",
                        [[
Return true when the string ends with `suffix`.

The comparison is case-sensitive and literal. An empty suffix always matches.

```lua
print(("hello"):ends_with("lo")) --> true
print(("hello"):ends_with("he")) --> false
```
]]),
                    entry("string.contains", "string.contains(value, needle)", "method",
                        "Return true when a string contains `needle`.",
                        [[
Return true when the string contains `needle`.

The search is plain text, so pattern characters such as `%` and `.` have no special meaning. Case is significant.

```lua
print(("hello"):contains("ell")) --> true
print(("hello"):contains("ELL")) --> false
```
]]),
                    entry("string.is_empty", "string.is_empty(value)", "method",
                        "Return true for `nil` or the empty string.",
                        [[
Return true when the value is `nil` or the empty string.

Any non-empty string returns false. This helper is convenient for validating optional string arguments.

```lua
print(""):is_empty()   --> true
print("x"):is_empty()  --> false
```
]]),
                    entry("string.is_not_empty", "string.is_not_empty(value)", "method",
                        "Return true for a non-nil, non-empty string.",
                        [[
Return true when the value is a non-nil, non-empty string.

The logical complement of `string.is_empty`. `nil` and `""` both return false.

```lua
print("x"):is_not_empty() --> true
print(""):is_not_empty()  --> false
```
]]),
                    entry("string.split", "string.split(value [, separator])", "method",
                        "Split a string into multiple values.",
                        [[
Split a string into multiple return values.

`separator` defaults to a comma. The separator is literal text, not a Lua pattern, and may contain several characters. Empty fields are preserved, including leading and trailing ones.

```lua
local a, b, c = ("1,2,3"):split(",")
print(a, b, c) --> 1 2 3

local parts = table.pack(("a<>b"):split("<>"))
print(parts.n) --> 2
```
]]),
                    entry("string.to_table", "string.to_table(value [, separator])", "method",
                        "Split a string into a table.",
                        [[
Split a string into an array using a literal separator.

`separator` defaults to a comma. Empty fields are preserved, and the function accepts multi-character separators. Use `string.split` when multiple return values are more convenient.

```lua
table.print(("1,2,3"):to_table()) --> { "1", "2", "3" }
```
]]),
                    entry("string.trim", "string.trim(value)", "method",
                        "Remove leading and trailing whitespace.",
                        [[
Remove leading and trailing whitespace from a string.

Whitespace includes spaces, tabs, carriage returns, newlines and NUL bytes. The argument must be a string; the result is a new string.

```lua
print(("  hello\n"):trim()) --> "hello"
```
]]),
                    entry("string.ltrim", "string.ltrim(value)", "method",
                        "Remove leading whitespace.",
                        [[
Remove leading whitespace from a string.

Spaces, tabs, carriage returns, newlines and NUL bytes are stripped from the start only. The trailing part of the string is left untouched.

```lua
print(("  hello  "):ltrim()) --> "hello  "
```
]]),
                    entry("string.rtrim", "string.rtrim(value)", "method",
                        "Remove trailing whitespace.",
                        [[
Remove trailing whitespace from a string.

Spaces, tabs, carriage returns, newlines and NUL bytes are stripped from the end only. The leading part of the string is left untouched.

```lua
print(("  hello  "):rtrim()) --> "  hello"
```
]]),
                    entry("string.base64encode", "string.base64encode(value)", "method",
                        "Encode a string as standard Base64.",
                        [[
Encode a string as standard Base64 using the `A-Z a-z 0-9 + /` alphabet and padding.

The argument must be a string. Binary data, including NUL bytes, is preserved. Use `base64urlEncode` when the result must be URL-safe.

```lua
print(("hello"):base64encode()) --> "aGVsbG8="
```
]]),
                    entry("string.base64decode", "string.base64decode(value)", "method",
                        "Decode a standard Base64 string.",
                        [[
Decode a standard Base64 string, returning the original bytes.

The input must use the standard Base64 alphabet with correct padding. Invalid input raises an error rather than returning a partial result.

```lua
print(("aGVsbG8="):base64decode()) --> "hello"
```
]]),
                    entry("string.base64urlEncode", "string.base64urlEncode(value)", "method",
                        "Encode a string as URL-safe Base64.",
                        [[
Encode a string as URL-safe Base64 using the `-` and `_` characters in place of `+` and `/`.

Padding is included, so the result can be decoded with `base64urlDecode`. The input may contain arbitrary bytes.

```lua
print(("a+b/c?"):base64urlEncode())
```
]]),
                    entry("string.base64urlDecode", "string.base64urlDecode(value)", "method",
                        "Decode a URL-safe Base64 string.",
                        [[
Decode a URL-safe Base64 string, accepting `-` and `_` as the last two alphabet characters.

Invalid input raises an error. Use `base64decode` for the standard alphabet.

```lua
print(("aGVsbG8="):base64urlDecode()) --> "hello"
```
]]),
                    entry("string.urlEncode", "string.urlEncode(value)", "method",
                        "Percent-encode a string for use in a URL.",
                        [[
Percent-encode a string for use in a URL.

Letters, digits, `-`, `_`, `.` and `~` are left unchanged. Every other byte is replaced by `%XX` with uppercase hexadecimal digits, including spaces (which become `%20`).

```lua
print(("a b/c"):urlEncode()) --> "a%20b%2Fc"
```
]]),
                    entry("string.utf8len", "string.utf8len(value)", "method",
                        "Return the number of UTF-8 characters in a string.",
                        [[
Count the number of UTF-8 code points in a string.

The argument must be valid UTF-8; malformed input raises an error. The count is not the byte length: `"ÖÄÜ"` has length 3 even though it occupies more bytes.

```lua
print(("héllo"):utf8len()) --> 5
```
]]),
                    entry("table.copy", "table.copy(value [, copies])", "function",
                        "Deep-copy a table.",
                        "`copies` tracks already copied tables, which also makes the function safe for cyclic tables."),
                    entry("table.tostring", "table.tostring(value [, name])", "function",
                        "Pretty-print a table as a string.",
                        [[
Pretty-print a table as a Lua-like string and return it.

The output is produced by `serpent.block`, with sorted keys, four-space indentation and no comments. When `name` is supplied, the result is prefixed with `name = `.

```lua
print(table.tostring({ b = 2, a = { 1 } }))
```
]]),
                    entry("table.print", "table.print(value [, name])", "function",
                        "Pretty-print a table to standard output.",
                        [[
Pretty-print a table to standard output.

This is equivalent to `print(table.tostring(value, name))`. The table is formatted with sorted keys and four-space indentation.

```lua
table.print({ b = 2, a = 1 }, "config")
```
]]),
                    entry("table.remove_if", "table.remove_if(value, predicate)", "function",
                        "Remove elements for which `predicate` is true.",
                        [[
Remove, in place, every array element for which `predicate(item)` is truthy.

The table is compacted and returned, so the original table keeps its identity. Non-array keys are not inspected.

```lua
local t = { 1, 2, 3, 4 }
table.remove_if(t, function(n) return n % 2 == 0 end)
--> t is { 1, 3 }
```
]]),
                    entry("table.filter", "table.filter(value, predicate)", "function",
                        "Return a new table with elements accepted by `predicate`.",
                        [[
Return a new array containing the elements for which `predicate(item)` is truthy.

The original table is not modified. Only the array part is visited, and the result is a new array with consecutive indexes.
]]),
                    entry("table.add_all", "table.add_all(target, ...)", "function",
                        "Append all arguments to a table.",
                        [[
Append the given values to the end of a table and return that table.

Arguments that are tables are flattened one level: their array parts are appended element by element. Non-table arguments are appended directly. Non-array keys in table arguments are ignored.

```lua
local t = { 1 }
table.add_all(t, 2, { 3, 4 }, 5)
--> t is { 1, 2, 3, 4, 5 }
```
]]),
                    entry("table.insert_all", "table.insert_all(target, index, ...)", "function",
                        "Insert all arguments at a position.",
                        [[
Insert the given values into a table starting at `index`, shifting later elements right.

Table arguments are flattened one level, like `table.add_all`. The table is modified in place and returned.

```lua
local t = { 1, 4 }
table.insert_all(t, 2, 2, 3)
--> t is { 1, 2, 3, 4 }
```
]]),
                    entry("table.load", "table.load(filename)", "function",
                        "Load a serialized table from a file.",
                        [[
Load a serialized table from a file and return the resulting value.

The file contents are prefixed with `return` and evaluated, so the file must contain a Lua expression rather than a statement list. `table.save` produces compatible files.

```lua
local value = table.load("config.lua")
```
]]),
                    entry("table.save", "table.save(filename, value)", "function",
                        "Serialize a table to a file.",
                        [[
Serialize a table and write it to a file.

The output uses `table.tostring`, producing sorted keys, four-space indentation and no comments. The file is replaced if it already exists. The function returns nothing.

```lua
table.save("config.lua", { retries = 3, host = "localhost" })
```
]]),
                    entry("table.default", "table.default(value, defaults [, error])", "function",
                        "Fill missing keys from a defaults table.",
                        "Returns `value`, with each missing key copied from `defaults`.  When `error` is true, unexpected keys raise an error."),
                    entry("table.insert_sorted", "table.insert_sorted(value, item [, comparator])", "function",
                        "Insert an item while keeping a sorted table ordered.",
                        [[
Insert `item` into an already sorted array, keeping the array ordered.

The default comparator is `a < b`; pass a custom comparator as the third argument. The insertion position is found with a binary search, and the table is modified in place. The function returns nothing.

```lua
local t = {}
table.insert_sorted(t, 3)
table.insert_sorted(t, 1)
--> t is { 1, 3 }
```
]]),
                    entry("table.next", "table.next(value)", "function",
                        "Iterator helper used by `stream`.",
                        [[
Return a stateless iterator over the array part of a table.

Each call to the iterator returns the next value, or `nil` when there are no more values. This is the iterator used internally by `stream` and is equivalent to `ipairs` for well-formed arrays.

```lua
for value in table.next { "a", "b" } do
    print(value)
end
```
]]),
                    entry("io.read_lines", "io.read_lines(filename)", "function",
                        "Read all lines from a file into a table.",
                        [[
Read a text file into an array of lines and return the array.

Line terminators are removed and empty lines are preserved. The file is opened read-only and closed before returning. An open failure raises an error through `assert`.

Local files take priority. If the file does not exist locally, it is read from the payload attached to the executable.

```lua
local lines = io.read_lines("data.txt")
print(lines[1])
```
]]),
                    entry("io.write_lines", "io.write_lines(filename, lines [, eol])", "function",
                        "Write a table of lines to a file.",
                        [[
Write an array of lines to a file, replacing any existing contents.

Each line is written followed by `eol`, which defaults to `"\n"`. The file is opened in binary write mode and closed afterwards. An open failure raises an error through `assert`.

```lua
io.write_lines("out.txt", { "one", "two" })
```
]]),
                    entry("io.read_file", "io.read_file(filename)", "function",
                        "Read an entire file as a string.",
                        [[
Read an entire file as a string.

The file is opened in binary read mode and closed before returning. An open failure raises an error through `assert`, so check the path or wrap the call in `pcall` if missing files are expected.

Local files take priority. If the file does not exist locally, it is read from the payload attached to the executable. The same fallback applies to read-only files opened directly with `io.open` or iterated with `io.lines`.
]]),
                    entry("io.write_file", "io.write_file(filename, data)", "function",
                        "Write a string to a file, replacing its contents.",
                        [[
Write a string to a file, replacing its previous contents.

The file is opened in binary write mode, the data is written, and the file is closed. An open failure raises an error through `assert`.

```lua
io.write_file("out.txt", "hello")
```
]]),
                    entry("io.append_file", "io.append_file(filename, data)", "function",
                        "Append a string to a file.",
                        [[
Append a string to a file, creating the file if it does not exist.

The file is opened in append/update binary mode and closed afterwards. An open failure raises an error through `assert`.
]]),
                    entry("os.name", "os.name", "field",
                        "Operating system name.",
                        "One of `windows`, `linux`, `macos`, or the platform name reported by the interpreter."),
                    entry("os.home", "os.home", "field",
                        "The current user's home directory.",
                        [[
The current user's home directory as a string, or `nil` when it cannot be determined.

On Windows the value is built from `HOMEDRIVE` and `HOMEPATH`; elsewhere it comes from `HOME`.
]]),
                    entry("os.is_windows", "os.is_windows", "field",
                        "True on Windows.",
                        [[
True when the interpreter is running on Windows, false on every other platform.

This is a boolean companion to the `os.name` string.
]]),
                    entry("os.is_linux", "os.is_linux", "field",
                        "True on Linux.",
                        [[
True when the interpreter is running on Linux, false on every other platform.
]]),
                    entry("os.is_mac", "os.is_mac", "field",
                        "True on macOS.",
                        [[
True when the interpreter is running on macOS, false on every other platform.

The field is named `is_mac` even though `os.name` uses the value `"macos"`.
]]),
                    entry("os.separator", "os.separator", "field",
                        "The platform path separator (`\\` or `/`).",
                        [[
The platform's path separator: `\` on Windows and `/` elsewhere.

This is a one-character string intended for building paths, and it matches the separator used by the `filesystem` module.
]]),
                    entry("os.nanotime", "os.nanotime()", "function",
                        "Return a monotonic timestamp in nanoseconds.",
                        [[
Return a monotonic timestamp in nanoseconds.

The value is suitable for measuring elapsed time, not for displaying wall-clock dates. It is used by `timer` and `benchmark`.

```lua
local start = os.nanotime()
-- work
print(os.nanotime() - start)
```
]]),
                    entry("math.round", "math.round(value)", "function",
                        "Round a number to the nearest integer.",
                        [[
Round a number to the nearest integer.

Exact halves are rounded to the nearest even integer (banker's rounding): `0.5` becomes `0`, `1.5` becomes `2`, and `-2.5` becomes `-2`. Non-half values round to the nearest integer. The argument must be a number.

```lua
math.round(2.4) --> 2
math.round(2.5) --> 2
math.round(42.6) --> 43
```
]]),
                    entry("math.maxdouble", "math.maxdouble", "field",
                        "The largest finite double.",
                        [[
The largest finite IEEE-754 double-precision value, approximately `1.7976931348623157e308`.

This is a constant number, useful as an initial value for minimum searches.
]]),
                    entry("math.mindouble", "math.mindouble", "field",
                        "The smallest positive normalized double.",
                        [[
The smallest positive normalized IEEE-754 double-precision value, approximately `2.2250738585072014e-308`.

Denormalized values are smaller. This constant is useful as an initial value for maximum searches.
]]),
                }),

                module("benchmark", "benchmark", "Small benchmark runner with nanosecond precision.", [==[
`benchmark.run(table [, iterations])` runs every function in a benchmark table and
prints per-run timings and memory use.

Special keys `before_all`, `before_each`, `after_each` and `after_all` are called
around the run.  A key `before_<name>` or `after_<name>` is called around the
matching benchmark function.  The optional `iterations` argument overrides the
`iter` field of the benchmark table (default 3).
]==], {
                    entry("benchmark.run", "benchmark.run(bench [, iterations])", "function",
                        "Run a benchmark table and print the summary.",
                        "The benchmark table contains functions to measure plus optional setup and teardown hooks."),
                }),

                module("collection", "collection", "Java-style collections: lists, maps and sets.", [==[
`collection` provides `list`, `map` and `set` factories.  All collections support
`size`, `is_empty`, `add_all`, `remove_all`, `contains_all`, `equals`, `copy`,
`stream`, `union`, `intersection` and `difference`.  Lists and sets also support
`to_array`; use `map:values():to_array()` for maps.
]==], {
                    entry("collection:size", "collection:size()", "method",
                        "Return the number of elements.",
                        [[
Return the number of elements in the collection.

The value is maintained by the collection implementation, so it is O(1) for lists, maps and sets. Use `#collection` where the metatable provides a length operator.
]]),
                    entry("collection:is_empty", "collection:is_empty()", "method",
                        "Return true when the collection has no elements.",
                        [[
Return true when the collection contains no elements.

This is equivalent to `collection:size() == 0` and is O(1).
]]),
                    entry("collection:add_all", "collection:add_all(items)", "method",
                        "Add all items from another collection or table.",
                        [[
Add every element from another collection or table.

For a collection, its iterator is used, so values (not indexes) are added. For a plain table, the array part is traversed with `next`. Returns the collection itself for chaining.

```lua
local list = require("collection").list
local l = list:new():add_all { 1, 2 }
```
]]),
                    entry("collection:remove_all", "collection:remove_all(items)", "method",
                        "Remove all items found in another collection or table.",
                        [[
Remove every element supplied by another collection or table.

For plain tables the array values are used. The return value follows the first removal attempt: it is true when that first item was present and removed, otherwise false. This means callers should not rely on the result as an "any removed" flag.

```lua
local set = require("collection").set
local s = set:new { 1, 2, 3 }
s:remove_all { 2, 3 }
```
]]),
                    entry("collection:contains_all", "collection:contains_all(items)", "method",
                        "Return true when every item is present.",
                        [[
Return true when every element in the supplied collection or table is present in this collection.

The check stops at the first missing element. An empty input returns true. The input may be any collection or a plain array-like table.
]]),
                    entry("collection:equals", "collection:equals(other)", "method",
                        "Compare two collections for equal contents.",
                        [[
Compare this collection with another collection or plain table for equal contents.

Every element of the other object must be contained in this one, and the element counts must match. Element order is not significant, and duplicate values are compared by simple membership.

```lua
local set = require("collection").set
local s = set:new { 1, 2 }
print(s:equals { 2, 1 }) --> true
```
]]),
                    entry("collection:copy", "collection:copy()", "method",
                        "Return a shallow copy.",
                        [[
Return a shallow copy of the collection.

A new collection of the same kind is created with the current elements. The elements themselves are not copied, so nested tables are shared with the original. Ordered maps and sets are rebuilt through their ordinary constructor, so the copy may not preserve insertion order.

```lua
local l = list:new():add_all { { 1 }, 2 }
local copy = l:copy()
print(copy:get(1) == l:get(1)) --> true (same nested table)
```
]]),
                    entry("collection:stream", "collection:stream()", "method",
                        "Return a `stream` over the collection.",
                        [[
Return a `stream` over the collection's elements.

The stream is built from the collection's iterator, so sets and ordered maps preserve their iteration order. The collection itself is not modified.

```lua
local sum = require("collection").list:new{1,2,3}:stream():sum()
```
]]),
                    entry("collection:union", "collection:union(...)", "method",
                        "Return the union with other collections.",
                        [[
Return a new collection containing this collection's elements plus all elements from the given collections or tables.

The receiver is not modified. The result is created with `self:new(self)`, so it has the same collection type. Ordered variants are rebuilt through their ordinary constructor and may not preserve insertion order. Duplicate values follow the rules of that type (sets deduplicate, lists keep duplicates).
]]),
                    entry("collection:intersection", "collection:intersection(...)", "method",
                        "Return the intersection with other collections.",
                        [[
Return a new collection containing only elements that are present in this collection and in every given collection or table.

The receiver is unchanged. The result is a copy of the receiver reduced with `retain_all` for each argument, so type-specific behavior is preserved, but ordered variants may lose insertion order.
]]),
                    entry("collection:difference", "collection:difference(...)", "method",
                        "Return the difference with other collections.",
                        [[
Return a new collection containing the receiver's elements that are not present in any of the given collections or tables.

The receiver is unchanged. The result starts as a copy and removes each argument's elements in turn. Because the copy uses the ordinary constructor, ordered variants may lose insertion order.
]]),
                    entry("collection:to_array", "collection:to_array()", "method",
                        "Return the contents as an array.",
                        [[
Return the collection's elements as a plain array.

The array is built from `iterate_indexed`, so lists and sets produce consecutive indexes. The bundled map implementation does not define indexed iteration; use `map:values():to_array()` for maps instead of calling this method on a map.

```lua
local items = require("collection").list:new{ "a", "b" }:to_array()
--> { "a", "b" }
```
]]),
                }),

                module("collection.list", "collection.list", "Ordered list collection.", [==[
A list is an ordered sequence.  Methods that mutate a list return the list, so
calls can be chained.
]==], {
                    entry("collection.list.new", "collection.list.new([initial])", "function",
                        "Create a new list.",
                        [[
Create a new empty list, optionally populated from an array or another collection.

The initial values are added through `add_all`, so they become the list's elements in iteration order. A plain list keeps insertion order; use `new_sorted` for automatic sorting.

```lua
local list = require("collection").list
local l = list:new { "a", "b" }
print(l:size()) --> 2
```
]]),
                    entry("collection.list.new_sorted", "collection.list.new_sorted([initial [, comparator]])", "function",
                        "Create a list that keeps its elements sorted.",
                        [[
Create a list that keeps its elements in sorted order.

The optional comparator receives two values and returns true when the first sorts before the second; the default is `a < b`. The optional initial array or collection is inserted one element at a time in sorted position.

```lua
local list = require("collection").list
local l = list:new_sorted { "c", "a", "b" }
print(l:get(1)) --> "a"
```
]]),
                    entry("collection.list:add", "list:add([index,] item)", "method",
                        "Add one item, optionally at an index.",
                        [[
Add one item to the list, optionally at a 1-based index.

With one argument the item is appended, or inserted in sorted position for a sorted list. With two arguments the first is an index and the second is the item; inserting by index is not allowed in a sorted list. Passing more than two arguments raises an error. Returns the list.

```lua
local l = list:new():add("b"):add(1, "a")
--> { "a", "b" }
```
]]),
                    entry("collection.list:add_all", "list:add_all([index,] items)", "method",
                        "Add all items from a table or collection.",
                        [[
Add every item from an array or collection.

With one argument the items are appended (or inserted in sorted order for a sorted list). With two arguments the first is a starting index and the second is the collection; items are inserted from that index onward. Returns the list.
]]),
                    entry("collection.list:clear", "list:clear([size])", "method",
                        "Remove all items.",
                        [[
Remove all items from the list and reset its size to zero.

The optional argument is a size or capacity hint; the bundled implementation accepts a number but does not preallocate storage. Passing a table clears the list and then adds that table's items. Other argument types raise an error. Returns the list.

```lua
local l = list:new { 1, 2, 3 }:clear()
print(l:is_empty()) --> true
```
]]),
                    entry("collection.list:contains", "list:contains(item)", "method",
                        "Return true when the item is present.",
                        [[
Return true when the list contains the given value.

Comparison uses `==`, so table values are found by identity. The search is linear from the beginning of the list.
]]),
                    entry("collection.list:get", "list:get(index)", "method",
                        "Return the item at an index.",
                        [[
Return the item at a 1-based index, or `nil` when the index is outside the list.

A non-number index raises an argument error. Negative and zero indexes simply produce `nil`.
]]),
                    entry("collection.list:set", "list:set(index, item)", "method",
                        "Replace the item at an index.",
                        [[
Replace the item at a 1-based index and return the previous value.

A non-number index raises an argument error. Setting an index outside the current list stores the value there without changing the size; only `add` maintains the list length.
]]),
                    entry("collection.list:index_of", "list:index_of(item)", "method",
                        "Return the first index of an item, or 0.",
                        [[
Return the 1-based index of the first occurrence of an item, or `0` when it is absent.

Comparison uses `==`. The alias semantics are those of a linear forward search.

```lua
local l = list:new { "a", "b", "a" }
print(l:index_of("a")) --> 1
print(l:index_of("z")) --> 0
```
]]),
                    entry("collection.list:last_index_of", "list:last_index_of(item)", "method",
                        "Return the last index of an item, or 0.",
                        [[
Return the 1-based index of the last occurrence of an item, or `0` when it is absent.

The whole list is scanned, with later matches replacing earlier ones.
]]),
                    entry("collection.list:remove", "list:remove(item)", "method",
                        "Remove the first occurrence of an item.",
                        [[
Remove the first occurrence of an item from the list.

Returns true when an item was removed and false when it was not found. Later elements shift down to fill the gap, and the size is decremented.
]]),
                    entry("collection.list:remove_index", "list:remove_index(index)", "method",
                        "Remove the item at an index.",
                        [[
Remove the item at a 1-based index.

The list is compacted and its size is decremented. Returns the list itself, not the removed value, so the call can be chained.

```lua
local l = list:new { "a", "b", "c" }:remove_index(2)
--> { "a", "c" }
```
]]),
                    entry("collection.list:retain_all", "list:retain_all(items)", "method",
                        "Keep only items present in another collection.",
                        [[
Keep only items that are present in another collection or array-like table.

The list is modified in place, preserving the relative order of survivors, and is returned. A plain table is converted to a set for fast membership tests.
]]),
                    entry("collection.list:sublist", "list:sublist(from, to)", "method",
                        "Return a new list containing the given range.",
                        [[
Return a new list containing the inclusive range from `from` through `to`.

Both indexes must be numbers. The result is a new list; the original is unchanged. Values outside the list's current range may leave holes, so callers should pass valid indexes.

```lua
list:new{ "a", "b", "c" }:sublist(2, 3):to_array() --> { "b", "c" }
```
]]),
                    entry("collection.list:for_each", "list:for_each(func)", "method",
                        "Call `func` for every item.",
                        [[
Call `func(item)` for every item in list order.

Returns the list for chaining. Mutating the list during iteration has unspecified results.
]]),
                    entry("collection.list:for_each_index", "list:for_each_index(func)", "method",
                        "Call `func(index, item)` for every item.",
                        [[
Call `func(index, item)` for every item, with 1-based indexes.

Returns the list for chaining. This is useful when the position matters as well as the value.

```lua
list:new{ "a", "b" }:for_each_index(function(i, v) print(i, v) end)
```
]]),
                    entry("collection.list:iterate", "list:iterate()", "method",
                        "Return an iterator over items.",
                        [[
Return an iterator over the list's values.

Each call returns the next value, or `nil` at the end. Values are produced in array order.

```lua
for value in list:new{ "a", "b" }:iterate() do print(value) end
```
]]),
                    entry("collection.list:iterate_indexed", "list:iterate_indexed()", "method",
                        "Return an iterator over indexes and items.",
                        [[
Return an iterator over indexes and values.

Each call yields a 1-based index followed by the corresponding value. This is a thin wrapper over `ipairs` on the internal array.
]]),
                    entry("collection.list:iterator", "list:iterator(func)", "method",
                        "Call a function for every item until it returns false.",
                        [[
Call `func(item)` for every item until the callback returns `false` or `nil`.

Returns true when every callback returned a non-false value, false when iteration stopped early. This is a traversal helper, not an iterator factory.

```lua
local ok = list:new{ 1, 2, 3 }:iterator(function(v) return v < 3 end)
--> false
```
]]),
                    entry("collection.list:iterator_indexed", "list:iterator_indexed(func)", "method",
                        "Call an indexed function for every item until it returns false.",
                        [[
Call `func(index, item)` for every item until the callback returns `false` or `nil`.

Returns true when every callback returned a non-false value, false when iteration stopped early.
]]),
                }),

                module("collection.map", "collection.map", "Key-value map collection.", [==[
Maps preserve key/value associations and provide ordered variants through
`new_ordered`.
]==], {
                    entry("collection.map.new", "collection.map.new([initial])", "function",
                        "Create a new map.",
                        [[
Create a map from an optional table or existing map.

A plain table's key/value pairs are copied; an existing map's entries are copied through `put_all`. Iteration follows native table order. Use `new_ordered` when insertion order matters.

```lua
local map = require("collection").map
local m = map:new { a = 1, b = 2 }
print(m:get("a")) --> 1
```
]]),
                    entry("collection.map.new_ordered", "collection.map.new_ordered([initial])", "function",
                        "Create a map that iterates in insertion order.",
                        [[
Create a map that remembers insertion order for iteration.

The optional initial table or map is copied in its iteration order. Updating an existing key keeps its original position; removing and re-inserting a key moves it to the end.

```lua
local map = require("collection").map
local m = map:new_ordered { a = 1, b = 2 }
m:put("c", 3)
for k in m:iterate() do print(k) end --> a, b, c
```
]]),
                    entry("collection.map:put", "map:put(key, value)", "method",
                        "Associate a key with a value.",
                        [[
Associate `key` with `value` and return the previous value for that key, or `nil`.

If `value` is `nil`, the key is removed instead of stored. Adding a new non-nil key increments the size; in an ordered map it is appended to the insertion order.

```lua
local m = map:new()
print(m:put("a", 1)) --> nil
print(m:put("a", 2)) --> 1
```
]]),
                    entry("collection.map:get", "map:get(key)", "method",
                        "Return the value for a key, or nil.",
                        [[
Return the value associated with `key`, or `nil` when the key is absent.

Because `nil` is also used for missing entries, `contains_key` is the reliable existence test.
]]),
                    entry("collection.map:get_or_default", "map:get_or_default(key, default)", "method",
                        "Return a value or a default.",
                        [[
Return the value for `key`, or `default` when the key is absent.

A stored `false` value is returned as `false`, not replaced by the default.
]]),
                    entry("collection.map:put_all", "map:put_all(table)", "method",
                        "Copy all key/value pairs from a table or map.",
                        [[
Copy all key/value pairs from a plain table or another map into this map.

A collection argument must be a map; other collection types raise an argument error. Existing keys are overwritten, and the map itself is returned.

```lua
local m = map:new():put_all { a = 1, b = 2 }
```
]]),
                    entry("collection.map:put_if_absent", "map:put_if_absent(key, value)", "method",
                        "Insert a key only when it is not present.",
                        [[
Insert `value` only when `key` is not already present.

Returns `nil` when the value was inserted, or the existing value when the key was already present. A `nil` value is not inserted. Ordered maps append newly inserted keys.
]]),
                    entry("collection.map:remove", "map:remove(key [, value])", "method",
                        "Remove a key, optionally only when it has a given value.",
                        [[
Remove `key`, optionally only when its current value equals `value`.

With one argument, returns the removed value, or `nil` when the key was absent. With two arguments, returns true when the value matched and was removed, false when it did not, and `nil` when the key was absent. Removing the last key shrinks the size; ordered maps also remove it from the order.
]]),
                    entry("collection.map:merge", "map:merge(key, value, func)", "method",
                        "Merge a value into an existing key using `func`.",
                        [[
Merge a new value into `key` using a callback.

When the key exists, `func(key, value, old_value)` computes the replacement and `func` is required. When the key is absent, `value` is stored as-is and the callback is not called. Returns the final value, which may be `nil` to remove the key.

```lua
local m = map:new()
m:merge("count", 1) --> 1
m:merge("count", 2, function(_, new, old) return new + old end) --> 3
```
]]),
                    entry("collection.map:replace", "map:replace(key, old, new)", "method",
                        "Replace a value when it currently equals `old`.",
                        [[
Replace an existing value, in either conditional or unconditional form.

`m:replace(key, old, new)` replaces the value only when it currently equals `old`, and returns the old value. `m:replace(key, value)` sets the key to `value` unconditionally; if `value` is `nil`, the key is removed. In both forms the previous value is returned, or `nil` when the key was absent.
]]),
                    entry("collection.map:contains_key", "map:contains_key(key)", "method",
                        "Return true when a key exists.",
                        [[
Return true when the map has a non-nil value for `key`.

This is the correct existence check when values may legitimately be `false`.
]]),
                    entry("collection.map:contains_value", "map:contains_value(value)", "method",
                        "Return true when a value exists.",
                        [[
Return true when any entry in the map has the given value.

Comparison uses `==`, so table values are matched by identity rather than deep content. The search is linear.
]]),
                    entry("collection.map:entry_set", "map:entry_set()", "method",
                        "Return the entries as a set.",
                        [[
Return a set of tables, one per entry, each with `key` and `value` fields.

The set contains newly created entry tables, not references to the map. Entries are added to the set in the map's iteration order, but the returned value is an ordinary set.

```lua
for entry in map:new{ a = 1 }:entry_set():iterate() do
    print(entry.key, entry.value)
end
```
]]),
                    entry("collection.map:key_set", "map:key_set()", "method",
                        "Return the keys as a set.",
                        [[
Return a set containing every key in the map.

The returned set is independent of the map; modifying it does not affect the map. Iteration order follows the source map.
]]),
                    entry("collection.map:values", "map:values()", "method",
                        "Return the values as a collection.",
                        [[
Return a list containing every value in the map.

Values appear in the map's iteration order: insertion order for ordered maps, native table order otherwise. The returned list is independent of the map.
]]),
                    entry("collection.map:equals", "map:equals(other)", "method",
                        "Compare two maps for equal contents.",
                        [[
Compare this map with another map or plain table for equal key/value pairs.

A collection argument must be a map with the same size. Every key in the other object must exist here with an equal (not deep-equal) value, and the total counts must match.
]]),
                    entry("collection.map:compute", "map:compute(key, func)", "method",
                        "Compute a new value for a key.",
                        [[
Compute a new value for `key` with `func(key, old_value)` and store the result.

The callback is called even when the key is absent, with `nil` as the old value. If it returns `nil`, the key is removed; otherwise the value is stored. The computed value is returned.
]]),
                    entry("collection.map:compute_if_absent", "map:compute_if_absent(key, func)", "method",
                        "Compute a value only when the key is absent.",
                        [[
Compute and store a value only when `key` is absent.

The callback receives the key and its return value is stored when non-nil. If the key already exists, the existing value is returned without calling the callback.

```lua
local m = map:new()
print(m:compute_if_absent("a", function() return "A" end)) --> "A"
print(m:compute_if_absent("a", function() return "Z" end)) --> "A"
```
]]),
                    entry("collection.map:compute_if_present", "map:compute_if_present(key, func)", "method",
                        "Compute a value only when the key is present.",
                        [[
Recompute a value only when `key` is present.

The callback receives `(key, old_value)`. A non-nil result replaces the value; `nil` removes the key. Returns the new value, or `nil` when the key was absent.
]]),
                    entry("collection.map:for_each", "map:for_each(func)", "method",
                        "Call `func(key, value)` for every entry.",
                        [[
Call `func(key, value)` for every entry in the map.

Iteration follows insertion order for ordered maps and native table order otherwise. Returns the map for chaining.
]]),
                    entry("collection.map:iterate", "map:iterate()", "method",
                        "Return an iterator over keys and values.",
                        [[
Return an iterator yielding `key, value` pairs.

Ordered maps iterate in insertion order; ordinary maps use `pairs`. Returns the standard iterator triple suitable for a generic `for` loop.

```lua
for key, value in map:new{ a = 1 }:iterate() do print(key, value) end
```
]]),
                    entry("collection.map:iterator", "map:iterator(func)", "method",
                        "Call a function for every entry until it returns false.",
                        [[
Call `func(key, value)` for every entry until the callback returns `false` or `nil`.

Returns true when all callbacks returned a non-false value, false when iteration stopped early. This is a traversal helper, not an iterator factory.
]]),
                    entry("collection.map:size", "map:size()", "method",
                        "Return the number of entries.",
                        [[
Return the number of key/value entries in the map.

The count is maintained by `put` and `remove`, so it is O(1) and does not scan the table.
]]),
                    entry("collection.map:is_empty", "map:is_empty()", "method",
                        "Return true when the map has no entries.",
                        [[
Return true when the map contains no entries.

This is equivalent to `map:size() == 0`.
]]),
                }),

                module("collection.set", "collection.set", "Set collection with optional insertion order.", [==[
A set stores unique values.  `new_ordered` preserves insertion order during
iteration.
]==], {
                    entry("collection.set.new", "collection.set.new([initial])", "function",
                        "Create a new set.",
                        [[
Create a set from an optional initial collection or array-like table.

Duplicate values are stored only once, and element order follows the native table iteration order unless `new_ordered` is used. The initial table is copied, not referenced.

```lua
local set = require("collection").set
local s = set:new { 1, 2, 2, 3 }
print(s:size()) --> 3
```
]]),
                    entry("collection.set.new_ordered", "collection.set.new_ordered([initial])", "function",
                        "Create an insertion-ordered set.",
                        [[
Create a set that preserves insertion order during iteration.

The optional initial collection or array is added in order. Removing and re-adding a value places it at the end of the order. Use `iterate`, `iterate_indexed` or `for_each` to observe the order.

```lua
local s = require("collection").set:new_ordered { "b", "a" }
s:add("c")
for v in s:iterate() do print(v) end --> b, a, c
```
]]),
                    entry("collection.set:add", "set:add(item)", "method",
                        "Add one unique value.",
                        [[
Add a value to the set and return the set.

Adding a value that is already present leaves the set unchanged. `nil` is not a valid set element and raises an argument error, as does passing more than one value. Use `set:add_all` to add several items at once.

```lua
local s = require("collection").set:new()
s:add("x"):add("x") --> size remains 1
```
]]),
                    entry("collection.set:remove", "set:remove(item)", "method",
                        "Remove a value.",
                        [[
Remove a value from the set.

Returns true when the value was present and removed, false otherwise. Removing an absent value is harmless. Ordered sets keep the relative order of their remaining values.
]]),
                    entry("collection.set:contains", "set:contains(item)", "method",
                        "Return true when a value is present.",
                        [[
Return true when the set contains the given value.

Lookup is a direct table-key test, so it is O(1) on average. Values must be valid Lua table keys.
]]),
                    entry("collection.set:retain_all", "set:retain_all(items)", "method",
                        "Keep only values also present in another collection.",
                        [[
Keep only values that are also present in the supplied collection or table.

The set is modified in place and returned. For ordered sets, the surviving values retain their insertion order. Plain array-like tables and other collections are both accepted.
]]),
                    entry("collection.set:for_each", "set:for_each(func)", "method",
                        "Call `func(value)` for every value.",
                        [[
Call `func(value)` for every value in the set.

The iteration order is insertion order for ordered sets and native table order otherwise. Returns the set for chaining. Mutating the set during iteration has unspecified results.
]]),
                    entry("collection.set:iterate", "set:iterate()", "method",
                        "Return an iterator over values.",
                        [[
Return an iterator over the set's values.

Each call to the iterator returns the next value, or `nil` when exhausted. Ordered sets preserve insertion order; ordinary sets follow native table order.

```lua
for value in set:new{ "a", "b" }:iterate() do print(value) end
```
]]),
                    entry("collection.set:iterate_indexed", "set:iterate_indexed()", "method",
                        "Return an iterator over indexes and values.",
                        [[
Return an iterator over indexes and values.

Each call yields a consecutive 1-based index and the corresponding value. Ordered sets iterate their insertion-order array; ordinary sets count values in native table order.
]]),
                    entry("collection.set:iterator", "set:iterator(func)", "method",
                        "Call a function for every value until it returns false.",
                        [[
Call `func(value)` for every value until the callback returns `false` or `nil`.

Returns true when every callback returned a non-false value, false when iteration stopped early. This is a traversal helper, not an iterator factory.

```lua
local s = require("collection").set:new { 1, 2, 3 }
local ok = s:iterator(function(v) return v < 3 end) --> false, because 3 fails the predicate
```
]]),
                    entry("collection.set:iterator_indexed", "set:iterator_indexed(func)", "method",
                        "Call an indexed function for every value until it returns false.",
                        [[
Call `func(index, value)` for every value until the callback returns `false` or `nil`.

Returns true when every callback returned a non-false value, false when iteration stopped early. Indexes start at 1.
]]),
                    entry("collection.set:size", "set:size()", "method",
                        "Return the number of values.",
                        [[
Return the number of unique values in the set.

The count is maintained as values are added and removed, so it is O(1) and does not scan the set.
]]),
                    entry("collection.set:is_empty", "set:is_empty()", "method",
                        "Return true when the set is empty.",
                        [[
Return true when the set contains no values.

This is equivalent to `set:size() == 0`.
]]),
                }),

                module("crossline", "crossline", "Readline, screen, cursor, history and paging helpers.", [==[
`crossline` is a small self-contained readline replacement.  The module exposes
the low-level screen and cursor helpers plus history and paging functions used by
the REPL.
]==], {
                    entry("crossline.readline", "crossline.readline([prompt [, initial]])", "function",
                        "Read a line with editing and history.",
                        [[
Read one line from the terminal with editing and history.

`prompt` defaults to `"> "`. `initial` pre-fills the edit buffer and may be modified interactively; it is limited to 4095 bytes. History navigation, incremental search and completion keys are handled by the editor.

Returns the entered line as a string, or `nil` when standard input reaches end-of-file. The returned line does not include the newline.

```lua
local cl = require "crossline"
local line = cl.readline("name> ")
if line then print("hello " .. line) end
```
]]),
                    entry("crossline.set_prompt_color", "crossline.set_prompt_color(fg [, bg])", "function",
                        "Set the prompt colour.",
                        [[
Set the foreground and background colours used for the readline prompt.

`fg` and `bg` are numeric colour values, normally selected from `crossline.color.fg` and `crossline.color.bg`; the two values are combined into one terminal colour code. Omitting either value disables that component. The setting affects subsequently printed prompts and returns nothing.

```lua
local cl = require "crossline"
cl.set_prompt_color(cl.color.fg.green, cl.color.bg.default)
local line = cl.readline("> ")
```
]]),
                    entry("crossline.set_color", "crossline.set_color(fg [, bg])", "function",
                        "Set the current output colour.",
                        [[
Set the foreground and background colours used for subsequent terminal output.

`fg` and `bg` are numeric values from `crossline.color.fg` and `crossline.color.bg`; omitting a component leaves it at the default colour. The call returns nothing and does not change the prompt colour.

```lua
local cl = require "crossline"
cl.set_color(cl.color.fg.yellow)
print("warning")
cl.set_color(cl.color.fg.default)
```
]]),
                    entry("crossline.print_paged", "crossline.print_paged(text)", "function",
                        "Print long text through the pager.",
                        [[
Print a string or an array of lines through the pager.

Paging is temporarily enabled for the duration of the call. A string is split on newline characters; a table is printed one element per line. When the terminal reaches the bottom, the user may continue with Space or Enter or abort with another key.

Returns `true` when all output was printed and `false` when the user stopped early. Paging is disabled again before returning.

```lua
local cl = require "crossline"
cl.print_paged({ "line one", "line two", "line three" })
```
]]),
                    entry("crossline.screen.dimensions", "crossline.screen.dimensions()", "function",
                        "Return the terminal width and height.",
                        [[
Return the current terminal size as a table.

The `x` field is the number of columns and `y` is the number of rows. The result is a fresh table and may change when the terminal is resized.

```lua
local cl = require "crossline"
local size = cl.screen.dimensions()
print(size.x, size.y)
```
]]),
                    entry("crossline.screen.clear", "crossline.screen.clear()", "function",
                        "Clear the terminal screen.",
                        [[
Clear the terminal screen and leave the cursor at the home position.

The function emits the terminal control sequence directly and works on ANSI-compatible terminals. It returns nothing and does not alter history or paging state.

```lua
local cl = require "crossline"
cl.screen.clear()
```
]]),
                    entry("crossline.cursor.get", "crossline.cursor.get()", "function",
                        "Return the current cursor position (`x`, `y`).",
                        [[
Return the current cursor position as a table.

The result has numeric `x` (column) and `y` (row) fields using the terminal's coordinate system. The call does not move the cursor or change terminal state.

```lua
local cl = require "crossline"
local pos = cl.cursor.get()
print(pos.x, pos.y)
```
]]),
                    entry("crossline.cursor.set", "crossline.cursor.set(x, y)", "function",
                        "Move the cursor to a position.",
                        [[
Move the cursor to an absolute position.

Coordinates may be passed as two numbers (`x`, `y`) or as a table with `x` and `y` fields. The position uses the same coordinate system as `cursor.get`. The function returns nothing.

```lua
local cl = require "crossline"
cl.cursor.set(1, 1)
cl.cursor.set({ x = 10, y = 5 })
```
]]),
                    entry("crossline.cursor.move", "crossline.cursor.move(x, y)", "function",
                        "Move the cursor relative to its current position.",
                        [[
Move the cursor relative to its current position.

Positive `x` moves right, positive `y` moves down; negative values move left and up. As with `cursor.set`, the arguments may be two numbers or a table with `x` and `y` fields. No value is returned.

```lua
local cl = require "crossline"
cl.cursor.move(2, 0)
cl.cursor.move({ x = -1, y = 1 })
```
]]),
                    entry("crossline.cursor.hide", "crossline.cursor.hide()", "function",
                        "Hide the cursor.",
                        [[
Hide the terminal cursor.

This is useful while redrawing a prompt or progress display. It returns nothing; call `cursor.show()` to restore the cursor. Showing an already hidden cursor is harmless.

```lua
local cl = require "crossline"
cl.cursor.hide()
-- draw something
cl.cursor.show()
```
]]),
                    entry("crossline.cursor.show", "crossline.cursor.show()", "function",
                        "Show the cursor.",
                        [[
Show the terminal cursor after it was hidden.

The call emits the terminal control sequence and returns nothing. It does not move the cursor or restore a previous position.

```lua
local cl = require "crossline"
cl.cursor.hide()
cl.cursor.show()
```
]]),
                    entry("crossline.history.save", "crossline.history.save(filename)", "function",
                        "Save the command history.",
                        [[
Write the in-memory command history to a file.

The file is opened for writing and overwritten; each history entry is written on its own line without numeric prefixes. If the file cannot be opened the failure is silently ignored. The function returns nothing.

```lua
local cl = require "crossline"
cl.history.save(os.home .. "/.config/zli/repl_history")
```
]]),
                    entry("crossline.history.load", "crossline.history.load(filename)", "function",
                        "Load the command history.",
                        [[
Load command history from a file.

Non-empty lines are appended to the in-memory history with trailing CR/LF removed. A missing or unreadable file is silently ignored, making this safe to call during startup. The function returns nothing.

```lua
local cl = require "crossline"
cl.history.load(os.home .. "/.config/zli/repl_history")
```
]]),
                    entry("crossline.history.show", "crossline.history.show()", "function",
                        "Print the command history.",
                        [[
Print the current history with sequence numbers.

Output goes to standard output and may be paged when standard input and output are terminals. The history itself is not modified. The function returns nothing.

```lua
local cl = require "crossline"
cl.history.show()
```
]]),
                    entry("crossline.history.clear", "crossline.history.clear()", "function",
                        "Clear the command history.",
                        [[
Erase all in-memory history entries.

The history file on disk is not touched; use `history.save` afterwards if the cleared state should persist. The function returns nothing.

```lua
local cl = require "crossline"
cl.history.clear()
```
]]),
                    entry("crossline.paging.start", "crossline.paging.start()", "function",
                        "Start paging output.",
                        [[
Enable paging for subsequent output.

While paging is active, `paging.print` and `paging.check` count printed lines and prompt the user when the screen is full. The function returns nothing. Calling it when paging is already active just resets the line counter.

```lua
local cl = require "crossline"
cl.paging.start()
cl.paging.print("first line")
cl.paging.stop()
```
]]),
                    entry("crossline.paging.stop", "crossline.paging.stop()", "function",
                        "Stop paging output.",
                        [[
Disable paging.

Subsequent `paging.print` calls still print their text but do not pause for the user. The function returns nothing and is safe to call when paging is already off.

```lua
local cl = require "crossline"
cl.paging.stop()
```
]]),
                    entry("crossline.paging.check", "crossline.paging.check()", "function",
                        "Check whether paging is active.",
                        [[
Advance the pager by a line length and report whether output may continue.

`line_len` is the number of characters about to be displayed and is required. When paging is disabled, or input/output is not a terminal, the function immediately returns `true`. On a full screen it waits for Space or Enter and returns `true` to continue, or `false` when the user pressed another key to stop.

```lua
local cl = require "crossline"
cl.paging.start()
local keep_going = cl.paging.check(#"some output")
cl.paging.stop()
```
]]),
                    entry("crossline.paging.print", "crossline.paging.print(text)", "function",
                        "Print text through the pager.",
                        [[
Print text through the pager.

The argument may be a string, which is split on newlines, or an array of strings. Each line is written to standard output and checked against the terminal height. The function returns `true` when every line was printed, or `false` when the user stopped paging early.

```lua
local cl = require "crossline"
cl.paging.start()
local complete = cl.paging.print({ "row 1", "row 2", "row 3" })
cl.paging.stop()
print(complete)
```
]]),
                }, { upstream = "https://github.com/jcwangxp/Crossline", license = "MIT" }),

                module("filesystem", "filesystem", "Filesystem and path manipulation.", [==[
`filesystem` provides module-level functions and path objects.  A path object is
a table with `path`, `name`, `full_path` and the path methods documented below.
Path objects are accepted anywhere a path string is accepted.

```lua
local fs = require "filesystem"
local p = fs.path("src/version")
p.full_path        --> "src/version"
p:exists()
p:size()
```
]==], {
                    entry("filesystem.cwd", "fs.cwd() / fs.current_directory()", "function",
                        "Return the current working directory.",
                        [[
Return the absolute path of the current working directory as a string. The path is resolved through the operating system, so it has no trailing separator and no `.` or `..` components.

On failure the function follows the module's error-handling mode: it returns `nil, message` by default, or raises when `fs:config { error_handling = "raise" }` was applied.

```lua
local fs = require "filesystem"
print(fs.cwd())
```
]]),
                    entry("filesystem.create_path", "fs.create_path(path, name)", "function",
                        "Create a path object from a directory and file name.",
                        [[
Build a path object from a directory part and a final name, without normalizing either component.

`path` is stored in the `path` field, `name` in the `name` field, and the joined result in `full_path`. A separator is inserted when `path` does not already end with one. Both arguments must be strings.

```lua
local p = require("filesystem").create_path("src", "version")
print(p.full_path) --> "src/version"
print(p.name)      --> "version"
```
]]),
                    entry("filesystem.path", "fs.path(...)", "function",
                        "Normalize components into a path object.",
                        "Accepts strings, path objects and path component tables.  Relative paths stay relative; paths beginning with `.` or `..` are resolved against the current directory."),
                    entry("filesystem.ensure_path", "fs.ensure_path(path)", "function",
                        "Return a path object, converting a string when needed.",
                        [[
Return a path object for `path`. A string is converted with `fs.path`; a table that already has a `full_path` field is returned unchanged.

Any other value raises an error, regardless of the module error-handling mode, because the check protects later filesystem calls from malformed path objects.
]]),
                    entry("filesystem.get_path", "fs.get_path(path)", "function",
                        "Return the underlying path string of a path object.",
                        [[
Return the path string stored in a path object, or the argument itself when it is already a string.

The function only extracts the value; it does not check existence or normalize the path. It is useful when passing a path object to another library.

```lua
local fs = require "filesystem"
local p = fs.path("src/version")
print(fs.get_path(p)) --> "src/version"
```
]]),
                    entry("filesystem.absolute", "fs.absolute(path)", "function",
                        "Return the absolute path, or nil when it does not exist.",
                        [[
Resolve `path` to its absolute, canonical form, following symbolic links. The path must exist.

Returns `nil` when the path cannot be resolved, for example because it is missing or a component is not accessible. It does not raise in the default error-handling mode.

```lua
local fs = require "filesystem"
print(fs.absolute("src/version"))
```
]]),
                    entry("filesystem.concat_path", "fs.concat_path(path, file)", "function",
                        "Join a path with a file name.",
                        [[
Join a directory path and a file name without normalizing the result.

`path` may be a string or an array of components; component arrays are joined with `fs.separator`. If `file` is `nil` or empty, `path` is returned unchanged. A separator is added when `path` does not already end in `/` or `\`.

```lua
local fs = require "filesystem"
print(fs.concat_path("src", "main.lua")) --> "src/main.lua"
```
]]),
                    entry("filesystem.split_path", "fs.split_path(path)", "function",
                        "Split a path into components.",
                        [[
Split a path into its slash- or backslash-separated components and return them as an array.

Separators and repeated separators are discarded, but `.` and `..` components are preserved. A leading root separator or drive letter is not included in the result.

```lua
local fs = require "filesystem"
table.print(fs.split_path("/usr/local/bin")) --> { "usr", "local", "bin" }
```
]]),
                    entry("filesystem.create_tree", "fs.create_tree(path)", "function",
                        "Create a directory and all missing parents.",
                        [[
Create `path` and every missing parent directory. Existing directories are left alone, so the call is idempotent.

`path` may be a string or a path object. Directory creation errors follow the module's error-handling mode.

```lua
local fs = require "filesystem"
fs.create_tree("build/cache/data")
```
]]),
                    entry("filesystem.delete_tree", "fs.delete_tree(path)", "function",
                        "Delete a directory tree recursively.",
                        [[
Recursively delete a directory tree, including the directory named by `path` itself.

Children are removed before their containing directory, and symbolic-link cycles are not followed. Deletion errors follow the module's error-handling mode.

```lua
require("filesystem").delete_tree("build/cache")
```
]]),
                    entry("filesystem.list", "path:list()", "method",
                        "Return the directory entries as an array of path objects.",
                        [[
Return the entries of a directory as an array of path objects. The returned paths are absolute, with `path` set to the directory and `name` set to the entry name.

`path` may be a path object or a string; with no argument the current directory is listed. Directory-open and traversal errors follow the module's error-handling mode.

```lua
local fs = require "filesystem"
for _, entry in ipairs(fs.path("src"):list()) do
    print(entry.name)
end
```
]]),
                    entry("filesystem.dir", "path:dir()", "method",
                        "Return the directory entries keyed by name.",
                        [[
Return the entries of a directory as a table keyed by entry name. Each value is a path object whose `full_path` points at the entry.

This is the keyed counterpart of `path:list()`. Errors are reported according to the module's error-handling mode.

```lua
local fs = require "filesystem"
local entries = fs.path("src"):dir()
print(entries["main.lua"].full_path)
```
]]),
                    entry("filesystem.iterate", "fs.iterate(path [, sorted])", "method",
                        "Iterate the entries of a directory.",
                        [[
Iterate the entries of a directory, yielding the entry name and its path object.

By default the order is the native directory order. Pass `true` as `sorted` to iterate names in sorted order. This is normally used as `for name, entry in fs.iterate(path) do ... end` or `path:iterate()`.

```lua
local fs = require "filesystem"
for name, entry in fs.path("src"):iterate(true) do
    print(name, entry.full_path)
end
```
]]),
                    entry("filesystem.walk", "fs.walk(path, func [, dir_first])", "function",
                        "Walk a directory tree, calling `func(path)` for each entry.",
                        [[
Walk a directory tree, calling `func(path)` once for every entry, including the starting path.

When `dir_first` is true, a directory is passed to `func` before its children. Otherwise children are visited first and the directory is reported on the way out. Symbolic-link targets are resolved and each real directory is visited at most once, which prevents cycles.

A string path must exist; the function then walks its absolute form. Errors opening or traversing a directory follow the module's error-handling mode.

```lua
local fs = require "filesystem"
fs.walk("src", function(path)
    print(path.full_path)
end, true)
```
]]),
                    entry("filesystem.tree", "fs.tree(path [, dir_first])", "function",
                        "Return all paths in a directory tree.",
                        [[
Return every path in a directory tree as an array, including the starting directory.

The order matches `fs.walk`: children before their directory by default, or directories first when `dir_first` is true. The starting path must exist.

```lua
local fs = require "filesystem"
local paths = fs.tree("src", true)
print(#paths)
```
]]),
                    entry("filesystem.tree_size", "fs.tree_size(path)", "function",
                        "Return the total size of files in a tree.",
                        [[
Return the combined size in bytes of all regular files below `path`. Directories and symbolic links do not add to the total.

The starting path is included in the walk, so a regular file passed directly contributes its own size. Errors follow the module's error-handling mode.
]]),
                    entry("filesystem.tree_size_hr", "fs.tree_size_hr(path)", "function",
                        "Return a human-readable tree size.",
                        [[
Return the total size of a directory tree formatted by `fs.size_to_hr`, for example `"12.40 KB"`.

This is a convenience wrapper around `fs.tree_size(path)`; it uses the same walk and error behavior.
]]),
                    entry("filesystem.stream", "fs.stream(path)", "function",
                        "Create a stream over directory entries.",
                        [[
Create a `stream` over the directory entries returned by `fs.list(path)`.

The stream yields path objects in native directory order. It does not recurse; use `fs.stream_tree` for a recursive stream.

```lua
local fs = require "filesystem"
local names = fs.path("src"):stream():map(function(p) return p.name end):toarray()
```
]]),
                    entry("filesystem.stream_tree", "fs.stream_tree(path [, dir_first])", "function",
                        "Create a stream over a directory tree.",
                        [[
Create a `stream` over all paths returned by `fs.tree(path, dir_first)`.

`dir_first` controls whether directories are yielded before their children, matching the corresponding `fs.walk` option. The stream includes the starting path.

```lua
local fs = require "filesystem"
local count = fs.stream_tree("src"):filter(function(p) return p:is_file() end):count()
```
]]),
                    entry("filesystem.read_all", "fs.read_all(path)", "function",
                        "Read an entire file as a string.",
                        [[
Read an entire file as a string and return it. The file is opened in text mode and closed before returning.

On failure the function follows the module's error-handling mode and returns `nil, message` by default. The path may be a string or a path object.

```lua
local text = require("filesystem").read_all("src/version")
```
]]),
                    entry("filesystem.read_lines", "fs.read_lines(path [, mode])", "function",
                        "Read a file into an array of lines.",
                        [[
Read a file into an array of lines. `mode` is passed to the underlying `file:lines` call and defaults to `"l"` (line without the terminator). Use `"L"` to keep newline characters.

On failure the function returns `nil, message` by default, or raises in raise mode.

```lua
local lines = require("filesystem").read_lines("src/version")
print(lines[1])
```
]]),
                    entry("filesystem.lines", "fs.lines(path [, mode])", "function",
                        "Iterate the lines of a file.",
                        [[
Iterate the lines of a file, yielding a 1-based index and the line text.

The optional `mode` is passed to `file:read` and defaults to `"l"` (line without its terminator); use `"L"` to keep newline characters. The file is closed automatically when the loop finishes. An open failure follows the module's error-handling mode.

```lua
local fs = require "filesystem"
for i, line in fs.lines("src/version") do
    print(i, line)
end
```
]]),
                    entry("filesystem.parent", "fs.parent(path)", "function",
                        "Return the parent path.",
                        [[
Return the parent directory of `path` as a path object, or `nil` when there is no parent.

Trailing separators are ignored. A root or drive root has no parent. A relative single-component path such as `"file"` resolves to the current directory because `fs.path(".")` is used as its parent.

```lua
local fs = require "filesystem"
print(fs.path("src/main.lua"):parent().full_path) --> "src"
```
]]),
                    entry("filesystem.child", "fs.child(path, name)", "function",
                        "Return a child path.",
                        [[
Return a new path object formed by joining `path` and `name`. No existence check is performed.

`name` must be a non-empty string; otherwise the function raises an error. The result is normalized by `fs.path`.

```lua
local fs = require "filesystem"
print(fs.path("src"):child("version").full_path) --> "src/version"
```
]]),
                    entry("filesystem.sibling", "fs.sibling(path, name)", "function",
                        "Return a sibling path.",
                        [[
Return a path in the same directory as `path` but with `name` as its final component. No existence check is performed.

A missing or empty name raises an error. For a path without a separator, the result is simply `fs.path(name)`.

```lua
local fs = require "filesystem"
print(fs.path("src/version"):sibling("main.lua").full_path)
```
]]),
                    entry("filesystem.to_relative", "fs.to_relative(path, base [, include_top])", "function",
                        "Return a path relative to a base path.",
                        [[
Return `path` expressed relative to `base`. Relative inputs are first resolved to absolute paths, so they must exist.

When `include_top` is true, the parent of `base` is used as the anchor, so `base` itself appears in the result. A trailing `/` is added when the result names a directory. If `path` is not below the anchor, its normalized full path is returned unchanged.

```lua
local fs = require "filesystem"
print(fs.to_relative("test/temp", "test")) --> "temp/"
```
]]),
                    entry("filesystem.is_empty", "fs.is_empty(path)", "function",
                        "Return true when a directory has no entries.",
                        [[
Return true when the directory named by `path` contains no entries. The path is converted with `fs.ensure_path` first.

The directory must exist and be readable. A failed listing raises a Lua error even in the default return-error mode, because the failure value is not a directory listing.
]]),
                    entry("filesystem.chmod", "fs.chmod(path, mode)", "function",
                        "Change file permissions on Linux.",
                        [[
Change a path's permissions on Linux using an octal mode string such as `"755"` or `"644"`.

The path may be a string or a path object. Returns true when the `chmod` command succeeds. It returns false on non-Linux systems, when the mode contains anything other than octal digits, or when the command fails. The function never raises.

```lua
local fs = require "filesystem"
assert(fs.chmod("script.sh", "755"))
```
]]),
                    entry("filesystem.chown", "fs.chown(path, owner)", "function",
                        "Change file ownership on Linux.",
                        [[
Change the owner of a file or directory on Linux using the system `chown` command.

`owner` is a string such as `"user"`, `"user:group"` or `"1000:1000"`; only letters, digits, `_`, `.`, `:`, and `-` are accepted. Returns true on success and false on non-Linux systems, invalid input, or command failure. It never raises.
]]),
                    entry("filesystem.size_to_hr", "fs.size_to_hr(bytes)", "function",
                        "Format a byte count as a human-readable size.",
                        [[
Format a byte count as a human-readable string using binary units (`KB`, `MB`, `GB`, `TB`).

Values below 1024 are returned as an integer followed by `" B"`; larger values use two decimal places. The argument must be an integer, otherwise an argument error is raised.

```lua
local fs = require "filesystem"
print(fs.size_to_hr(2048)) --> "2.00 KB"
```
]]),
                    entry("filesystem.config", "fs:config(options)", "method",
                        "Configure a loaded filesystem module.",
                        "Accepts `{ error_handling = \"return\" | \"raise\" }` and returns the same module table."),

                    entry("filesystem.path:exists", "path:exists()", "method",
                        "Return true when the path exists.",
                        [[
Return true when the path names an existing file or directory, and false otherwise.

The check is a direct open attempt, so permission failures and broken symbolic links also produce false. It does not raise for a missing path.
]]),
                    entry("filesystem.path:is_file", "path:is_file()", "method",
                        "Return true for a regular file.",
                        [[
Return true when the path currently refers to a regular file.

The path is examined with a stat call; missing paths and other filesystem errors follow the module's error-handling mode.
]]),
                    entry("filesystem.path:is_directory", "path:is_directory()", "method",
                        "Return true for a directory.",
                        [[
Return true when the path currently refers to a directory.

The path is examined with a stat call; missing paths and other filesystem errors follow the module's error-handling mode.
]]),
                    entry("filesystem.path:size", "path:size()", "method",
                        "Return the file size in bytes.",
                        [[
Return the size of the file or directory in bytes as an integer.

The value comes from the platform stat call. A missing path or stat failure follows the module's error-handling mode.
]]),
                    entry("filesystem.path:size_hr", "path:size_hr()", "method",
                        "Return a human-readable size.",
                        [[
Return the size of the path formatted with binary units, such as `"4.20 MB"`.

This combines `path:size()` with `fs.size_to_hr`; stat errors follow the module's error-handling mode.
]]),
                    entry("filesystem.path:stat", "path:stat()", "method",
                        "Return file metadata.",
                        [[
Return a table of metadata for the path. The table always contains `is_file`, `is_directory`, `size`, `size_hr`, `create_time`, `create_time_ms`, `create_time_stamp`, `modify_time`, `modify_time_ms`, `modify_time_stamp`, `mode` and `mode_flags`.

When the platform reports an access time, `access_time`, `access_time_ms` and `access_time_stamp` are also present. The `create_time` fields reflect the platform's creation/change timestamp and may have platform-specific semantics. A stat failure follows the module's error-handling mode.

```lua
local st = require("filesystem").path("src/version"):stat()
print(st.size, st.mode_flags)
```
]]),
                    entry("filesystem.path:access_time", "path:access_time()", "method",
                        "Return the last access time.",
                        [[
Return the last access time as a Unix timestamp in seconds, or `nil` when the platform does not report it.

Stat errors follow the module's error-handling mode.
]]),
                    entry("filesystem.path:create_time", "path:create_time()", "method",
                        "Return the creation time.",
                        [[
Return the platform's creation/change time as a Unix timestamp in seconds.

On POSIX systems this is usually the inode change time (`ctime`), not the original creation time. Stat errors follow the module's error-handling mode.
]]),
                    entry("filesystem.path:modify_time", "path:modify_time()", "method",
                        "Return the last modification time.",
                        [[
Return the last modification time as a Unix timestamp in seconds.

Stat errors follow the module's error-handling mode.
]]),
                    entry("filesystem.path:access_time_ms", "path:access_time_ms()", "method",
                        "Return access time in milliseconds.",
                        [[
Return the last access time as a Unix timestamp in milliseconds, or `nil` when the platform does not expose an access time.

Stat errors follow the module's error-handling mode.
]]),
                    entry("filesystem.path:create_time_ms", "path:create_time_ms()", "method",
                        "Return creation time in milliseconds.",
                        [[
Return the platform's creation/change time in milliseconds since the Unix epoch.

This is the millisecond form of `path:create_time()`; stat errors follow the module's error-handling mode.
]]),
                    entry("filesystem.path:modify_time_ms", "path:modify_time_ms()", "method",
                        "Return modification time in milliseconds.",
                        [[
Return the last modification time in milliseconds since the Unix epoch.

This is the millisecond form of `path:modify_time()`; stat errors follow the module's error-handling mode.
]]),
                    entry("filesystem.path:access_time_stamp", "path:access_time_stamp()", "method",
                        "Return a formatted access timestamp.",
                        [[
Return the last access time formatted as `YYYY/MM/DD HH:MM:SS` in local time, or `nil` when no access time is available.

Stat errors follow the module's error-handling mode.
]]),
                    entry("filesystem.path:create_time_stamp", "path:create_time_stamp()", "method",
                        "Return a formatted creation timestamp.",
                        [[
Return the platform's creation/change time formatted as `YYYY/MM/DD HH:MM:SS` in local time.

This is the formatted form of `path:create_time()`; stat errors follow the module's error-handling mode.
]]),
                    entry("filesystem.path:modify_time_stamp", "path:modify_time_stamp()", "method",
                        "Return a formatted modification timestamp.",
                        [[
Return the last modification time formatted as `YYYY/MM/DD HH:MM:SS` in local time.

This is the formatted form of `path:modify_time()`; stat errors follow the module's error-handling mode.
]]),
                    entry("filesystem.path:mode", "path:mode()", "method",
                        "Return the file mode.",
                        [[
Return the file permission bits as an integer, directly from the platform stat call.

Use `path:mode_flags()` for a readable `drwxr-xr-x`-style string. Stat errors follow the module's error-handling mode.
]]),
                    entry("filesystem.path:mode_flags", "path:mode_flags()", "method",
                        "Return the file mode flags.",
                        [[
Return the file type and permissions as a POSIX-style 10-character string, for example `"-rw-r--r--"` or `"drwxr-xr-x"`.

On Windows the permission bits are reported as all enabled. Stat errors follow the module's error-handling mode.
]]),
                    entry("filesystem.path:open", "path:open([mode])", "method",
                        "Open the file and return a file handle.",
                        [[
Open the path with `io.open` and return a Lua file handle plus the usual second result from `io.open`.

`mode` defaults to `"r"`. A missing file or permission failure therefore returns `nil, message` exactly as `io.open` does.

```lua
local p = require("filesystem").path("src/version")
local f = assert(p:open("r"))
print(f:read("a"))
f:close()
```
]]),
                    entry("filesystem.path:rename", "path:rename(new_path) / path:mv(new_path)", "method",
                        "Rename or move the path.",
                        [[
Rename or move the path to `new_path`. The aliases `path:mv` and `fs`-style names refer to the same operation.

The destination may be a string or a path object. On success there is no return value; errors follow the module's error-handling mode.
]]),
                    entry("filesystem.path:delete", "path:delete() / path:rm()", "method",
                        "Delete the file or empty directory.",
                        [[
Delete the file or empty directory named by the path. Non-empty directories are not removed recursively; use `path:delete_tree()` for that.

The aliases `path:rm` and `path:delete` are equivalent. Errors follow the module's error-handling mode.
]]),
                    entry("filesystem.path:change_directory", "path:change_directory() / path:cd()", "method",
                        "Change the current directory to this path.",
                        [[
Change the process working directory to this path. The aliases `path:cd` and `path:change_directory` are equivalent.

The path must be an existing directory. Errors follow the module's error-handling mode; on success there is no return value.
]]),
                    entry("filesystem.path:create_directory", "path:create_directory() / path:mkdir()", "method",
                        "Create the directory.",
                        [[
Create this directory as a single filesystem operation. Missing parents are not created and an existing directory is an error; use `fs.create_tree` for recursive creation.

The aliases `path:mkdir` and `path:create_directory` are equivalent. Errors follow the module's error-handling mode.
]]),
                    entry("filesystem.path:read_all", "path:read_all()", "method",
                        "Read the file as a string.",
                        [[
Read the file named by the path as a string.

This is the method form of `fs.read_all`; open and read errors follow the module's error-handling mode.
]]),
                    entry("filesystem.path:read_lines", "path:read_lines([mode])", "method",
                        "Read the file into an array of lines.",
                        [[
Read the file named by the path into an array of lines. The optional `mode` is passed to `file:lines` and defaults to `"l"`.

This is the method form of `fs.read_lines`; open and read errors follow the module's error-handling mode.
]]),
                    entry("filesystem.path:lines", "path:lines([mode])", "method",
                        "Iterate the lines of the file.",
                        [[
Iterate the lines of the file named by the path, yielding `index, line`.

The optional `mode` defaults to `"l"`; use `"L"` to keep line terminators. The underlying file is closed automatically when iteration finishes. Open errors follow the module's error-handling mode.

```lua
local p = require("filesystem").path("src/version")
for i, line in p:lines() do
    print(i, line)
end
```
]]),
                    entry("filesystem.path:iterate", "path:iterate([sorted])", "method",
                        "Iterate directory entries.",
                        [[
Iterate the directory entries, yielding entry names and path objects. Pass `true` as `sorted` for name order; the default is native directory order.

This is the method form of `fs.iterate`; directory errors follow the module's error-handling mode.
]]),
                    entry("filesystem.path:delete_tree", "path:delete_tree()", "method",
                        "Delete the directory tree.",
                        [[
Recursively delete this directory tree, including the directory itself.

This is the method form of `fs.delete_tree`; deletion errors follow the module's error-handling mode.
]]),
                    entry("filesystem.path:walk", "path:walk(func [, dir_first])", "method",
                        "Walk the directory tree.",
                        [[
Walk this directory tree, calling `func(path)` for each entry including the starting directory.

`dir_first` controls whether a directory is reported before or after its contents. Symbolic-link cycles are avoided by visiting each real directory once.

```lua
require("filesystem").path("src"):walk(function(p)
    if p:is_file() then print(p.full_path) end
end)
```
]]),
                    entry("filesystem.path:parent", "path:parent()", "method",
                        "Return the parent path.",
                        [[
Return the parent directory as a path object, or `nil` at a filesystem root.

This is the method form of `fs.parent`; trailing separators are ignored and relative single-component paths resolve against the current directory.
]]),
                    entry("filesystem.path:child", "path:child(name)", "method",
                        "Return a child path.",
                        [[
Return a new path object formed by appending `name` to this path.

`name` must be a non-empty string. The result is normalized; no existence check is made.
]]),
                    entry("filesystem.path:sibling", "path:sibling(name)", "method",
                        "Return a sibling path.",
                        [[
Return a path in the same directory with `name` as its final component.

A missing or empty name raises an error. No existence check is performed.
]]),
                    entry("filesystem.path:stream", "path:stream()", "method",
                        "Create a stream over directory entries.",
                        [[
Create a `stream` over this directory's entries.

The stream yields path objects from `fs.list`; it does not recurse. Directory errors follow the module's error-handling mode.
]]),
                    entry("filesystem.path:stream_tree", "path:stream_tree([dir_first])", "method",
                        "Create a stream over the tree.",
                        [[
Create a `stream` over this directory tree, including the starting path.

`dir_first` controls whether directories are yielded before their contents. The stream is built from `fs.tree`.

```lua
local files = require("filesystem").path("src"):stream_tree():filter(function(p)
    return p:is_file()
end):count()
```
]]),
                    entry("filesystem.path:tree", "path:tree([dir_first])", "method",
                        "Return the tree as an array of paths.",
                        [[
Return every path in this directory tree as an array, including the starting directory.

`dir_first` controls the order. The path must exist; otherwise errors follow the module's error-handling mode.
]]),
                    entry("filesystem.path:to_relative", "path:to_relative(base [, include_top])", "method",
                        "Return a relative path.",
                        [[
Return this path expressed relative to `base`, optionally including `base` itself when `include_top` is true.

Both paths are resolved to absolute paths first, so relative inputs must exist. A trailing `/` is added for directories. If the path is not below the anchor, its normalized full path is returned.

```lua
local fs = require "filesystem"
print(fs.path("test/temp"):to_relative("test")) --> "temp/"
```
]]),
                    entry("filesystem.path:chmod", "path:chmod(mode)", "method",
                        "Change permissions.",
                        [[
Change this path's permissions on Linux using an octal mode string such as `"755"` or `"644"`.

Returns true on success and false on non-Linux systems, invalid modes, or command failure. It never raises.

```lua
local p = require("filesystem").path("script.sh")
p:chmod("755")
```
]]),
                    entry("filesystem.path:chown", "path:chown(owner)", "method",
                        "Change ownership.",
                        [[
Change this path's owner on Linux. `owner` is a user name, `user:group` pair, or numeric uid/gid pair.

Returns true on success and false on non-Linux systems, invalid input, or command failure. It never raises.
]]),
                }, { aliases = { "fs" } }),

                module("grid", "grid", "Line-drawing text grids (tables).", [==[
`grid.new(config [, rows])` creates a text table.  `config` is an array of column
definitions: `{ name, align, min_width, max_width, fixed_width }`.  The table
configuration may also set `show_header` and `padding`.
]==], {
                    entry("grid.new", "grid.new(config [, rows])", "function",
                        "Create a grid.",
                        [[
Create a new grid from an array of column definitions.

Each column may set `name`, `align`, `min_width`, `max_width` and `fixed_width`; defaults are left alignment, minimum width 1 and maximum width 30. The optional configuration table may also set `show_header` (default true) and `padding` (default true). An optional `rows` array is added immediately. Both `grid.new(config)` and `grid:new(config)` are supported.

```lua
local grid = require "grid"
local g = grid.new({
    { name = "name" },
    { name = "size", align = "right", min_width = 4 },
})
g:add_row("version", 7)
print(g:tostring())
```
]]),
                    entry("grid:add_row", "grid:add_row(...) / grid:add_row(table)", "method",
                        "Add a row of values.",
                        [[
Add a row of values to the grid.

Values may be passed as separate arguments or as one array table. Each value is converted with `tostring`, and column widths grow to fit the content up to each column's `max_width`. The row is stored for later rendering; the method returns nothing.

```lua
local g = require("grid").new { { name = "item" }, { name = "qty" } }
g:add_row("apple", 3)
```
]]),
                    entry("grid:add_rows", "grid:add_rows(rows)", "method",
                        "Add multiple rows.",
                        [[
Add multiple rows to the grid.

`rows` must be an array of rows, where each row is itself an array of cell values (or a single table passed to `add_row`). Each row is added with `grid:add_row`; the method returns nothing.
]]),
                    entry("grid:header_string", "grid:header_string()", "method",
                        "Return the header lines.",
                        [[
Return the rendered header block as a string.

The block contains the top border and, when `show_header` is enabled, the header row. If the grid has no rows yet, this also initializes the column widths used by later row rendering.
]]),
                    entry("grid:row_string", "grid:row_string(...)", "method",
                        "Return one rendered row.",
                        [[
Return one rendered row as a string, including the separator border.

The values are formatted but not stored in the grid. If this is the first rendering call, the header block is included before the border and the row.

```lua
print(g:row_string("banana", 5))
```
]]),
                    entry("grid:last_string", "grid:last_string()", "method",
                        "Return the bottom border.",
                        [[
Return the bottom border of the grid as a string.

Column widths are calculated first if they have not been initialized. This is the same border printed by `grid:print_last` and appended by `grid:tostring`.
]]),
                    entry("grid:print_header", "grid:print_header()", "method",
                        "Print the header.",
                        [[
Print the header block returned by `grid:header_string`.

The output includes the top border and, when configured, the header row.
]]),
                    entry("grid:print_row", "grid:print_row(...)", "method",
                        "Print one row.",
                        [[
Print one rendered row returned by `grid:row_string`.

The values are formatted for display but are not added to the grid's stored rows.
]]),
                    entry("grid:print_last", "grid:print_last()", "method",
                        "Print the bottom border.",
                        [[
Print the bottom border of the grid.

This is equivalent to `print(grid:last_string())`; the return value is that of `print`.
]]),
                    entry("grid:tostring", "grid:tostring()", "method",
                        "Render the complete table as a string.",
                        [[
Render the complete grid as a string.

The result includes the top border, optional header row, all stored rows with separator borders, and the bottom border. The grid's `__tostring` metamethod calls this method, so `tostring(grid)` works too.

```lua
local g = require("grid").new { { name = "name" } }
g:add_row("value")
print(g:tostring())
```
]]),
                }),

                module("httpclient", "httpclient", "HTTP client based on Zig's HTTP client.", [==[
Every request function returns `response, body`.  `response` contains the status
line, headers and convenience fields.  On transport failure the functions return
`nil, message` unless `options.raiseError` is set.

Options include `header`, `query`, `parseJson`, `basicAuth`, `save` and
`raiseError`.  A table body is encoded as JSON automatically.
]==], {
                    entry("httpclient.get", "httpclient.get(url [, options [, body]])", "function",
                        "Perform a GET request.",
                        [[
Perform an HTTP GET request.

Returns `response, body` on success. `response` contains fields such as `status`, `status_name`, `reason`, `success`, `version`, `content_type`, `content_length`, `location` and `content_disposition` when present. GET requests cannot send a body; passing one raises an argument error.

Options include `header`, `query`, `parseJson`, `basicAuth`, `save` and `raiseError`. A table in `options.query` is URL-encoded and appended to the URL.

```lua
local http = require "httpclient"
local response, body = http.get("https://example.com", {
    query = { page = 2 },
})
print(response.status, #body)
```
]]),
                    entry("httpclient.head", "httpclient.head(url [, options [, body]])", "function",
                        "Perform a HEAD request.",
                        [[
Perform an HTTP HEAD request.

Returns the response metadata and an empty body. HEAD, like GET, cannot send a body. On a transport failure the function returns `nil, message` unless `options.raiseError` is true, in which case it raises.

```lua
local http = require "httpclient"
local response = http.head("https://example.com")
print(response.status, response.content_length)
```
]]),
                    entry("httpclient.post", "httpclient.post(url [, options [, body]])", "function",
                        "Perform a POST request.",
                        [[
Perform an HTTP POST request.

The optional body may be a string or a table. A table is encoded with cjson and the request gains `content_type: application/json` unless the caller already supplied one. Returns `response, body`.

The usual options apply, including headers, query parameters, JSON response parsing, authentication, saving the response and raising on transport errors.

```lua
local http = require "httpclient"
local response, body = http.post("https://example.com/api", nil, {
    name = "zli",
})
print(response.status)
```
]]),
                    entry("httpclient.put", "httpclient.put(url [, options [, body]])", "function",
                        "Perform a PUT request.",
                        [[
Perform an HTTP PUT request.

The body rules are the same as for `post`: strings are sent as-is and tables are JSON-encoded with an automatic content type. Returns `response, body`, or `nil, message` on transport failure unless `raiseError` is set.

```lua
local http = require "httpclient"
local response, body = http.put("https://example.com/item/1", nil, "new value")
print(response.success)
```
]]),
                    entry("httpclient.patch", "httpclient.patch(url [, options [, body]])", "function",
                        "Perform a PATCH request.",
                        [[
Perform an HTTP PATCH request.

Accepts an optional string or table body, just like `post` and `put`. The response body is returned as the second result and may be decoded with `options.parseJson`.

```lua
local http = require "httpclient"
local response, body = http.patch("https://example.com/item/1", nil, { done = true })
print(response.status, type(body))
```
]]),
                    entry("httpclient.delete", "httpclient.delete(url [, options [, body]])", "function",
                        "Perform a DELETE request.",
                        [[
Perform an HTTP DELETE request.

DELETE cannot send a body; supplying one raises an argument error. It returns `response, body` and supports the same options as the other convenience methods, including JSON parsing and response saving.

```lua
local http = require "httpclient"
local response, body = http.delete("https://example.com/item/1")
print(response.success)
```
]]),
                    entry("httpclient.call", "httpclient.call(method, url [, options [, body]])", "function",
                        "Perform a request with an explicit method.",
                        [[
Perform a request with an explicit HTTP method.

`method` is an upper-case method name such as `"GET"`, `"POST"`, `"PATCH"` or `"OPTIONS"`. `options` must be a table; the low-level call understands `header` and `privileged_headers` but not the Lua-level conveniences such as `query`, `basicAuth`, `parseJson`, `save` or `raiseError`. For POST, PUT and PATCH, `body` must already be a string.

Returns `response, body` on success. Failures follow the module `error_handling` setting: `nil, message` by default, or a raised error when configured to raise.

```lua
local http = require "httpclient"
local response, body = http.call("GET", "https://example.com", {
    header = { ["user-agent"] = "zli" },
})
print(response.status)
```
]]),
                    entry("httpclient.config", "httpclient:config(options)", "method",
                        "Configure a loaded httpclient module.",
                        [[
Configure the loaded httpclient module.

The supported option is `error_handling`, set to `"return"` or `"raise"`. It affects the low-level `call` function; the convenience request functions already honour `options.raiseError`.

Use colon syntax so the module table is passed first, then the options table. The module table is returned.

```lua
local http = require "httpclient"
http:config({ error_handling = "raise" })
assert(http.error_handling == "raise")
```
]]),
                }),

                module("httpserver", "httpserver", "HTTP server based on Zig's HTTP server.", [==[
`httpserver.serve(options)` starts a server.  Options include `address`, `port`,
`web_root`, `cache_web_root`, method route tables (`GET`, `POST`, ...) and a
`*` route table used for every method.

A route value may be a response string or a function `(options, request)`
returning a string, a response table, or a table that is encoded as JSON.
Request tables contain `method`, `target`, `version`, `body` and other request
metadata; message headers are available as named fields.  Responses use
`{ status, body, header }`.
]==], {
                    entry("httpserver.serve", "httpserver.serve(options)", "function",
                        "Start an HTTP server.",
                        [[
Start the HTTP server and process requests until the process is stopped.

`serve` accepts one options table and blocks while listening. The fields are:

- `address` — bind address, default `"127.0.0.1"`.
- `port` — TCP port, default `8080`.
- `web_root` — directory used for `GET` requests that no route matched.
- `cache_web_root` — cache lifetime for `web_root` responses, or `false` to
  disable caching.
- `GET`, `POST`, ... — tables mapping a request target to a route value.
- `*` — route table used for every method without a method-specific match.

A target is matched exactly or as a Lua pattern that consumes the whole target.
A route may be a response string or a function. The function receives
`(options, request)` and may return a string, a response table, or a data table
that is encoded as JSON. The request table contains `method`, `target`,
`version`, `body` and request metadata; message headers are available as named
fields. Responses use `{ status, body, header }`; `status` defaults to `200`
and a JSON body gets a JSON content type.

The call does not return during normal operation. Invalid options raise an
argument error, and address or bind failures are reported according to the
module's `error_handling` setting.

```lua
local http = require "httpserver"
http.serve {
    address = "127.0.0.1",
    port = 8080,
    GET = { ["/"] = "hello" },
    POST = { ["/echo"] = function(_, request)
        return { status = http.status.created, body = request.body }
    end },
}
```
]]),
                    entry("httpserver.config", "httpserver:config(options)", "method",
                        "Configure a loaded httpserver module.",
                        [[
Configure the loaded module in place.

The supported option is `error_handling`, set to `"return"` or `"raise"`. It
controls failures in the native binding, such as an invalid address or a port
that cannot be bound; argument errors still raise. The options table may be the
first or second argument, and the module table is returned, so calls can be
chained.

```lua
local http = require "httpserver"
http:config { error_handling = "raise" }
assert(http.error_handling == "raise")
```
]]),
                    entry("httpserver.serve_file", "httpserver.serve_file(path)", "function",
                        "Serve a file from disk.",
                        [[
Turn a file on disk into a response table.

A regular file is read in binary mode and returned as
`{ status = 200, body = ..., header = { content_type = ... } }`. If the path is
a directory, `index.html` or `index.htm` is served when present; otherwise a
generated HTML directory listing is returned. A missing or unreadable file
returns `{ status = 404 }` instead of raising.

```lua
local http = require "httpserver"
local response = http.serve_file("doc/README.md")
assert(response.status == http.status.ok)
assert(response.body:find("ZLI", 1, true))
```
]]),
                    entry("httpserver.resolve_web_path", "httpserver.resolve_web_path(root, target)", "function",
                        "Resolve a URL path inside a web root.",
                        [[
Turn a request target into a path below a web root.

The root gets a trailing slash if needed. Query strings and fragments are
removed, percent-escapes are decoded, and backslashes are treated as
separators. `.` components are dropped and `..` removes the previous component;
leading `..` cannot climb above the root because there is no previous component
to remove.

The function only normalizes the path. `httpserver.serve` separately checks the
resolved file against the web root before serving it, so traversal attempts are
rejected with `403`.

```lua
local http = require "httpserver"
assert(http.resolve_web_path("/srv/", "/a/../a") == "/srv/a")
assert(http.resolve_web_path("/srv/", "/%61?x=1") == "/srv/a")
assert(http.resolve_web_path("/srv/", "/../../etc/passwd") == "/srv/etc/passwd")
```
]]),
                    entry("httpserver.content_type", "httpserver.content_type(filename)", "function",
                        "Look up a MIME type by file extension.",
                        [[
Return the MIME type for a file name.

The extension after the last dot is lower-cased and looked up in the built-in
MIME table. Returns `nil` when the name has no extension or the extension is
unknown. The file does not need to exist.

```lua
local http = require "httpserver"
assert(http.content_type("index.HTML") == "text/html")
assert(http.content_type("archive.unknown") == nil)
```
]]),
                    entry("httpserver.cache", "httpserver.cache(func [, time])", "function",
                        "Cache a route handler's result.",
                        [[
Wrap a route handler so its response is reused for a while.

The optional `time` is the lifetime in seconds; `nil` or `true` keeps the
response until it is cleared or evicted by a cache sweep. A value of `0`
refreshes on every request. Entries are keyed by `request.target`, so do not
share one wrapper between methods whose responses differ. Expired entries are
removed by `free_cache` and by the periodic sweep configured with
`cache_free_cycle`.

The returned function has the same `(options, request)` signature as the
handler.

```lua
local http = require "httpserver"
local calls = 0
local handler = http.cache(function()
    calls = calls + 1
    return "value"
end, 60)
assert(handler({}, { target = "/a" }) == "value")
assert(handler({}, { target = "/a" }) == "value")
assert(calls == 1)
```
]]),
                    entry("httpserver.status", "httpserver.status", "field",
                        "HTTP status code table.",
                        [[
Numeric HTTP status codes indexed by lower-case names.

`ok`, `created`, `not_found`, `internal_server_error` and the other standard
codes are available. Lookup is case-insensitive through a metatable, so
`status.NOT_FOUND` also works. Treat the table as read-only.

```lua
local http = require "httpserver"
print(http.status.ok)        --> 200
print(http.status.not_found) --> 404
```
]]),
                    entry("httpserver.cache_free_cycle", "httpserver.cache_free_cycle([seconds])", "function",
                        "Set the cache expiry cycle.",
                        [[
Set how often expired entries are swept automatically.

`seconds` is the interval between sweeps performed during `httpserver.cache`
lookups. Passing `nil` or `0` disables automatic sweeping; entries are then
only removed by `httpserver.free_cache`. The default at startup is `300`
seconds. Returns nothing.

```lua
local http = require "httpserver"
http.cache_free_cycle(60)
http.cache_free_cycle(0) -- disable automatic sweeps
```
]]),
                    entry("httpserver.free_cache", "httpserver.free_cache([cycle])", "function",
                        "Free expired cache entries.",
                        [[
Remove cached responses older than a number of seconds.

`cycle` defaults to the value configured by `httpserver.cache_free_cycle`.
Entries whose age is strictly greater than `cycle` are discarded; pass `-1` to
expire everything that has a cached response. The function also resets the
timestamp used by the automatic sweep and returns nothing.

```lua
local http = require "httpserver"
http.free_cache(-1)
```
]]),
                    entry("httpserver.clear_cache", "httpserver.clear_cache()", "function",
                        "Clear the content cache.",
                        [[
Discard every cached response and reset the automatic sweep timer.

Call this between tests or after changing a handler that is behind
`httpserver.cache`. Returns nothing.

```lua
local http = require "httpserver"
http.clear_cache()
```
]]),
                }),

                module("webserver", "webserver", "Concurrent HTTP server with keep-alive, assets and server sent events.", [==[
`webserver` is the transport used by `webui`, and is usable on its own.  It
serves HTTP/1.1 keep-alive requests from concurrent connection tasks while all
Lua callbacks run on the task that called `serve`; the Lua state therefore has
exactly one entering task.

Events are delivered with server sent events, so a connection can push updates
to the browser at any time:

```lua
local web = require "webserver"

web.asset_set("webui/hello.txt", "hello", "text/plain; charset=utf-8")

web.serve {
    port = 8080,
    stop_path = "/__stop",
    on_start = function(info) print(info.url) end,
    routes = {
        GET = { ["/"] = function() return "<h1>hello</h1>" end },
        POST = { ["/echo"] = function(request) return { status = 201, body = request.body } end },
    },
}
```

`serve` options:

| Option        | Description                                                                             |
| ------------- | --------------------------------------------------------------------------------------- |
| `address`     | Bind address, default `"127.0.0.1"`.                                                    |
| `port`        | TCP port, default `8080`.  `0` asks the operating system for a free port.               |
| `allow_remote` | Allow binding to a non loopback address.  Off by default.                              |
| `token`       | Session token, at most 64 characters.  Generated per run when omitted.                   |
| `routes`      | Table of method name to target/response pairs, or `handler`.                             |
| `handler`     | `function(request) -> response` used instead of `routes`.                                |
| `assets_dir`  | Development override: read registered assets from this directory first.                  |
| `stop_path`   | Target that stops the server on `POST`.  Off by default.                                 |
| `warn_ms`     | Log handlers that run longer than this.  Default `500`, `0` disables the warning.        |

Responses are a string, a `{ status, body, header }` table, or a plain data
table which is encoded as JSON.  Headers are lower cased on the request side.
Parameters come from the query string or a form encoded body and are available
as `method`, `target`, `path`, `query`, `body`, `client` and `headers`.

Security: mutating requests require the session cookie (`webui_session`) and,
when present, an `Origin` header that matches the bound host and port.  Assets
are served under `/__webui/` and resolved as runtime, filesystem (only with
`assets_dir`), payload and finally compiled in data.
]==], {
                    entry("webserver.serve", "webserver.serve(options)", "function",
                        [==[Start the server and dispatch requests until stop is called.]==],
                        [==[
Start the HTTP server and block.  The call is the dispatcher: connection tasks
hand requests to it and it runs the Lua route handler on the calling task.

```lua
web.serve {
    port = 0,
    routes = { GET = { ["/"] = "hello" } },
    on_start = function(info) print(info.url) end,
}
```

`on_start` receives a table with `address`, `port`, `url` and `token`.  The call
returns after `webserver.stop()` and joins every connection task before it
returns, so the payload archive and the Lua state can be released safely.

Limits: 16 KiB request head, 1 MiB body (larger bodies get `413` and the
connection is closed) and 16 concurrent connections.
]==]),
                    entry("webserver.stop", "webserver.stop()", "function",
                        [==[Stop the running server.]==],
                        [==[Requests the dispatcher to return from `serve`.  Listener and client sockets are woken up and every task is joined before `serve` returns.  Calling it without a running server does nothing.]==]),
                    entry("webserver.asset", "webserver.asset(name)", "function",
                        [==[Return a registered or payload asset.]==],
                        [==[
Return `body, content_type, source` for an asset such as `"webui/app.css"`.
`source` is `"runtime"`, `"filesystem"`, `"payload"` or `"embedded"`.

```lua
local body, content_type, source = web.asset("webui/app.js")
```
]==]),
                    entry("webserver.asset_set", "webserver.asset_set(name, body [, content_type])", "function",
                        [==[Register an asset served by the web server.]==],
                        [==[
Add or replace an asset.  The content type is derived from the name when it is
omitted.  Assets can only change before `serve` starts; calls while serving
return `nil, message`.

```lua
web.asset_set("webui/extra.txt", "hello", "text/plain; charset=utf-8")
```
]==]),
                    entry("webserver.asset_list", "webserver.asset_list()", "function",
                        [==[List the registered assets.]==],
                        [==[Returns an array of `{ name, content_type, source }` tables in registration order.  Assets that only exist in the payload or on disk are not listed.]==]),
                    entry("webserver.broadcast", "webserver.broadcast(event, data)", "function",
                        [==[Send a server sent event to every client.]==],
                        [==[
Publish an event to all connected browsers and return the number of clients it
was queued for.  `data` may contain newlines; each line is sent as its own SSE
`data:` field.  `html` events are coalesced per client so only the newest tree
stays queued.

```lua
web.broadcast("toast", '{"kind":"info","text":"hello"}')
```
]==]),
                    entry("webserver.sse", "webserver.sse(client_id, event, data)", "function",
                        [==[Send a server sent event to one client.]==],
                        [==[Like `webserver.broadcast`, but only for the given client id.  Returns the number of clients the event was queued for (`0` or `1`).]==]),
                    entry("webserver.clients", "webserver.clients()", "function",
                        [==[List the connected clients.]==],
                        [==[Returns an array of `{ id, transport }` tables, where `transport` is `'http'` or `'sse'`.  Ids are also passed to request tables and event callbacks.]==]),
                    entry("webserver.info", "webserver.info()", "function",
                        [==[Describe the running server.]==],
                        [==[Returns `{ address, port, url, token }` while serving and `nil` otherwise.  With `port = 0` the table contains the port the operating system assigned.]==]),
                    entry("webserver.config", "webserver:config(options)", "method",
                        [==[Configure a loaded webserver module.]==],
                        [==[The supported option is `error_handling`, set to `'return'` or `'raise'`.  It controls failures such as an address that cannot be bound; argument errors still raise.]==]),
                    entry("webserver.status", "webserver.status", "table",
                        [==[Named HTTP status codes.]==],
                        [==[Maps lower case names to numeric codes, for example `webserver.status.not_found` (`404`) or `webserver.status.internal_server_error` (`500`).  Unknown names return `nil`.]==]),
                }),

                module("webui", "webui", "Server side component model that renders pages for the browser.", [==[
`webui` lets a Lua program describe its user interface as a tree of components.
The server renders HTML, the browser only executes htmx and the event stream:

```lua
local ui = require "webui"

local page = ui.page { title = "Hello World" }
local field = ui.textField {
    name = "user", value = "world",
    onChange = function(src) ui.current.greeting:setText("Hello " .. src:value()) end,
}
page:add(ui.horizontalLayout {
    ui.label { text = "User Name" }, field,
    ui.button { text = "Say hello", onClick = function() ui.notify("hello " .. ui.current.user:value()) end },
    ui.label { name = "greeting", text = "" },
})

ui.serve { page = page }
```

Components accept their children in the table constructor or through
`parent:add(child)`; `add` returns the parent so calls can be chained.  Unknown
options raise immediately, which catches typos such as `onCLick`.

Display text and editable values are separate: `label`, `button`, `heading`
and `link` use `text`, while `textField`, `textArea`, `checkbox`, `select` and
`radioGroup` use `value` (all reachable with `:text()`, `:value()`,
`:setText()`, `:setValue()`).  `name = "user"` registers a component, makes it
reachable as `ui.current.user` inside a callback, and makes the browser submit
its value with every event.

Events:

| Handler       | Components                                  | Fired when                                   |
| ------------- | ------------------------------------------- | -------------------------------------------- |
| `onClick`     | `button`, `link`                            | the component is clicked                     |
| `onInput`     | `textField`, `textArea`                     | the text changes (debounced by 120 ms)       |
| `onChange`    | `textField`, `textArea`, `checkbox`, `select`, `radioGroup`, `tabs` | the value is committed |
| `onSelect`    | `list`                                      | a list item is selected                      |
| `onRowClick`  | `table`                                     | a table row is clicked                       |
| `onClose`     | `dialog`                                    | the close button is used                     |

The browser only applies updates for the route it is currently showing, so a
page with several routes never morphs into another route by accident.

Handlers are called as `function(src, event)`.  `event` contains `kind`,
`value`, `client` and `values` (all submitted form values).  A callback may
change the tree; the page is re-rendered and pushed to every connected browser
afterwards.  Errors are logged on the server and reported as a toast; the last
good tree stays visible.

Every component accepts the same base options, whatever its kind:

| option            | meaning                                                                                                       |
| ----------------- | ------------------------------------------------------------------------------------------------------------- |
| `name`            | registers the component for `ui.current.<name>`; value holding kinds also submit it with every event           |
| `class`           | extra space separated classes, added after the built in ones                                                   |
| `width`, `height` | pixel count (`300`), CSS length (`"50%"`) or `"full"`                                                          |
| `grow`            | flex grow factor inside a layout                                                                               |
| `hidden`          | renders the `hidden` attribute, which hides the component even when its kind sets a display style               |
| `disabled`        | disables the component where the kind has a disabled state                                                     |
| `style`           | table of CSS properties: `{ ["text-align"] = "right" }`; names and values are validated                        |
| `aria`            | table of ARIA attributes without the prefix: `{ label = "backspace" }` renders `aria-label="backspace"`        |
| `data`            | table rendered as `data-*` attributes: `{ row = 3 }` renders `data-row="3"`                                    |

`name` has to be unique on a page and may not be `id`, `kind` or `values`.
`style` values may not contain `;`, braces or `url(...)`; `aria` and `data`
names are checked as attribute names and their values are escaped.

Layout components take the arrangement options on top of the base ones: `align`
(`'vertical'`/`'horizontal'`, or `'column'`/`'row'`), `gap` and `padding` (pixel
count or CSS length), plus `justify` (for example `'space-between'`,
`'flex-end'`) and `wrap` on `verticalLayout` and `horizontalLayout`.  A page
adds `title`, `theme`, `lang` and `css` (raw CSS appended to the document
head); a panel adds `title`.  `margin` is not a component option; use
`style = { margin = ... }`.

The browser side bundles htmx 2.0.11, idiomorph 0.7.4 and htmx-ext-sse 2.2.4,
all published under 0BSD by the htmx project; the assets are compiled into the
binary and served from `/__webui/`.
]==], {
                    entry("webui.page", "ui.page(options)", "function",
                        [==[Create a page.]==],
                        [==[Creates the root component.  Options include `title`, `theme` (`'auto'`, `'light'`, `'dark'`), `lang`, `align`, `gap`, `padding` and `css` (raw CSS appended to the document head).  Children may be passed in the table constructor.]==]),
                    entry("webui.verticalLayout", "ui.verticalLayout(options)", "function",
                        [==[Stack children vertically.]==],
                        [==[Flex container with `align = 'vertical'` by default.  Accepts `gap`, `padding`, `width`, `height`, `justify`, `wrap`, `align` and the common options.]==]),
                    entry("webui.horizontalLayout", "ui.horizontalLayout(options)", "function",
                        [==[Place children in a row.]==],
                        [==[Flex container with `align = 'horizontal'` by default.  The same options as `verticalLayout` apply; narrow screens wrap it into a column.]==]),
                    entry("webui.panel", "ui.panel(options)", "function",
                        [==[Group children in a bordered panel.]==],
                        [==[Container with an optional `title` header.  `ui.card` is an alias.  Accepts children and the common layout options.]==]),
                    entry("webui.label", "ui.label(options)", "function",
                        [==[Show a piece of text.]==],
                        [==[Renders `text` as escaped inline text.  `muted = true` uses the secondary text colour.  `ui.label "text"` is shorthand for `ui.label { text = "text" }`.]==]),
                    entry("webui.heading", "ui.heading(options)", "function",
                        [==[Show a heading.]==],
                        [==[Renders `text` as `<hN>` where `N` is `level` (1 to 6, default 2).  An invalid level raises.]==]),
                    entry("webui.button", "ui.button(options)", "function",
                        [==[Show a button.]==],
                        [==[Renders a `<button type="button">` with `text` and calls `onClick` when it is clicked.  `disabled = true` disables it.  Buttons never submit a form.]==]),
                    entry("webui.textField", "ui.textField(options)", "function",
                        [==[Single line text input.]==],
                        [==[`type` selects `text` (default), `password`, `email` or another browser input type.  Supports `label`, `placeholder`, `readonly`, `value`, `onInput` and `onChange`.  A `name` makes the value available to callbacks and to `ui.current`.]==]),
                    entry("webui.textArea", "ui.textArea(options)", "function",
                        [==[Multi line text input.]==],
                        [==[Like `textField`, but rendered as a `<textarea>` with `rows` and `value`.  `onInput` fires while typing, `onChange` when the value is committed.]==]),
                    entry("webui.checkbox", "ui.checkbox(options)", "function",
                        [==[Checkbox with a label.]==],
                        [==[`checked` is the boolean value, `text` the label.  `onChange` fires when the box is toggled; named checkboxes report `true` when checked and `false` when not.]==]),
                    entry("webui.select", "ui.select(options)", "function",
                        [==[Drop down selection.]==],
                        [==[`options` is an array of strings or `{ value, label }` tables.  `value` is the selected entry and `placeholder` adds an empty first entry.  `onChange` fires on selection.]==]),
                    entry("webui.radioGroup", "ui.radioGroup(options)", "function",
                        [==[Group of radio buttons.]==],
                        [==[`options` uses the same shape as `select`.  `value` is the selected entry and `onChange` fires when the selection changes.  All radios share the component `name`.]==]),
                    entry("webui.list", "ui.list(options)", "function",
                        [==[Simple bullet or numbered list.]==],
                        [==[`items` is an array of strings; `ordered = true` renders `<ol>`.  With `onSelect` every item becomes clickable and `event.value` is the 1 based index.]==]),
                    entry("webui.table", "ui.table(options)", "function",
                        [==[Table with columns and rows.]==],
                        [==[
`columns` is an array of field names or `{ header, field }` tables; `rows` is an
array of tables.  `empty` is shown for an empty row list.  With `rowKey`, the
returned key keeps the row id stable across renders.

```lua
ui.table {
    columns = { "name", { header = "Age", field = "age" } },
    rows = { { name = "Ada", age = 36 } },
    rowKey = function(row) return row.name end,
    onRowClick = function(_, event) print(event.value) end,
}
```
]==]),
                    entry("webui.image", "ui.image(options)", "function",
                        [==[Show an image.]==],
                        [==[Requires `src`; `alt` is passed through.  The image is limited to the available width by the stylesheet.]==]),
                    entry("webui.link", "ui.link(options)", "function",
                        [==[Show a link.]==],
                        [==[Renders `text` as an `<a href>`.  With `route = true` the link navigates inside the page: htmx fetches the target route, morphs the page and updates the browser history.]==]),
                    entry("webui.markdown", "ui.markdown(options)", "function",
                        [==[Render Markdown.]==],
                        [==[Renders `text` with the bundled `markdown` module.  The result is trusted HTML, so only pass content you control.]==]),
                    entry("webui.html", "ui.html(options)", "function",
                        [==[Render raw HTML.]==],
                        [==[Inserts `text` without escaping.  Use it for trusted markup only; scripts are blocked by the page CSP but everything else is inserted as is.]==]),
                    entry("webui.divider", "ui.divider(options)", "function",
                        [==[Horizontal divider line.]==],
                        [==[Renders an `<hr>` across the available width and accepts the common options such as `width`, `margin` and `style`.  Useful to separate groups of components inside a layout.]==]),
                    entry("webui.progress", "ui.progress(options)", "function",
                        [==[Progress bar.]==],
                        [==[`value` and `max` set the progress; `indeterminate = true` renders a bar without a value.  Values outside the range are rendered as given and normalised by the browser.]==]),
                    entry("webui.tabs", "ui.tabs(options)", "function",
                        [==[Tabbed container.]==],
                        [==[`labels` names the tabs and the children are the tab bodies.  `index` or `value` selects the visible tab; with `onChange` clicking a tab reports the new index in `event.value`.]==]),
                    entry("webui.dialog", "ui.dialog(options)", "function",
                        [==[Modal dialog.]==],
                        [==[Renders a modal `<dialog>` with an optional `title`.  `ui.open(dialog)` adds it to the page and opens it; `dialog:close()` closes it.  `onClose` runs when the close button (`closeText`, default `'Close'`) is used.]==]),
                    entry("webui.open", "ui.open(dialog)", "function",
                        [==[Add a dialog to the page and open it.]==],
                        [==[Appends the dialog to the active page, marks it open and returns it.  The dialog stays in the tree after closing, so it can be reopened without being recreated.]==]),
                    entry("webui.confirm", "ui.confirm(options)", "function",
                        [==[Ask for confirmation without blocking.]==],
                        [==[Creates and opens a dialog with `text`, a yes button and a no button.  `onYes` or `onNo` is called after the dialog closes; the server never waits for the answer.]==]),
                    entry("webui.notify", "ui.notify(text [, options])", "function",
                        [==[Show a toast in the browser.]==],
                        [==[Queues a notification for the browser that sent the current event.  `options.kind` is `'info'` (default), `'warn'` or `'error'` and `options.ms` is the display time in milliseconds (`0` keeps it).]==]),
                    entry("webui.focus", "ui.focus(component)", "function",
                        [==[Move the browser focus.]==],
                        [==[Asks the client to focus the component after the next update.  Useful after validation errors or when a dialog opens.]==]),
                    entry("webui.navigate", "ui.navigate(path)", "function",
                        [==[Switch to another route.]==],
                        [==[Replaces the page with the page served at `path`, pushes the new URL into the browser history and re-renders the target page.  An unknown route is reported as a toast and ignored.]==]),
                    entry("webui.refresh", "ui.refresh()", "function",
                        [==[Force a re-render.]==],
                        [==[Marks the page as changed even when the callback did not touch the tree.  Useful when a callback changes data that a renderer reads from Lua closures.]==]),
                    entry("webui.stop", "ui.stop()", "function",
                        [==[Stop the UI server.]==],
                        [==[Calls `webserver.stop()`, so `ui.serve` returns.  Cleanup code after `ui.serve` runs normally.]==]),
                    entry("webui.serve", "ui.serve(options)", "function",
                        [==[Render one page or several routes and handle events.]==],
                        [==[
Start the UI server and block.  Options:

| Option         | Description                                                                       |
| -------------- | --------------------------------------------------------------------------------- |
| `page`         | Single page served at `/`.                                                        |
| `pages`        | Table of route to page, for example `{ ["/"] = a, ["/b"] = b }`.                  |
| `api`          | Optional REST routes as `{ GET = { ["/api/x"] = fn } }`; used before pages.        |
| `address`      | Bind address, default `"127.0.0.1"`.                                              |
| `port`         | TCP port, default `8080`; `0` picks a free port.                                   |
| `token`        | Session token, at most 64 characters; generated per run when omitted.               |
| `allow_remote` | Allow a non loopback bind.                                                        |
| `assets_dir`   | Development override for the `/__webui/` assets.                                   |
| `stop_path`    | Target that stops the server on `POST` (tests and tools).                          |
| `warn_ms`      | Warn about callbacks slower than this (default `500`).                             |
| `open_browser` | Open the URL with `xdg-open`/`start`/`open`.  Default `true`.                       |
| `on_start`     | Called with `{ address, port, url, token }` before serving.                         |

The printed URL is the one to open.  `ui.serve` returns after `ui.stop()`.
]==]),
                    entry("ui.current", "ui.current.name", "table",
                        [==[Access named components inside a callback.]==],
                        [==[
Returns the component registered with `name = "..."` on the page whose callback
is running.  Names are unique per page, so two routes cannot shadow each other.
Using `ui.current` outside a callback, or with an unknown name, raises.

```lua
onClick = function() ui.current.user:setValue("clicked") end
```
]==]),
                }),
                module("log", "log", "Simple logging library.", [==[
`require "log"` returns the root logger.  Named child loggers are created by
indexing the root logger.  The root logger writes to stdout by default.

Levels: `OFF`, `FATAL`, `ERROR`, `WARN`, `INFO`, `DEBUG`, `TRACE`.

```lua
local log = require "log"
log:info("hello")
log:setLevel(log.level.DEBUG)
log:addAppender(log.appender.file("/tmp/app.log"))
local child = log["worker"]
child:warn("from a named logger")
```
]==], {
                    entry("log:fatal", "log:fatal(message)", "method",
                        "Log a fatal message.",
                        [[
Log a fatal-level message.

The message is emitted when both this logger's level and the root logger's level are at least `FATAL`. It is passed to every appender attached to this logger and, for named child loggers, also to the root appenders. The function returns nothing.

```lua
local log = require "log"
log:fatal("unrecoverable configuration error")
```
]]),
                    entry("log:error", "log:error(message)", "method",
                        "Log an error message.",
                        [[
Log an error-level message.

Errors are emitted when the effective level allows `ERROR` or anything more verbose. The message is written by all applicable appenders with a timestamp and level tag. The function returns nothing.

```lua
local log = require "log"
log:error("request failed")
```
]]),
                    entry("log:warn", "log:warn(message)", "method",
                        "Log a warning.",
                        [[
Log a warning.

The record is emitted when the logger and root thresholds both allow `WARN`. Appender failures propagate normally; no status value is returned.

```lua
local log = require "log"
log:warn("using the fallback configuration")
```
]]),
                    entry("log:info", "log:info(message)", "method",
                        "Log an informational message.",
                        [[
Log an informational message.

This is the default threshold for both root and child loggers, so `info` records are visible until a stricter level is set. The message may be a string or any value accepted by the appender's `write` call; convert structured values to text first.

```lua
local log = require "log"
log:info("service started")
```
]]),
                    entry("log:debug", "log:debug(message)", "method",
                        "Log a debug message.",
                        [[
Log a debug-level message.

Debug records are hidden at the default `INFO` level and appear after lowering the relevant logger threshold. No value is returned.

```lua
local log = require "log"
log:setLevel(log.level.DEBUG)
log:debug("cache hit")
```
]]),
                    entry("log:trace", "log:trace(message)", "method",
                        "Log a trace message.",
                        [[
Log a trace-level message.

Trace is the most verbose level. It is emitted only when both the logger and the root logger are configured for `TRACE`. The call returns nothing.

```lua
local log = require "log"
log:setLevel(log.level.TRACE)
log:trace("entering parser")
```
]]),
                    entry("log:setLevel", "log:setLevel(level)", "method",
                        "Set the logger level.",
                        [[
Set the threshold for this logger.

`level` should be one of the numeric values in `log.level` (`OFF` through `TRACE`). Records below the threshold are suppressed. A child logger is also capped by the root logger's threshold, so lowering only the child is not enough when the root is stricter.

Returns nothing.

```lua
local log = require "log"
local child = log["worker"]
child:setLevel(log.level.DEBUG)
```
]]),
                    entry("log:setAppender", "log:setAppender(appender)", "method",
                        "Replace the logger appender.",
                        [[
Replace all appenders attached to this logger with one appender.

An appender is any table with an `append(logger, level, message)` method. The built-in constructors are in `log.appender`. Root appenders are still used for child loggers after their own appenders run.

Returns nothing.

```lua
local log = require "log"
log:setAppender(log.appender.file("/tmp/app.log"))
```
]]),
                    entry("log:addAppender", "log:addAppender(appender)", "method",
                        "Add an appender.",
                        [[
Add an appender without removing the existing ones.

Appenders run in insertion order. Child loggers call their own appenders first and then the root logger's appenders, so the same record can be written to several destinations.

Returns nothing.

```lua
local log = require "log"
log:addAppender(log.appender.file("/tmp/audit.log", "w"))
```
]]),
                    entry("log.level", "log.level", "field",
                        "Logger level constants.",
                        [[
The table of numeric logger levels.

Both upper-case and lower-case keys are present: `OFF`, `FATAL`, `ERROR`, `WARN`, `INFO`, `DEBUG`, `TRACE` and the same names in lower case. Numeric values increase with verbosity, and thresholds are compared with `>=`, so a larger level enables more messages.

This field is a table; treat it as read-only.
]]),
                    entry("log.appender", "log.appender", "field",
                        "Built-in appenders: `stdout`, `file`, `none`.",
                        [[
The built-in appender constructors and the no-op appender.

`log.appender.stdout` is a function returning an appender for standard output. `log.appender.file(filename [, mode])` opens a file and returns an appender, raising an error if the file cannot be opened; `mode` defaults to `"a"`. `log.appender.none` is a ready-made appender that discards messages.

This field is a table of functions and one appender object.
]]),
                }, { aliases = { "logger" } }),

                module("luastrip", "luastrip", "Lua source stripper/compactor.", [==[
`luastrip` removes comments and unnecessary whitespace while preserving Lua
semantics.  Malformed or unterminated input is handled without aborting the
interpreter.
]==], {
                    entry("luastrip.string", "luastrip.string(source)", "function",
                        "Strip a Lua source string.",
                        [[
Remove comments and unnecessary whitespace from a Lua source string and return the compacted source.

The stripper preserves token boundaries and string literals. Malformed or unterminated input is handled without crashing the interpreter; the function may return a partially stripped string or an error according to the module's error-handling mode.

```lua
local luastrip = require "luastrip"
print(luastrip.string("local a = 1 -- note")) --> "local a=1"
```
]]),
                    entry("luastrip.file", "luastrip.file(input, output)", "function",
                        "Strip a Lua source file into another file.",
                        [[
Read a Lua source file, strip comments and unnecessary whitespace, and write the result to another file.

Returns `true` on success. `input` and `output` may be path objects or strings. I/O and stripping errors follow the module's error-handling mode (`nil, message` by default, or a raised error in raise mode).
]]),
                    entry("luastrip.config", "luastrip:config(options)", "method",
                        "Configure a loaded luastrip module.",
                        [[
Configure a loaded `luastrip` module and return it.

The options table accepts `error_handling = "return"` or `"raise"`. The setting controls whether `luastrip.string` and `luastrip.file` return errors or raise them.

```lua
local luastrip = require("luastrip"):config { error_handling = "raise" }
```
]]),
                }),

                module("memoize", "memoize", "Function result memoization.", [==[
`memoize(func)` returns a wrapper that caches results.  Cache keys are the
arguments; cached values are held weakly.
]==], {
                }),

                module("stream", "stream", "Functional-style streams inspired by Java streams.", [==[
`stream(iterator)` wraps an iterator, table or function.  Most operations return a
new stream; terminal operations consume it.

Named functions can be passed as strings when a function has been registered with
the `lambda` helper.
]==], {
                    entry("stream.stream", "stream(iterator)", "function",
                        "Create a stream from an iterator, table or function.",
                        [[
Create a stream from an iterator, an array-like table, or a Lua iterator function.

A table containing a `next` field is treated as an existing stream and wrapped directly; any other table is iterated over its array part with `table.next`. A function may be passed with its state and control values as additional arguments. A non-function, non-table value becomes a one-element stream.

```lua
local stream = require "stream"
print(stream({ 1, 2, 3 }):sum()) --> 6
for n in stream(ipairs { "a", "b" }) do print(n) end
```
]]),
                    entry("stream.of", "stream():of(...)", "method",
                        "Create a stream from values.",
                        [[
Create a stream over the values passed as arguments. The method is available on a stream instance, so the usual form is `stream():of(...)`.

The values are stored in an array and iterated in order. This is a convenient alternative to writing `stream { ... }`.

```lua
local stream = require "stream"
print(stream():of(1, 2, 3):concat(",")) --> "1,2,3"
```
]]),
                    entry("stream:map", "stream:map(func)", "method",
                        "Transform each value.",
                        [[
Return a lazy stream that applies `func` to every value.

The function may be a Lua function or a string accepted by the `lambda` helper. `false` results are treated as ordinary values, not as end-of-stream. The source stream is consumed as the mapped stream is consumed.

```lua
stream({ 1, 2, 3 }):map(function(n) return n * 2 end):toarray() --> { 2, 4, 6 }
```
]]),
                    entry("stream:peek", "stream:peek(func)", "method",
                        "Inspect each value without changing it.",
                        [[
Return a lazy stream that calls `func(value)` for each value and passes the original value through unchanged.

This is intended for debugging or side effects. `func` may be a function or a registered lambda string.
]]),
                    entry("stream:filter", "stream:filter(func)", "method",
                        "Keep values accepted by `func`.",
                        [[
Return a lazy stream containing only values for which `func(value)` is truthy.

The stream pulls values from its source until it finds a match, so filters can be chained efficiently. `false` and `nil` are rejected; other values are kept.

```lua
stream({ 1, 2, 3, 4 }):filter(function(n) return n % 2 == 0 end):toarray() --> { 2, 4 }
```
]]),
                    entry("stream:skip", "stream:skip(count)", "method",
                        "Skip the first `count` values.",
                        [[
Skip the first `count` values and return the same stream, now positioned after them.

This operation is eager: it consumes the skipped values immediately. Negative counts behave like zero.

```lua
stream({ 1, 2, 3, 4 }):skip(2):toarray() --> { 3, 4 }
```
]]),
                    entry("stream:limit", "stream:limit(count)", "method",
                        "Limit the stream to `count` values.",
                        [[
Return a stream that yields at most `count` values from the source.

The limit is applied lazily and the source is not advanced beyond the requested values until another value is requested. A count of zero produces an empty stream.
]]),
                    entry("stream:reverse", "stream:reverse()", "method",
                        "Reverse the remaining values.",
                        [[
Consume the remaining values and return a new stream that yields them in reverse order.

The entire source is read into memory first, so this cannot be used on an infinite stream. The original stream is exhausted by the call.
]]),
                    entry("stream:sort", "stream:sort([comparator])", "method",
                        "Sort the remaining values.",
                        [[
Consume the remaining values and return a new stream sorted by the optional comparator.

The default comparator is `a < b`. Sorting requires reading the whole source into memory, so the original stream is exhausted.

```lua
stream({ 3, 1, 2 }):sort():toarray() --> { 1, 2, 3 }
```
]]),
                    entry("stream:maptonumber", "stream:maptonumber()", "method",
                        "Convert each value to a number.",
                        [[
Return a lazy stream that converts each value with `tonumber`.

Values that cannot be converted become `nil`; because `nil` also marks the end of a stream, a failed conversion effectively terminates that stream.
]]),
                    entry("stream:distinct", "stream:distinct()", "method",
                        "Drop duplicate values.",
                        [[
Return a lazy stream that drops duplicate values, keeping the first occurrence of each.

Duplicate detection uses the value itself as a table key, so values must be usable as Lua table keys. Encounter order is preserved.
]]),
                    entry("stream:split", "stream:split(func)", "method",
                        "Split into matching and non-matching streams.",
                        [[
Split the stream into two lazy streams according to a predicate.

The first stream yields values for which `func(value)` is truthy; the second yields the remaining values. Both streams share the same source, so consuming one advances the other. Pull values from both in parallel for predictable results.

```lua
local odd, even = stream({ 1, 2, 3, 4 }):split(function(n) return n % 2 == 1 end)
print(odd:concat(","))  --> "1,3"
print(even:concat(",")) --> "2,4"
```
]]),
                    entry("stream:join", "stream:join(...)", "method",
                        "Concatenate streams.",
                        [[
Return a lazy stream that concatenates this stream with the given streams.

The extra arguments must be stream objects. Each stream is consumed in turn. This is useful for chaining the two results of `split` back together.

```lua
local a, b = stream({ 1, 2 }):split(function(n) return n == 1 end)
print(a:join(b):concat(",")) --> "1,2"
```
]]),
                    entry("stream:foreach", "stream:foreach(func)", "method",
                        "Consume the stream, calling `func` for each value.",
                        [[
Consume the stream, calling `func(value)` for every value.

This is a terminal operation: the source is exhausted. It returns nothing. `func` may be a function or a registered lambda string.
]]),
                    entry("stream:toarray", "stream:toarray()", "method",
                        "Consume the stream into an array.",
                        [[
Consume the stream and return its values as a new array in encounter order.

This is a terminal operation. `false` values are retained; only `nil` ends the stream.
]]),
                    entry("stream:tosortedarray", "stream:tosortedarray([comparator])", "method",
                        "Consume into a sorted array.",
                        [[
Consume the stream into an array and sort it with the optional comparator.

The default comparator is `a < b`. This is a terminal operation, and the entire stream is read into memory.

```lua
stream({ "b", "a" }):tosortedarray() --> { "a", "b" }
```
]]),
                    entry("stream:print", "stream:print()", "method",
                        "Print each value.",
                        [[
Consume the stream, printing each value with `print`.

This is a terminal operation intended for quick inspection. Like `toarray`, it exhausts the source.
]]),
                    entry("stream:concat", "stream:concat([separator])", "method",
                        "Join values into a string.",
                        [[
Consume the stream and join its values into a string.

`separator` is passed to `table.concat` and defaults to an empty string. Non-string values must be convertible by `table.concat`.

```lua
stream({ 1, 2, 3 }):concat("-") --> "1-2-3"
```
]]),
                    entry("stream:allmatch", "stream:allmatch(func)", "method",
                        "Return true when every value matches.",
                        [[
Return true when every value in the stream satisfies `func`, and false as soon as one does not.

An empty stream returns true. This is a terminal operation, but it stops early on the first non-match.
]]),
                    entry("stream:firstmatch", "stream:firstmatch(func)", "method",
                        "Return the first matching value.",
                        [[
Return the first value for which `func(value)` is truthy, or `nil` when none matches.

Matching stops at the first hit. This is a terminal operation and leaves earlier values consumed.
]]),
                    entry("stream:nonmatch", "stream:nonmatch(func)", "method",
                        "Return true when no value matches.",
                        [[
Return true when no value in the stream satisfies `func`.

This is the negation of `stream:anymatch`; it stops at the first match. An empty stream returns true.
]]),
                    entry("stream:anymatch", "stream:anymatch(func)", "method",
                        "Return true when any value matches.",
                        [[
Return true when at least one value in the stream satisfies `func`, and false otherwise.

Evaluation stops at the first match. This is a terminal operation.
]]),
                    entry("stream:first", "stream:first()", "method",
                        "Return the first value.",
                        [[
Return the first value of the stream, or `nil` when the stream is empty.

This consumes one value, plus any values skipped by earlier lazy stages.
]]),
                    entry("stream:last", "stream:last()", "method",
                        "Return the last value.",
                        [[
Consume the stream and return its final value, or `nil` when it is empty.

The entire source is read to find the last value.
]]),
                    entry("stream:count", "stream:count()", "method",
                        "Count the remaining values.",
                        [[
Consume the stream and return the number of remaining values.

This is implemented as a reduction and reads the whole source.
]]),
                    entry("stream:sum", "stream:sum()", "method",
                        "Sum numeric values.",
                        [[
Consume the stream and return the sum of its numeric values.

An empty stream produces `0`. Non-numeric values cause an arithmetic error.
]]),
                    entry("stream:average", "stream:average()", "method",
                        "Average numeric values.",
                        [[
Consume the stream and return the arithmetic mean of its numeric values.

An empty stream returns `0`; otherwise the result is the sum divided by the count.
]]),
                    entry("stream:median", "stream:median()", "method",
                        "Median numeric value.",
                        [[
Consume the stream and return its median after sorting the values.

For an even number of values the two middle values are averaged. An empty stream returns `0`. The optional argument is accepted for compatibility but is not used.
]]),
                    entry("stream:iterator", "stream:iterator()", "method",
                        "Return the underlying iterator.",
                        [[
Return the underlying iterator function for this stream.

The iterator yields one value per call and returns `nil` when exhausted. Passing it to `stream` wraps the remaining values in a new stream object.
]]),
                    entry("stream:collector", "stream:collector(func)", "method",
                        "Apply a collector function.",
                        [[
Call a collector function with the stream's iterator and return the collector's result.

`func` receives the underlying `next` function and can consume it in any way. A string lambda may also be supplied. This is a terminal operation if the collector consumes the iterator.
]]),
                    entry("stream:reduce", "stream:reduce(state, func)", "method",
                        "Fold the stream into a value.",
                        [[
Fold the remaining values into an accumulator and return the final state.

`func(state, value)` is called for every value, starting with `state`. The function may be a function or a registered lambda string. An empty stream returns the initial state unchanged.

```lua
stream({ 1, 2, 3 }):reduce(0, function(sum, n) return sum + n end) --> 6
```
]]),
                    entry("stream:min", "stream:min([comparator])", "method",
                        "Return the minimum value.",
                        [[
Consume the stream and return its minimum value using the optional comparator.

The default comparator is `a < b`. An empty stream returns `nil`.

```lua
stream({ 4, 1, 3 }):min() --> 1
```
]]),
                    entry("stream:max", "stream:max([comparator])", "method",
                        "Return the maximum value.",
                        [[
Consume the stream and return its maximum value using the optional comparator.

The default comparator is `a < b`. An empty stream returns `nil`.

```lua
stream({ 4, 1, 3 }):max() --> 4
```
]]),
                    entry("stream:groupby", "stream:groupby(func)", "method",
                        "Group values by a key function.",
                        [[
Consume the stream and group values into a plain table keyed by `func(value)`.

Each key maps to an array of the values that produced it. The function may be a function or a registered lambda string. This is a terminal operation.

```lua
local groups = stream({ "ant", "ape", "bee" }):groupby(function(s) return s:sub(1, 1) end)
print(#groups.a) --> 2
```
]]),
                }),

                module("tar", "tar", "Read and write tar archives.", [==[
The tar module supports uncompressed tar plus gzip, xz and zstd-compressed tar
files when the corresponding support is available.

`tar.open(filename)` returns a reader.  `tar.create(filename)` returns a writer.
`tar.extract(archive, destination)` extracts an archive.
]==], {
                    entry("tar.open", "tar.open(filename)", "function",
                        "Open a tar archive for reading.",
                        [[
Open a tar archive and return an iterator over its entries.

The file may be plain tar or compressed with gzip, xz or zstd; the compression is detected from the stream. Each iteration returns an entry table with the fields and methods documented below, and returns `nil` after the last entry. Opening or reading failures follow the module error policy.

```lua
local tar = require "tar"
for entry in tar.open("backup.tar.gz") do
    print(entry.type, entry.name, entry.size_hr)
end
```
]]),
                    entry("tar.create", "tar.create(filename [, level])", "function",
                        "Create a tar archive for writing.",
                        [[
Create a tar archive and return a writer object.

The output is uncompressed unless the filename ends in `.gz` or `.tgz`, in which case gzip compression is used. `level` selects gzip compression and accepts `"default"`, `"fastest"`, `"best"` or a digit string from `"1"` to `"9"`; it is ignored for uncompressed archives.

On failure the module error policy applies: with the default `"return"` policy the result is `nil, message`; with `"raise"` an error is raised.

```lua
local tar = require "tar"
local writer = tar.create("backup.tar.gz", "best")
writer:add_file_bytes("hello.txt", "hello")
writer:close()
```
]]),
                    entry("tar.extract", "tar.extract(filename, destination)", "function",
                        "Extract an entire archive into a directory.",
                        [[
Extract an archive's files and directories into an existing destination directory.

The archive may be plain tar or compressed with gzip, xz or zstd; compression is detected automatically. The destination must already exist. On success the function returns `true`; failures follow the module error policy and return `nil, message` by default. Support for special entry kinds such as symbolic links depends on the platform.

```lua
local tar = require "tar"
local ok, err = tar.extract("backup.tar.gz", "restore")
assert(ok, err)
```
]]),
                    entry("tar.config", "tar:config(options)", "method",
                        "Configure a loaded tar module.",
                        [[
Configure the loaded tar module.

The only supported option is `error_handling`, whose value is `"return"` or `"raise"`. It controls whether failures in module and writer operations return `nil, message` or raise a Lua error. The option may be passed directly or through the module table when using colon syntax.

The module table is returned and the option is stored back into it.

```lua
local tar = require "tar"
tar:config({ error_handling = "raise" })
assert(tar.error_handling == "raise")
```
]]),
                    entry("tar.writer:setRoot", "writer:setRoot(root)", "method",
                        "Set the root directory written into the archive.",
                        [[
Set the path prefix stripped from archive member names.

When a path passed to `add_dir` or `add_file` starts with this prefix, the prefix is removed before the entry is written. This lets an absolute workspace path produce clean relative names inside the archive. Backslashes are normalised to `/`.

Returns the writer for chaining.

```lua
local tar = require "tar"
local w = tar.create("out.tar")
w:setRoot("/tmp/project")
w:add_dir("/tmp/project/src")
w:close()
```
]]),
                    entry("tar.writer:add_dir", "writer:add_dir(path)", "method",
                        "Add a directory entry.",
                        [[
Write a directory entry to the archive.

The path is converted to an archive name with forward slashes and with the root prefix from `setRoot` removed. This function adds only the directory entry itself; it does not recurse into the directory.

Returns the writer so calls can be chained.

```lua
local tar = require "tar"
tar.create("dirs.tar"):add_dir("docs"):add_dir("docs/api"):close()
```
]]),
                    entry("tar.writer:add_file", "writer:add_file(path, archive_path)", "method",
                        "Add a file.",
                        [[
Add a file from disk to the archive.

`path` is the existing filesystem path. `archive_path` is the name stored in the tar, with backslashes normalised and the configured root prefix removed. Both arguments are required. The file is streamed, so large inputs do not need to fit in memory.

Returns the writer for chaining. I/O failures follow the module error policy.

```lua
local tar = require "tar"
tar.create("src.tar")
    :add_file("src/main.lua", "main.lua")
    :close()
```
]]),
                    entry("tar.writer:add_file_bytes", "writer:add_file_bytes(path, data)", "method",
                        "Add a file from memory.",
                        [[
Add an in-memory string as a regular file.

`path` is the member name inside the archive and `data` is its complete contents. No filesystem access occurs. Returns the writer for chaining.

```lua
local tar = require "tar"
tar.create("config.tar")
    :add_file_bytes("config/app.ini", "debug = true\n")
    :close()
```
]]),
                    entry("tar.writer:add_link", "writer:add_link(path, target)", "method",
                        "Add a symbolic link.",
                        [[
Write a symbolic-link entry.

`path` is the link's name inside the archive and `target` is the link target stored in the entry. The target does not need to exist on disk. Returns the writer for chaining.

```lua
local tar = require "tar"
tar.create("links.tar")
    :add_link("latest", "releases/v1")
    :close()
```
]]),
                    entry("tar.writer:close", "writer:close()", "method",
                        "Finish and close the archive.",
                        [[
Finish the archive and close the output file.

For gzip archives this writes the compression trailer before closing. The writer must not be used after this call; the returned value is empty. A writer that is garbage-collected without `close` also attempts to flush, but calling `close` explicitly reports failures at a predictable point.

```lua
local tar = require "tar"
local w = tar.create("one.tar")
w:add_file_bytes("a.txt", "a")
w:close()
```
]]),
                    entry("tar.entry:name", "entry.name", "field",
                        "The path stored in the archive.",
                        [[
The member path stored in the archive, as a string.

Directory entries may or may not end with `/`, depending on how the archive was created. Use `is_directory` rather than inspecting the name when classifying an entry.

This field is read-only.
]]),
                    entry("tar.entry:type", "entry.type", "field",
                        "The tar entry type (`file`, `directory`, `sym_link`, ...).",
                        [[
The tar entry kind as a string.

Common values are `"file"`, `"directory"` and `"sym_link"`; other tar kinds are reported by their standard names. Prefer the boolean helpers `is_file`, `is_directory` and `is_link` when only those three categories matter.

This field is read-only.
]]),
                    entry("tar.entry:size", "entry.size", "field",
                        "Uncompressed size in bytes.",
                        [[
The uncompressed size of the current entry in bytes.

Directories usually report zero. For a regular file this is the exact number of bytes that `bytes` or `extract` will read.

This field is read-only.
]]),
                    entry("tar.entry:size_hr", "entry.size_hr", "field",
                        "Human-readable size.",
                        [[
The entry size formatted for humans, for example `"1.5 KB"`.

The value is produced by the filesystem module's human-readable size helper and is intended for display only. Use `size` for arithmetic.

This field is read-only.
]]),
                    entry("tar.entry:link_name", "entry.link_name", "field",
                        "Symbolic-link target.",
                        [[
The target of a symbolic-link entry.

For entries that are not links this is the empty string. The target is exactly the text stored in the archive and is not resolved.

This field is read-only.
]]),
                    entry("tar.entry:mode_flags", "entry.mode_flags", "field",
                        "POSIX mode string.",
                        [[
The POSIX permission bits rendered as a ten-character string.

The first character describes the entry kind (`-`, `d`, `l`, and so on), followed by the owner, group and other `rwx` triples, for example `"-rw-r--r--"`. Unknown mode bits produce `?` for the kind.

This field is read-only.
]]),
                    entry("tar.entry:is_file", "entry.is_file", "field",
                        "True for a regular file.",
                        [[
True when the current entry is a regular file.

Only regular-file entries support `bytes()` and `extract()`. The field is a boolean snapshot of the entry that was just yielded.

This field is read-only.
]]),
                    entry("tar.entry:is_directory", "entry.is_directory", "field",
                        "True for a directory.",
                        [[
True when the current entry is a directory.

Directory entries normally carry no payload, although `extract` on the whole archive creates the corresponding directory. This is a boolean snapshot.

This field is read-only.
]]),
                    entry("tar.entry:is_link", "entry.is_link", "field",
                        "True for a symbolic link.",
                        [[
True when the current entry is a symbolic link.

The target text is available in `link_name`. This is a boolean snapshot and does not check whether the target exists.

This field is read-only.
]]),
                    entry("tar.entry:bytes", "entry:bytes()", "method",
                        "Read the current regular file into a string.",
                        [[
Read the current regular-file entry into a string.

The function streams the remaining payload of the entry and returns it. It may only be called for a file entry created by `tar.open`; calling it for a directory or link fails according to the module error policy.

```lua
local tar = require "tar"
for entry in tar.open("src.tar") do
    if entry.is_file then
        print(entry.name, #entry:bytes())
    end
end
```
]]),
                    entry("tar.entry:extract", "entry:extract(destination)", "method",
                        "Extract the current regular file.",
                        [[
Extract the current regular-file entry to a filesystem path.

`destination` is the full output path. Parent directories are not created automatically, so they must already exist. The entry payload is streamed to the new file and the function returns nothing on success. Non-file entries fail according to the module error policy.

```lua
local tar = require "tar"
for entry in tar.open("src.tar") do
    if entry.name == "main.lua" then
        entry:extract("main.lua")
    end
end
```
]]),
                }),

                module("timer", "timer", "Nanosecond timer.", [==[
`timer.new([start])` creates a timer and optionally starts it immediately.
Timers use `os.nanotime` and are monotonic.
]==], {
                    entry("timer.new", "timer.new([start])", "function",
                        "Create a timer.",
                        [[
Create a nanosecond-resolution timer backed by the monotonic `os.nanotime` clock.

When `start` is truthy the timer is started immediately; otherwise call `timer:start()` before measuring. The object exposes the timer methods and a `laps` array.

```lua
local timer = require "timer"
local t = timer.new(true)
-- work
print(t:stop())
```
]]),
                    entry("timer:start", "timer:start()", "method",
                        "Start or restart the timer.",
                        [[
Start or restart the timer, using the current monotonic time as the new origin.

Returns the timer object. Existing lap timestamps and the previous stop time are not cleared; call `timer:reset()` for a completely fresh timer.
]]),
                    entry("timer:lap", "timer:lap()", "method",
                        "Record a lap and return the lap time.",
                        [[
Record a lap at the current time and return the duration since the previous lap, or since the start for the first lap.

The timestamp is appended to `timer.laps`. The timer must have been started. Returns a duration in nanoseconds.
]]),
                    entry("timer:stop", "timer:stop()", "method",
                        "Stop the timer and return the elapsed time.",
                        [[
Stop the timer at the current time and return the elapsed duration since it was started.

The stop time is remembered by `timer:time()`. Stopping again updates the stop time and the reported duration.
]]),
                    entry("timer:time", "timer:time()", "method",
                        "Return the last measured time.",
                        [[
Return the last measured `stop - start` duration, or `nil` if the timer has not been stopped.

Starting the timer again does not immediately change this value; it changes when `stop()` is called again.
]]),
                    entry("timer:elapsed", "timer:elapsed()", "method",
                        "Return the time since the timer started.",
                        [[
Return the duration from the start time to now, without stopping the timer.

Returns `nil` when the timer has not been started. The value is in nanoseconds and comes from the monotonic clock.
]]),
                    entry("timer:lap_elapsed", "timer:lap_elapsed()", "method",
                        "Return the time since the last lap.",
                        [[
Return the time elapsed since the most recent lap, or since the start when no lap has been recorded.

The timer is not stopped and no lap is recorded. Calling this before `timer:start()` is an error.
]]),
                    entry("timer:reset", "timer:reset()", "method",
                        "Reset the timer and its laps.",
                        [[
Clear the start time, stop time and all recorded laps.

The timer becomes unstarted, so `timer:time()` and `timer:elapsed()` return `nil` until `start()` is called again. The function does not return the timer.
]]),
                }),

                module("uuid", "uuid", "UUID generation.", [==[
The `uuid` module generates RFC 9562 UUIDs.  `uuid.v4()` generates a random
UUID and `uuid.v7()` a time-ordered UUID.
]==], {
                    entry("uuid.v4", "uuid.v4()", "function",
                        "Generate a version 4 (random) UUID.",
                        [[
Generate a version 4 (random) UUID and return it as a lowercase 36-character string.

The version and variant bits are set according to RFC 9562. Each call uses random data, so values are not ordered.

```lua
local uuid = require "uuid"
print(uuid.v4()) --> "f47ac10b-58cc-4372-a567-0e02b2c3d479" (example)
```
]]),
                    entry("uuid.v7", "uuid.v7()", "function",
                        "Generate a version 7 (time-ordered) UUID.",
                        [[
Generate a version 7 (time-ordered) UUID and return it as a lowercase 36-character string.

The first 48 bits contain a Unix millisecond timestamp, so UUIDs created in the same millisecond share a prefix and later values generally sort after earlier ones. Random bits fill the remainder.

```lua
local uuid = require "uuid"
local id = uuid.v7()
```
]]),
                }),

                module("xlsxmlwriter", "xlsxmlwriter", "Simple Excel XML writer.", [==[
`require "xlsxmlwriter"` returns a constructor.  Calling it with a filename
creates a workbook object.

```lua
local workbook = require("xlsxmlwriter")("book.xml")
workbook:newSheet("Data")
workbook:addRow { "name", 42, { year = 2026, month = 10, day = 23 } }
workbook:close()
```
]==], {
                    entry("xlsxmlwriter:newSheet", "workbook:newSheet([name])", "method",
                        "Start a new worksheet.",
                        [[
Start a new worksheet in the workbook, closing the current worksheet first.

If `name` is omitted, a name such as `"Sheet1"` is generated from the sheet count. The name is XML-escaped. Returns the workbook object so calls can be chained.

```lua
local workbook = require("xlsxmlwriter")("book.xml")
workbook:newSheet("Data")
```
]]),
                    entry("xlsxmlwriter:closeSheet", "workbook:closeSheet()", "method",
                        "Close the current worksheet.",
                        [[
End the current row, if one is open, and close the current worksheet.

If no worksheet is open the call does nothing. Returns the workbook for chaining.
]]),
                    entry("xlsxmlwriter:nextRow", "workbook:nextRow(...)", "method",
                        "Start a new row, optionally with cells.",
                        [[
End any open row and start a new row, optionally filling it with cells.

Additional arguments are passed to `workbook:cells`. The row counter is incremented and the workbook is returned.

```lua
workbook:nextRow("name", "count")
```
]]),
                    entry("xlsxmlwriter:endRow", "workbook:endRow()", "method",
                        "End the current row.",
                        [[
Close the currently open row.

If no row is open the call does nothing. Returns the workbook for chaining.
]]),
                    entry("xlsxmlwriter:addRow", "workbook:addRow(values)", "method",
                        "Add a complete row from a table.",
                        [[
Add a complete row from an array of cell values.

The table is unpacked and passed to `nextRow`, so nested arrays are not flattened and the table must be an array. Returns the workbook.

```lua
workbook:addRow { "alice", 42 }
```
]]),
                    entry("xlsxmlwriter:cells", "workbook:cells(...)", "method",
                        "Append cells to the current row.",
                        [[
Append one or more cell values to the current row, opening a row first if necessary.

Each value is written by `workbook:cell`. Returns the workbook.
]]),
                    entry("xlsxmlwriter:addCells", "workbook:addCells(values)", "method",
                        "Append cells from a table.",
                        [[
Append all values from an array table to the current row.

The table is unpacked and passed to `cells`. Returns the workbook.
]]),
                    entry("xlsxmlwriter:cell", "workbook:cell(value)", "method",
                        "Append a single cell.",
                        [[
Append a single value to the current row, opening a row if needed.

Strings become string cells and numbers become numeric cells. A table with `year`, `month` and `day` becomes a date cell; adding `hour`, `min` and `sec` makes it a date-time cell; a table with only the time fields becomes a time cell. Other values are converted with `tostring` and written as strings. XML special characters are escaped.

```lua
workbook:cell("text"):cell(3.14):cell { year = 2026, month = 10, day = 24 }
```
]]),
                    entry("xlsxmlwriter:close", "workbook:close()", "method",
                        "Finish the workbook and close the file.",
                        [[
Close the current worksheet, write the closing workbook tag, and close the output file.

After this call the workbook should not be used further. Returns the workbook object.
]]),
                }),

                module("zip", "zip", "Create zip archives.", [==[
`zip.create(filename)` creates a zip archive.  The writer supports files,
in-memory data, directories and nested archives.  `zip.add_directory` adds a
filesystem directory tree.  Timestamps are stored in UTC.
]==], {
                    entry("zip.create", "zip.create(filename)", "function",
                        "Create a zip archive for writing.",
                        [[
Create a new zip archive for writing.

The file is truncated if it already exists. The returned writer supports `add_file`, `create_directory`, streaming `open`/`write`/`close`, and `close_zip`. On failure the module returns `nil, message`; configure `error_handling` to raise instead.

```lua
local zip = require "zip"
local z = zip.create("bundle.zip")
z:add_file("README.md", "README.md")
z:close_zip()
```
]]),
                    entry("zip.open", "zip.open(filename)", "function",
                        "Open an existing zip archive for appending.",
                        [[
Open an existing zip archive so entries can be appended.

The archive must already exist and contain a valid central directory. New entries are added after the existing ones; existing entries are not rewritten. Returns a writer or `nil, message`.

```lua
local zip = require "zip"
local z = zip.open("bundle.zip")
z:add_file("src/version", "version.txt")
z:close_zip()
```
]]),
                    entry("zip.create_after", "zip.create_after(filename)", "function",
                        "Create a zip archive after existing file data.",
                        [[
Create a zip archive after existing non-zip file data.

This is used to append a zip payload to an executable or another container: the current file contents are preserved and the new zip starts at the end. The path must already exist. Returns a writer or `nil, message`.

```lua
local zip = require "zip"
local z = zip.create_after("app.bin")
z:add_file("config.lua", "config.lua")
z:close_zip()
```
]]),
                    entry("zip.add_directory", "zip.add_directory(writer, path [, include_top [, level]])", "function",
                        "Add a directory tree to an archive.",
                        [[
Recursively add a filesystem directory tree to an archive.

Files are added with paths relative to `path`. When `include_top` is true the top directory name is included in the archive paths; otherwise its contents are placed at the archive root. Empty directories are written explicitly. `level` defaults to `zip.level.default`.

Returns the number of entries added. Files inside non-empty directories count individually; the parent directory itself is implied by the file paths.

```lua
local zip = require "zip"
local z = zip.create("src.zip")
local count = zip.add_directory(z, "src", true)
z:close_zip()
print(count > 0) --> true
```
]]),
                    entry("zip.level", "zip.level", "field",
                        "Compression level constants.",
                        [[
A table of named compression levels.

The fields are `store` (0), `fastest` (1), `fast` (3), `normal` (5), `default` (6), `high` (7) and `max` (9). Any integer from 0 to 9 is also accepted by the writer. Higher values produce smaller archives at the cost of CPU time.

This field is a table; treat it as read-only.
]]),
                    entry("zip.writer:add_file", "writer:add_file(path, archive_path [, level [, comment]])", "method",
                        "Add a file.",
                        [[
Add a file from disk to the archive.

`path` is the source file. `archive_path` is required and becomes the member name. `level` defaults to 6 and must be between 0 and 9; `comment` optionally sets the per-entry comment. The file is streamed into the archive.

Returns `true` on success. On failure the call returns `nil, message` or raises according to the configured error policy.

```lua
local zip = require "zip"
local z = zip.create("out.zip")
z:add_file("src/version", "version.txt", zip.level.max, "version file")
z:close_zip()
```
]]),
                    entry("zip.writer:create_directory", "writer:create_directory(path)", "method",
                        "Add a directory entry.",
                        [[
Add an explicit directory entry to the archive.

A trailing `/` is added when missing. Empty directories need this call because adding files does not create standalone directory records. The function returns nothing.

```lua
local zip = require "zip"
local z = zip.create("dirs.zip")
z:create_directory("empty")
z:close_zip()
```
]]),
                    entry("zip.writer:open", "writer:open(path [, level [, comment]])", "method",
                        "Open an entry for streaming writes.",
                        [[
Start a new archive entry for streaming writes.

`path` is the member name. `level` defaults to 6 and `comment` optionally sets the entry comment. Any entry already being written is closed first. After opening, use `write` one or more times and then `close` or `close_zip`.

Returns the writer for chaining.

```lua
local zip = require "zip"
local z = zip.create("stream.zip")
z:open("notes.txt"):write("first line\n"):write("second line\n"):close()
z:close_zip()
```
]]),
                    entry("zip.writer:write", "writer:write(data)", "method",
                        "Write data to the current entry.",
                        [[
Write one or more strings to the currently open entry.

All arguments from the first onward are converted to strings and appended to the entry. Numbers are accepted. The call does not close the entry; use `close` when finished.

Returns the writer for chaining. Writing without an open entry, or after the archive is closed, follows the configured error policy.

```lua
local zip = require "zip"
local z = zip.create("numbers.zip")
z:open("values.txt"):write("one ", "two ", 3):close()
z:close_zip()
```
]]),
                    entry("zip.writer:close", "writer:close()", "method",
                        "Close the current entry.",
                        [[
Close the entry currently being written.

The archive remains open so another entry can be opened or added. Closing when no entry is active is harmless. Returns the writer for chaining, or `nil, message` when the archive is already closed.

```lua
local zip = require "zip"
local z = zip.create("out.zip")
z:open("a.txt"):write("a"):close()
z:add_file("src/version", "version.txt")
z:close_zip()
```
]]),
                    entry("zip.writer:close_zip", "writer:close_zip()", "method",
                        "Finish and close the archive.",
                        [[
Finish the archive and close the underlying zip file.

Any open entry is closed first. An optional `comment` string is stored as the archive comment in the central directory. After this call the writer must not be used again; entries added later are not guaranteed to be written.

Returns nothing. The writer is also finalized during garbage collection, but explicit closing surfaces errors.

```lua
local zip = require "zip"
local z = zip.create("final.zip")
z:add_file("README.md", "README.md")
z:close_zip("built by ZLI")
```
]]),
                }),

                module("unzip", "unzip", "Read and extract zip archives.", [==[
`unzip.open(filename)` returns an archive object.  Archives expose entries as
tables with `name`, `path`, `full_path`, `is_file`, `is_directory`, sizes,
timestamps and `extract`.
]==], {
                    entry("unzip.open", "unzip.open(filename)", "function",
                        "Open a zip archive.",
                        [[
Open a zip archive for reading.

Returns an archive object with `list`, `dir`, `info`, `read_all`, `lines`, `extract`, `payload_start` and `close` methods. On failure it returns `nil, message`; the message includes the path that could not be opened.

```lua
local unzip = require "unzip"
local archive = assert(unzip.open("bundle.zip"))
print(#archive:list())
archive:close()
```
]]),
                    entry("unzip.extract", "unzip.extract(filename, destination)", "function",
                        "Extract an archive to a directory.",
                        [[
Extract every entry of an archive into a directory.

`filename` is the archive path and `destination` is the output directory. Missing directories are created, and directory entries are recreated. Returns `true` when the archive was opened and processed, or `nil, message` when it could not be opened.

```lua
local unzip = require "unzip"
local ok, err = unzip.extract("bundle.zip", "out")
assert(ok, err)
```
]]),
                    entry("unzip:list", "archive:list()", "method",
                        "Return entries as an array.",
                        [[
Return an array of entry tables.

The order is the order stored in the archive's central directory. An empty archive returns an empty table. Each entry carries name, path, size, CRC, timestamp and extraction helpers; see the entry methods below. A closed archive or invalid central directory follows the module error policy.

```lua
local unzip = require "unzip"
local archive = assert(unzip.open("bundle.zip"))
for _, entry in ipairs(archive:list()) do
    print(entry.full_path, entry.uncompressed_size)
end
```
]]),
                    entry("unzip:dir", "archive:dir()", "method",
                        "Return entries keyed by path.",
                        [[
Return entry tables keyed by their full archive path.

This is convenient when looking up a known member without scanning the array from `list`. Directory keys end with `/`. An empty archive returns an empty table.

```lua
local unzip = require "unzip"
local archive = assert(unzip.open("bundle.zip"))
local entry = archive:dir()["src/main.lua"]
print(entry and entry.is_file)
```
]]),
                    entry("unzip:info", "archive:info()", "method",
                        "Return archive information.",
                        [[
Return archive-level information.

The result contains `entries`, the number of members, and `comment`, the archive comment (an empty string when absent). Corrupt metadata raises an internal error; a closed archive returns `nil, message`.

```lua
local unzip = require "unzip"
local archive = assert(unzip.open("bundle.zip"))
local info = archive:info()
print(info.entries, info.comment)
```
]]),
                    entry("unzip:extract", "archive:extract(name [, destination])", "method",
                        "Extract one archive member.",
                        [[
Extract one member of the archive.

`name` is the member's full path in the archive. `destination` is optional and defaults to the same path, relative to the current directory. Parent directories are not created. Returns `true` on success, or `nil, message` when the member cannot be found or opened.

```lua
local unzip = require "unzip"
local archive = assert(unzip.open("bundle.zip"))
archive:extract("src/main.lua", "main.lua")
archive:close()
```
]]),
                    entry("unzip:read_all", "archive:read_all(name)", "method",
                        "Read an entry as a string.",
                        [[
Read a named member into a string.

Returns the complete uncompressed contents. A missing member, a closed archive, or an unreadable stream produces `nil, message` under the default error policy.

```lua
local unzip = require "unzip"
local archive = assert(unzip.open("bundle.zip"))
local text = archive:read_all("README.md")
print(#text)
```
]]),
                    entry("unzip:lines", "archive:lines(name)", "method",
                        "Iterate the lines of an entry.",
                        [[
Iterate over the lines of a named member.

Returns an iterator suitable for a `for` loop. Lines are returned without their line-ending characters, matching `io.lines`. Missing members and closed archives follow the module error policy.

```lua
local unzip = require "unzip"
local archive = assert(unzip.open("bundle.zip"))
for line in archive:lines("README.md") do
    print(line)
end
```
]]),
                    entry("unzip:payload_start", "archive:payload_start()", "method",
                        "Return the offset of an appended zip payload.",
                        [[
Return the byte offset where an appended zip payload starts.

The value is the offset of the first local file header in the underlying file, so it points at the beginning of the zip data rather than at the first compressed byte. It is used by the compiler to replace an existing payload. An empty archive returns `nil`.

```lua
local unzip = require "unzip"
local archive = assert(unzip.open("app.bin"))
local offset = archive:payload_start()
print(offset)
archive:close()
```
]]),
                    entry("unzip:close", "archive:close()", "method",
                        "Close the archive.",
                        [[
Close the archive and release its file handle.

Calling `close` more than once is safe. The method returns nothing. After closing, other archive methods report that the archive is closed.

```lua
local unzip = require "unzip"
local archive = assert(unzip.open("bundle.zip"))
archive:close()
```
]]),
                    entry("unzip.entry:read_all", "entry:read_all()", "method",
                        "Read the entry as a string.",
                        [[
Read this entry's complete contents into a string.

The entry must be a regular file. A directory entry or a closed archive follows the module error policy. The archive remains open for further reads.

```lua
local unzip = require "unzip"
local archive = assert(unzip.open("bundle.zip"))
local entry = archive:dir()["README.md"]
print(entry:read_all())
```
]]),
                    entry("unzip.entry:lines", "entry:lines()", "method",
                        "Iterate the entry's lines.",
                        [[
Iterate over this entry's lines.

Returns an iterator that yields each line without its newline characters. This is equivalent to reading through `entry:open()` and calling `read("l")` repeatedly, but simpler for scripts.

```lua
local unzip = require "unzip"
local archive = assert(unzip.open("bundle.zip"))
local entry = archive:dir()["README.md"]
for line in entry:lines() do
    print(line)
end
```
]]),
                    entry("unzip.entry:extract", "entry:extract([destination])", "method",
                        "Extract the entry.",
                        [[
Extract this entry to a file.

`destination` is optional; when omitted the entry's stored `full_path` is used relative to the current directory. Parent directories are not created automatically. Returns `true` on success, or `nil, message` if the file or directory cannot be written.

```lua
local unzip = require "unzip"
local archive = assert(unzip.open("bundle.zip"))
local entry = archive:dir()["src/main.lua"]
entry:extract("main.lua")
```
]]),
                }),

                module("gzip", "gzip", "Read and write gzip-compressed files.", [==[
`gzip.open(filename [, mode [, level]])` opens a gzip-compressed file.  The
default mode is `"r"`; pass `"w"` to create or truncate the file.  Reading and
writing handles expose the methods documented below.  `gzip.compress` and
`gzip.decompress` are one-shot helpers.  `gzip.open` readers and both helpers
consume a single gzip member; concatenated members and trailing bytes are not
followed.
]==], {
                    entry("gzip.open", "gzip.open(filename [, mode [, level]])", "function",
                        "Open a gzip-compressed file.",
                        [[
Open a gzip file for reading or writing.

`mode` is `"r"` (the default) or `"w"`. `level` selects compression when writing and accepts `"store"`, `"fastest"`, `"fast"`, `"normal"`, `"default"`, `"high"`, `"max"`, `"best"` or a number from `0` to `9`. The default is `6`. Level `0` stores data without compression.

Returns a reader or writer object. On failure it returns `nil, message`.

```lua
local gzip = require "gzip"
local file = assert(gzip.open("data.txt.gz", "w", 9))
file:write("hello\n")
file:close()
```
]]),
                    entry("gzip.compress", "gzip.compress(data [, level])", "function",
                        "Compress a string into gzip data.",
                        [[
Compress a complete string and return the gzip stream.

`level` has the same meaning and default as for `gzip.open`. The result can be written to a `.gz` file or passed to `gzip.decompress`.

```lua
local gzip = require "gzip"
local packed = gzip.compress("hello world", "best")
```
]]),
                    entry("gzip.decompress", "gzip.decompress(data)", "function",
                        "Decompress a complete gzip stream.",
                        [[
Decompress a complete gzip stream and return the original string.

Invalid, truncated or checksum-failing input returns `nil, message`; it does not return partial output. Only the first gzip member is consumed.

```lua
local gzip = require "gzip"
local text = gzip.decompress(gzip.compress("hello world"))
print(text) --> hello world
```
]]),
                    entry("gzip.reader:read", "reader:read([count | format])", "method",
                        "Read decompressed bytes.",
                        [[
Read data from the gzip stream.

With a number, read at most that many bytes. With `"a"` read the rest of the stream. `"l"` and `"L"` read one line without or with the line ending. The default is `"l"`. Returns `nil` at end of stream.

```lua
local gzip = require "gzip"
local reader = assert(gzip.open("data.txt.gz"))
local first = reader:read("l")
local rest = reader:read("a")
reader:close()
```
]]),
                    entry("gzip.reader:read_all", "reader:read_all()", "method",
                        "Read the whole stream.",
                        [[
Read the remainder of the gzip stream into a string. Equivalent to `reader:read("a")`.

```lua
local gzip = require "gzip"
local reader = assert(gzip.open("data.txt.gz"))
local text = reader:read_all()
reader:close()
```
]]),
                    entry("gzip.reader:lines", "reader:lines()", "method",
                        "Iterate over decompressed lines.",
                        [[
Return an iterator that yields each line without its line-ending characters.

```lua
local gzip = require "gzip"
local reader = assert(gzip.open("data.txt.gz"))
for line in reader:lines() do
    print(line)
end
reader:close()
```
]]),
                    entry("gzip.reader:seek", "reader:seek([whence [, offset]])", "method",
                        "Move to another uncompressed position.",
                        [[
Move the read position in the uncompressed stream.

`whence` is `"set"`, `"cur"` or `"end"` and defaults to `"cur"`; `offset` defaults to `0`. Seeking restarts decompression from the beginning and discards bytes as needed, so it is not a constant-time operation. Returns the new absolute position.

```lua
local gzip = require "gzip"
local reader = assert(gzip.open("data.txt.gz"))
reader:seek("set", 0)
```
]]),
                    entry("gzip.reader:close", "reader:close()", "method",
                        "Close a gzip reader.",
                        [[
Close the underlying file and release decompression state. Calling `close` more than once is safe.
]]),
                    entry("gzip.writer:write", "writer:write(...)", "method",
                        "Write data to a gzip file.",
                        [[
Write one or more strings to the gzip stream. Numbers are accepted and converted to strings. Returns the writer for chaining.

```lua
local gzip = require "gzip"
local writer = assert(gzip.open("out.gz", "w"))
writer:write("first line\n", "second line\n")
writer:close()
```
]]),
                    entry("gzip.writer:flush", "writer:flush()", "method",
                        "Flush compressed data.",
                        [[
Flush buffered compressed data to the file without ending the gzip stream. Returns the writer for chaining.
]]),
                    entry("gzip.writer:close", "writer:close()", "method",
                        "Finish and close a gzip file.",
                        [[
Finish the deflate stream, write the gzip trailer, flush the file and close it.

The writer must not be used after `close`. A writer that is garbage-collected without an explicit `close` attempts to finish as well, but explicit closing reports failures at a predictable point. Calling `close` more than once is safe.
]]),
                }),
            },
        },

        {
            id = "third_party",
            title = "Third-party libraries",
            source = "third_party",
            modules = {
                module("argparse", "argparse", "Feature-rich command-line parser.", [==[
`argparse` is a feature-rich command-line parser inspired by Python's argparse.
The entry point is `argparse(name, description)`.

```lua
local parser = require("argparse")("myprog", "does something useful")
parser:argument("input", "input file")
parser:flag("-v --verbose", "verbose output")
local args = parser:parse()
```
]==], {
                    entry("argparse:argument", "parser:argument(name [, description [, default]])", "method",
                        "Add a positional argument.",
                        [[
Add a positional argument and return its `Argument` object so settings can be chained.

`name` is used both as the help label and as the default result key. `description` appears in the generated help. A string `default` is used when the argument is absent and is shown in the help text.

Positional arguments are consumed in declaration order. A missing required value makes parsing fail through the parser's error handler.

```lua
local parser = require("argparse")("copy", "copy a file")
parser:argument("source", "file to read")
parser:argument("destination", "file to write"):default("out.txt")
local args = parser:parse({ "in.txt" })
print(args.source, args.destination) --> in.txt out.txt
```
]]),
                    entry("argparse:option", "parser:option(name [, description [, default]])", "method",
                        "Add an option.",
                        [[
Add a named option and return its `Option` object.

`name` is a whitespace-separated list of aliases, for example `"-o --output"`. The default result key comes from the long alias when one exists, otherwise from the short alias; hyphens become underscores. `description` is shown in help and a string `default` is reported there as well.

An option that takes a value consumes the next command-line word. Options may be written as `--name=value` or as bundled short flags. Missing or unknown options cause the parser to report an error.

```lua
local parser = require("argparse")("example")
parser:option("-o --output", "output file", "a.out")
local args = parser:parse({ "--output=result.txt" })
print(args.output) --> result.txt
```
]]),
                    entry("argparse:flag", "parser:flag(name [, description])", "method",
                        "Add a boolean flag.",
                        [[
Add a boolean option that consumes no value.

This is shorthand for `parser:option(name, description):args(0)`. When the flag appears more than once the normal option overwrite rules apply. If the flag is absent its result is `nil`, not `false`.

```lua
local parser = require("argparse")("example")
parser:flag("-v --verbose", "show details")
local args = parser:parse({ "-v" })
print(args.verbose) --> true
```
]]),
                    entry("argparse:command", "parser:command(name [, description])", "method",
                        "Add a subcommand.",
                        [[
Add a subcommand and return its parser object.

The returned command is a full parser: it can have its own arguments, options and nested commands. When the command name is seen, the result field named after the command (or its `target`) is set to `true`, and parsing continues with the command's parser.

By default a parser with commands requires one to be present. Use `:require_command(false)` on the parent when the command is optional.

```lua
local parser = require("argparse")("tool")
local build = parser:command("build", "build the project")
build:flag("--release", "optimised build")
local args = parser:parse({ "build", "--release" })
print(args.build, args.release) --> true true
```
]]),
                    entry("argparse:mutex", "parser:mutex(...)", "method",
                        "Create a mutually exclusive group.",
                        [[
Create a mutually exclusive group from options and positional arguments.

Pass already-created `Option` or `Argument` objects. During parsing at most one element from the group may be used; using two reports an error. The group also affects the generated usage line. Returns the parser so calls can be chained.

```lua
local parser = require("argparse")("tool")
local quiet = parser:flag("-q --quiet")
local loud = parser:flag("-l --loud")
parser:mutex(quiet, loud)
```
]]),
                    entry("argparse:group", "parser:group(name, ...)", "method",
                        "Create an argument group.",
                        [[
Create a named help group.

The first argument is the heading shown in `get_help()`. The remaining arguments are existing options, positional arguments or commands. Grouping only changes help layout; parsing behavior is unchanged.

Passing anything other than those element types raises an assertion error. Returns the parser for chaining.

```lua
local parser = require("argparse")("tool")
local input = parser:argument("input")
local verbose = parser:flag("-v --verbose")
parser:group("Input", input)
parser:group("Output", verbose)
```
]]),
                    entry("argparse:parse", "parser:parse([args])", "method",
                        "Parse command-line arguments.",
                        [[
Parse command-line arguments and return a table of results.

`args` defaults to the global `arg` table. The result contains one field per argument or option plus `true` for each command seen. Defaults and custom actions are applied before the table is returned.

Parse errors are not exceptions: `parse` prints the usage and an error message to stderr and exits with status 1. Use `pparse` when the caller must handle errors.

```lua
local parser = require("argparse")("echo")
parser:argument("text")
local args = parser:parse({ "hello" })
print(args.text) --> hello
```
]]),
                    entry("argparse:pparse", "parser:pparse([args])", "method",
                        "Parse arguments, returning an error message instead of raising.",
                        [[
Parse arguments without terminating the process on a parse error.

Returns `true, result` on success, or `false, message` when the command line is invalid. The error message is the same text that `parse` would print; no usage block is written to stderr.

Errors raised by user callbacks and other non-parser failures are re-raised rather than converted into a `false` result.

```lua
local parser = require("argparse")("tool")
parser:argument("count"):convert(tonumber)
local ok, result = parser:pparse({ "many" })
print(ok, result:match("malformed") ~= nil) --> false true
```
]]),
                    entry("argparse:get_usage", "parser:get_usage()", "method",
                        "Return the generated usage string.",
                        [[
Return the generated one-line (or wrapped) usage string.

The text starts with `Usage:` and lists options, positional arguments, mutex groups and commands in a stable order. A custom string assigned through the parser's `usage` property is returned unchanged.

The result is a string and has no side effects; it is also included at the top of `get_help()`.

```lua
local parser = require("argparse")("tool")
parser:add_help(false)
parser:argument("file")
print(parser:get_usage()) --> Usage: tool <file>
```
]]),
                    entry("argparse:get_help", "parser:get_help()", "method",
                        "Return the generated help text.",
                        [[
Return the complete generated help text as a string.

The text contains the usage line, the parser description, grouped arguments, options and commands, and the optional epilog. Hidden elements are omitted. Line wrapping follows the configured help margins and maximum width.

The function does not print or exit. Printing the result is the caller's responsibility.

```lua
local parser = require("argparse")("tool", "does useful work")
parser:flag("-v --verbose", "show details")
print(parser:get_help())
```
]]),
                    entry("argparse:add_help_command", "parser:add_help_command([value])", "method",
                        "Add a help command.",
                        [[
Add a `help` subcommand to the parser.

The command prints help for the parser when invoked without an argument, or for a named command when given one, then exits with status 0. An unknown command name is reported as an error.

Pass a string or table to customise the command through the usual command properties. Returns the parser.

```lua
local parser = require("argparse")("tool")
parser:add_help_command()
parser:command("build")
-- running "tool help build" prints the build command's help
```
]]),
                    entry("argparse:add_complete", "parser:add_complete([value])", "method",
                        "Add shell completion support.",
                        [[
Add a `--completion <shell>` option that emits a completion script.

Accepted shells are `bash`, `zsh` and `fish`. The generated script is written to stdout and the process exits with status 0, so the option must be handled before other work.

Pass a string or table to customise the option object. Returns the parser.

```lua
local parser = require("argparse")("tool")
parser:add_complete()
-- "tool --completion bash" prints a bash completion script
```
]]),
                    entry("argparse:get_bash_complete", "parser:get_bash_complete()", "method",
                        "Generate a bash completion script.",
                        [[
Return a bash completion script for this parser as a string.

The script completes option names and, for parsers with commands, command names and their options. The parser name must be shell-safe: characters outside letters, digits, `_`, `-`, `+` and `.` make the internal safety assertion fail.

This function is normally called indirectly by `add_complete`; it neither prints nor exits.

```lua
local parser = require("argparse")("mytool")
parser:flag("--verbose")
local script = parser:get_bash_complete()
assert(script:match("complete"))
```
]]),
                    entry("argparse:get_zsh_complete", "parser:get_zsh_complete()", "method",
                        "Generate a zsh completion script.",
                        [[
Return a zsh completion script for this parser.

The result starts with a `#compdef` line followed by the completion function and any per-command helpers. As with the bash generator, the parser name and option aliases must be shell-safe.

Calling the function has no output or exit side effects.

```lua
local parser = require("argparse")("mytool")
parser:option("--output")
local script = parser:get_zsh_complete()
assert(script:match("#compdef mytool"))
```
]]),
                    entry("argparse:get_fish_complete", "parser:get_fish_complete()", "method",
                        "Generate a fish completion script.",
                        [[
Return a fish completion script for this parser.

The script defines command-detection helpers plus completions for options, arguments and subcommands. Shell-unsafe names trigger the same assertion as the other completion generators.

The returned string is not printed automatically.

```lua
local parser = require("argparse")("mytool")
parser:flag("--verbose")
local script = parser:get_fish_complete()
assert(script:match("complete"))
```
]]),
                    entry("argparse:error", "parser:error(message [, ...])", "method",
                        "Raise a parser error.",
                        [[
Report a parser error and terminate the program.

The current usage string is written to stderr, followed by a blank line and `Error: ` plus the formatted message. `...` are passed to `string.format`. The function then calls `os.exit(1)`, so it never returns.

Use `pparse` or a custom action if the caller needs to recover from invalid input.

```lua
local parser = require("argparse")("tool")
parser:error("invalid value '%s'", "x")
-- prints usage and "Error: invalid value 'x'", then exits 1
```
]]),
                    entry("argparse.Argument:args", "argument:args(...)", "method",
                        "Set or get the argument's target names.",
                        [[
Set how many values one occurrence of an element consumes.

The argument may be a number, a table boundary string such as `"2"`, `"2-4"`, `"2+"`, `"*"`, `"+"` or `"?"`, or another supported range form. It updates both the minimum and maximum value counts and returns the element.

For options, the value is the number of words after the option. For positional arguments it controls how many command-line words the argument collects.

```lua
local parser = require("argparse")("tool")
local point = parser:argument("coords"):args(2)
local args = parser:parse({ "10", "20" })
print(args.coords[1], args.coords[2]) --> 10 20
```
]]),
                    entry("argparse.Argument:count", "argument:count(count)", "method",
                        "Set how many values the argument consumes.",
                        [[
Set how many times an option may occur on the command line.

The value uses the same boundary syntax as `args`: a number, `"n-m"`, `"n+"`, `"*"`, `"+"` or `"?"`. A minimum greater than zero makes the option required; a maximum limits repetition. Returns the element.

This setting is primarily useful on options. Combine it with `:args` when each occurrence also takes several values.

```lua
local parser = require("argparse")("tool")
local include = parser:option("-I --include"):count("*")
local args = parser:parse({ "-I", "one", "-I", "two" })
print(#args.include) --> 2
```
]]),
                    entry("argparse.Argument:default", "argument:default(value)", "method",
                        "Set the default value.",
                        [[
Set the value used when the element is not supplied.

A string default is stored as the displayed default and is inserted when the argument or option is unused. A non-string default (number, table, boolean, or `nil`) is used as the initial result value and is not shown in help.

For options, defaults participate in usage rendering and in `show_default`. Returns the element.

```lua
local parser = require("argparse")("tool")
parser:option("--retries", "attempts", "3"):convert(tonumber)
local args = parser:parse({})
print(args.retries) --> 3
```
]]),
                    entry("argparse.Argument:target", "argument:target(name)", "method",
                        "Set the result field name.",
                        [[
Choose the result-table field written by this element.

By default a positional argument uses its name and an option derives a name from its aliases, replacing `-` with `_`. Setting a target overrides that choice and is useful when several elements share a name or when the Lua identifier would be inconvenient.

Returns the element.

```lua
local parser = require("argparse")("tool")
parser:flag("--dry-run"):target("dry_run")
local args = parser:parse({ "--dry-run" })
print(args.dry_run) --> true
```
]]),
                    entry("argparse.Argument:convert", "argument:convert(func)", "method",
                        "Set a value conversion function.",
                        [[
Set a conversion applied to each raw command-line value.

`func` may be a function, a table whose numeric index selects a converter for the corresponding value position, or a lookup table. A function receives the raw string and returns the converted value; returning `nil, message` reports a parse error. Choices are checked before conversion.

Returns the element.

```lua
local parser = require("argparse")("tool")
parser:argument("count"):convert(tonumber)
local args = parser:parse({ "42" })
print(math.type(args.count)) --> integer
```
]]),
                    entry("argparse.Argument:choices", "argument:choices(...)", "method",
                        "Restrict values to a set of choices.",
                        [[
Restrict accepted values to a fixed set.

Pass an array of strings. A value outside the set causes a parse error that lists the allowed choices; the choices also replace the usual placeholder in usage and help. Conversion runs after the choice check.

Returns the element.

```lua
local parser = require("argparse")("tool")
parser:argument("mode"):choices({ "fast", "safe" })
local ok = parser:pparse({ "slow" })
print(ok) --> false
```
]]),
                    entry("argparse.Argument:argname", "argument:argname(name)", "method",
                        "Set the display name in help output.",
                        [[
Set the placeholder used for this element in usage and help output.

The value may be a string or an array of strings, one per consumed value. It does not change parsing or the result key. Returns the element.

```lua
local parser = require("argparse")("tool")
parser:add_help(false)
parser:argument("file"):argname("PATH")
print(parser:get_usage()) --> Usage: tool PATH
```
]]),
                    entry("argparse.Argument:show_default", "argument:show_default(boolean)", "method",
                        "Control whether the default is shown in help.",
                        [[
Control whether a string default is displayed in help output.

`boolean` defaults to `true`. When enabled and a string default is set, help appends `(default: value)` to the description. Non-string defaults are initial values and are never shown. Returns the element.

```lua
local parser = require("argparse")("tool")
parser:option("--level", "log level", "info"):show_default(false)
assert(not parser:get_help():find("default: info", 1, true))
```
]]),
                    entry("argparse.Argument:hidden", "argument:hidden(boolean)", "method",
                        "Hide the argument from help output.",
                        [[
Hide this element from usage and help output.

The element is still parsed and still produces a result; only its documentation is suppressed. This is useful for compatibility options and internal switches. Returns the element.

```lua
local parser = require("argparse")("tool")
parser:flag("--internal"):hidden(true)
assert(not parser:get_help():find("--internal", 1, true))
```
]]),
                    entry("argparse.Argument:overwrite", "argument:overwrite(boolean)", "method",
                        "Control overwriting of repeated results.",
                        [[
Control what happens when an option is repeated more often than allowed.

With `true` (the default for options), later occurrences overwrite earlier results according to the action: `store` keeps the last value, `append` drops the oldest element, and `count` keeps its current count. With `false`, exceeding the maximum count raises a parse error. Returns the element.

```lua
local parser = require("argparse")("tool")
local tag = parser:option("--tag"):overwrite(false)
local ok = parser:pparse({ "--tag", "a", "--tag", "b" })
print(ok) --> false
```
]]),
                }, { upstream = "https://github.com/luarocks/argparse", license = "MIT", aliases = { "argparse.new" } }),

                module("F", "F", "String interpolation inspired by Python f-strings.", [==[
`require "F"` returns a tagged string function.  Expressions inside `{}` are
evaluated and formatted.

```lua
local F = require "F"
print(F"1 + 2 = {1 + 2}")
```
]==], {
                }, { upstream = "https://github.com/dsidirop/f-strings", license = "MIT" }),

                module("csv", "csv (ftcsv)", "Fast CSV parser and writer.", [==[
`require "csv"` is the bundled `ftcsv` library.  It parses CSV strings and files
and encodes Lua tables as CSV.
]==], {
                    entry("csv.parse", "csv.parse(input [, delimiter [, options]])", "function",
                        "Parse CSV data.",
                        [[
Parse a CSV file or string and return an array of rows plus the final header list.

`input` is normally a filename. Set `options.loadFromString = true` to parse the string directly. The delimiter must be one character and defaults to `,`.

With the default `headers = true`, each row is a table keyed by the header row. Set `headers = false` to receive arrays. Other options include `rename` (map original headers to new names), `fieldsToKeep`, `headerFunc`, and `ignoreQuotes`.

```lua
local csv = require "csv"
local rows = csv.parse("a,b\n1,2\n", ",", { loadFromString = true })
print(rows[1].a, rows[1].b) --> 1 2
```
]]),
                    entry("csv.parseLine", "csv.parseLine(line [, delimiter [, options]])", "function",
                        "Parse a single CSV line.",
                        [[
Parse a CSV file incrementally and return an iterator over its rows.

Each iteration yields a 1-based row number and the parsed row (a table when `headers` is true, otherwise an array). The first result may include the header row depending on the options.

Options are the same as `csv.parse`, except that `loadFromString` is not supported and `bufferSize` may be set to control the read chunk size. A buffer that is too small for a row raises an error.

```lua
local csv = require "csv"
for i, row in csv.parseLine("data.csv") do
    print(i, row.name)
end
```
]]),
                    entry("csv.encode", "csv.encode(table [, delimiter [, options]])", "function",
                        "Encode a table as CSV.",
                        [[
Encode an array of row tables as a CSV string.

Headers are taken from the keys of the first row (sorted), or from `options.fieldsToKeep`. By default every field is quoted and rows end with `\r\n`. Options include `allowMissingKeys`, `onlyRequiredQuotes`, and `encodeNilAs`.

```lua
local csv = require "csv"
local text = csv.encode({ { name = "alice", age = 30 }, { name = "bob", age = 41 } })
print(text)
```
]]),
                }, { upstream = "https://github.com/FourierTransformer/ftcsv", license = "MIT" }),

                module("lpeg", "lpeg", "Parsing Expression Grammars for Lua.", [==[
LPeg provides pattern matching and parsing based on PEGs.  Patterns are combined
with arithmetic operators: `*` (sequence), `+` (choice), `-` (difference),
`^` (repetition), `#` (and predicate), `-p` (not predicate).  Captures use the
`C*` functions.

The complete LPeg manual is authoritative; this reference lists the public
constructors and capture helpers.
]==], {
                    entry("lpeg.match", "lpeg.match(pattern, subject [, init])", "function",
                        "Match a pattern against a string.",
                        [[
Match a pattern against a subject string.

Matching is anchored at `init`: the pattern must match a prefix of the subject starting there, not an arbitrary substring. `init` defaults to 1 and may be negative to count from the end.

On success the function returns the position just after the match, or all captured values when the pattern captures anything. On failure it returns `nil`. This is the function form of the `:match` pattern method.

```lua
local lpeg = require "lpeg"
print(lpeg.match(lpeg.P("abc"), "abcdef")) --> 4
print(lpeg.match(lpeg.C(lpeg.R("09")^1), "123x")) --> 123
```
]]),
                    entry("lpeg.P", "lpeg.P(value)", "function",
                        "Create a literal pattern or convert a value.",
                        [[
Convert a Lua value into an LPeg pattern.

Strings become literal matches, non-negative numbers match exactly that many characters, negative numbers succeed only when fewer than that many characters remain, and booleans always succeed or fail. A table is treated as a grammar, while a function becomes a match-time capture on the empty string. Existing patterns are returned unchanged.

```lua
local lpeg = require "lpeg"
print(lpeg.P("abc"):match("abcdef")) --> 4
print(lpeg.P(2):match("xy")) --> 3
print(lpeg.P(-1):match("")) --> 1
```
]]),
                    entry("lpeg.R", "lpeg.R(...)", "function",
                        "Create a pattern matching ranges of characters.",
                        [[
Create a pattern matching one character from one or more inclusive ranges.

Each argument is a two-character string such as `"09"` or `"az"`. The resulting pattern matches a single character whose code lies in any range. With no arguments it always fails. The `utfR` constructor handles Unicode code points.

```lua
local lpeg = require "lpeg"
local hex = lpeg.R("09", "af", "AF")^1
print(hex:match("BEEF")) --> 5
```
]]),
                    entry("lpeg.S", "lpeg.S(set)", "function",
                        "Create a pattern matching any character in a set.",
                        [[
Create a pattern matching any single character in a set.

The argument is the complete set as a string, so `S("+-*/")` accepts one arithmetic operator. An empty set always fails. For a one-character string, `S(c)` is equivalent to `P(c)`.

```lua
local lpeg = require "lpeg"
local op = lpeg.S("+-*/")
print(op:match("+")) --> 2
print(op:match("x")) --> nil
```
]]),
                    entry("lpeg.V", "lpeg.V(name)", "function",
                        "Reference a grammar rule.",
                        [[
Create a non-terminal reference for use inside a grammar.

The argument is the rule name or numeric index in the enclosing grammar table. References are resolved when that table is converted to a pattern with `lpeg.P`, which allows recursive grammars. A `V` reference used outside a grammar is an error.

```lua
local lpeg = require "lpeg"
local p = lpeg.P{ "(" * lpeg.V(1)^0 * ")" }
print(p:match("(())")) --> 5
```
]]),
                    entry("lpeg.B", "lpeg.B(pattern)", "function",
                        "Match a pattern behind the current position.",
                        [[
Create a behind predicate that checks text before the current position.

The pattern matches only when `pattern` matches immediately before the current position, and it never consumes input. The referenced pattern must have a fixed length and must not contain captures.

```lua
local lpeg = require "lpeg"
local p = lpeg.B("ab") * lpeg.P("cd")
print(p:match("abcd", 3)) --> 5
```
]]),
                    entry("lpeg.C", "lpeg.C(pattern)", "function",
                        "Capture the matched substring.",
                        [[
Create a simple capture around a pattern.

The capture value is the substring matched by `pattern`. If the inner pattern also captures values, those values follow the substring in the result. A failing pattern produces no capture.

```lua
local lpeg = require "lpeg"
local word = lpeg.C(lpeg.R("az")^1)
print(word:match("hello")) --> hello
```
]]),
                    entry("lpeg.Cc", "lpeg.Cc(...)", "function",
                        "Produce constant captures.",
                        [[
Create a constant capture that produces the given values.

The pattern matches the empty string and returns every argument unchanged. Constants are useful for tagging grammar results or providing fixed fields in table captures.

```lua
local lpeg = require "lpeg"
local tag = lpeg.Cc("number") * lpeg.C(lpeg.R("09")^1)
local kind, value = tag:match("42")
print(kind, value) --> number 42
```
]]),
                    entry("lpeg.Cmt", "lpeg.Cmt(pattern, function)", "function",
                        "Match-time capture.",
                        [[
Create a match-time capture.

`function` is called immediately as `function(subject, position, ...captures)`. Returning a number moves the match position to that number; returning `true` succeeds without consuming input; returning `false`, `nil` or nothing fails the match. Any additional return values become capture values.

Unlike ordinary captures, the function runs while matching and may depend on the subject.

```lua
local lpeg = require "lpeg"
local p = lpeg.Cmt(lpeg.P(1)^0, function(s, i)
    return i > #s, #s
end)
print(p:match("abc")) --> 3
```
]]),
                    entry("lpeg.Cb", "lpeg.Cb(name)", "function",
                        "Back-reference capture.",
                        [[
Create a back-reference capture.

It matches the empty string and returns the values produced by the most recent complete, outermost group capture with the given key. The key may be any non-nil Lua value. Named groups are created with `lpeg.Cg(pattern, name)`.

```lua
local lpeg = require "lpeg"
local p = lpeg.Cg(lpeg.Cc("tag"), "kind") * lpeg.Cb("kind")
print(p:match("")) --> tag
```
]]),
                    entry("lpeg.Carg", "lpeg.Carg(n)", "function",
                        "Capture an extra argument.",
                        [[
Create an argument capture.

It matches the empty string and returns the `n`-th extra argument passed to `lpeg.match` after the initial position. This lets a pattern read contextual values without globals.

```lua
local lpeg = require "lpeg"
print(lpeg.match(lpeg.Carg(1), "", 1, "context")) --> context
```
]]),
                    entry("lpeg.Cp", "lpeg.Cp()", "function",
                        "Capture the current position.",
                        [[
Create a position capture.

It matches the empty string and returns the current 1-based subject position as a number. Wrapping a pattern with two `Cp` captures is a convenient way to find both ends of a match.

```lua
local lpeg = require "lpeg"
local p = lpeg.Cp() * lpeg.P("ab") * lpeg.Cp()
print(p:match("xab")) --> nil
print(p:match("abx")) --> 1 3
```
]]),
                    entry("lpeg.Cs", "lpeg.Cs(pattern)", "function",
                        "Substitution capture.",
                        [[
Create a substitution capture.

The result is the substring matched by `pattern`, with the text of every inner capture replaced by that capture's value. Inner values must therefore be strings. Non-captured text is copied unchanged.

```lua
local lpeg = require "lpeg"
local p = lpeg.Cs((lpeg.R("az")^1 / string.upper) * lpeg.P(1)^0)
print(p:match("hello world")) --> HELLO world
```
]]),
                    entry("lpeg.Ct", "lpeg.Ct(pattern)", "function",
                        "Table capture.",
                        [[
Create a table capture.

Anonymous capture values are stored in successive integer keys, while named groups created with `lpeg.Cg` are stored under their names. The single result is the new table. Captures that produce no value are omitted.

```lua
local lpeg = require "lpeg"
local p = lpeg.Ct(lpeg.C(lpeg.R("az")^1) * lpeg.P("=") * lpeg.C(lpeg.R("09")^1))
local t = p:match("age=42")
print(t[1], t[2]) --> age 42
```
]]),
                    entry("lpeg.Cf", "lpeg.Cf(pattern, function)", "function",
                        "Fold capture.",
                        [[
Create a fold capture.

`function` receives the accumulated value followed by the values captured by `pattern`, and its first return value replaces the accumulator. This construction is deprecated in LPeg 1.1 in favour of the `%` accumulator capture, but remains available.

```lua
local lpeg = require "lpeg"
local number = lpeg.R("09")^1 / tonumber
local add = function(a, b) return a + b end
local sum = lpeg.Cf(number * ("," * number)^0, add)
print(sum:match("10,30,43")) --> 83
```
]]),
                    entry("lpeg.Cg", "lpeg.Cg(pattern [, name])", "function",
                        "Group capture.",
                        [[
Group the captures produced by a pattern into one capture.

Without a name the values are joined into a single capture. With a name the group is also stored under that key by an enclosing `lpeg.Ct`, and can be retrieved later with `lpeg.Cb`. A named group usually produces no value by itself.

```lua
local lpeg = require "lpeg"
local p = lpeg.Ct(lpeg.Cg(lpeg.C(lpeg.R("az")^1), "name"))
local t = p:match("lua")
print(t.name) --> lua
```
]]),
                    entry("lpeg.type", "lpeg.type(value)", "function",
                        "Return the LPeg type of a value.",
                        [[
Return the LPeg type name for a value.

Patterns return the string `"pattern"`. Every other Lua value returns `nil`. This is useful for APIs that accept either a pattern or a value that can be converted with `lpeg.P`.

```lua
local lpeg = require "lpeg"
print(lpeg.type(lpeg.P("x"))) --> pattern
print(lpeg.type("x")) --> nil
```
]]),
                    entry("lpeg.version", "lpeg.version", "field",
                        "The running LPeg version string.",
                        [[
The running LPeg version as a string such as `"LPeg 1.1.0"`.

This field is a string, not a callable function. Read it directly when reporting diagnostics or checking for features.

```lua
local lpeg = require "lpeg"
print(lpeg.version) --> LPeg 1.1.0
```
]]),
                    entry("lpeg.setmaxstack", "lpeg.setmaxstack(size)", "function",
                        "Set the maximum backtracking stack size.",
                        [[
Set the maximum size of LPeg's backtracking stack.

The default limit is 400 entries. Deeply recursive grammars or heavily backtracking patterns may need a larger value; well-written patterns usually do not. The function returns nothing.

```lua
local lpeg = require "lpeg"
lpeg.setmaxstack(1000)
```
]]),
                    entry("lpeg.locale", "lpeg.locale([table])", "function",
                        "Create locale-aware patterns.",
                        [[
Create a table of locale-aware character-class patterns.

The fields are `alnum`, `alpha`, `cntrl`, `digit`, `graph`, `lower`, `print`, `punct`, `space`, `upper` and `xdigit`, each matching one character in that class. When a table is supplied, the fields are added to it and the same table is returned; calling `lpeg.locale(lpeg)` therefore adds `lpeg.alpha`, `lpeg.digit` and the others directly to the module.

```lua
local lpeg = require "lpeg"
lpeg.locale(lpeg)
local word = lpeg.alpha^1
print(word:match("hello")) --> 6
```
]]),
                    entry("lpeg.utfR", "lpeg.utfR(...)", "function",
                        "Create UTF-8 aware range patterns.",
                        [[
Create a pattern matching one UTF-8 encoded code point in a range.

`cp1` and `cp2` are numeric code points with inclusive bounds. The pattern validates the UTF-8 byte sequence as well as the code-point range. The Unicode maximum is 0x10FFFF; surrogate code points are allowed by the range check.

```lua
local lpeg = require "lpeg"
local ascii_printable = lpeg.utfR(0x20, 0x7E)^1
print(ascii_printable:match("hello")) --> 6
```
]]),
                }, { upstream = "https://www.inf.puc-rio.br/~roberto/lpeg/", license = "MIT" }),

                module("re", "re", "Regular expressions built on LPeg.", [==[
`re` implements a regular-expression syntax on top of LPeg.  Patterns can be
matched, searched, substituted and used in grammars.
]==], {
                    entry("re.match", "re.match(subject, pattern [, init])", "function",
                        "Match a pattern against a string.",
                        [[
Match a regular-expression pattern against a subject.

The pattern may be a string or an already compiled LPeg pattern. `init` optionally selects the starting position. The result is the sequence of captures produced by the pattern; if the pattern captures nothing, it is the position after the match. A failed match returns `nil`.

```lua
local re = require "re"
print(re.match("the number 423 is odd", "({%a+} / .)*"))
--> the number is odd
```
]]),
                    entry("re.find", "re.find(subject, pattern [, init])", "function",
                        "Find the first match.",
                        [[
Search for the first occurrence of a pattern in a subject.

Returns the 1-based index where the match starts and the index where it ends, inclusive. Both values are `nil` when no match exists. The optional `init` gives a starting position, with negative values counted from the end.

```lua
local re = require "re"
local first, last = re.find("the number 423 is odd", "[0-9]+")
print(first, last) --> 12 14
```
]]),
                    entry("re.updatelocale", "re.updatelocale()", "function",
                        "Refresh the locale-dependent character classes.",
                        [[
Re-read the current C locale and update the predefined character classes used by `%a`, `%c`, `%d`, `%g`, `%l`, `%p`, `%s`, `%u`, `%w` and `%x` (and their uppercase complements).

Call this after changing the process locale. The function returns nothing and does not affect already compiled patterns.

```lua
local re = require "re"
re.updatelocale()
```
]]),
                    entry("re.gsub", "re.gsub(subject, pattern, replacement)", "function",
                        "Replace matches.",
                        [[
Replace every occurrence of a pattern in a subject.

`replacement` follows LPeg capture rules, so it may be a string with `%1`-style references, a function, a table, or a number selecting a capture. The whole subject is returned with all matches replaced.

```lua
local re = require "re"
print(re.gsub("hello World", "[aeiou]", "."))
--> h.ll. W.rld
```
]]),
                    entry("re.compile", "re.compile(pattern [, defs])", "function",
                        "Compile a pattern.",
                        [[
Compile a regular-expression string into an LPeg pattern.

The optional `defs` table supplies Lua values for named definitions used by the expression. If the argument is already an LPeg pattern it is returned unchanged. Invalid syntax raises an error containing `incorrect pattern`.

```lua
local re = require "re"
local number = re.compile("%d+")
print(number:match("123")) --> 4
```
]]),
                }, { upstream = "https://www.inf.puc-rio.br/~roberto/lpeg/re.html", license = "MIT" }),

                module("cjson", "cjson", "Fast JSON encoding and decoding.", [==[
`cjson.encode(value)` and `cjson.decode(string)` are the common entry points.
The module also exposes configuration functions for number precision, invalid
numbers, sparse arrays, maximum depth and indentation.
]==], {
                    entry("cjson.encode", "cjson.encode(value)", "function",
                        "Encode a Lua value as JSON.",
                        [[
Serialise a Lua value as a JSON string.

Booleans, numbers, strings, `nil` and tables are supported. Tables with only consecutive positive integer keys become JSON arrays; other tables become objects with string keys. Unsupported values such as functions, threads and non-null userdata raise an error unless the skip option is enabled.

Encoding is controlled by the module configuration functions, including maximum depth, number precision, sparse-array handling and invalid numbers.

```lua
local cjson = require "cjson"
print(cjson.encode({ true, { foo = "bar" } }))
--> [true,{"foo":"bar"}]
```
]]),
                    entry("cjson.decode", "cjson.decode(string)", "function",
                        "Decode a JSON string.",
                        [[
Deserialise a JSON string into a Lua value.

Objects become tables, arrays become integer-keyed tables, and JSON `null` becomes the light userdata value `cjson.null`. Numeric object keys are converted to strings. Invalid numbers are accepted by default; see `decode_invalid_numbers`.

Syntax errors raise a Lua error rather than returning `nil`.

```lua
local cjson = require "cjson"
local value = cjson.decode('[true,{"n":1}]')
print(value[1], value[2].n) --> true 1
print(cjson.decode("null") == cjson.null) --> true
```
]]),
                    entry("cjson.new", "cjson.new()", "function",
                        "Create a separate cjson instance.",
                        [[
Create an independent cjson instance.

The new module has its own configuration and encoding buffer, so changing one instance does not affect another. This is useful for threads or for keeping a strict encoder separate from a permissive one.

```lua
local cjson = require "cjson"
local pretty = cjson.new()
pretty.encode_indent("  ")
print(pretty.encode({ a = 1 }))
```
]]),
                    entry("cjson.encode_empty_table_as_object", "cjson.encode_empty_table_as_object(boolean)", "function",
                        "Control empty-table encoding.",
                        [[
Control how empty Lua tables are encoded.

With `true` (the default) an empty table becomes `{}`. With `false` it becomes `[]`. Tables carrying `cjson.empty_array_mt` or `cjson.array_mt` are always arrays. The function returns the current setting and changes it only when an argument is supplied.

```lua
local cjson = require "cjson"
cjson.encode_empty_table_as_object(false)
print(cjson.encode({})) --> []
```
]]),
                    entry("cjson.decode_array_with_array_mt", "cjson.decode_array_with_array_mt(boolean)", "function",
                        "Control array metatables.",
                        [[
Control whether decoded JSON arrays carry `cjson.array_mt`.

The default is `false`. When enabled, arrays produced by `decode` get the array metatable, which lets a later `encode` preserve the array type even for empty arrays.

The function returns the current setting and only changes it when given an argument.

```lua
local cjson = require "cjson"
cjson.decode_array_with_array_mt(true)
local value = cjson.decode("[]")
print(getmetatable(value) == cjson.array_mt) --> true
```
]]),
                    entry("cjson.decode_allow_comment", "cjson.decode_allow_comment(boolean)", "function",
                        "Allow comments while decoding.",
                        [[
Allow `//` and `/* ... */` comments while decoding.

Comments are disabled by default. When enabled they may appear wherever whitespace is allowed. Unterminated block comments still produce a decode error.

Returns the current setting; the value changes only when an argument is provided.

```lua
local cjson = require "cjson"
cjson.decode_allow_comment(true)
print(cjson.decode('{ // note\n "a": 1 }').a) --> 1
```
]]),
                    entry("cjson.encode_sparse_array", "cjson.encode_sparse_array(convert, ratio, safe)", "function",
                        "Configure sparse-array handling.",
                        [[
Configure how sparse Lua arrays are encoded.

`convert` controls whether an excessively sparse array becomes a JSON object instead of raising an error. `ratio` and `safe` determine the threshold: an array is excessively sparse when its maximum index exceeds both `safe` and `item_count * ratio`. Defaults are `false`, `2` and `10`.

All three current settings are returned. Missing arguments leave the corresponding setting unchanged.

```lua
local cjson = require "cjson"
cjson.encode_sparse_array(true)
print(cjson.encode({ [1000] = "x" }))
--> {"1000":"x"}
```
]]),
                    entry("cjson.encode_max_depth", "cjson.encode_max_depth(depth)", "function",
                        "Set the maximum encode depth.",
                        [[
Set the maximum nesting depth accepted by `encode`.

The default is 1000. Exceeding the limit raises an error, preventing recursive or extremely deep tables from exhausting the stack. The value must be a positive integer.

Returns the current setting; it changes only when an argument is supplied.

```lua
local cjson = require "cjson"
local depth = cjson.encode_max_depth(50)
print(depth) --> 50
```
]]),
                    entry("cjson.decode_max_depth", "cjson.decode_max_depth(depth)", "function",
                        "Set the maximum decode depth.",
                        [[
Set the maximum nesting depth accepted by `decode`.

The default is 1000. Deeper JSON arrays or objects are rejected with an error. This limits stack use on hostile input. The value must be a positive integer.

Returns the current setting; it changes only when an argument is supplied.

```lua
local cjson = require "cjson"
print(cjson.decode_max_depth(200)) --> 200
```
]]),
                    entry("cjson.encode_number_precision", "cjson.encode_number_precision(precision)", "function",
                        "Set number precision.",
                        [[
Set the number of significant digits used when encoding numbers.

The default is 14 and the accepted range is 1 to 16. Lower values trade accuracy for speed when serialising large amounts of numeric data. Returns the current setting.

```lua
local cjson = require "cjson"
cjson.encode_number_precision(6)
print(cjson.encode({ math.pi })) --> [3.14159]
```
]]),
                    entry("cjson.encode_keep_buffer", "cjson.encode_keep_buffer(boolean)", "function",
                        "Keep the encode buffer between calls.",
                        [[
Control whether the encoder keeps its reusable buffer between calls.

Keeping the buffer (the default) avoids repeated allocations and is fastest. Disabling it frees the buffer after every `encode` call, which is useful when the buffer would otherwise retain a large peak allocation.

Returns the current setting; the value changes only when an argument is provided.

```lua
local cjson = require "cjson"
cjson.encode_keep_buffer(false)
local keep = cjson.encode_keep_buffer()
print(keep) --> false
```
]]),
                    entry("cjson.encode_invalid_numbers", "cjson.encode_invalid_numbers(boolean)", "function",
                        "Control encoding of NaN and infinity.",
                        [[
Control how NaN and infinity are encoded.

`false` (the default) raises an error. `true` writes the non-standard tokens `NaN` and `Infinity`. The string `"null"` writes JSON `null`, keeping the output standards-compliant. Returns the current setting in the same form.

```lua
local cjson = require "cjson"
cjson.encode_invalid_numbers("null")
print(cjson.encode({ 0 / 0 })) --> [null]
```
]]),
                    entry("cjson.decode_invalid_numbers", "cjson.decode_invalid_numbers(boolean)", "function",
                        "Control decoding of NaN and infinity.",
                        [[
Control whether non-standard numeric tokens are accepted while decoding.

The default is `true`, so NaN, infinity and hexadecimal numbers are decoded. Set it to `false` to reject them. The current setting is returned and changes only when an argument is supplied.

```lua
local cjson = require "cjson"
cjson.decode_invalid_numbers(false)
local ok = pcall(cjson.decode, "NaN")
print(ok) --> false
```
]]),
                    entry("cjson.encode_escape_forward_slash", "cjson.encode_escape_forward_slash(boolean)", "function",
                        "Escape forward slashes.",
                        [[
Control whether `/` is escaped as `\/` in encoded strings.

Escaping is enabled by default in this build. Disabling it produces shorter, still valid JSON. Returns the current setting.

```lua
local cjson = require "cjson"
cjson.encode_escape_forward_slash(false)
print(cjson.encode({ "a/b" })) --> ["a/b"]
```
]]),
                    entry("cjson.encode_skip_unsupported_value_types", "cjson.encode_skip_unsupported_value_types(boolean)", "function",
                        "Skip unsupported values.",
                        [[
Control what happens when encoding unsupported Lua types.

The default is `false`: functions, threads and userdata raise an error. When enabled, values that cannot be represented are omitted instead of aborting the whole encode operation. Returns the current setting.

```lua
local cjson = require "cjson"
cjson.encode_skip_unsupported_value_types(true)
print(cjson.encode({ 1, print, 2 })) --> [1,2]
```
]]),
                    entry("cjson.encode_indent", "cjson.encode_indent(value)", "function",
                        "Pretty-print JSON with indentation.",
                        [[
Set the indentation used for pretty-printed JSON.

Pass a string such as `"  "` or `"\t"`. The empty string disables indentation. Returns the current indent, or `""` when pretty-printing is off. Arrays and objects gain newlines and the requested indentation.

```lua
local cjson = require "cjson"
cjson.encode_indent("  ")
print(cjson.encode({ a = 1 }))
--> {
-->   "a": 1
--> }
```
]]),
                }, { upstream = "https://github.com/openresty/lua-cjson", license = "MIT" }),

                module("sqlite3", "sqlite3", "LuaSQLite3 binding.", [==[
The `sqlite3` module provides database, statement and result objects.  The most
common entry points are `sqlite3.open`, `db:exec`, `db:prepare`, `stmt:bind` and
the row iterators `db:nrows`, `db:rows` and `db:urows`.
]==], {
                    entry("sqlite3.open", "sqlite3.open(filename [, flags])", "function",
                        "Open a database file.",
                        [[
Open an existing SQLite database or create it when it does not exist, and return a database handle.

The optional `flags` argument is passed to `sqlite3_open_v2`; it defaults to `sqlite3.OPEN_READWRITE + sqlite3.OPEN_CREATE`. Constants such as `OPEN_READONLY`, `OPEN_SHAREDCACHE` and `OPEN_NOMUTEX` are available on the module.

On failure it returns `nil, error_code, error_message` rather than raising.

```lua
local sqlite3 = require "sqlite3"
local db = assert(sqlite3.open("app.sqlite3"))
db:exec("create table if not exists notes (body text)")
db:close()
```
]]),
                    entry("sqlite3.open_memory", "sqlite3.open_memory()", "function",
                        "Open an in-memory database.",
                        [[
Open a private in-memory SQLite database and return its handle. The database disappears when the handle is closed or garbage-collected.

On failure it returns `nil, error_code, error_message`. This is convenient for tests and temporary caches.

```lua
local sqlite3 = require "sqlite3"
local db = assert(sqlite3.open_memory())
db:exec("create table t (n integer)")
```
]]),
                    entry("sqlite3.open_ptr", "sqlite3.open_ptr(pointer)", "function",
                        "Open a database from a raw pointer.",
                        [[
Wrap an existing raw `sqlite3 *` pointer, passed as light userdata, in a Lua database handle.

The pointer is validated with a lightweight SQLite call; an invalid pointer raises an argument error. Use `db:get_ptr()` on another handle to obtain a compatible pointer when moving a database between Lua states.

```lua
local db = assert(sqlite3.open("app.sqlite3"))
local ptr = db:get_ptr()
local same = sqlite3.open_ptr(ptr)
```
]]),
                    entry("sqlite3.version", "sqlite3.version()", "function",
                        "Return the SQLite version.",
                        [[
Return the version string of the SQLite library that is linked into the interpreter, for example `"3.45.1"`.

The result comes from `sqlite3_libversion` and does not allocate or raise.
]]),
                    entry("sqlite3.lversion", "sqlite3.lversion()", "function",
                        "Return the LuaSQLite3 version.",
                        [[
Return the version of the bundled LuaSQLite3 binding, such as `"0.9.6"`.

This identifies the Lua wrapper, not the underlying SQLite engine; use `sqlite3.version()` for the engine version.
]]),
                    entry("sqlite3.complete", "sqlite3.complete(sql)", "function",
                        "Return true when a SQL string is complete.",
                        [[
Return true when `sql` contains one or more complete SQL statements, and false when another statement terminator is still needed.

The check uses SQLite's own parser and is useful for interactive input buffering.

```lua
local sqlite3 = require "sqlite3"
print(sqlite3.complete("select 1;")) --> true
print(sqlite3.complete("select 1"))  --> false
```
]]),
                    entry("sqlite3.temp_directory", "sqlite3.temp_directory([path])", "function",
                        "Get or set the temporary directory.",
                        [[
Get or set the directory SQLite uses for temporary files.

With no argument it returns the current directory string (possibly `nil`). With a string it sets the directory and returns the previous value; passing `nil` explicitly clears the setting. The setter is unavailable on Windows in this binding.

```lua
local sqlite3 = require "sqlite3"
sqlite3.temp_directory("/tmp")
```
]]),
                    entry("sqlite3.backup_init", "sqlite3.backup_init(target_db, target_name, source_db, source_name)", "function",
                        "Create an online backup object.",
                        [[
Start an online backup from a source database to a destination database and return a backup object.

The databases are passed as open handles, together with the source and destination database names (`"main"`, `"temp"`, or an attached name). Source and target must be different. On failure the function returns `nil`; details are stored on the destination handle and are available through `db:errcode()` and `db:errmsg()`.

```lua
local dst = assert(sqlite3.open("copy.sqlite3"))
local backup = sqlite3.backup_init(dst, "main", src, "main")
backup:step(-1)
backup:finish()
```
]]),
                    entry("sqlite3.db:exec", "db:exec(sql)", "method",
                        "Execute SQL statements.",
                        [[
Compile and execute one or more SQL statements. The alias `db:execute` behaves identically.

The function returns `sqlite3.OK` on success or a numeric SQLite error code. If a row callback is supplied, it is called as `func(udata, column_count, values, names)` for every result row. Returning `0` continues; returning a non-zero value aborts the remaining statements and makes `exec` return `sqlite3.ABORT`.

```lua
local db = assert(require("sqlite3").open_memory())
db:exec("create table t (n integer); insert into t values (1), (2)")
db:exec("select n from t", function(_, _, values)
    print(values[1])
    return 0
end)
```
]]),
                    entry("sqlite3.db:execute", "db:execute(sql)", "method",
                        "Alias for `db:exec`.",
                        [[
Alias for `db:exec`. It compiles and runs all statements in the SQL string and returns `sqlite3.OK` or an error code.

The optional row callback and userdata argument have the same behavior as in `db:exec`.
]]),
                    entry("sqlite3.db:prepare", "db:prepare(sql)", "method",
                        "Prepare a SQL statement.",
                        [[
Compile a single SQL statement and return a prepared statement object.

Use `stmt:bind*` to supply parameters, `stmt:step()` to execute or fetch rows, and `stmt:finalize()` when finished. The statement keeps a reference to the database, so finalize it before closing the database.

A preparation error is raised as a Lua error with the SQLite message.

```lua
local db = assert(require("sqlite3").open_memory())
db:exec("create table t (n integer)")
local stmt = db:prepare("insert into t values (?)")
stmt:bind_values(42)
stmt:step()
stmt:finalize()
```
]]),
                    entry("sqlite3.db:rows", "db:rows(sql [, parameters])", "method",
                        "Iterate result rows as arrays.",
                        [[
Return an iterator over the result rows as packed arrays. Index `1` is the first selected column.

Optional parameters may be supplied as individual values matching the statement's placeholders, or as one table whose numeric or named fields provide them. Preparation and binding errors are raised as Lua errors.

```lua
for row in db:rows("select n, n * 2 from t where n > ?", 1) do
    print(row[1], row[2])
end
```
]]),
                    entry("sqlite3.db:nrows", "db:nrows(sql [, parameters])", "method",
                        "Iterate result rows as name/value tables.",
                        [[
Return an iterator over the result rows as tables keyed by column name.

Parameters are supplied in the same way as for `db:rows`: either positional values or a single table. Duplicate column names overwrite earlier values in the resulting table.

```lua
for row in db:nrows("select n as number from t") do
    print(row.number)
end
```
]]),
                    entry("sqlite3.db:urows", "db:urows(sql [, parameters])", "method",
                        "Iterate a single-column result.",
                        [[
Return an iterator that unpacks each result row into separate values.

For a query selecting three columns, the loop variables receive those three values directly. Parameters use the same positional-or-table convention as the other row iterators.

```lua
for n, doubled in db:urows("select n, n * 2 from t") do
    print(n, doubled)
end
```
]]),
                    entry("sqlite3.db:close", "db:close()", "method",
                        "Close the database.",
                        [[
Close the database handle and release its resources.

All prepared statements should be finalized first. Returns `sqlite3.OK` on success or a numeric SQLite error code. Calling `close` on an already closed handle raises an argument error, so close each handle only once.

```lua
local db = assert(require("sqlite3").open_memory())
print(db:close()) --> 0 (sqlite3.OK)
```
]]),
                    entry("sqlite3.db:isopen", "db:isopen()", "method",
                        "Return true when the database is open.",
                        [[
Return true while the database handle is open and false after `db:close()`.

The check does not touch the database file.
]]),
                    entry("sqlite3.db:changes", "db:changes()", "method",
                        "Return the number of changed rows.",
                        [[
Return the number of rows changed, inserted or deleted by the most recent `INSERT`, `UPDATE` or `DELETE` statement.

Changes performed indirectly by triggers are not counted. Use `db:total_changes()` for the cumulative count.

```lua
db:exec("update t set n = n + 1")
print(db:changes())
```
]]),
                    entry("sqlite3.db:total_changes", "db:total_changes()", "method",
                        "Return total changed rows.",
                        [[
Return the total number of rows modified by `INSERT`, `UPDATE` or `DELETE` since the database was opened.

Unlike `db:changes()`, this includes changes made by trigger programs and accumulates across statements.
]]),
                    entry("sqlite3.db:last_insert_rowid", "db:last_insert_rowid()", "method",
                        "Return the last inserted row id.",
                        [[
Return the rowid of the most recent successful insert on this database.

If no insert has occurred, the result is `0`. Inside a trigger, the value refers to the row inserted by the trigger until the trigger finishes.
]]),
                    entry("sqlite3.db:errcode", "db:errcode()", "method",
                        "Return the last error code.",
                        [[
Return the numeric result code or extended result code of the most recent failed operation on this database.

Use `db:errmsg()` for the accompanying human-readable message. Successful operations do not necessarily reset the stored code.
]]),
                    entry("sqlite3.db:errmsg", "db:errmsg()", "method",
                        "Return the last error message.",
                        [[
Return the error message associated with the most recent failed operation on this database.

The message comes from SQLite and may include constraint or I/O details. The alias `db:error_message` is also available.
]]),
                    entry("sqlite3.db:busy_timeout", "db:busy_timeout(timeout)", "method",
                        "Set the busy timeout.",
                        [[
Set a busy timeout in milliseconds, so SQLite waits for locks instead of immediately returning `sqlite3.BUSY`.

A value less than or equal to zero disables the timeout and removes any handler installed with `db:busy_handler`. Returns a numeric result code.

```lua
db:busy_timeout(5000) -- wait up to five seconds
```
]]),
                    entry("sqlite3.db:interrupt", "db:interrupt()", "method",
                        "Interrupt the current operation.",
                        [[
Request cancellation of any pending operation on this database.

SQLite checks the flag at its next opportunity and aborts the operation, which normally surfaces as `sqlite3.INTERRUPT`. The function returns nothing and is safe to call when no operation is running.
]]),
                    entry("sqlite3.db:create_function", "db:create_function(name, nargs, func [, userdata])", "method",
                        "Register a scalar SQL function.",
                        [[
Register a scalar SQL function implemented in Lua.

`name` is the SQL name, `nargs` is the exact argument count (`-1` accepts any number), and `func` receives a callback context followed by the SQL arguments. Call `context:result_*` to return a value. An optional `userdata` argument is available through `context:user_data()`.

```lua
db:create_function("double", 1, function(ctx, n)
    ctx:result_int(n * 2)
end)
```
]]),
                    entry("sqlite3.db:create_aggregate", "db:create_aggregate(name, nargs, step, final [, userdata])", "method",
                        "Register an aggregate SQL function.",
                        [[
Register an aggregate SQL function. `step` is called once per input row and `final` once at the end.

Both callbacks receive a function context; use `context:set_aggregate_data()` and `context:get_aggregate_data()` to carry state between rows, and `context:result_*` in `final` to produce the result. An optional userdata value is exposed by `context:user_data()`.

```lua
db:create_aggregate("total", 1, function(ctx, n)
    ctx:set_aggregate_data((ctx:get_aggregate_data() or 0) + n)
end, function(ctx)
    ctx:result_int(ctx:get_aggregate_data() or 0)
end)
```
]]),
                    entry("sqlite3.db:create_collation", "db:create_collation(name, func)", "method",
                        "Register a collation.",
                        [[
Register a collation function used by SQLite for ordering and comparisons.

`func(a, b)` must return `0` when the strings compare equal, `-1` when `a` sorts before `b`, and `1` when `a` sorts after `b`. The collation name can then be used in column definitions and `ORDER BY ... COLLATE name` clauses.

```lua
db:create_collation("nocase", function(a, b)
    a, b = a:lower(), b:lower()
    return a == b and 0 or (a < b and -1 or 1)
end)
```
]]),
                    entry("sqlite3.db:trace", "db:trace(func [, userdata])", "method",
                        "Install a trace callback.",
                        [[
Install a trace callback that runs just before each SQL statement is evaluated.

The callback receives the optional userdata value followed by the SQL text. Call `db:trace(nil)` to remove the callback.

```lua
db:trace(function(_, sql) print("SQL:", sql) end)
```
]]),
                    entry("sqlite3.db:progress_handler", "db:progress_handler(n, func [, userdata])", "method",
                        "Install a progress handler.",
                        [[
Install a callback that SQLite invokes periodically during long-running `exec` or `step` calls.

The callback runs once every `n` virtual-machine operations and receives the optional userdata argument. Returning a non-zero value aborts the current query, rolls back its changes, and makes the operation return `sqlite3.INTERRUPT`. Pass `nil` as the callback to remove it.

```lua
db:progress_handler(1000, function() return 0 end)
```
]]),
                    entry("sqlite3.db:update_hook", "db:update_hook(func [, userdata])", "method",
                        "Install an update hook.",
                        [[
Install a data-change notification callback.

The callback receives optional userdata, the operation constant (`sqlite3.INSERT`, `sqlite3.UPDATE` or `sqlite3.DELETE`), the database name, the table name, and the affected rowid. Pass `nil` to remove the hook.
]]),
                    entry("sqlite3.db:commit_hook", "db:commit_hook(func [, userdata])", "method",
                        "Install a commit hook.",
                        [[
Install a callback invoked whenever a transaction is about to commit.

The callback receives the optional userdata argument. Returning `false` or `nil` allows the commit; returning any other value converts it into a rollback. Pass `nil` to remove the hook.
]]),
                    entry("sqlite3.db:rollback_hook", "db:rollback_hook(func [, userdata])", "method",
                        "Install a rollback hook.",
                        [[
Install a callback invoked whenever a transaction is rolled back.

The callback receives the optional userdata argument. Pass `nil` to remove the hook.
]]),
                    entry("sqlite3.stmt:step", "stmt:step()", "method",
                        "Advance a prepared statement.",
                        [[
Advance a prepared statement to its next result.

Returns `sqlite3.ROW` when a row is available, `sqlite3.DONE` when execution has finished, or an error code such as `sqlite3.BUSY`, `sqlite3.ERROR` or `sqlite3.MISUSE`. After `DONE` or an error, call `stmt:reset()` before executing the statement again.

```lua
local rc = stmt:step()
if rc == sqlite3.ROW then
    print(stmt:get_values()[1])
end
```
]]),
                    entry("sqlite3.stmt:reset", "stmt:reset()", "method",
                        "Reset a prepared statement.",
                        [[
Reset a prepared statement so it can be executed again.

Existing parameter bindings are retained. The function returns the current SQLite error code for the statement, usually `sqlite3.OK`.

```lua
stmt:reset()
stmt:step()
```
]]),
                    entry("sqlite3.stmt:finalize", "stmt:finalize()", "method",
                        "Finalize a prepared statement.",
                        [[
Free a prepared statement and all resources associated with it.

Returns `sqlite3.OK` when the statement was never executed or completed successfully, otherwise the last execution error code. The statement must not be used after finalization.
]]),
                    entry("sqlite3.stmt:bind", "stmt:bind(index, value)", "method",
                        "Bind a value to a parameter.",
                        [[
Bind a Lua value to parameter `index`, where statement parameters are numbered from 1.

Strings bind as text, integers as SQLite integers, other numbers as doubles, booleans as `0`/`1`, and `nil` removes any previous binding. Unsupported types raise an error. Returns `sqlite3.OK` or an error code.

```lua
stmt:bind(1, "hello")
stmt:bind(2, 42)
```
]]),
                    entry("sqlite3.stmt:bind_values", "stmt:bind_values(...)", "method",
                        "Bind positional parameters.",
                        [[
Bind one value to each statement parameter, in order from 1 to `bind_parameter_count()`.

The number of values must exactly match the parameter count, otherwise an error is raised. Returns `sqlite3.OK` or the first binding error code.

```lua
stmt:bind_values("alice", 30)
```
]]),
                    entry("sqlite3.stmt:bind_names", "stmt:bind_names(table)", "method",
                        "Bind named parameters.",
                        [[
Bind parameters from a table.

Named placeholders of the form `:name` or `$name` are looked up by the name without the leading marker. Unnamed parameters use numeric keys `1..n`. Returns `sqlite3.OK` or an error code.

```lua
stmt = db:prepare("insert into t values (:name, :age)")
stmt:bind_names { name = "alice", age = 30 }
```
]]),
                    entry("sqlite3.stmt:columns", "stmt:columns()", "method",
                        "Return result column names.",
                        [[
Return the number of columns in the statement's result set.

The value is `0` for statements that do not return rows, such as `INSERT` or `UPDATE`.
]]),
                    entry("sqlite3.stmt:get_value", "stmt:get_value(index)", "method",
                        "Return a result value.",
                        [[
Return the value of result column `index`. Column indexes start at 0.

The statement must currently be positioned on a row (`stmt:step()` returned `sqlite3.ROW`); otherwise a misuse error is raised.
]]),
                    entry("sqlite3.stmt:get_values", "stmt:get_values()", "method",
                        "Return all result values.",
                        [[
Return the current row as an array, with column `0` stored at index 1.

The statement must be positioned on a result row. Column values are converted to Lua strings, numbers, booleans or `nil` according to SQLite's types.
]]),
                    entry("sqlite3.stmt:get_type", "stmt:get_type(index)", "method",
                        "Return a result value type.",
                        [[
Return the declared SQL type of result column `index`, using a 0-based column index.

The result is the type written in the schema or query (`"INTEGER"`, `"TEXT"`, and so on), or `nil` when the column has no declared type. It is not the runtime storage class of the current value.
]]),
                    entry("sqlite3.stmt:get_types", "stmt:get_types()", "method",
                        "Return all result value types.",
                        [[
Return an array of declared SQL types for all result columns.

Index 1 describes column 0, and so on. Columns without a declared type yield `nil` entries.
]]),
                    entry("sqlite3.stmt:get_uvalue", "stmt:get_uvalue(index)", "method",
                        "Return an uncoerced result value.",
                        [[
Return a single result value without packing it into a table.

This bundled LuaSQLite3 build does not expose a singular `get_uvalue` method; use `stmt:get_values()` for an array or `stmt:get_uvalues()` for multiple return values. The entry is kept as a compatibility reference.
]]),
                    entry("sqlite3.stmt:get_uvalues", "stmt:get_uvalues()", "method",
                        "Return all uncoerced result values.",
                        [[
Return all values of the current row as multiple Lua return values.

For a three-column query, `local a, b, c = stmt:get_uvalues()` receives the three columns directly. The statement must be positioned on a result row.
]]),
                    entry("sqlite3.stmt:get_utype", "stmt:get_utype(index)", "method",
                        "Return an uncoerced result type.",
                        [[
Return a single declared column type without packing it into a table.

This bundled build does not expose a singular `get_utype` method; use `stmt:get_types()` for an array or `stmt:get_utypes()` for multiple return values. The entry is kept as a compatibility reference.
]]),
                    entry("sqlite3.stmt:get_utypes", "stmt:get_utypes()", "method",
                        "Return all uncoerced result types.",
                        [[
Return the declared types of all result columns as multiple Lua return values.

Columns without a declared type produce `nil` in the corresponding position.
]]),
                    entry("sqlite3.stmt:get_name", "stmt:get_name(index)", "method",
                        "Return a column name.",
                        [[
Return the name of result column `index`, using a 0-based column index.

The name is the column alias if one was specified, otherwise the column or expression name chosen by SQLite.
]]),
                    entry("sqlite3.stmt:get_names", "stmt:get_names()", "method",
                        "Return all column names.",
                        [[
Return an array containing the names of all result columns.

Index 1 corresponds to column 0. Names are taken from aliases when present.
]]),
                    entry("sqlite3.stmt:get_named_values", "stmt:get_named_values()", "method",
                        "Return results as a name/value table.",
                        [[
Return the current result row as a table keyed by column name.

The statement must be positioned on a row. Duplicate column names overwrite earlier values.

```lua
stmt:step()
local row = stmt:get_named_values()
print(row.name)
```
]]),
                    entry("sqlite3.stmt:get_named_types", "stmt:get_named_types()", "method",
                        "Return result types as a name/value table.",
                        [[
Return a table mapping each result column name to its declared SQL type.

Duplicate names overwrite earlier entries. Columns without a declared type map to `nil`.
]]),
                    entry("sqlite3.stmt:bind_parameter_count", "stmt:bind_parameter_count()", "method",
                        "Return the number of parameters.",
                        [[
Return the number of distinct parameters in the prepared statement.

Repeated named parameters count once, while gaps in `?NNN` numbering are reflected in the largest index returned.
]]),
                    entry("sqlite3.stmt:bind_parameter_name", "stmt:bind_parameter_name(index)", "method",
                        "Return a parameter name.",
                        [[
Return the name of parameter `index`, including its leading `:`, `$` or `@` marker.

The index is 1-based. An unnamed `?` or `?NNN` parameter yields `nil`; an out-of-range index raises an error.
]]),
                    entry("sqlite3.stmt:bind_blob", "stmt:bind_blob(index, data)", "method",
                        "Bind a blob value.",
                        [[
Bind a Lua string as a BLOB value to parameter `index`.

The entire string, including embedded NUL bytes, is copied into SQLite. The binding uses transient storage, so the Lua string may be collected after the call. Returns `sqlite3.OK` or an error code.

```lua
stmt:bind_blob(1, "\0\1\2binary")
```
]]),
                }, { upstream = "http://lua.sqlite.org/", license = "MIT" }),

                module("luaunit", "luaunit", "Unit-testing framework for Lua.", [==[
LuaUnit discovers global tables whose names begin with `Test` and functions whose
names begin with `test`.  Assertions are exported as `assert*` functions.

`luaunit.run()` runs the registered tests and returns the number of failures.
]==], {
                    entry("luaunit.run", "luaunit.run([...])", "function",
                        "Run the test suite.",
                        [[
Run the registered test suite and return the number of failures and errors (zero means success).

With no arguments, command-line options are taken from the script's `arg` table. You may instead pass option strings such as `"-v"`, `"--quiet"`, `"--shuffle"` or `"--pattern"`. LuaUnit discovers global tables named `Test*` and functions named `test*`.

```lua
local lu = require "luaunit"
Test_math = {}
function Test_math:test_addition() lu.assertEquals(1 + 1, 2) end
os.exit(lu.run())
```
]]),
                    entry("luaunit.assertEquals", "luaunit.assertEquals(actual, expected [, message])", "function",
                        "Assert equality.",
                        [[
Assert that two values are equal. Tables are compared deeply, including nested keys and values; other values use ordinary `==`.

An optional message is appended to the failure output. A mismatch fails the current test by raising an error.

```lua
lu.assertEquals({ a = 1, b = { 2, 3 } }, { b = { 2, 3 }, a = 1 })
```
]]),
                    entry("luaunit.assertNotEquals", "luaunit.assertNotEquals(actual, expected [, message])", "function",
                        "Assert inequality.",
                        [[
Assert that two values are not equal, using the same deep table comparison as `assertEquals`.

The assertion passes when the values have different types or any nested table content differs. An optional message is added to the failure.
]]),
                    entry("luaunit.assertAlmostEquals", "luaunit.assertAlmostEquals(actual, expected, margin [, message])", "function",
                        "Assert approximate equality.",
                        [[
Assert that two numbers, or two tables of numbers, are equal within `margin`.

If `margin` is omitted or `nil`, LuaUnit's `EPS` value is used. Negative margins are rejected. An optional message is appended on failure.

```lua
lu.assertAlmostEquals(0.1 + 0.2, 0.3, 1e-9)
```
]]),
                    entry("luaunit.assertItemsEquals", "luaunit.assertItemsEquals(actual, expected [, message])", "function",
                        "Assert that two tables contain the same items.",
                        [[
Assert that two tables contain the same items, ignoring order and keys.

Each value in one table must match some value in the other and vice versa, using deep equality. The comparison is O(n^2), so it is intended for small tables.
]]),
                    entry("luaunit.assertStrContains", "luaunit.assertStrContains(value, substring [, isPattern [, message]])", "function",
                        "Assert that a string contains a substring.",
                        [[
Assert that `value` contains `substring`.

By default the search is plain text. Pass `true` as `isPattern` to treat `substring` as a Lua pattern. An optional message is appended to the failure.

```lua
lu.assertStrContains("hello world", "lo wo")
lu.assertStrContains("abc123", "%d+", true)
```
]]),
                    entry("luaunit.assertStrIContains", "luaunit.assertStrIContains(value, substring [, message])", "function",
                        "Case-insensitive substring assertion.",
                        [[
Assert that `value` contains `substring`, ignoring letter case.

The search is always plain text, so pattern characters have no special meaning. An optional message is appended to the failure.

```lua
lu.assertStrIContains("Hello World", "hello")
```
]]),
                    entry("luaunit.assertNotStrContains", "luaunit.assertNotStrContains(value, substring [, isPattern [, message]])", "function",
                        "Assert that a string does not contain a substring.",
                        [[
Assert that `value` does not contain `substring`.

Plain-text matching is the default; pass `true` as `isPattern` to use a Lua pattern. An optional message is appended to the failure.
]]),
                    entry("luaunit.assertNotStrIContains", "luaunit.assertNotStrIContains(value, substring [, message])", "function",
                        "Case-insensitive negative substring assertion.",
                        [[
Assert that `value` does not contain `substring`, ignoring letter case.

The search is plain text. An optional message is appended to the failure.
]]),
                    entry("luaunit.assertStrMatches", "luaunit.assertStrMatches(value, pattern [, start [, final [, message]]])", "function",
                        "Assert a string pattern match.",
                        [[
Assert that the whole of `value`, or the range from `start` through `final`, matches the Lua pattern.

`start` defaults to 1 and `final` to the string length. The pattern must cover the entire selected range, not merely occur somewhere inside it.

```lua
lu.assertStrMatches("2026-10-24", "%d%d%d%d%-%d%d%-%d%d")
```
]]),
                    entry("luaunit.assertError", "luaunit.assertError(func, ...)", "function",
                        "Assert that a call raises an error.",
                        [[
Assert that calling `func` with the supplied arguments raises an error.

The error message and type are not checked. Extra arguments after `func` are passed to it.

```lua
lu.assertError(function() error("boom") end)
```
]]),
                    entry("luaunit.assertErrorMsgEquals", "luaunit.assertErrorMsgEquals(message, func, ...)", "function",
                        "Assert an exact error message.",
                        [[
Assert that calling `func` raises an error whose message exactly equals `message`.

File and line prefixes added by `error(..., 2)` are significant; use `assertErrorMsgContentEquals` to ignore them. Extra arguments after `func` are passed through.

```lua
lu.assertErrorMsgEquals("boom", function() error("boom", 0) end)
```
]]),
                    entry("luaunit.assertErrorMsgContentEquals", "luaunit.assertErrorMsgContentEquals(message, func, ...)", "function",
                        "Assert an error message ignoring file and line prefix.",
                        [[
Assert that `func` raises an error whose message equals `message` after removing a leading `file:line:` prefix.

This is convenient for errors raised with a level argument. Extra arguments after `func` are passed through.
]]),
                    entry("luaunit.assertErrorMsgContains", "luaunit.assertErrorMsgContains(partial, func, ...)", "function",
                        "Assert an error message contains text.",
                        [[
Assert that `func` raises an error whose message contains `partial` as plain text.

Any file and line prefix is left in place, so the substring may match anywhere in the full message. Extra arguments after `func` are passed through.
]]),
                    entry("luaunit.assertErrorMsgMatches", "luaunit.assertErrorMsgMatches(pattern, func, ...)", "function",
                        "Assert an error message matches a pattern.",
                        [[
Assert that `func` raises an error whose entire message matches the Lua pattern.

The pattern is matched against the complete message, including any file and line prefix, and must cover the whole string. Extra arguments after `func` are passed through.
]]),
                    entry("luaunit.assertEvalToTrue", "luaunit.assertEvalToTrue(value [, message])", "function",
                        "Assert that a value evaluates to true.",
                        [[
Assert that `value` evaluates to true in Lua, meaning it is neither `false` nor `nil`.

Numbers, strings and tables all pass, including `0` and the empty string. Use `assertIsTrue` when the value must be exactly `true`.
]]),
                    entry("luaunit.assertEvalToFalse", "luaunit.assertEvalToFalse(value [, message])", "function",
                        "Assert that a value evaluates to false.",
                        [[
Assert that `value` is `false` or `nil`, the only Lua values that evaluate to false.

Use `assertIsFalse` when the value must be exactly `false` rather than `nil`.
]]),
                    entry("luaunit.assertIsTrue", "luaunit.assertIsTrue(value [, message])", "function",
                        "Assert a true value.",
                        [[
Assert that `value` is exactly the boolean `true`.

Truthy non-boolean values fail this assertion; use `assertEvalToTrue` for Lua truthiness. An optional message is appended to the failure.
]], { "luaunit.assertTrue" }),
                    entry("luaunit.assertNotIsTrue", "luaunit.assertNotIsTrue(value [, message])", "function",
                        "Assert a non-true value.",
                        [[
Assert that `value` is not exactly the boolean `true`.

Both `false` and any non-boolean value pass; use `assertIsFalse` for an exact `false` check.
]]),
                    entry("luaunit.assertIsFalse", "luaunit.assertIsFalse(value [, message])", "function",
                        "Assert a false value.",
                        [[
Assert that `value` is exactly the boolean `false`.

`nil` and other falsy values fail this assertion; use `assertEvalToFalse` for Lua falsiness.
]], { "luaunit.assertFalse" }),
                    entry("luaunit.assertNotIsFalse", "luaunit.assertNotIsFalse(value [, message])", "function",
                        "Assert a non-false value.",
                        [[
Assert that `value` is not exactly the boolean `false`.

`nil`, `true` and non-boolean values all pass. An optional message is appended on failure.
]]),
                    entry("luaunit.assertIsNil", "luaunit.assertIsNil(value [, message])", "function",
                        "Assert nil.",
                        [[
Assert that `value` is `nil`.

The alias `assertNil` behaves identically. An optional message is appended to the failure.
]], { "luaunit.assertNil" }),
                    entry("luaunit.assertNotIsNil", "luaunit.assertNotIsNil(value [, message])", "function",
                        "Assert not nil.",
                        [[
Assert that `value` is not `nil`.

The alias `assertNotNil` behaves identically. An optional message is appended to the failure.
]], { "luaunit.assertNotNil" }),
                    entry("luaunit.assertIs", "luaunit.assertIs(actual, expected [, message])", "function",
                        "Assert identity.",
                        [[
Assert that `actual` and `expected` are the same value, using `==`.

For tables and functions this checks identity rather than content; use `assertEquals` for structural comparison.
]]),
                    entry("luaunit.assertNotIs", "luaunit.assertNotIs(actual, expected [, message])", "function",
                        "Assert non-identity.",
                        [[
Assert that `actual` and `expected` are not the same value.

Table contents are not compared; two distinct tables always pass even when their fields match.
]]),
                    entry("luaunit.assertIsNaN", "luaunit.assertIsNaN(value [, message])", "function",
                        "Assert NaN.",
                        [[
Assert that `value` is the NaN number value.

The check works even though NaN is not equal to itself. An optional message is appended on failure.
]]),
                    entry("luaunit.assertNotIsNaN", "luaunit.assertNotIsNaN(value [, message])", "function",
                        "Assert not NaN.",
                        [[
Assert that `value` is not NaN.

Non-number values also pass. An optional message is appended on failure.
]]),
                    entry("luaunit.assertIsInf", "luaunit.assertIsInf(value [, message])", "function",
                        "Assert infinity.",
                        [[
Assert that `value` is either positive or negative infinity.

Use `assertIsPlusInf` or `assertIsMinusInf` when the sign matters.
]]),
                    entry("luaunit.assertIsPlusInf", "luaunit.assertIsPlusInf(value [, message])", "function",
                        "Assert positive infinity.",
                        [[
Assert that `value` is positive infinity (`math.huge`).

An optional message is appended to the failure.
]]),
                    entry("luaunit.assertIsMinusInf", "luaunit.assertIsMinusInf(value [, message])", "function",
                        "Assert negative infinity.",
                        [[
Assert that `value` is negative infinity (`-math.huge`).

An optional message is appended to the failure.
]]),
                    entry("luaunit.assertNotIsInf", "luaunit.assertNotIsInf(value [, message])", "function",
                        "Assert a finite number.",
                        [[
Assert that `value` is a finite number and not positive or negative infinity.

Non-number values also pass. An optional message is appended on failure.
]]),
                    entry("luaunit.assertIsPlusZero", "luaunit.assertIsPlusZero(value [, message])", "function",
                        "Assert positive zero.",
                        [[
Assert that `value` is positive zero (`0.0`).

IEEE-754 distinguishes positive and negative zero even though `0.0 == -0.0`; this assertion checks the sign bit.
]]),
                    entry("luaunit.assertIsMinusZero", "luaunit.assertIsMinusZero(value [, message])", "function",
                        "Assert negative zero.",
                        [[
Assert that `value` is negative zero (`-0.0`).

IEEE-754 distinguishes negative zero from positive zero even though they compare equal with `==`.
]]),
                    entry("luaunit.assertTableContains", "luaunit.assertTableContains(table, expected [, message])", "function",
                        "Assert that a table contains expected entries.",
                        [[
Assert that table `t` contains `expected` as one of its values.

Every value is compared with deep equality, and keys are ignored. The table must be a table; an optional message is appended on failure.

```lua
lu.assertTableContains({ "a", "b", "c" }, "b")
```
]]),
                    entry("luaunit.assertNotTableContains", "luaunit.assertNotTableContains(table, expected [, message])", "function",
                        "Assert that a table does not contain expected entries.",
                        [[
Assert that table `t` does not contain `expected` as any of its values.

Values are compared with deep equality. An optional message is appended on failure.
]]),
                    entry("luaunit.fail", "luaunit.fail([message])", "function",
                        "Fail the current test.",
                        [[
Fail the current test immediately with `message`, or with a generic failure message when it is omitted.

The function raises an error through LuaUnit, so it is normally used inside a test function to report an unexpected branch.
]]),
                    entry("luaunit.failIf", "luaunit.failIf(condition [, message])", "function",
                        "Fail when a condition is true.",
                        [[
Fail the current test when `condition` is truthy.

`nil` and `false` do nothing. An optional message is used in the failure report.

```lua
lu.failIf(#items == 0, "expected at least one item")
```
]]),
                    entry("luaunit.skip", "luaunit.skip([message])", "function",
                        "Skip the current test.",
                        [[
Skip the current test and mark it as skipped rather than failed.

An optional message explains why the test was skipped. Execution of the test stops at the call.
]]),
                    entry("luaunit.skipIf", "luaunit.skipIf(condition [, message])", "function",
                        "Skip when a condition is true.",
                        [[
Skip the current test when `condition` is truthy.

`nil` and `false` let the test continue. An optional message is reported with the skipped test.
]]),
                    entry("luaunit.success", "luaunit.success()", "function",
                        "End the current test successfully.",
                        [[
Mark the current test as successful and stop executing it.

This is rarely needed because a test that returns normally succeeds. It is useful for early exits from tests that intentionally inspect multiple paths.
]]),
                    entry("luaunit.setVerbosity", "luaunit.setVerbosity(level)", "function",
                        "Set the runner verbosity.",
                        [[
Set the default verbosity used by later `run()` calls.

Values are integers: `0` is quiet, `1` is low, `10` is the default, and `20` is verbose. The aliases `set_verbosity` and `SetVerbosity` are also provided.

```lua
local lu = require "luaunit"
lu.setVerbosity(0)
```
]]),
                }, { upstream = "https://github.com/bluebird75/luaunit", license = "BSD" }),

                module("serpent", "serpent", "Lua serializer and pretty printer.", [==[
`serpent.serialize(value [, options])` returns a Lua expression that recreates
the value.  `serpent.line` and `serpent.block` are convenience formatters.
]==], {
                    entry("serpent.serialize", "serpent.serialize(value [, options])", "function",
                        "Serialize a value to a Lua expression.",
                        [[
Serialize a Lua value into a Lua expression that reconstructs it.

The default output is single-line unless an `indent` option is supplied. Useful options include `name` (wrap the result in a local block), `compact`, `sortkeys`, `comment`, `nocode` (skip function bodies), `sparse`, and `maxlevel`. Shared and cyclic tables are handled with local references.

```lua
local serpent = require "serpent"
print(serpent.serialize({ 1, 2, answer = 42 }))
```
]]),
                    entry("serpent.line", "serpent.line(value [, options])", "function",
                        "Serialize a value on one line.",
                        [=[
Serialize a value on one line, with sorted keys and comments enabled by default.

Pass an options table to override defaults such as `sortkeys` or `comment`. The result is a Lua expression; it is not printed.

```lua
local serpent = require "serpent"
print(serpent.line({ b = 2, a = 1 })) --> {a=1,b=2} --[[table: ...]]
```
]=]),
                    entry("serpent.block", "serpent.block(value [, options])", "function",
                        "Serialize a value in block form.",
                        [[
Serialize a value in indented block form, using two spaces by default and sorting keys.

Comments and sorting are enabled unless overridden by the options table. This is the most readable form for nested data.

```lua
local serpent = require "serpent"
print(serpent.block({ list = { 1, 2, 3 } }))
```
]]),
                    entry("serpent.dump", "serpent.dump(value [, options])", "function",
                        "Serialize a value in compact form.",
                        [[
Return a compact serialization with the root named `_`, intended for debugging output.

The output uses compact tables and includes the shared-reference prologue when needed. Pass `{ print = true }`-style options only if your application handles them; this function itself returns a string and does not print.
]]),
                    entry("serpent.load", "serpent.load(string)", "function",
                        "Load a serialized value.",
                        [[
Load a value from text produced by `serpent.serialize`.

Returns `true, value` on success. On failure it returns `false, error_message` when the text compiled but evaluation failed, or `nil, syntax_error` when the text could not be compiled. The default environment permits table construction but not function calls.

```lua
local ok, value = require("serpent").load("{ 1, 2, name = 'x' }")
assert(ok)
print(value.name)
```
]]),
                }, { upstream = "https://github.com/pkulchenko/serpent", license = "MIT" }),

                module("markdown", "markdown (md4c)", "Markdown parsing and HTML rendering based on md4c.", [==[
`require "markdown"` exposes md4c directly.  The module has two parts: an
event-based parser and the md4c-html renderer.

The parser accepts either a table of callbacks or a single function.  A table
may contain `enter_block`, `leave_block`, `enter_span`, `leave_span`, `text`
and `debug_log`; missing entries are ignored.  A single function receives the
callback name as its first argument.

```lua
local markdown = require "markdown"

local events = {}
markdown.parse("# Title\n\nHello **world**.", function(name, kind, detail)
    events[#events + 1] = name .. ":" .. tostring(kind)
end)

print(markdown.html("# Title")) --> <h1>Title</h1>
```

The parser and renderer accept an options table.  `dialect` is `"commonmark"`
(the default) or `"github"`.  `flags` adds parser extensions and
`renderer_flags` controls md4c-html.  Both flag fields accept either a number
or an array of names from the matching constants table.

The `*_file` functions read the path from the local filesystem first and fall
back to the executable payload when the local file does not exist.
]==], {
                    entry("markdown.parse", "markdown.parse(text, callbacks [, options])", "function",
                        "Parse Markdown text through md4c callbacks.",
                        [[
Parse `text` and invoke Lua callbacks for each md4c block, span and text
event.  `callbacks` is either a table of named functions or one function used
for every event.  The table keys and single-function names are `enter_block`,
`leave_block`, `enter_span`, `leave_span`, `text` and `debug_log`.

Block and span callbacks receive `(kind, detail)`, text callbacks receive
`(kind, text)`, and debug callbacks receive `(message)`.  Detail is a table for
events that carry metadata, such as heading levels, table alignment and link
URLs, and `nil` otherwise.  With a single callback, the callback name is added
as the first argument: `(name, kind, detail)` or `(name, kind, text)`.

Returning `false` from any callback stops parsing and makes `parse` return
`false`.  Errors raised inside a callback propagate unchanged.  On success the
function returns `true`.

```lua
local markdown = require "markdown"
markdown.parse("## Hi", {
    enter_block = function(kind, detail)
        if kind == "h" then print(detail.level) end
    end,
    text = function(kind, text) print(kind, text) end,
})
```
]]),
                    entry("markdown.parse_file", "markdown.parse_file(path, callbacks [, options])", "function",
                        "Parse a Markdown file, falling back to the payload.",
                        [[
Read `path` and parse it with the same callbacks and options as
`markdown.parse`.  Local files are read first.  If the local path does not
exist, the executable payload is searched, which makes bundled documentation
and scripts parseable from a standalone ZLI executable.

A path object from the `filesystem` module is also accepted.  File errors
return `nil, message`.  Callback aborts and callback errors behave exactly as in
`markdown.parse`.

```lua
local markdown = require "markdown"
local ok = markdown.parse_file("main.lua", { text = function(_, text) end })
assert(ok)
```
]]),
                    entry("markdown.html", "markdown.html(text [, options]) / markdown.html(text, output [, options])", "function",
                        "Render Markdown as HTML.",
                        [[
Render `text` with md4c-html.  Without an output callback the function
returns the complete HTML string.  With an output function as the second
argument it calls `output(chunk)` for successive pieces of HTML and returns
`true` on success.  Chunk boundaries are arbitrary; concatenate all chunks to
obtain the document.

An output callback may return `false` to stop collecting output; later chunks
are discarded and the function returns `false`.  Errors raised by the callback
propagate unchanged.  The generated HTML contains the body contents only and
does not include an HTML document wrapper.

```lua
local markdown = require "markdown"
print(markdown.html("**bold**"))

local chunks = {}
markdown.html("# Title", function(chunk) chunks[#chunks + 1] = chunk end)
```
]]),
                    entry("markdown.html_file", "markdown.html_file(path [, options]) / markdown.html_file(path, output [, options])", "function",
                        "Render a Markdown file as HTML.",
                        [[
Read `path` through the common local-first/payload-fallback file reader and
render it with md4c-html.  Without an output callback it returns the complete
HTML string.  With an output callback it streams chunks to Lua and returns
`true` on success.

The second argument is treated as an options table unless it is a function, so
`markdown.html_file(path, { dialect = "github" })` selects GitHub extensions.
File and rendering failures return `nil, message`.

```lua
local markdown = require "markdown"
local html = markdown.html_file("README.md", { dialect = "github" })
print(#html)
```
]]),
                    entry("markdown.dialects", "markdown.dialects", "table",
                        "Named md4c dialects.",
                        [[
Named values for the `dialect` option.  A dialect is a predefined set of
parser flags and may be combined with additional entries from
`markdown.flags`.

| Dialect | Description |
| --- | --- |
| `commonmark` | CommonMark mode with no extensions enabled. |
| `github` | GitHub-style dialect: permissive URL, e-mail and WWW autolinks, tables, strikethrough, task lists, admonitions and footnotes. |
]]),
                    entry("markdown.flags", "markdown.flags", "table",
                        "Named md4c parser flags.",
                        [[
Named values for the `flags` option.  The option accepts either an integer
bitmask or an array whose entries are names from this table or integer flags.

| Flag | Description |
| --- | --- |
| `collapse_whitespace` | Collapse non-trivial whitespace in normal text into a single space. |
| `permissive_atx_headers` | Accept ATX headings without a space after the `#` characters. |
| `permissive_url_autolinks` | Recognize URLs as autolinks without angle brackets. |
| `permissive_email_autolinks` | Recognize e-mail addresses as autolinks without angle brackets or a `mailto:` prefix. |
| `no_indented_code_blocks` | Disable indented code blocks; only fenced code blocks are recognized. |
| `no_html_blocks` | Disable raw HTML blocks. |
| `no_html_spans` | Disable raw inline HTML spans. |
| `tables` | Enable the tables extension. |
| `strikethrough` | Enable `~~strikethrough~~` spans. |
| `permissive_www_autolinks` | Recognize `www.` links as autolinks even without a scheme prefix. |
| `tasklists` | Enable task-list items such as `- [x] done`. |
| `task_lists` | Alias for `tasklists`. |
| `latex_math_spans` | Enable inline `$...$` and display `$$...$$` LaTeX math spans. |
| `wikilinks` | Enable wiki-link spans. |
| `wiki_links` | Alias for `wikilinks`. |
| `underline` | Enable underline spans and disable `_` as emphasis. |
| `hard_soft_breaks` | Treat every soft line break as a hard break. |
| `spoilers` | Enable spoiler spans written with double vertical bars. |
| `superscripts` | Enable `^superscript^` spans. |
| `subscripts` | Enable `~subscript~` spans. |
| `admonitions` | Enable admonition blocks such as notes, tips and warnings. |
| `footnotes` | Enable `[^label]` footnote references and definitions. |
| `highlight` | Enable `==highlight==` spans. |
| `preserve_blank_lines` | Report runs of blank lines as `blank` block events. |
| `insert` | Enable insertion spans. |
]]),
                    entry("markdown.html_flags", "markdown.html_flags", "table",
                        "Named md4c-html renderer flags.",
                        [[
Named values for the `renderer_flags` option.  The option accepts either an
integer bitmask or an array whose entries are names from this table or integer
flags.

| Flag | Description |
| --- | --- |
| `debug` | Write md4c debug output to standard error. |
| `verbatim_entities` | Keep HTML entities verbatim instead of resolving them. |
| `skip_utf8_bom` | Skip a UTF-8 byte-order mark at the start of the input. |
| `xhtml` | Generate XHTML-style self-closing tags such as `<br />`. |
]]),
                }, { upstream = "https://github.com/mity/md4c", license = "MIT" }),
                module("xml2lua", "xml2lua", "Pure-Lua XML parser and table-to-XML serializer.", [==[
`xml2lua` is a non-validating XML parser written entirely in Lua.  It parses
well-formed XML into a handler and can also turn a Lua table back into XML.
There is no dependency on an XML library or a C module.

The parser is split into a tokenizer and a handler.  `xml2lua.parser(handler)`
returns a parser that drives the handler; `handler` is usually one of the
bundled handler modules:

| Handler | Result |
| --- | --- |
| `xmlhandler.tree` | Natural Lua table with tag names as keys. |
| `xmlhandler.dom` | DOM-like tree of typed nodes. |
| `xmlhandler.print` | Event trace written to standard output for debugging. |

```lua
local xml2lua = require "xml2lua"
local handler = require("xmlhandler.tree"):new()

local parser = xml2lua.parser(handler)
parser:parse [[<people><person age="42"><name>Ada</name></person></people>]]

print(handler.root.people.person.name) --> Ada
print(handler.root.people.person._attr.age) --> 42
```

The parser checks basic XML syntax and balanced tags, but it does not validate
an XML schema.  It handles declarations, processing instructions, comments,
CDATA, DOCTYPE declarations and the standard XML entities.  Namespaces and
character-set conversion are not interpreted.

The table representation uses `_attr` for attributes.  A single child is
reduced to a plain value where possible, while repeated siblings become an
array.  `xml2lua.toXml` reverses that convention: fields named `_attr` become
attributes, arrays repeat the containing tag, and all other fields become
nested elements.
]==], {
                    entry("xml2lua.parser", "xml2lua.parser(handler)", "function",
                        "Create an XML parser for a handler.",
                        [[
Create a parser object that sends parser events to `handler`.

The handler is a table with any of the callbacks `starttag`, `endtag`, `text`,
`cdata`, `comment`, `dtd`, `pi` and `decl`; missing callbacks are ignored.  Use
`xmlhandler.tree`, `xmlhandler.dom`, `xmlhandler.print`, or a custom handler.

The returned parser has a `parse(xml [, parseAttributes])` method.  `parse`
consumes one complete XML string and resets its internal tag stack for that
call.  Passing `false` as `parseAttributes` suppresses attribute parsing in
handlers that honour the setting.

The convenience constructor enables whitespace stripping and entity expansion
and installs an error handler that raises `Parse Error [char=pos]`.  Use
`XmlParser.new` directly when different options are needed.

```lua
local xml2lua = require "xml2lua"
local handler = require("xmlhandler.tree"):new()
xml2lua.parser(handler):parse("<root><value>42</value></root>")
print(handler.root.root.value) --> 42
```
]]),
                    entry("xml2lua.toXml", "xml2lua.toXml(table [, rootName [, level]])", "function",
                        "Serialize a Lua table as XML.",
                        [[
Convert a Lua table to an XML string.

A table field named `_attr` is written as attributes on the containing tag.
An array field repeats the field name for each element.  Other fields become
nested tags whose text is the field value converted with `tostring`.  Empty
tables produce self-closing tags.  `rootName` names the outermost element; if it
is omitted and the table contains exactly one field, that field name is used.

`level` is the initial indentation level and is mainly for internal recursion.
Output is pretty-printed with two spaces per level when `xml2lua.pretty` is
true.  Set it to `false` for a single-line result.

```lua
local xml2lua = require "xml2lua"
print(xml2lua.toXml {
    person = { name = "Ada", _attr = { id = "7" } },
}, "people"))
```
]]),
                    entry("xml2lua.printable", "xml2lua.printable(table)", "function",
                        "Recursively print a table.",
                        [[
Recursively print a table with one field per line.

Nested tables are indented by two spaces per level.  Scalar values are printed
as `key=value` using `tostring`.  The function writes through `print` and does
not return a value.  It is a debugging aid for inspecting parsed XML.

```lua
local xml2lua = require "xml2lua"
xml2lua.printable { people = { person = { name = "Ada" } } }
```
]]),
                    entry("xml2lua.toString", "xml2lua.toString(value)", "function",
                        "Render a value in a compact table syntax.",
                        [[
Return a compact string representation of a value.

Tables are rendered as `{key=value,...}` and nested tables are rendered
recursively.  Scalar values are returned unchanged rather than converted with
`tostring`.  Field order follows `pairs`, so the result is intended for
debugging rather than stable serialization.  Recursive tables are not
supported.

```lua
local xml2lua = require "xml2lua"
print(xml2lua.toString { answer = 42 }) --> {answer=42}
```
]]),
                    entry("xml2lua.loadFile", "xml2lua.loadFile(path)", "function",
                        "Read an XML document from a file.",
                        [[
Open `path` in text mode, read the complete file and return its contents.

The file is closed before returning.  On failure the underlying `io.open`
error message is raised.  In ZLI the read also sees bundled payload files when
no local file exists, because `io.open` provides that fallback.

```lua
local xml2lua = require "xml2lua"
local text = xml2lua.loadFile("document.xml")
```
]]),
                    entry("xml2lua.getSpaces", "xml2lua.getSpaces(level)", "function",
                        "Return indentation for a nesting level.",
                        [[
Return a string of spaces for the given nesting `level`.

When `xml2lua.pretty` is true, the result contains `level * 2` spaces.
Otherwise it is the empty string.  This helper is used by the XML serializers
and can also be used by custom writers.

```lua
local xml2lua = require "xml2lua"
print(#xml2lua.getSpaces(3)) --> 6
```
]]),
                    entry("xml2lua.addTagValueAttr", "xml2lua.addTagValueAttr(tagName, tagValue, attrTable, level)", "function",
                        "Append one element to the XML output buffer.",
                        [[
Append an opening tag, its value and a closing tag to `xml2lua.xmltb`.

`attrTable` may be `nil` or a table of attribute names and values.  An empty
`tagValue` produces a self-closing tag such as `<name/>`.  Indentation comes
from `xml2lua.getSpaces(level)`.  This is a low-level helper used by
`xml2lua.parseTableToXml`; callers must initialize `xml2lua.xmltb`.

```lua
local xml2lua = require "xml2lua"
xml2lua.xmltb = {}
xml2lua.addTagValueAttr("name", "Ada", { id = "7" }, 0)
```
]]),
                    entry("xml2lua.startTag", "xml2lua.startTag(tagName, attrTable, level)", "function",
                        "Append an opening tag to the XML output buffer.",
                        [[
Append `<tagName ...>` to `xml2lua.xmltb`.

`attrTable` may be `nil`; otherwise its fields are written as
`name="value"` attributes.  `tagName` may be `nil`, in which case nothing is
appended.  Indentation comes from `xml2lua.getSpaces(level)`.  The matching
closing tag is normally added with `xml2lua.endTag`.

```lua
local xml2lua = require "xml2lua"
xml2lua.xmltb = {}
xml2lua.startTag("person", { id = "7" }, 0)
xml2lua.endTag("person", 0)
```
]]),
                    entry("xml2lua.endTag", "xml2lua.endTag(tagName, level)", "function",
                        "Append a closing tag to the XML output buffer.",
                        [[
Append `</tagName>` to `xml2lua.xmltb`.

`tagName` may be `nil`, in which case nothing is appended.  Indentation comes
from `xml2lua.getSpaces(level)`.  The function does not check that a matching
opening tag exists.

```lua
local xml2lua = require "xml2lua"
xml2lua.xmltb = {}
xml2lua.startTag("empty", nil, 0)
xml2lua.endTag("empty", 0)
```
]]),
                    entry("xml2lua.isChildArray", "xml2lua.isChildArray(table)", "function",
                        "Test whether a table contains array indexes.",
                        [[
Return true when `table` has at least one numeric field.

The check uses `pairs`, so the presence of any integer key is enough; a field
named `1` and a normal array both count.  The function is used by
`xml2lua.parseTableToXml` to decide whether a field represents repeated tags.

```lua
local xml2lua = require "xml2lua"
assert(xml2lua.isChildArray { "a", "b" })
assert(not xml2lua.isChildArray { name = "Ada" })
```
]]),
                    entry("xml2lua.isTableEmpty", "xml2lua.isTableEmpty(table)", "function",
                        "Test whether a table only contains attributes.",
                        [[
Return true when `table` has no fields other than `_attr`.

An empty table is empty, and a table containing only an `_attr` table is also
considered empty for XML serialization.  Such values are written as
self-closing tags.  Any other field, including a false boolean, makes the
result false.

```lua
local xml2lua = require "xml2lua"
assert(xml2lua.isTableEmpty {})
assert(xml2lua.isTableEmpty { _attr = { id = "7" } })
assert(not xml2lua.isTableEmpty { value = false })
```
]]),
                    entry("xml2lua.parseTableToXml", "xml2lua.parseTableToXml(value, tagName, level)", "function",
                        "Append a table value to the XML output buffer.",
                        [[
Recursively append `value` to `xml2lua.xmltb` using `tagName` as the element
name.

Array values repeat the tag for every item.  Tables with only `_attr` become
self-closing tags, and other tables become nested elements.  Scalar values
become text elements.  A field named `_attr` is never emitted as an element.
The function is normally called through `xml2lua.toXml`.

```lua
local xml2lua = require "xml2lua"
xml2lua.xmltb = {}
xml2lua.parseTableToXml({ "a", "b" }, "item", 0)
print(table.concat(xml2lua.xmltb, "\n"))
```
]]),
                    entry("xml2lua.pretty", "xml2lua.pretty", "field",
                        "Enable pretty-printed XML output.",
                        [[
When true, `xml2lua.toXml` inserts newlines and two spaces of indentation per
level.  Set it to `false` to serialize without whitespace between tags.  The
field is a normal module global and defaults to true.

`xml2lua.toString` and parser output are not affected by this setting.
]]),
                }, { upstream = "https://github.com/manoelcampos/xml2lua", license = "MIT" }),

                module("XmlParser", "XmlParser", "Low-level XML tokenizer used by xml2lua.", [==[
`XmlParser` is the tokenizer behind `xml2lua`.  Most programs should use
`xml2lua.parser(handler)` instead, but constructing the tokenizer directly
allows the parsing options to be changed.

```lua
local XmlParser = require "XmlParser"
local handler = require("xmlhandler.tree"):new()
local parser = XmlParser.new(handler, {
    stripWS = false,
    expandEntities = true,
    errorHandler = function(message, position)
        error(message .. " at " .. position)
    end,
})
parser:parse("<root>  text  </root>")
```

The options table may contain:

| Option | Description |
| --- | --- |
| `stripWS` | Strip leading and trailing whitespace from text events. |
| `expandEntities` | Expand the standard XML entities and numeric character references. |
| `errorHandler` | Function called as `errorHandler(message, position)` for parse errors. |

Boolean options must be `true` or `false`; the parser tests them for truth, so
passing `0` still enables an option.
]==], {
                    entry("XmlParser.new", "XmlParser.new(handler [, options])", "function",
                        "Create a tokenizer for a handler.",
                        [[
Create a new tokenizer that sends events to `handler`.

`options` is a table with the optional fields `stripWS`, `expandEntities` and
`errorHandler`.  When an option is omitted it is false or nil, so text is not
stripped and entities are not expanded.  `errorHandler` is called with the
message and the character position of a parse error; if no handler is set,
errors are silently ignored by the tokenizer.

```lua
local XmlParser = require "XmlParser"
local handler = require("xmlhandler.tree"):new()
local parser = XmlParser.new(handler, { stripWS = true })
parser:parse("<root><value>42</value></root>")
```
]]),
                    entry("XmlParser:parse", "parser:parse(xml [, parseAttributes])", "method",
                        "Tokenize an XML document.",
                        [[
Parse the complete XML document in `xml` and invoke the handler callbacks.

The method maintains its own tag stack and reports unbalanced or incomplete
tags through the configured error handler.  Passing `false` as
`parseAttributes` sets `handler.parseAttributes = false`; handlers that support
the setting then omit attributes.  The default is true.

The string is parsed as one document.  There is no streaming interface and no
charset handling; decode non-UTF-8 input before calling.

```lua
local parser = require("XmlParser").new(require("xmlhandler.tree"):new(), {
    stripWS = true,
    expandEntities = true,
})
parser:parse("<root><value>42</value></root>")
```
]]),
                }, { upstream = "https://github.com/manoelcampos/xml2lua", license = "MIT" }),

                module("xmlhandler.tree", "xmlhandler.tree", "Convert XML to a natural Lua table.", [==[
`xmlhandler.tree` maps XML elements directly to Lua tables.

Tag names become keys; text becomes the value of the containing key; attributes
are collected in an `_attr` table.  A single child is reduced to a plain value,
while repeated siblings become an array.  Mixed content is not represented
faithfully because text and child elements are stored in the same table.

Call `handler:new()` to create a handler for one document.  The module table
itself can also be passed directly, but a new instance avoids state shared with
other parses.

```lua
local handler = require("xmlhandler.tree"):new()
require("xml2lua").parser(handler):parse [[
<people>
  <person type="natural"><name>Ada</name></person>
</people>
]]

print(handler.root.people.person.name) --> Ada
print(handler.root.people.person._attr.type) --> natural
```
]==], {
                    entry("xmlhandler.tree:new", "handler:new()", "method",
                        "Create an independent tree handler.",
                        [[
Create and return a new tree handler with an empty root and tag stack.

Each handler should be used for one XML document.  Creating a new handler
avoids reusing the root and stack from an earlier parse.

```lua
local handler = require("xmlhandler.tree"):new()
local parser = require("xml2lua").parser(handler)
parser:parse("<root><value>42</value></root>")
```
]]),
                    entry("xmlhandler.tree:reduce", "handler:reduce(node, key, parent)", "method",
                        "Collapse single-child nodes.",
                        [[
Recursively collapse nodes that contain exactly one child and no attributes.

When a node is an array with one value, that value replaces the array in
`parent[key]`.  The optional `handler.options.noreduce` table can list tag names
that must stay as arrays even when they have one child.

This method is called automatically when the outermost tag closes.  It is
exposed for custom post-processing but normally does not need to be called
directly.
]]),
                    entry("xmlhandler.tree:starttag", "handler:starttag(tag)", "method",
                        "Handle an opening tag event.",
                        [[
Create a node for an opening tag and add it to the current parent.

`tag` is a table with `name` and optional `attrs`.  Attributes are copied into
the node's `_attr` field when attribute parsing is enabled.  Repeated siblings
are converted to an array.  The new node becomes the current parent until its
closing tag arrives.
]]),
                    entry("xmlhandler.tree:endtag", "handler:endtag(tag, position)", "method",
                        "Handle a closing tag event.",
                        [[
Close the current node and restore its parent.

`tag.name` must match the node on top of the handler stack.  When the
outermost element closes, `handler:reduce` collapses single-child nodes.  The
`position` argument is accepted for parser compatibility and is only used in
error messages.
]]),
                    entry("xmlhandler.tree:text", "handler:text(text)", "method",
                        "Handle a text or CDATA event.",
                        [[
Append `text` to the current node.

The value is stored as the next array item on the current node.  After
`reduce`, a node with a single text child becomes a plain string.

```lua
local handler = require("xmlhandler.tree"):new()
require("xml2lua").parser(handler):parse("<root>text</root>")
print(handler.root.root) --> text
```
]]),
                    entry("xmlhandler.tree:cdata", "handler:cdata(text)", "method",
                        "Handle a CDATA event.",
                        [[
Append raw CDATA content to the current node.

This is an alias of `xmlhandler.tree:text`; CDATA is not entity-expanded, so
characters such as `&` and `<` remain as written.  The result is stored exactly
like ordinary text and participates in the same reduction rules.
]]),
                    entry("xmlhandler.tree.root", "handler.root", "field",
                        "Root table of the parsed document.",
                        [[
After parsing, `root` contains the document tree.  It starts as an empty table
and gains one field named after the outermost XML element.

For a document whose root element is `<people>`, the parsed data is in
`handler.root.people`.  The field remains empty if parsing produced no element.
]]),
                    entry("xmlhandler.tree.options", "handler.options", "field",
                        "Tree handler options.",
                        [[
Handler options table.  The only supported field is `noreduce`, a table of
tag names that should stay as arrays even when they contain a single child.

```lua
local handler = require("xmlhandler.tree"):new()
handler.options.noreduce.item = true
```

The parser also sets `parseAttributes` on the handler for each parse call.
]]),
                }, { upstream = "https://github.com/manoelcampos/xml2lua", license = "MIT" }),

                module("xmlhandler.dom", "xmlhandler.dom", "Build a DOM-like node tree from XML.", [==[
`xmlhandler.dom` builds a tree of typed nodes instead of the natural Lua table
produced by `xmlhandler.tree`.  Every node has a `_type` field:

| Node type | Contents |
| --- | --- |
| `ROOT` | Document node; `_children` holds the document contents. |
| `ELEMENT` | `_name`, optional `_attr`, and `_children`. |
| `TEXT` | `_text` containing character data. |
| `COMMENT` | `_text` containing the comment body. |
| `PI` | Processing instruction with `_name` and optional `_attr`. |
| `DECL` | XML declaration with `_name` and `_attr`. |
| `DTD` | DOCTYPE declaration with `_name` and `_text`. |

Use `handler:new()` for each document.  After parsing, `handler.root` is the
`ROOT` node and `handler:toXml(handler.root)` renders the tree back to XML.

```lua
local handler = require("xmlhandler.dom"):new()
require("xml2lua").parser(handler):parse [[<?xml version="1.0"?>
<root><item id="7">value</item></root>]]

print(handler.root._type)                  --> ROOT
print(handler.root._children[2]._name)     --> root
print(handler:toXml(handler.root))
```

Comments, processing instructions, declarations and DTD nodes are included by
default.  Set the corresponding options to false before parsing to omit them:
`commentNode`, `piNode`, `dtdNode` and `declNode`.
]==], {
                    entry("xmlhandler.dom:new", "handler:new()", "method",
                        "Create an independent DOM handler.",
                        [[
Create and return a new DOM handler with an empty document root and tag
stack.

Use a new handler for each document so nodes from different parses are not
mixed.  The handler options can be changed before parsing, for example
`handler.options.commentNode = false`.

```lua
local handler = require("xmlhandler.dom"):new()
handler.options.piNode = false
```
]]),
                    entry("xmlhandler.dom:toXml", "handler:toXml(node)", "method",
                        "Render a DOM node as XML.",
                        [[
Return an XML string for `node` and its descendants.

Elements are indented, attributes are written from `_attr`, and text is escaped
for `&`, `<` and `>`.  Empty elements become self-closing tags.  Comments,
processing instructions, declarations and DTD nodes are rendered in their XML
syntax.

Pass `handler.root` to serialize the complete document.

```lua
local handler = require("xmlhandler.dom"):new()
require("xml2lua").parser(handler):parse("<root><item>value</item></root>")
print(handler:toXml(handler.root))
```
]]),
                    entry("xmlhandler.dom:starttag", "handler:starttag(tag)", "method",
                        "Handle an opening tag event.",
                        [[
Create an `ELEMENT` node for `tag` and append it to the current parent.

The first element becomes `handler.root` during parsing; after the document
closes, `handler.root` is replaced by the `ROOT` document node.  Attributes are
stored in `_attr`, and the element becomes the current parent until its closing
tag.
]]),
                    entry("xmlhandler.dom:endtag", "handler:endtag(tag)", "method",
                        "Handle a closing tag event.",
                        [[
Close the current element and restore its parent.

`tag.name` must match the open element.  When the outermost element closes, the
document `ROOT` node becomes `handler.root` and is used for subsequent
preamble and postamble nodes.

]]),
                    entry("xmlhandler.dom:text", "handler:text(text)", "method",
                        "Handle a text event.",
                        [[
Create a `TEXT` node containing `text` and append it to the current
element's `_children`.

Text nodes are kept separate from element nodes, so the DOM representation
preserves mixed content and whitespace exactly as reported by the parser.
]]),
                    entry("xmlhandler.dom:cdata", "handler:cdata(text)", "method",
                        "Handle a CDATA event.",
                        [[
Create a `TEXT` node from raw CDATA content.

This is an alias of `xmlhandler.dom:text`; entity references inside CDATA are
not expanded.  The node is appended to the current element in the same way as
ordinary text.
]]),
                    entry("xmlhandler.dom:comment", "handler:comment(text)", "method",
                        "Handle a comment event.",
                        [[
Create a `COMMENT` node containing `text` and append it to the current
parent.

Comments are included when `handler.options.commentNode` is true, which is the
default.  Set it to false before parsing to discard comment nodes while still
parsing the surrounding document.
]]),
                    entry("xmlhandler.dom:pi", "handler:pi(tag)", "method",
                        "Handle a processing instruction.",
                        [[
Create a `PI` node from `tag` and append it to the current parent.

`tag.name` is the instruction target and `tag.attrs` holds its attributes.
Processing instructions are included when `handler.options.piNode` is true,
which is the default.
]]),
                    entry("xmlhandler.dom:decl", "handler:decl(tag)", "method",
                        "Handle the XML declaration.",
                        [[
Append a `DECL` node for the XML declaration.

`tag.name` is normally `xml`, and `tag.attrs` contains fields such as `version`
and `encoding`.  Declarations are included when `handler.options.declNode` is
true, which is the default.
]]),
                    entry("xmlhandler.dom:dtd", "handler:dtd(tag)", "method",
                        "Handle a DOCTYPE declaration.",
                        [[
Append a `DTD` node for a DOCTYPE declaration.

`tag.name` is `DOCTYPE` and `tag.value` contains the declaration text, stored
as the node's `_text`.  DOCTYPE nodes are included when
`handler.options.dtdNode` is true, which is the default.
]]),
                    entry("xmlhandler.dom.root", "handler.root", "field",
                        "Document root node.",
                        [[
After parsing, `root` is the `ROOT` node whose `_children` contains the
document in order, including declarations, comments and processing
instructions.

Before parsing, `root` is nil.  During parsing it temporarily points at the
outermost element; `xmlhandler.dom:endtag` replaces it with the document node
when that element closes.
]]),
                    entry("xmlhandler.dom.current", "handler.current", "field",
                        "Current insertion node.",
                        [[
The node that receives new children while parsing.

It starts as the document `ROOT` node, becomes each open element in turn, and
is restored when that element closes.  Custom handler code can use it to add
nodes at the current position.
]]),
                    entry("xmlhandler.dom.options", "handler.options", "field",
                        "DOM handler options.",
                        [[
Options controlling which non-element nodes are included in the tree.

| Option | Description |
| --- | --- |
| `commentNode` | Include comment nodes. |
| `piNode` | Include processing-instruction nodes. |
| `dtdNode` | Include DOCTYPE nodes. |
| `declNode` | Include the XML declaration. |

All four default to true.  Set an option to false before parsing to omit that
kind of node.

```lua
local handler = require("xmlhandler.dom"):new()
handler.options.commentNode = false
```
]]),
                }, { upstream = "https://github.com/manoelcampos/xml2lua", license = "MIT" }),

                module("xmlhandler.print", "xmlhandler.print", "Print XML parser events for debugging.", [==[
`xmlhandler.print` is a debugging handler that writes parser events to standard
output.  It implements the same callbacks as the other handlers.

```lua
local handler = require "xmlhandler.print"
require("xml2lua").parser(handler):parse("<root><item>value</item></root>")
```

The output uses labels such as `Start`, `End`, `Text`, `CDATA`, `Comment`,
`DTD`, `PI` and `XML Decl`.  Attribute lines are prefixed with ` + `.
]==], {
                    entry("xmlhandler.print:starttag", "handler:starttag(tag, start, end)", "method",
                        "Print an opening tag event.",
                        [[
Write the element name and any attributes to standard output.

The output starts with `Start    : ` followed by the tag name.  Each attribute
is printed on its own line as ` + name='value'`.  The `start` and `end`
position arguments are accepted for parser compatibility and are not printed.
]]),
                    entry("xmlhandler.print:endtag", "handler:endtag(tag, start, end)", "method",
                        "Print a closing tag event.",
                        [[
Write `End      : ` followed by the closing tag name to standard output.

The `start` and `end` position arguments are accepted for parser compatibility
and are not printed.
]]),
                    entry("xmlhandler.print:text", "handler:text(text, start, end)", "method",
                        "Print a text event.",
                        [[
Write `Text     : ` followed by the text to standard output.

The text is printed exactly as supplied by the parser, so whitespace stripping
and entity expansion follow the parser options.  Position arguments are
accepted but not printed.
]]),
                    entry("xmlhandler.print:cdata", "handler:cdata(text, start, end)", "method",
                        "Print a CDATA event.",
                        [[
Write `CDATA    : ` followed by the raw CDATA content to standard output.

CDATA is not entity-expanded.  Position arguments are accepted for parser
compatibility and are not printed.
]]),
                    entry("xmlhandler.print:comment", "handler:comment(text, start, end)", "method",
                        "Print a comment event.",
                        [[
Write `Comment  : ` followed by the comment body to standard output.

The body is printed as supplied by the parser.  Position arguments are accepted
for parser compatibility and are not printed.
]]),
                    entry("xmlhandler.print:dtd", "handler:dtd(tag, start, end)", "method",
                        "Print a DOCTYPE event.",
                        [[
Write `DTD      : ` followed by the DOCTYPE name to standard output.

Attributes on `tag` are printed as separate ` + name='value'` lines when
present.  Position arguments are accepted but not printed.
]]),
                    entry("xmlhandler.print:pi", "handler:pi(tag, start, end)", "method",
                        "Print a processing-instruction event.",
                        [[
Write `PI       : ` followed by the instruction target to standard output.

Attributes on `tag` are printed as separate ` + name='value'` lines when
present.  Position arguments are accepted but not printed.
]]),
                    entry("xmlhandler.print:decl", "handler:decl(tag, start, end)", "method",
                        "Print an XML declaration event.",
                        [[
Write `XML Decl : ` followed by the declaration name to standard output.

Attributes such as `version` and `encoding` are printed as separate
` + name='value'` lines.  Position arguments are accepted but not printed.
]]),
                }, { upstream = "https://github.com/manoelcampos/xml2lua", license = "MIT" }),
            },
        },

        {
            id = "tools",
            title = "Command line tools",
            source = "zli",
            -- Rendered as a single chapter without a module subheading.
            flat = true,
            modules = {
                module("tools", "tools", "Tools shipped in the ZLI payload.", [==[
Tools are started with `zli @name`.  Compiled executables can include the same
scripts in their payload.
]==], {
                    entry("@repl", "zli @repl", "tool",
                        "Start the interactive REPL.",
                        [[
Start the interactive Read-Eval-Print Loop.

The REPL runs `~/.config/zli/init.lua`, then `~/.config/zli/repl_init.lua`,
before showing the prompt. The generated `repl_init.lua` preloads every bundled
library: `argparse`, `benchmark`, `crossline`, `collection`, `csv`, `F`,
`filesystem`, `grid`, `gzip`, `httpclient`, `httpserver`, `cjson`, `log`,
`lpeg`, `luaunit`, `luastrip`, `markdown`, `memoize`, `re`, `serpent`,
`sqlite3`, `stream`, `tar`, `timer`, `unzip`, `uuid`, `xlsxmlwriter`,
`xml2lua` and `zip`;
edit that file to change the defaults. History is kept in
`~/.config/zli/repl_history`.

Enter `quit` or `exit`, or press Ctrl-D, to leave. `?expression` pretty-prints
tables and strings, `:help` shows the index, and `:help <name>` or
`:help --search <term>` looks up documentation. Incomplete statements continue
on the next line, and F1 shows the editing help. Running `zli` with no arguments
also starts the REPL.

```bash
zli @repl
```
]]),
                    entry("@sqlite", "zli @sqlite", "tool",
                        "Start the SQLite CLI.",
                        [[
Start the interactive SQLite command line.

The session begins with an in-memory database. A statement is executed when a
line contains `;`; continuation lines use the `>>` prompt. SQL errors are
printed and the session continues.

Commands are also terminated with `;`:

- `open "file.db";` closes the current database and opens a file.
- `close;` closes the current database and starts a new in-memory one.
- `file "script.sql";` executes statements from a file.
- `mode;` prints the current output mode.
- `mode table|csv|json|lua;` selects pretty table, CSV, JSON or Lua-table
  output.
- `quit;` or `exit;` leaves the CLI; Ctrl-D also exits.

History is stored in `~/.config/zli/sqlite_history`.

```bash
zli @sqlite
```
]]),
                    entry("@compile", "zli @compile <config>", "tool",
                        "Package Lua files into a standalone executable.",
                        [[
Create an executable that carries the listed files in its own payload.

The config is required. It may be a table constructor, for example
`output_name = "app"` plus `files = { ... }`, or a chunk that returns such a
table. `output_name` is required. `files` must be a non-empty list; each item is
either a path string or a table with `file` and an optional `name`. The entry
name defaults to the file's basename. Every source file must exist.

The tool copies the running executable, removes an existing payload, appends
the new zip payload and exits. On Windows `.exe` is added to `output_name` when
missing; on Linux the result is made executable (`755`). Errors are printed and
cause exit status `1`.

```lua
return {
    output_name = "myapp",
    files = {
        { file = "src/main.lua", name = "main.lua" },
        { file = "assets/data.txt" },
    },
}
```
]]),
                    entry("@test", "zli @test <file>", "tool",
                        "Run a LuaUnit test file.",
                        [[
Execute a LuaUnit suite from the command line.

The file is read and executed, then LuaUnit runs every test whose name matches
`Test`; the process exits with LuaUnit's status. Test files can define global
tables named `Test...` or use LuaUnit directly. The normal ZLI init script runs
first, so configuration from `~/.config/zli/init.lua` is active. A missing file
argument prints an error and exits with status `1`.

```bash
zli @test test/test_stream.lua
```
]]),
                    entry("@manual", "zli @manual [options]", "tool",
                        "Serve the bundled reference manual.",
                        [[
Serve the bundled reference manual over HTTP.

The manual combines the Lua language and standard-library reference with all
authored library, tool and ZLI documentation. It listens on `127.0.0.1:8080`
by default and opens a browser using the platform launcher unless `--no-open`
is given. `/` (also `/index.html` and `/manual.html`) serves the manual,
`/search...` redirects to `/?q=...`, and `/favicon.ico` returns `204`.
Search runs in the browser from an index embedded in the page; there is no
server-rendered results page. A `?q=` parameter opens the page with search
results.

Options are `--port <port>`, `--address <address>`, `--no-open` and
`--output <file>`. `--output` writes the same self-contained HTML manual to the
file and exits instead of starting the server. Invalid options or values print
usage and exit with status `2`.

```bash
zli @manual --port 9000 --no-open
zli @manual --output /tmp/manual.html
```
]]),
                    entry("@help", "zli @help [options] [query]", "tool",
                        "Look up documentation.",
                        [[
Look up bundled documentation from the command line.

With a query, an exact entry name is shown first; otherwise a ranked result
list is printed. `--search` forces the ranked list, `--list` prints every
documented module and entry (including the Lua standard library), and
`--markdown` emits the generated library reference. A query may be split across
several arguments and is joined with spaces. With no query, a short index is
printed.

`--output <file>` writes the selected output to a file instead of stdout.
`--search` without a query is an error (status `2`), and a query with no matches
prints an error and exits with status `1`.

```bash
zli @help string.byte
zli @help --search trim
zli @help --list
zli @help --markdown --output doc/libraries.md
```
]]),
                    entry("@serve", "zli @serve [directory]", "tool",
                        "Serve a directory over HTTP.",
                        [[
Start a static file server for a directory.

The directory defaults to `./`. The tool listens on `127.0.0.1:8080`, prints
the URL, tries to open a browser on Windows or Linux, and serves the tree with
caching of static files disabled. Directories use `index.html` or `index.htm`
when present and otherwise produce a listing. Path traversal outside the web
root is rejected and MIME types come from the built-in `httpserver` table.

Only the first argument is used; the server blocks until the process is
stopped.

```bash
zli @serve ./public
zli @serve
```
]]),
                }),
            },
        },

        {
            id = "zli_topics",
            title = "ZLI",
            source = "zli",
            -- Rendered as a single chapter without a module subheading.
            flat = true,
            modules = {
                module("ZLI", "ZLI runtime", "Interpreter globals and configuration.", [==[
The `ZLI` table is available to every script and REPL session.
]==], {
                    entry("ZLI.version", "ZLI.version", "field",
                        "The ZLI version string.",
                        [[
Version string of the running ZLI build.

The value comes from the version file embedded in the binary, for example
`"0.2.1"`. It is a string and should be treated as read-only.

```lua
print(ZLI.version)
```
]]),
                    entry("ZLI.error_handling", "ZLI.error_handling", "field", "Default error style for libraries.", "Set to `\"raise\"` before `require` to make libraries raise instead of returning `nil, message`."),
                    entry("ZLI.exe_path", "ZLI.exe_path", "field",
                        "The real path of the running executable.",
                        [[
Real filesystem path of the running executable.

ZLI resolves the executable path at startup instead of trusting `argv[0]`, so
the value remains usable when the binary is found through `PATH` or invoked
through a symlink. `@compile` uses it as the source binary to copy. The field is
a string and is read-only.

```lua
print(ZLI.exe_path)
```
]]),
                    entry("ZLI.dofile", "ZLI.dofile(name)", "function",
                        "Run a script from the payload.",
                        [[
Run a Lua script stored in the attached payload.

`name` is looked up as written and then with a `.lua` suffix, so both `tool` and
`tool.lua` work; `dir/tool` is supported. The script runs with the current
global environment and `arg` table. Errors, including a missing payload or
missing script, are raised; the function does not return a value.

This is the mechanism behind startup selection and is available to scripts that
want to invoke another payload entry.

```lua
local ok, err = pcall(ZLI.dofile, "does-not-exist")
print(ok, err) --> false  script 'does-not-exist' not found in payload
```
]]),
                    entry("zli.init", "~/.config/zli/init.lua", "topic",
                        "User init script.",
                        [[
User init script, executed before every script and REPL session.

The file lives at `~/.config/zli/init.lua`. ZLI creates the configuration
directory and a commented starter file on first use. The script runs in the
global environment after the standard libraries and the `ZLI` table are
available, so it can set `ZLI.error_handling`, define helper globals, or preload
modules; anything it leaves global is visible to the selected program. An error
in this file aborts startup.

```lua
-- ~/.config/zli/init.lua
ZLI.error_handling = "raise"
function greet(name)
    return "hello " .. name
end
```
]]),
                    entry("zli.repl_init", "~/.config/zli/repl_init.lua", "topic",
                        "REPL init script.",
                        [[
REPL-only init script.

The file lives at `~/.config/zli/repl_init.lua` and is executed by `@repl`
after the global `init.lua`. If missing, the REPL creates it with assignments
for every bundled library: `argparse`, `benchmark`, `crossline`, `collection`,
`csv`, `F`, `filesystem`, `grid`, `gzip`, `httpclient`, `httpserver`, `cjson`,
`log`, `lpeg`, `luaunit`, `luastrip`, `markdown`, `memoize`, `re`, `serpent`,
`sqlite3`, `stream`, `tar`, `timer`, `unzip`, `uuid`, `xlsxmlwriter`,
`xml2lua` and `zip`.
Use it for prompt helpers and other state that should exist only in interactive
sessions; errors abort the REPL.

```lua
-- ~/.config/zli/repl_init.lua
function reload(name)
    package.loaded[name] = nil
    return require(name)
end
```
]]),
                    entry("zli.payload", "payload", "topic",
                        "Embedded zip payload.",
                        [[
The zip archive appended to the ZLI executable.

The payload holds `main.lua`, the command line tools, library modules and
documentation. `zli @name` runs `name` or `name.lua` from it, and `@dir/name`
is supported. Lua's `require` also searches the payload for `name.lua` and
`name/init.lua`, so bundled modules load without being extracted. The payload
is opened through the real executable path, which keeps it available when the
binary is reached through `PATH` or a symlink.

Compiled executables created by `@compile` replace the standard payload with
the files listed in their config. A binary without an attached payload cannot
run `@` tools or `ZLI.dofile`.

```bash
zli @repl
zli @help string.byte
```
]]),
                    entry("zli.argv0", "argv[0] and payload selection", "topic", "How the executable name selects a payload script.", [==[When no tool or script is given, ZLI selects a payload entry from the executable basename: `<exe-name>.lua` first, then `main.lua`, then `init.lua`.  On Windows, a trailing `.exe` is stripped from the basename.

The basename comes from `argv[0]`, so symlinks with different names can select different payload tools from the same executable.  The payload zip itself is opened through the real executable path, so the binary also works when found through `PATH`.

The Lua `arg[0]` value remains the executable name used to invoke ZLI; the selected payload script is not substituted into the argument table.  This is also true for filesystem scripts: the script path is not reflected in `arg[0]`.]==]),
                    entry("zli.compile", "compiled executables", "topic",
                        "Standalone executables created by `@compile`.",
                        [[
Standalone executables produced by `@compile`.

A compiled executable is a copy of ZLI with its standard payload replaced by
the files in the compile config. At startup it still runs
`~/.config/zli/init.lua`; then it selects `<executable-name>.lua`, `main.lua` or
`init.lua` from the new payload. A specific payload entry can be started with
`zli @name`, including `@dir/name`. On Windows the executable suffix is added
automatically; on Linux the output is marked executable.

The executable remains a full ZLI binary: standard libraries and native
bindings are available, but the bundled documentation and tools are only
present if their files were included in the config.

```bash
zli @compile myapp.lua
./myapp
```
]]),
                }),
            },
        },
    },
}