diff --git a/docs/src/mods/api/duration.md b/docs/src/mods/api/duration.md index 77fbdf3..b1480e1 100644 --- a/docs/src/mods/api/duration.md +++ b/docs/src/mods/api/duration.md @@ -1,15 +1,15 @@ --- title: "duration" -description: - "Reusable immutable duration values for date arithmetic and formatting." +description: "Represent, calculate, and humanize time spans." --- -Reusable immutable duration values for date arithmetic and formatting. +Represent, calculate, and humanize time spans. ## Usage ```lua -local Duration = require "mods.duration" +local mods = require "mods" +local Duration = mods.duration local shift = Duration({ day = 2, hour = 3 }) print(shift:format("D [days] HH:mm")) --> 2 days 03:00 @@ -17,27 +17,22 @@ print(shift:format("D [days] HH:mm")) --> 2 days 03:00 ## Functions -| Function | Description | -| ---------------------- | ------------------------------------------------------------------------------------------------------------ | -| [`new(input, unit?)`] | Create a duration from a numeric amount and unit. | -| [`new(input?)`] | Create a duration from numeric parts, an ISO 8601 string, or another duration. | -| [`is_duration(value)`] | Return `true` when the value is a duration created by [`mods.duration(...)`] or [`mods.date.duration(...)`]. | - -**Duration**: - -| Function | Description | -| ----------------------------------------------- | ------------------------------------------------------------------------- | -| [`add(value, unit?)`] | Return a new duration with another duration or unit amount added. | -| [`as(unit)`] | Return the duration expressed in the requested unit. | -| [`clone()`] | Return a shallow copy of the duration value. | -| [`compare(other)`] | Compare this duration to another duration-like value. | -| [`equals(other)`] | Return `true` when both duration values have identical components. | -| [`format(pattern)`] | Format the duration using duration tokens like `Y`, `MM`, `DD`, and `HH`. | -| [`humanize(with_suffix_or_options?, options?)`] | Return a human-readable relative-style phrase for the duration. | -| [`normalize()`] | Return a compacted duration using the module's canonical carry rules. | -| [`subtract(value, unit?)`] | Return a new duration with another duration or unit amount subtracted. | -| [`to_iso()`] | Return an ISO 8601 duration string. | -| [`tostring()`] | Return a debug-friendly string representation of the duration. | +| Function | Description | +| ----------------------------------------------- | ------------------------------------------------------------------------------ | +| [`new(input, unit?)`] | Create a duration from a numeric amount and unit. | +| [`new(input?)`] | Create a duration from numeric parts, an ISO 8601 string, or another duration. | +| [`add(value, unit?)`] | Return a new duration with another duration or unit amount added. | +| [`as(unit)`] | Return the duration expressed in the requested unit. | +| [`clone()`] | Return a shallow copy of the duration value. | +| [`compare(other)`] | Compare this duration to another duration-like value. | +| [`equals(other)`] | Return `true` when both duration values have identical components. | +| [`format(pattern)`] | Format the duration using duration tokens like `Y`, `MM`, `DD`, and `HH`. | +| [`humanize(with_suffix_or_options?, options?)`] | Return a human-readable relative-style phrase for the duration. | +| [`is_duration(value)`] | Return `true` when the value is a duration created by [`mods.duration(...)`]. | +| [`normalize()`] | Return a compacted duration using the module's canonical carry rules. | +| [`subtract(value, unit?)`] | Return a new duration with another duration or unit amount subtracted. | +| [`to_iso()`] | Return an ISO 8601 duration string. | +| [`tostring()`] | Return a debug-friendly string representation of the duration. | **Metamethods**: @@ -55,8 +50,8 @@ Create a duration from a numeric amount and unit. **Parameters**: - `input` (`number`): Numeric amount to convert into a duration. -- `unit?` ([`mods.DateUnit`]): Unit used with the numeric amount. Defaults to - `"ms"`. +- `unit?` ([`mods.durationUnit`]): Unit used with the numeric amount. Defaults + to `"ms"`. **Returns**: @@ -88,36 +83,12 @@ Create a duration from numeric parts, an ISO 8601 string, or another duration. ```lua local a = Duration({ day = 2, hour = 3 }) local b = Duration("PT1H30M") +local c = Duration(a) ``` --- -### `is_duration(value)` {#is-duration} - -Return `true` when the value is a duration created by [`mods.duration(...)`] or -[`mods.date.duration(...)`]. - -**Parameters**: - -- `value` (`any`) - -**Returns**: - -- `isDuration` (`boolean`) - -**Example**: - -```lua -local Duration = require "mods.duration" -print(Duration.is_duration(Duration({ day = 2 }))) --> true -print(Duration.is_duration({ day = 2 })) --> false -``` - ---- - -### Duration - -#### `add(value, unit?)` {#add} +### `add(value, unit?)` {#add} Return a new duration with another duration or unit amount added. @@ -125,7 +96,7 @@ Return a new duration with another duration or unit amount added. - `value` (`number` | [`mods.DurationParts`] | [`mods.Duration`]): Signed amount to add, or another duration value. -- `unit?` ([`mods.DateUnit`]): Unit used when `value` is a number. +- `unit?` ([`mods.durationUnit`]): Unit used when `value` is a number. **Returns**: @@ -134,7 +105,6 @@ Return a new duration with another duration or unit amount added. **Example**: ```lua -local Duration = require "mods.duration" local a = Duration({ day = 2 }) local b = a:add(3, "hour") print(b:format("D [days] HH:mm:ss")) --> 2 days 03:00:00 @@ -142,13 +112,13 @@ print(b:format("D [days] HH:mm:ss")) --> 2 days 03:00:00 --- -#### `as(unit)` {#as} +### `as(unit)` {#as} Return the duration expressed in the requested unit. **Parameters**: -- `unit` ([`mods.DateUnit`]) +- `unit` ([`mods.durationUnit`]): Milliseconds **Returns**: @@ -157,14 +127,13 @@ Return the duration expressed in the requested unit. **Example**: ```lua -local Duration = require "mods.duration" local d = Duration({ day = 1, hour = 12 }) print(d:as("hour")) --> 36 ``` --- -#### `clone()` {#clone} +### `clone()` {#clone} Return a shallow copy of the duration value. @@ -175,7 +144,6 @@ Return a shallow copy of the duration value. **Example**: ```lua -local Duration = require "mods.duration" local d = Duration({ month = 1, day = 2 }) local copy = d:clone() print(copy == d, rawequal(copy, d)) --> true false @@ -183,7 +151,7 @@ print(copy == d, rawequal(copy, d)) --> true false --- -#### `compare(other)` {#compare} +### `compare(other)` {#compare} Compare this duration to another duration-like value. @@ -200,13 +168,12 @@ Returns `-1` when smaller, `0` when equal, and `1` when larger. **Example**: ```lua -local Duration = require "mods.duration" print(Duration({ day = 1 }):compare({ hour = 24 })) --> 0 ``` --- -#### `equals(other)` {#equals} +### `equals(other)` {#equals} Return `true` when both duration values have identical components. @@ -221,7 +188,6 @@ Return `true` when both duration values have identical components. **Example**: ```lua -local Duration = require "mods.duration" local a = Duration({ day = 2 }) local b = Duration({ day = 2 }) print(a:equals(b)) --> true @@ -229,7 +195,7 @@ print(a:equals(b)) --> true --- -#### `format(pattern)` {#format} +### `format(pattern)` {#format} Format the duration using duration tokens like `Y`, `MM`, `DD`, and `HH`. @@ -244,14 +210,13 @@ Format the duration using duration tokens like `Y`, `MM`, `DD`, and `HH`. **Example**: ```lua -local Duration = require "mods.duration" local d = Duration({ day = 2, hour = 3, minute = 4 }) print(d:format("D [days] HH:mm")) --> 2 days 03:04 ``` --- -#### `humanize(with_suffix_or_options?, options?)` {#humanize} +### `humanize(with_suffix_or_options?, options?)` {#humanize} Return a human-readable relative-style phrase for the duration. @@ -273,7 +238,6 @@ output or explicit unit clamping. **Example**: ```lua -local Duration = require "mods.duration" local d = Duration({ day = 3 }) print(d:humanize()) --> 3 days print(d:humanize(true)) --> in 3 days @@ -282,7 +246,28 @@ print(d:humanize({ short = true })) --> 3d --- -#### `normalize()` {#normalize} +### `is_duration(value)` {#is-duration} + +Return `true` when the value is a duration created by [`mods.duration(...)`]. + +**Parameters**: + +- `value` (`any`) + +**Returns**: + +- `isDuration` (`boolean`) + +**Example**: + +```lua +print(Duration.is_duration(Duration({ day = 2 }))) --> true +print(Duration.is_duration({ day = 2 })) --> false +``` + +--- + +### `normalize()` {#normalize} Return a compacted duration using the module's canonical carry rules. @@ -293,13 +278,12 @@ Return a compacted duration using the module's canonical carry rules. **Example**: ```lua -local Duration = require "mods.duration" print(Duration({ minute = 90 }):normalize()) --> duration(hours=1, minutes=30) ``` --- -#### `subtract(value, unit?)` {#subtract} +### `subtract(value, unit?)` {#subtract} Return a new duration with another duration or unit amount subtracted. @@ -307,7 +291,7 @@ Return a new duration with another duration or unit amount subtracted. - `value` (`number` | [`mods.DurationParts`] | [`mods.Duration`]): Signed amount to subtract, or another duration value. -- `unit?` ([`mods.DateUnit`]): Unit used when `value` is a number. +- `unit?` ([`mods.durationUnit`]): Unit used when `value` is a number. **Returns**: @@ -316,7 +300,6 @@ Return a new duration with another duration or unit amount subtracted. **Example**: ```lua -local Duration = require "mods.duration" local a = Duration({ day = 2, hour = 3 }) local b = a:subtract(3, "hour") print(b:format("D [days] HH:mm:ss")) --> 2 days 00:00:00 @@ -324,7 +307,7 @@ print(b:format("D [days] HH:mm:ss")) --> 2 days 00:00:00 --- -#### `to_iso()` {#to-iso} +### `to_iso()` {#to-iso} Return an ISO 8601 duration string. @@ -335,13 +318,12 @@ Return an ISO 8601 duration string. **Example**: ```lua -local Duration = require "mods.duration" print(Duration({ hour = 1, minute = 30 }):to_iso()) --> PT1H30M ``` --- -#### `tostring()` {#tostring} +### `tostring()` {#tostring} Return a debug-friendly string representation of the duration. @@ -352,7 +334,6 @@ Return a debug-friendly string representation of the duration. **Example**: ```lua -local Duration = require "mods.duration" print(Duration({ day = 2, hour = 3 })) --> duration(days=2, hours=3) ``` @@ -367,8 +348,8 @@ Create a duration from a numeric amount and unit. **Parameters**: - `input` (`number`): Numeric amount to convert into a duration. -- `unit?` ([`mods.DateUnit`]): Unit used with the numeric amount. Defaults to - `"ms"`. +- `unit?` ([`mods.durationUnit`]): Unit used with the numeric amount. Defaults + to `"ms"`. **Returns**: @@ -377,7 +358,6 @@ Create a duration from a numeric amount and unit. **Example**: ```lua -local Duration = require "mods.duration" local d = Duration(90, "minute") ``` @@ -399,9 +379,9 @@ Create a duration from numeric parts, an ISO 8601 string, or another duration. **Example**: ```lua -local Duration = require "mods.duration" local a = Duration({ day = 2, hour = 3 }) local b = Duration("PT1H30M") +local c = Duration(a) ``` --- @@ -421,7 +401,6 @@ Return `true` when both duration values have identical components. **Example**: ```lua -local Duration = require "mods.duration" print(Duration({ day = 2 }) == Duration({ day = 2 })) --> true ``` @@ -438,7 +417,6 @@ Return the same result as `tostring()` when coerced to a string. **Example**: ```lua -local Duration = require "mods.duration" print(Duration({ day = 2 })) --> duration(days=2) ``` @@ -455,12 +433,11 @@ print(Duration({ day = 2 })) --> duration(days=2) [`format(pattern)`]: #format [`humanize(with_suffix_or_options?, options?)`]: #humanize [`is_duration(value)`]: #is-duration -[`mods.DateUnit`]: /mods/types#mods-dateunit [`mods.DurationHumanizeOptions`]: /mods/types#mods-durationhumanizeoptions [`mods.DurationParts`]: /mods/types#mods-durationparts [`mods.Duration`]: /mods/api/duration -[`mods.date.duration(...)`]: /mods/api/date#duration [`mods.duration(...)`]: /mods/api/duration +[`mods.durationUnit`]: /mods/types#mods-durationunit [`new(input, unit?)`]: #new-1 [`new(input?)`]: #new [`normalize()`]: #normalize diff --git a/docs/src/mods/api/fs.md b/docs/src/mods/api/fs.md index a522f14..cef642f 100644 --- a/docs/src/mods/api/fs.md +++ b/docs/src/mods/api/fs.md @@ -549,13 +549,13 @@ Iterator over items in `path`. - `path` (`string`): Input path. - `opts?` - (`{hidden?:boolean, recursive?:boolean, follow?:boolean, type?:`[`mods.FsEntryType`]`}`): + (`{hidden?:boolean, recursive?:boolean, follow?:boolean, type?:`[`mods.fsEntryType`]`}`): Optional traversal options. **Returns**: - `iterator?` - (`(fun(state:table, prev?:string):basename?: string, type?: `[`mods.FsEntryType`]`)`): + (`(fun(state:table, prev?:string):basename?: string, type?: `[`mods.fsEntryType`]`)`): Iterator, or `nil` on failure. - `state` (`table` | `string`): Iterator state on success, or error message on failure. @@ -587,7 +587,7 @@ Return direct children of a directory. - `path` (`string`): Input path. - `opts?` - (`{hidden?:boolean, recursive?:boolean, follow?:boolean, type?:`[`mods.FsEntryType`]`, names?:boolean}`): + (`{hidden?:boolean, recursive?:boolean, follow?:boolean, type?:`[`mods.fsEntryType`]`, names?:boolean}`): Optional traversal options. **Returns**: @@ -663,8 +663,8 @@ fs.read_text("README.md") [`listdir(path, opts?)`]: #listdir [`lstat(path)`]: #lstat [`mkdir(path, parents?)`]: #mkdir -[`mods.FsEntryType`]: /mods/types#mods-fsentrytype [`mods.List`]: /mods/api/list +[`mods.fsEntryType`]: /mods/types#mods-fsentrytype [`read_bytes(path)`]: #read-bytes [`read_text(path)`]: #read-text [`rename(oldname, newname)`]: #rename diff --git a/docs/src/mods/api/glob.md b/docs/src/mods/api/glob.md index 6920ac6..8c27903 100644 --- a/docs/src/mods/api/glob.md +++ b/docs/src/mods/api/glob.md @@ -121,7 +121,7 @@ Return glob matches under `path`. - `path` (`string`): Input path. - `pattern?` (`string`): Optional pattern to match. -- `opts?` ([`mods.globOptions`]): Optional glob options. +- `opts?` ([`mods.GlobOptions`]): Optional glob options. **Returns**: @@ -165,7 +165,7 @@ Iterator over glob matches under `path`. - `path` (`string`): Input path. - `pattern?` (`string`): Optional pattern to match. -- `opts?` ([`mods.globOptions`]): Optional glob options. +- `opts?` ([`mods.GlobOptions`]): Optional glob options. **Returns**: @@ -253,7 +253,7 @@ print(matches == translated_matches) --> true [`has_magic(s)`]: #has-magic [`iglob(path, pattern?, opts?)`]: #iglob [`match(path, pattern, ignorecase?)`]: #match +[`mods.GlobOptions`]: /mods/types#mods-globoptions [`mods.List`]: /mods/api/list -[`mods.globOptions`]: /mods/types#mods-globoptions [`translate(pattern)`]: #translate diff --git a/docs/src/mods/api/is.md b/docs/src/mods/api/is.md index 4889086..fb44813 100644 --- a/docs/src/mods/api/is.md +++ b/docs/src/mods/api/is.md @@ -49,45 +49,51 @@ is("hello", "STRING") --> true **Path Checks**: -| Function | Description | -| ------------- | ------------------------------------------------------------ | -| [`block(v)`] | Returns `true` when `v` is a block device path. | -| [`char(v)`] | Returns `true` when `v` is a character device path. | -| [`device(v)`] | Returns `true` when `v` is a block or character device path. | -| [`dir(v)`] | Returns `true` when `v` is a directory path. | -| [`fifo(v)`] | Returns `true` when `v` is a FIFO path. | -| [`file(v)`] | Returns `true` when `v` is a file path. | -| [`link(v)`] | Returns `true` when `v` is a symlink path. | -| [`path(v)`] | Returns `true` when `v` is a valid filesystem path. | -| [`socket(v)`] | Returns `true` when `v` is a socket path. | +| Function | Description | +| ------------------- | ------------------------------------------------------------ | +| [`block_device(v)`] | Returns `true` when `v` is a block device path. | +| [`char_device(v)`] | Returns `true` when `v` is a character device path. | +| [`device(v)`] | Returns `true` when `v` is a block or character device path. | +| [`dir(v)`] | Returns `true` when `v` is a directory path. | +| [`fifo(v)`] | Returns `true` when `v` is a FIFO path. | +| [`file(v)`] | Returns `true` when `v` is a file path. | +| [`path(v)`] | Returns `true` when `v` is a valid filesystem path. | +| [`socket(v)`] | Returns `true` when `v` is a socket path. | +| [`symlink(v)`] | Returns `true` when `v` is a symlink path. | **Type Checks**: -| Function | Description | -| --------------- | -------------------------------------- | -| [`boolean(v)`] | Returns `true` when `v` is a boolean. | -| [`function(v)`] | Returns `true` when `v` is a function. | -| [`nil(v)`] | Returns `true` when `v` is `nil`. | -| [`number(v)`] | Returns `true` when `v` is a number. | -| [`string(v)`] | Returns `true` when `v` is a string. | -| [`table(v)`] | Returns `true` when `v` is a table. | -| [`thread(v)`] | Returns `true` when `v` is a thread. | -| [`userdata(v)`] | Returns `true` when `v` is userdata. | +| Function | Description | +| --------------- | ------------------------------------------------------- | +| [`Function(v)`] | Returns `true` when `v` is a function. | +| [`Nil(v)`] | Returns `true` when `v` is `nil`. | +| [`boolean(v)`] | Returns `true` when `v` is a boolean. | +| [`cdata(v)`] | Returns `true` when `v` is a cdata value (LuaJIT only). | +| [`number(v)`] | Returns `true` when `v` is a number. | +| [`string(v)`] | Returns `true` when `v` is a string. | +| [`table(v)`] | Returns `true` when `v` is a table. | +| [`thread(v)`] | Returns `true` when `v` is a thread. | +| [`userdata(v)`] | Returns `true` when `v` is userdata. | **Value Checks**: -| Function | Description | -| --------------- | ------------------------------------------- | -| [`callable(v)`] | Returns `true` when `v` is callable. | -| [`false(v)`] | Returns `true` when `v` is exactly `false`. | -| [`falsy(v)`] | Returns `true` when `v` is falsy. | -| [`integer(v)`] | Returns `true` when `v` is an integer. | -| [`true(v)`] | Returns `true` when `v` is exactly `true`. | -| [`truthy(v)`] | Returns `true` when `v` is truthy. | +| Function | Description | +| --------------- | ------------------------------------------------------ | +| [`False(v)`] | Returns `true` when `v` is exactly `false`. | +| [`True(v)`] | Returns `true` when `v` is exactly `true`. | +| [`callable(v)`] | Returns `true` when `v` is callable. | +| [`defined(v)`] | Returns `true` when `v` is defined (not `nil`). | +| [`falsy(v)`] | Returns `true` when `v` is falsy. | +| [`finite(v)`] | Returns `true` when `v` is a finite number. | +| [`float(v)`] | Returns `true` when `v` is a float number. | +| [`infinite(v)`] | Returns `true` when `v` is an infinite number. | +| [`integer(v)`] | Returns `true` when `v` is an integer. | +| [`nan(v)`] | Returns `true` when `v` is a NaN (not-a-number) value. | +| [`truthy(v)`] | Returns `true` when `v` is truthy. | ### Path Checks -#### `block(v)` {#block} +#### `block_device(v)` {#block-device} Returns `true` when `v` is a block device path. @@ -97,17 +103,17 @@ Returns `true` when `v` is a block device path. **Returns**: -- `isBlock` (`boolean`): Whether the check succeeds. +- `isBlockDevice` (`boolean`): Whether the check succeeds. **Example**: ```lua -is.block("/dev/sda") +is.block_device("/dev/sda") ``` --- -#### `char(v)` {#char} +#### `char_device(v)` {#char-device} Returns `true` when `v` is a character device path. @@ -117,12 +123,12 @@ Returns `true` when `v` is a character device path. **Returns**: -- `isChar` (`boolean`): Whether the check succeeds. +- `isCharDevice` (`boolean`): Whether the check succeeds. **Example**: ```lua -is.char("/dev/null") +is.char_device("/dev/null") ``` --- @@ -207,26 +213,6 @@ is.file("README.md") --- -#### `link(v)` {#link} - -Returns `true` when `v` is a symlink path. - -**Parameters**: - -- `v` (`any`): Value to validate. - -**Returns**: - -- `isLink` (`boolean`): Whether the check succeeds. - -**Example**: - -```lua -is.link("/path/to/link") -``` - ---- - #### `path(v)` {#path} Returns `true` when `v` is a valid filesystem path. @@ -271,11 +257,9 @@ is.socket("/path/to/socket") --- -### Type Checks - -#### `boolean(v)` {#boolean} +#### `symlink(v)` {#symlink} -Returns `true` when `v` is a boolean. +Returns `true` when `v` is a symlink path. **Parameters**: @@ -283,17 +267,19 @@ Returns `true` when `v` is a boolean. **Returns**: -- `isBoolean` (`boolean`): Whether the check succeeds. +- `isSymlink` (`boolean`): Whether the check succeeds. **Example**: ```lua -is.boolean(true) +is.symlink("/path/to/link") ``` --- -#### `function(v)` {#function} +### Type Checks + +#### `Function(v)` {#function} Returns `true` when `v` is a function. @@ -313,7 +299,7 @@ is.Function(function() end) --- -#### `nil(v)` {#nil} +#### `Nil(v)` {#nil} Returns `true` when `v` is `nil`. @@ -333,6 +319,46 @@ is.Nil(nil) --- +#### `boolean(v)` {#boolean} + +Returns `true` when `v` is a boolean. + +**Parameters**: + +- `v` (`any`): Value to validate. + +**Returns**: + +- `isBoolean` (`boolean`): Whether the check succeeds. + +**Example**: + +```lua +is.boolean(true) +``` + +--- + +#### `cdata(v)` {#cdata} + +Returns `true` when `v` is a cdata value (LuaJIT only). + +**Parameters**: + +- `v` (`any`): Value to validate. + +**Returns**: + +- `isCdata` (`boolean`): Whether the check succeeds. + +**Example**: + +```lua +is.cdata(v) +``` + +--- + #### `number(v)` {#number} Returns `true` when `v` is a number. @@ -435,6 +461,46 @@ is.userdata(io.stdout) ### Value Checks +#### `False(v)` {#false} + +Returns `true` when `v` is exactly `false`. + +**Parameters**: + +- `v` (`any`): Value to validate. + +**Returns**: + +- `isFalse` (`boolean`): Whether the check succeeds. + +**Example**: + +```lua +is.False(false) +``` + +--- + +#### `True(v)` {#true} + +Returns `true` when `v` is exactly `true`. + +**Parameters**: + +- `v` (`any`): Value to validate. + +**Returns**: + +- `isTrue` (`boolean`): Whether the check succeeds. + +**Example**: + +```lua +is.True(true) +``` + +--- + #### `callable(v)` {#callable} Returns `true` when `v` is callable. @@ -455,9 +521,9 @@ is.callable(function() end) --- -#### `false(v)` {#false} +#### `defined(v)` {#defined} -Returns `true` when `v` is exactly `false`. +Returns `true` when `v` is defined (not `nil`). **Parameters**: @@ -465,12 +531,14 @@ Returns `true` when `v` is exactly `false`. **Returns**: -- `isFalse` (`boolean`): Whether the check succeeds. +- `isDefined` (`boolean`): Whether the check succeeds. **Example**: ```lua -is.False(false) +is.defined(1) --> true +is.defined(false) --> true +is.defined(nil) --> false ``` --- @@ -495,6 +563,67 @@ is.falsy(false) --- +#### `finite(v)` {#finite} + +Returns `true` when `v` is a finite number. + +**Parameters**: + +- `v` (`any`): Value to validate. + +**Returns**: + +- `isFinite` (`boolean`): Whether the check succeeds. + +**Example**: + +```lua +is.finite(42) --> true +``` + +--- + +#### `float(v)` {#float} + +Returns `true` when `v` is a float number. + +**Parameters**: + +- `v` (`any`): Value to validate. + +**Returns**: + +- `isFloat` (`boolean`): Whether the check succeeds. + +**Example**: + +```lua +is.float(1.5) --> true +is.float(1.0) --> true (on Lua >= 5.3) or false (on Lua <= 5.2) +``` + +--- + +#### `infinite(v)` {#infinite} + +Returns `true` when `v` is an infinite number. + +**Parameters**: + +- `v` (`any`): Value to validate. + +**Returns**: + +- `isInfinite` (`boolean`): Whether the check succeeds. + +**Example**: + +```lua +is.infinite(math.huge) --> true +``` + +--- + #### `integer(v)` {#integer} Returns `true` when `v` is an integer. @@ -515,9 +644,9 @@ is.integer(42) --- -#### `true(v)` {#true} +#### `nan(v)` {#nan} -Returns `true` when `v` is exactly `true`. +Returns `true` when `v` is a NaN (not-a-number) value. **Parameters**: @@ -525,12 +654,12 @@ Returns `true` when `v` is exactly `true`. **Returns**: -- `isTrue` (`boolean`): Whether the check succeeds. +- `isNan` (`boolean`): Whether the check succeeds. **Example**: ```lua -is.True(true) +is.nan(0/0) ``` --- @@ -554,28 +683,34 @@ is.truthy("non-empty") ``` -[`block(v)`]: #block +[`False(v)`]: #false +[`Function(v)`]: #function +[`Nil(v)`]: #nil +[`True(v)`]: #true +[`block_device(v)`]: #block-device [`boolean(v)`]: #boolean [`callable(v)`]: #callable -[`char(v)`]: #char +[`cdata(v)`]: #cdata +[`char_device(v)`]: #char-device +[`defined(v)`]: #defined [`device(v)`]: #device [`dir(v)`]: #dir -[`false(v)`]: #false [`falsy(v)`]: #falsy [`fifo(v)`]: #fifo [`file(v)`]: #file -[`function(v)`]: #function +[`finite(v)`]: #finite +[`float(v)`]: #float +[`infinite(v)`]: #infinite [`integer(v)`]: #integer [`lfs`]: https://github.com/lunarmodules/luafilesystem -[`link(v)`]: #link -[`nil(v)`]: #nil +[`nan(v)`]: #nan [`number(v)`]: #number [`path(v)`]: #path [`socket(v)`]: #socket [`string(v)`]: #string +[`symlink(v)`]: #symlink [`table(v)`]: #table [`thread(v)`]: #thread -[`true(v)`]: #true [`truthy(v)`]: #truthy [`userdata(v)`]: #userdata diff --git a/docs/src/mods/api/list.md b/docs/src/mods/api/list.md index 2dd7074..738293a 100644 --- a/docs/src/mods/api/list.md +++ b/docs/src/mods/api/list.md @@ -1,5 +1,5 @@ --- -title: "List" +title: "list" description: "A list class for creating, transforming, and querying sequences of values." --- @@ -66,14 +66,14 @@ print(ls:index("b")) --> 2 **Queries**: -| Function | Description | -| ------------------ | ----------------------------------------------------------- | -| [`contains(v)`] | Return `true` if the list contains the value. | -| [`count(v)`] | Count how many times a value appears. | -| [`index(v)`] | Return the index of the first matching value. | -| [`index_if(pred)`] | Return the index of the first value matching the predicate. | -| [`isempty()`] | Return whether the list has no elements. | -| [`len()`] | Return the number of elements in the list. | +| Function | Description | +| ------------------ | ----------------------------------------------------------------------------- | +| [`contains(v)`] | Return `true` if the list contains the value. | +| [`count(v)`] | Count how many times a value appears. | +| [`index(v)`] | Return the index of the first matching value. | +| [`index_if(pred)`] | Return the index of the first value matching the predicate. | +| [`isempty()`] | Return whether the list has no elements. | +| [`len()`] | Return the length of the list, defined by its maximum positive integer index. | **Transforms**: @@ -666,22 +666,18 @@ ok = List():isempty() --> true #### `len()` {#len} -Return the number of elements in the list. +Return the length of the list, defined by its maximum positive integer index. **Returns**: -- `count` (`integer`): Element count. +- `length` (`integer`): List length. **Example**: ```lua -n = List({ "a", "b", "c" }):len() --> 3 +n = List({ "a", nil, "c" }):len() --> 3 ``` -> [!NOTE] -> -> Uses Lua's `#` operator. - --- ### Transforms diff --git a/docs/src/mods/api/log.md b/docs/src/mods/api/log.md index fc4d302..5727100 100644 --- a/docs/src/mods/api/log.md +++ b/docs/src/mods/api/log.md @@ -79,7 +79,7 @@ Emit an `info` record. **Parameters**: Emit a record for `level` when it passes the logger filter. **Parameters**: -- `levelname` ([`mods.LogLevel`]): Log level to emit. +- `levelname` ([`mods.logLevel`]): Log level to emit. - `...` (`any`): Additional values joined with spaces. --- @@ -95,9 +95,9 @@ Emit a `warn` record. **Parameters**: [`error(...)`]: #error [`info(...)`]: #info [`log(levelname, ...)`]: #log -[`mods.LogLevel`]: /mods/types#mods-loglevel [`mods.log.logger`]: /mods/types#mods-log-logger [`mods.log.new.opts`]: /mods/types#mods-log-new-opts +[`mods.logLevel`]: /mods/types#mods-loglevel [`new(opts?)`]: #new [`warn(...)`]: #warn diff --git a/docs/src/mods/api/runtime.md b/docs/src/mods/api/runtime.md index 877056d..fa86019 100644 --- a/docs/src/mods/api/runtime.md +++ b/docs/src/mods/api/runtime.md @@ -11,80 +11,35 @@ Lua runtime metadata and version compatibility flags. runtime = mods.runtime print(runtime.version) --> 501 | 502 | 503 | 504 | 505 -print(runtime.is_lua55) --> true | false ``` ## Fields -| Field | Description | -| -------------- | ------------------------------------------------- | -| [`is_lua51`] | True only on Lua 5.1 runtimes. | -| [`is_lua52`] | True only on Lua 5.2 runtimes. | -| [`is_lua53`] | True only on Lua 5.3 runtimes. | -| [`is_lua54`] | True only on Lua 5.4 runtimes. | -| [`is_lua55`] | True only on Lua 5.5 runtimes. | -| [`is_luajit`] | True when running under LuaJIT. | -| [`is_windows`] | True when running on a Windows host. | -| [`major`] | Major version number parsed from `version`. | -| [`minor`] | Minor version number parsed from `version`. | -| [`version`] | Numeric version encoded as `major * 100 + minor`. | +| Field | Description | +| -------------- | ----------------------------------------------------- | +| [`is_luajit`] | True when running under LuaJIT. | +| [`is_unix`] | True when running on a Unix-like host (Linux, macOS). | +| [`is_windows`] | True when running on a Windows host. | +| [`major`] | Major version number parsed from `version`. | +| [`minor`] | Minor version number parsed from `version`. | +| [`version`] | Numeric version encoded as `major * 100 + minor`. | -### `is_lua51` (`boolean`) {#is-lua51} - -True only on Lua 5.1 runtimes. - -```lua -print(runtime.is_lua51) --> true | false -``` - ---- - -### `is_lua52` (`boolean`) {#is-lua52} - -True only on Lua 5.2 runtimes. - -```lua -print(runtime.is_lua52) --> true | false -``` - ---- - -### `is_lua53` (`boolean`) {#is-lua53} - -True only on Lua 5.3 runtimes. - -```lua -print(runtime.is_lua53) --> true | false -``` - ---- - -### `is_lua54` (`boolean`) {#is-lua54} - -True only on Lua 5.4 runtimes. - -```lua -print(runtime.is_lua54) --> true | false -``` - ---- - -### `is_lua55` (`boolean`) {#is-lua55} +### `is_luajit` (`boolean`) {#is-luajit} -True only on Lua 5.5 runtimes. +True when running under LuaJIT. ```lua -print(runtime.is_lua55) --> true | false +print(runtime.is_luajit) --> true | false ``` --- -### `is_luajit` (`boolean`) {#is-luajit} +### `is_unix` (`boolean`) {#is-unix} -True when running under LuaJIT. +True when running on a Unix-like host (Linux, macOS). ```lua -print(runtime.is_luajit) --> true | false +print(runtime.is_unix) --> true | false ``` --- @@ -128,12 +83,8 @@ print(runtime.version) --> 501 | 502 | 503 | 504 | 505 ``` -[`is_lua51`]: #is-lua51 -[`is_lua52`]: #is-lua52 -[`is_lua53`]: #is-lua53 -[`is_lua54`]: #is-lua54 -[`is_lua55`]: #is-lua55 [`is_luajit`]: #is-luajit +[`is_unix`]: #is-unix [`is_windows`]: #is-windows [`major`]: #major [`minor`]: #minor diff --git a/docs/src/mods/api/utils.md b/docs/src/mods/api/utils.md index dea82f2..cefd869 100644 --- a/docs/src/mods/api/utils.md +++ b/docs/src/mods/api/utils.md @@ -147,7 +147,7 @@ Assert argument value using [`mods.validate`] and raise a Lua error on failure. - `argn` (`integer`): Argument index for error context. - `v` (`T`): Value to check. -- `validator?` ([`mods.ValidatorName`]): Validator name (defaults to +- `validator?` ([`mods.validatorName`]): Validator name (defaults to `"truthy"`). - `optional?` (`boolean`): Skip errors when `v` is `nil` (defaults to `false`). - `lv?` (`integer`): Error level passed to `error` (defaults to `3`). @@ -182,7 +182,7 @@ Validate a value using [`mods.validate`] and raise a Lua error on failure. - `name` (`string`): Name for the error prefix. - `v` (`any`): Value to validate. -- `validator?` ([`mods.ValidatorName`]): Validator name (defaults to +- `validator?` ([`mods.validatorName`]): Validator name (defaults to `"truthy"`). - `optional?` (`boolean`): Skip errors when `v` is `nil` (defaults to `false`). - `msg?` (`string`): Optional override template passed to [`mods.validate`]. @@ -210,7 +210,7 @@ Validate a value using [`mods.validate`] and raise a Lua error on failure. - `path` (`table`): Path parts for the error name. - `v` (`any`): Value to validate. -- `validator?` ([`mods.ValidatorName`]): Validator name (defaults to +- `validator?` ([`mods.validatorName`]): Validator name (defaults to `"truthy"`). - `optional?` (`boolean`): Skip errors when `v` is `nil` (defaults to `false`). - `msg?` (`string`): Optional override template passed to [`mods.validate`]. @@ -236,9 +236,9 @@ utils.validate({ "ctx", "users", 1, "name" }, 123, "string") [`assert_arg(argn, v, validator?, optional?, lv?)`]: #assert-arg [`keypath(...)`]: #keypath [`lazy_module(name, err?)`]: #lazy-module -[`mods.ValidatorName`]: /mods/types#mods-validatorname [`mods.utils.keypath`]: /mods/api/utils#keypath [`mods.validate`]: /mods/api/validate +[`mods.validatorName`]: /mods/types#mods-validatorname [`quote(v)`]: #quote [`validate(name, v, validator?, optional?, msg?)`]: #validate [`validate(path, v, validator?, optional?, msg?)`]: #validate-1 diff --git a/docs/src/mods/api/validate.md b/docs/src/mods/api/validate.md index 501e948..4d45373 100644 --- a/docs/src/mods/api/validate.md +++ b/docs/src/mods/api/validate.md @@ -110,17 +110,17 @@ ok, err = validate.number("x") --> false, "need number, got string" **Path Checks**: -| Function | Description | -| ------------------- | ------------------------------------------------------------------------------------------------------- | -| [`block(v, msg?)`] | Returns `true` when `v` is a block device path. Otherwise returns `false` and an error message. | -| [`char(v, msg?)`] | Returns `true` when `v` is a char device path. Otherwise returns `false` and an error message. | -| [`device(v, msg?)`] | Returns `true` when `v` is a block or char device path. Otherwise returns `false` and an error message. | -| [`dir(v, msg?)`] | Returns `true` when `v` is a directory path. Otherwise returns `false` and an error message. | -| [`fifo(v, msg?)`] | Returns `true` when `v` is a FIFO path. Otherwise returns `false` and an error message. | -| [`file(v, msg?)`] | Returns `true` when `v` is a file path. Otherwise returns `false` and an error message. | -| [`link(v, msg?)`] | Returns `true` when `v` is a symlink path. Otherwise returns `false` and an error message. | -| [`path(v, msg?)`] | Returns `true` when `v` is a valid filesystem path. Otherwise returns `false` and an error message. | -| [`socket(v, msg?)`] | Returns `true` when `v` is a socket path. Otherwise returns `false` and an error message. | +| Function | Description | +| ------------------------- | ------------------------------------------------------------------------------------------------------- | +| [`block_device(v, msg?)`] | Returns `true` when `v` is a block device path. Otherwise returns `false` and an error message. | +| [`char_device(v, msg?)`] | Returns `true` when `v` is a char device path. Otherwise returns `false` and an error message. | +| [`device(v, msg?)`] | Returns `true` when `v` is a block or char device path. Otherwise returns `false` and an error message. | +| [`dir(v, msg?)`] | Returns `true` when `v` is a directory path. Otherwise returns `false` and an error message. | +| [`fifo(v, msg?)`] | Returns `true` when `v` is a FIFO path. Otherwise returns `false` and an error message. | +| [`file(v, msg?)`] | Returns `true` when `v` is a file path. Otherwise returns `false` and an error message. | +| [`path(v, msg?)`] | Returns `true` when `v` is a valid filesystem path. Otherwise returns `false` and an error message. | +| [`socket(v, msg?)`] | Returns `true` when `v` is a socket path. Otherwise returns `false` and an error message. | +| [`symlink(v, msg?)`] | Returns `true` when `v` is a symlink path. Otherwise returns `false` and an error message. | **Registration**: @@ -130,31 +130,34 @@ ok, err = validate.number("x") --> false, "need number, got string" **Type Checks**: -| Function | Description | -| --------------------- | -------------------------------------------------------------------------------------------- | -| [`boolean(v, msg?)`] | Returns `true` when `v` is a boolean. Otherwise returns `false` and an error message. | -| [`function(v, msg?)`] | Returns `true` when `v` is a function. Otherwise returns `false` and an error message. | -| [`nil(v, msg?)`] | Returns `true` when `v` is `nil`. Otherwise returns `false` and an error message. | -| [`number(v, msg?)`] | Returns `true` when `v` is a number. Otherwise returns `false` and an error message. | -| [`string(v, msg?)`] | Returns `true` when `v` is a string. Otherwise returns `false` and an error message. | -| [`table(v, msg?)`] | Returns `true` when `v` is a table. Otherwise returns `false` and an error message. | -| [`thread(v, msg?)`] | Returns `true` when `v` is a thread. Otherwise returns `false` and an error message. | -| [`userdata(v, msg?)`] | Returns `true` when `v` is a userdata value. Otherwise returns `false` and an error message. | +| Function | Description | +| --------------------- | ------------------------------------------------------------------------------------------------------- | +| [`Function(v, msg?)`] | Returns `true` when `v` is a function. Otherwise returns `false` and an error message. | +| [`Nil(v, msg?)`] | Returns `true` when `v` is `nil`. Otherwise returns `false` and an error message. | +| [`boolean(v, msg?)`] | Returns `true` when `v` is a boolean. Otherwise returns `false` and an error message. | +| [`cdata(v, msg?)`] | Returns `true` when `v` is a cdata value (LuaJIT only). Otherwise returns `false` and an error message. | +| [`number(v, msg?)`] | Returns `true` when `v` is a number. Otherwise returns `false` and an error message. | +| [`string(v, msg?)`] | Returns `true` when `v` is a string. Otherwise returns `false` and an error message. | +| [`table(v, msg?)`] | Returns `true` when `v` is a table. Otherwise returns `false` and an error message. | +| [`thread(v, msg?)`] | Returns `true` when `v` is a thread. Otherwise returns `false` and an error message. | +| [`userdata(v, msg?)`] | Returns `true` when `v` is a userdata value. Otherwise returns `false` and an error message. | **Value Checks**: -| Function | Description | -| --------------------- | ------------------------------------------------------------------------------------------- | -| [`callable(v, msg?)`] | Returns `true` when `v` is callable. Otherwise returns `false` and an error message. | -| [`false(v, msg?)`] | Returns `true` when `v` is exactly `false`. Otherwise returns `false` and an error message. | -| [`falsy(v, msg?)`] | Returns `true` when `v` is falsy. Otherwise returns `false` and an error message. | -| [`integer(v, msg?)`] | Returns `true` when `v` is an integer. Otherwise returns `false` and an error message. | -| [`true(v, msg?)`] | Returns `true` when `v` is exactly `true`. Otherwise returns `false` and an error message. | -| [`truthy(v, msg?)`] | Returns `true` when `v` is truthy. Otherwise returns `false` and an error message. | +| Function | Description | +| --------------------- | ------------------------------------------------------------------------------------------------------ | +| [`False(v, msg?)`] | Returns `true` when `v` is exactly `false`. Otherwise returns `false` and an error message. | +| [`True(v, msg?)`] | Returns `true` when `v` is exactly `true`. Otherwise returns `false` and an error message. | +| [`callable(v, msg?)`] | Returns `true` when `v` is callable. Otherwise returns `false` and an error message. | +| [`defined(v, msg?)`] | Returns `true` when `v` is defined (not `nil`). Otherwise returns `false` and an error message. | +| [`falsy(v, msg?)`] | Returns `true` when `v` is falsy. Otherwise returns `false` and an error message. | +| [`integer(v, msg?)`] | Returns `true` when `v` is an integer. Otherwise returns `false` and an error message. | +| [`nan(v, msg?)`] | Returns `true` when `v` is a NaN (not-a-number) value. Otherwise returns `false` and an error message. | +| [`truthy(v, msg?)`] | Returns `true` when `v` is truthy. Otherwise returns `false` and an error message. | ### Path Checks -#### `block(v, msg?)` {#block} +#### `block_device(v, msg?)` {#block-device} Returns `true` when `v` is a block device path. Otherwise returns `false` and an error message. @@ -172,12 +175,12 @@ error message. **Example**: ```lua -ok, err = validate.block(".") +ok, err = validate.block_device(".") ``` --- -#### `char(v, msg?)` {#char} +#### `char_device(v, msg?)` {#char-device} Returns `true` when `v` is a char device path. Otherwise returns `false` and an error message. @@ -195,7 +198,7 @@ error message. **Example**: ```lua -ok, err = validate.char(".") +ok, err = validate.char_device(".") ``` --- @@ -292,10 +295,10 @@ ok, err = validate.file(".") --- -#### `link(v, msg?)` {#link} +#### `path(v, msg?)` {#path} -Returns `true` when `v` is a symlink path. Otherwise returns `false` and an -error message. +Returns `true` when `v` is a valid filesystem path. Otherwise returns `false` +and an error message. **Parameters**: @@ -310,15 +313,15 @@ error message. **Example**: ```lua -ok, err = validate.link(".") +ok, err = validate.path("README.md") ``` --- -#### `path(v, msg?)` {#path} +#### `socket(v, msg?)` {#socket} -Returns `true` when `v` is a valid filesystem path. Otherwise returns `false` -and an error message. +Returns `true` when `v` is a socket path. Otherwise returns `false` and an error +message. **Parameters**: @@ -333,15 +336,15 @@ and an error message. **Example**: ```lua -ok, err = validate.path("README.md") +ok, err = validate.socket(".") ``` --- -#### `socket(v, msg?)` {#socket} +#### `symlink(v, msg?)` {#symlink} -Returns `true` when `v` is a socket path. Otherwise returns `false` and an error -message. +Returns `true` when `v` is a symlink path. Otherwise returns `false` and an +error message. **Parameters**: @@ -356,7 +359,7 @@ message. **Example**: ```lua -ok, err = validate.socket(".") +ok, err = validate.symlink(".") ``` --- @@ -400,9 +403,9 @@ ok, err = validate(2, "odd") --> false, "2 does not satisfy odd" ### Type Checks -#### `boolean(v, msg?)` {#boolean} +#### `Function(v, msg?)` {#function} -Returns `true` when `v` is a boolean. Otherwise returns `false` and an error +Returns `true` when `v` is a function. Otherwise returns `false` and an error message. **Parameters**: @@ -418,15 +421,16 @@ message. **Example**: ```lua -ok, err = validate.boolean(true) --> true, nil -ok, err = validate.boolean(1) --> false, "boolean expected, got number" +ok, err = validate.Function(function() end) --> true, nil +ok, err = validate.Function(1) +--> false, "function expected, got number" ``` --- -#### `function(v, msg?)` {#function} +#### `Nil(v, msg?)` {#nil} -Returns `true` when `v` is a function. Otherwise returns `false` and an error +Returns `true` when `v` is `nil`. Otherwise returns `false` and an error message. **Parameters**: @@ -442,16 +446,15 @@ message. **Example**: ```lua -ok, err = validate.Function(function() end) --> true, nil -ok, err = validate.Function(1) ---> false, "function expected, got number" +ok, err = validate.Nil(nil) --> true, nil +ok, err = validate.Nil(0) --> false, "nil expected, got number" ``` --- -#### `nil(v, msg?)` {#nil} +#### `boolean(v, msg?)` {#boolean} -Returns `true` when `v` is `nil`. Otherwise returns `false` and an error +Returns `true` when `v` is a boolean. Otherwise returns `false` and an error message. **Parameters**: @@ -467,8 +470,31 @@ message. **Example**: ```lua -ok, err = validate.Nil(nil) --> true, nil -ok, err = validate.Nil(0) --> false, "nil expected, got number" +ok, err = validate.boolean(true) --> true, nil +ok, err = validate.boolean(1) --> false, "boolean expected, got number" +``` + +--- + +#### `cdata(v, msg?)` {#cdata} + +Returns `true` when `v` is a cdata value (LuaJIT only). Otherwise returns +`false` and an error message. + +**Parameters**: + +- `v` (`any`): Value to validate. +- `msg?` (`string`): Optional override template. + +**Returns**: + +- `isValid` (`boolean`): Whether the check succeeds. +- `err?` (`string`): Error message when the check fails. + +**Example**: + +```lua +ok, err = validate.cdata(v) ``` --- @@ -596,6 +622,54 @@ ok, err = validate.userdata(1) --> false, "userdata expected, got number ### Value Checks +#### `False(v, msg?)` {#false} + +Returns `true` when `v` is exactly `false`. Otherwise returns `false` and an +error message. + +**Parameters**: + +- `v` (`any`): Value to validate. +- `msg?` (`string`): Optional override template. + +**Returns**: + +- `isValid` (`boolean`): Whether the check succeeds. +- `err?` (`string`): Error message when the check fails. + +**Example**: + +```lua +ok, err = validate.False(false) --> true, nil +ok, err = validate.False(true) --> false, "false value expected, got true" +``` + +--- + +#### `True(v, msg?)` {#true} + +Returns `true` when `v` is exactly `true`. Otherwise returns `false` and an +error message. + +**Parameters**: + +- `v` (`any`): Value to validate. +- `msg?` (`string`): Optional override template. + +**Returns**: + +- `isValid` (`boolean`): Whether the check succeeds. +- `err?` (`string`): Error message when the check fails. + +**Example**: + +```lua +ok, err = validate.True(true) --> true, nil +ok, err = validate.True(false) --> false, "true value expected, got false" +``` + +--- + #### `callable(v, msg?)` {#callable} Returns `true` when `v` is callable. Otherwise returns `false` and an error @@ -620,9 +694,9 @@ ok, err = validate.callable(1) --> false, "callable value expected, got 1" --- -#### `false(v, msg?)` {#false} +#### `defined(v, msg?)` {#defined} -Returns `true` when `v` is exactly `false`. Otherwise returns `false` and an +Returns `true` when `v` is defined (not `nil`). Otherwise returns `false` and an error message. **Parameters**: @@ -638,8 +712,8 @@ error message. **Example**: ```lua -ok, err = validate.False(false) --> true, nil -ok, err = validate.False(true) --> false, "false value expected, got true" +ok, err = validate.defined(1) --> true, nil +ok, err = validate.defined(nil) --> false, "defined value expected, got no value" ``` --- @@ -692,10 +766,10 @@ ok, err = validate.integer(1.5) --> false, "integer value expected, got 1.5" --- -#### `true(v, msg?)` {#true} +#### `nan(v, msg?)` {#nan} -Returns `true` when `v` is exactly `true`. Otherwise returns `false` and an -error message. +Returns `true` when `v` is a NaN (not-a-number) value. Otherwise returns `false` +and an error message. **Parameters**: @@ -710,8 +784,8 @@ error message. **Example**: ```lua -ok, err = validate.True(true) --> true, nil -ok, err = validate.True(false) --> false, "true value expected, got false" +ok, err = validate.nan(0/0) --> true, nil +ok, err = validate.nan(1) --> false, "nan value expected, got 1" ``` --- @@ -739,29 +813,32 @@ ok, err = validate.truthy(false) --> false, "truthy value expected, got false" ``` -[`block(v, msg?)`]: #block +[`False(v, msg?)`]: #false +[`Function(v, msg?)`]: #function +[`Nil(v, msg?)`]: #nil +[`True(v, msg?)`]: #true +[`block_device(v, msg?)`]: #block-device [`boolean(v, msg?)`]: #boolean [`callable(v, msg?)`]: #callable -[`char(v, msg?)`]: #char +[`cdata(v, msg?)`]: #cdata +[`char_device(v, msg?)`]: #char-device +[`defined(v, msg?)`]: #defined [`device(v, msg?)`]: #device [`dir(v, msg?)`]: #dir -[`false(v, msg?)`]: #false [`falsy(v, msg?)`]: #falsy [`fifo(v, msg?)`]: #fifo [`file(v, msg?)`]: #file -[`function(v, msg?)`]: #function [`integer(v, msg?)`]: #integer [`lfs`]: https://github.com/lunarmodules/luafilesystem -[`link(v, msg?)`]: #link -[`nil(v, msg?)`]: #nil +[`nan(v, msg?)`]: #nan [`number(v, msg?)`]: #number [`path(v, msg?)`]: #path [`register(name, validator, template?)`]: #register [`socket(v, msg?)`]: #socket [`string(v, msg?)`]: #string +[`symlink(v, msg?)`]: #symlink [`table(v, msg?)`]: #table [`thread(v, msg?)`]: #thread -[`true(v, msg?)`]: #true [`truthy(v, msg?)`]: #truthy [`userdata(v, msg?)`]: #userdata diff --git a/docs/src/mods/types.md b/docs/src/mods/types.md index f7c1ca1..000ee26 100644 --- a/docs/src/mods/types.md +++ b/docs/src/mods/types.md @@ -94,35 +94,86 @@ Representation of date components. | `yday?` | `integer` | The day of the year (`1` to `366`). | | `year` | `integer` | The 4-digit year (e.g., `2026`). | -## [`mods.DurationHumanizeOptions`](https://github.com/BlueLua/mods/blob/main/types/duration.d.lua#L6-L12) +## [`mods.DurationHumanizeOptions`](https://github.com/BlueLua/mods/blob/main/types/duration.d.lua#L56-L63) + +Configuration options for humanizing durations into relative-style strings. | Key | Type | Description | | -------------- | ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------- | -| `max_unit?` | mods.DateUnit | Largest unit allowed when choosing the displayed unit. | -| `min_unit?` | mods.DateUnit | Smallest unit allowed when choosing the displayed unit. | -| `round?` | mods.DurationHumanizeRoundMode | Rounding mode for custom unit output. | +| `max_unit?` | mods.durationUnit | Largest unit allowed when choosing the displayed unit. | +| `min_unit?` | mods.durationUnit | Smallest unit allowed when choosing the displayed unit. | +| `round?` | mods.durationHumanizeRoundMode | Rounding mode for custom unit output. | | `short?` | `boolean` | Whether to use abbreviated unit labels like `2h`. | | `with_suffix?` | `boolean` | Whether to include `ago` / `in` style wording. | -## [`mods.DurationHumanizeRoundMode`](https://github.com/BlueLua/mods/blob/main/types/duration.d.lua#L3-L5) - - `"ceil"`  `"floor"`  `"round"`  `boolean` - -## [`mods.DurationParts`](https://github.com/BlueLua/mods/blob/main/types/duration.d.lua#L3-L5) - -| Key | Type | -| --------------- | -------- | -| `days?` | `number` | -| `hours?` | `number` | -| `milliseconds?` | `number` | -| `minutes?` | `number` | -| `months?` | `number` | -| `quarters?` | `number` | -| `seconds?` | `number` | -| `weeks?` | `number` | -| `years?` | `number` | - -## [`mods.FsEntryType`](https://github.com/BlueLua/mods/blob/main/types/fs.d.lua#L3-L12) +## [`mods.durationHumanizeRoundMode`](https://github.com/BlueLua/mods/blob/main/types/duration.d.lua#L15-L21) + +Rounding mode to use when humanizing durations. + +| Value | Description | +| --------- | --------------------------------------- | +| `"ceil"` | Round up (ceil). | +| `"floor"` | Round down (floor). | +| `"round"` | Round to the nearest integer. | +| `boolean` | Whether to round (true) or not (false). | + +## [`mods.DurationParts`](https://github.com/BlueLua/mods/blob/main/types/duration.d.lua#L3-L14) + +Representation of duration parts. + +| Key | Type | Description | +| --------------- | -------- | ----------------------------------------------- | +| `days?` | `number` | The day component (7 days = 1 week). | +| `hours?` | `number` | The hour component (24 hours = 1 day). | +| `milliseconds?` | `number` | The millisecond component (1000 ms = 1 second). | +| `minutes?` | `number` | The minute component (60 minutes = 1 hour). | +| `months?` | `number` | The month component (12 months = 1 year). | +| `quarters?` | `number` | The quarter component (3 months = 1 quarter). | +| `seconds?` | `number` | The second component (60 seconds = 1 minute). | +| `weeks?` | `number` | The week component. | +| `years?` | `number` | The year component. | + +## [`mods.durationUnit`](https://github.com/BlueLua/mods/blob/main/types/duration.d.lua#L22-L55) + +Supported units of time for duration representation and calculations. + +| Value | Description | +| ---------------- | ------------ | +| `"d"` | Days | +| `"day"` | Days | +| `"days"` | Days | +| `"h"` | Hours | +| `"hour"` | Hours | +| `"hours"` | Hours | +| `"M"` | Months | +| `"m"` | Minutes | +| `"millisecond"` | Milliseconds | +| `"milliseconds"` | Milliseconds | +| `"min"` | Minutes | +| `"mins"` | Minutes | +| `"minute"` | Minutes | +| `"minutes"` | Minutes | +| `"month"` | Months | +| `"months"` | Months | +| `"ms"` | Milliseconds | +| `"q"` | Quarters | +| `"quarter"` | Quarters | +| `"quarters"` | Quarters | +| `"s"` | Seconds | +| `"sec"` | Seconds | +| `"second"` | Seconds | +| `"seconds"` | Seconds | +| `"secs"` | Seconds | +| `"w"` | Weeks | +| `"week"` | Weeks | +| `"weeks"` | Weeks | +| `"y"` | Years | +| `"year"` | Years | +| `"years"` | Years | + +## [`mods.fsEntryType`](https://github.com/BlueLua/mods/blob/main/types/fs.d.lua#L3-L13) + +Filesystem entry type. | Value | Description | | ------------- | ------------------------------------- | @@ -135,7 +186,7 @@ Representation of date components. | `"socket"` | A socket. | | `"unknown"` | An unknown or unsupported entry type. | -## [`mods.globOptions`](https://github.com/BlueLua/mods/blob/main/types/glob.d.lua#L3-L9) +## [`mods.GlobOptions`](https://github.com/BlueLua/mods/blob/main/types/glob.d.lua#L3-L9) Options for glob matching and directory traversal. @@ -146,50 +197,60 @@ Options for glob matching and directory traversal. | `ignorecase?` | `boolean` | Whether to perform case-insensitive matching. | | `recursive?` | `boolean` | Whether to traverse directories recursively. | -## [`mods.log.levelno`](https://github.com/BlueLua/mods/blob/main/types/log.d.lua#L13-L20) +## [`mods.log.levelno`](https://github.com/BlueLua/mods/blob/main/types/log.d.lua#L15-L24) -| Name | Value | -| ------- | ------------- | -| `debug` | `10` | -| `error` | `40` | -| `info` | `20` | -| `off` | `"math.huge"` | -| `warn` | `30` | +Numeric severity levels used for log message filtering. -## [`mods.log.logger`](https://github.com/BlueLua/mods/blob/main/types/log.d.lua#L61-L63) +| Name | Value | Description | +| ------- | ------------- | ----------------------- | +| `debug` | `10` | Debug messages. | +| `error` | `40` | Error messages. | +| `info` | `20` | Informational messages. | +| `off` | `"math.huge"` | Logging disabled. | +| `warn` | `30` | Warning messages. | + +## [`mods.log.logger`](https://github.com/BlueLua/mods/blob/main/types/log.d.lua#L67-L69) | Key | Type | Description | | --------- | -------------------------------------------------------------------------------------------- | ----------------------------------------------------------- | | `debug` | `fun(...: any)` | Emit a `debug` record. | | `error` | `fun(...: any)` | Emit an `error` record. | | `info` | `fun(...: any)` | Emit an `info` record. | -| `log` | fun(levelname: mods.LogLevel, ...: any) | Emit a record for `level` when it passes the logger filter. | +| `log` | fun(levelname: mods.logLevel, ...: any) | Emit a record for `level` when it passes the logger filter. | | `private` | `_levelno` | mods.log.levelno | | `warn` | `fun(...: any)` | Emit a `warn` record. | -## [`mods.log.new.opts`](https://github.com/BlueLua/mods/blob/main/types/log.d.lua#L30-L34) +## [`mods.log.new.opts`](https://github.com/BlueLua/mods/blob/main/types/log.d.lua#L35-L40) + +Configuration options for creating a new logger instance. | Key | Type | Description | | ---------- | ---------------------------------------------------------------------- | ---------------------------------------------------------------------------- | -| `handler?` | mods.LogHandler | Optional handler function that receives each emitted record. | -| `level?` | mods.LogLevel | Minimum enabled level; use `"off"` to disable logging. Defaults to `"warn"`. | +| `handler?` | mods.logHandler | Optional handler function that receives each emitted record. | +| `level?` | mods.logLevel | Minimum enabled level; use `"off"` to disable logging. Defaults to `"warn"`. | | `name?` | `string` | Optional logger name included in emitted records. | -## [`mods.log.record`](https://github.com/BlueLua/mods/blob/main/types/log.d.lua#L22-L29) +## [`mods.log.record`](https://github.com/BlueLua/mods/blob/main/types/log.d.lua#L26-L34) + +A single log entry containing metadata and the formatted message. | Key | Type | Description | | ----------- | ------------------------------------------------------------------ | ------------------------------------ | | `args` | `{[integer]:any, n:integer}` | Original variadic arguments. | -| `levelname` | mods.LogLevel | Log level name. | +| `levelname` | mods.logLevel | Log level name. | | `levelno` | `integer` | Numeric severity used for filtering. | | `line` | `string` | Formatted plain-text log line. | | `message` | `string` | Joined message string. | -## [`mods.LogHandler`](https://github.com/BlueLua/mods/blob/main/types/log.d.lua#L11-L12) +## [`mods.logHandler`](https://github.com/BlueLua/mods/blob/main/types/log.d.lua#L12-L14) + +Callback function for handling log records. `fun(record: mods.log.record)` -## [`mods.LogLevel`](https://github.com/BlueLua/mods/blob/main/types/log.d.lua#L3-L10) +## [`mods.logLevel`](https://github.com/BlueLua/mods/blob/main/types/log.d.lua#L3-L11) + +Log level name or severity threshold. | Value | Description | | --------- | -------------------------- | @@ -200,53 +261,68 @@ Options for glob matching and directory traversal. | `"warn"` | Warning messages. | | `string` | Any custom log level name. | -## [`mods.ValidatorName`](https://github.com/BlueLua/mods/blob/main/types/is.d.lua#L6-L24) - -| Value | Description | -| ------------ | --------------------------------------------------------- | -| `"block"` | A block device path. | -| `"callable"` | A function or table with a `__call` metamethod. | -| `"char"` | A character device path. | -| `"device"` | A character or block device path. | -| `"dir"` | A directory path. | -| `"false"` | The boolean value false. | -| `"falsy"` | A falsy value (nil or false). | -| `"fifo"` | A named pipe (FIFO) path. | -| `"file"` | A regular file path. | -| `"integer"` | An integer number. | -| `"link"` | A symbolic link path. | -| `"path"` | Any existing path or symbolic link. | -| `"socket"` | A socket path. | -| `"true"` | The boolean value true. | -| `"truthy"` | A truthy value (not nil and not false). | -| `string` | Any validator name. | -| `type` | Any standard Lua type name (e.g., `"table"`, `"number"`). | - -## [`modsValidatorMessages`](https://github.com/BlueLua/mods/blob/main/types/validate.d.lua#L3-L31) - -| Key | Type | -| ----------- | -------- | -| `[string]` | `string` | -| `block?` | `string` | -| `boolean?` | `string` | -| `callable?` | `string` | -| `char?` | `string` | -| `device?` | `string` | -| `dir?` | `string` | -| `false?` | `string` | -| `falsy?` | `string` | -| `fifo?` | `string` | -| `file?` | `string` | -| `function?` | `string` | -| `integer?` | `string` | -| `link?` | `string` | -| `nil?` | `string` | -| `number?` | `string` | -| `path?` | `string` | -| `socket?` | `string` | -| `string?` | `string` | -| `table?` | `string` | -| `thread?` | `string` | -| `true?` | `string` | -| `truthy?` | `string` | -| `userdata?` | `string` | +## [`mods.validatorName`](https://github.com/BlueLua/mods/blob/main/types/is.d.lua#L3-L27) + +Supported validation and type check names. + +| Value | Description | +| ---------------- | --------------------------------------------------------- | +| `"block_device"` | A block device path. | +| `"callable"` | A function or table with a `__call` metamethod. | +| `"char_device"` | A character device path. | +| `"defined"` | A defined value (not nil). | +| `"device"` | A character or block device path. | +| `"dir"` | A directory path. | +| `"false"` | The boolean value false. | +| `"falsy"` | A falsy value (nil or false). | +| `"fifo"` | A named pipe (FIFO) path. | +| `"file"` | A regular file path. | +| `"finite"` | A finite number. | +| `"float"` | A float number. | +| `"infinite"` | An infinite number. | +| `"integer"` | An integer number. | +| `"nan"` | A NaN (not-a-number) value. | +| `"path"` | Any existing path or symbolic link. | +| `"socket"` | A socket path. | +| `"symlink"` | A symbolic link path. | +| `"true"` | The boolean value true. | +| `"truthy"` | A truthy value (not nil and not false). | +| `string` | Any validator name. | +| `type` | Any standard Lua type name (e.g., `"table"`, `"number"`). | + +## [`modsValidatorMessages`](https://github.com/BlueLua/mods/blob/main/types/validate.d.lua#L3-L38) + +Custom error message templates for validators, indexed by validator name. + +| Key | Type | Description | +| --------------- | -------- | ---------------------------------------------------------------- | +| `[string]` | `string` | Custom message template for a validator. | +| `block_device?` | `string` | Custom message template for block device validator failures. | +| `boolean?` | `string` | Custom message template for boolean validator failures. | +| `callable?` | `string` | Custom message template for callable validator failures. | +| `cdata?` | `string` | Custom message template for cdata validator failures. | +| `char_device?` | `string` | Custom message template for character device validator failures. | +| `defined?` | `string` | Custom message template for defined validator failures. | +| `device?` | `string` | Custom message template for device validator failures. | +| `dir?` | `string` | Custom message template for directory validator failures. | +| `false?` | `string` | Custom message template for false validator failures. | +| `falsy?` | `string` | Custom message template for falsy validator failures. | +| `fifo?` | `string` | Custom message template for named pipe validator failures. | +| `file?` | `string` | Custom message template for file validator failures. | +| `finite?` | `string` | Custom message template for finite validator failures. | +| `float?` | `string` | Custom message template for float validator failures. | +| `function?` | `string` | Custom message template for function validator failures. | +| `infinite?` | `string` | Custom message template for infinite validator failures. | +| `integer?` | `string` | Custom message template for integer validator failures. | +| `nan?` | `string` | Custom message template for nan validator failures. | +| `nil?` | `string` | Custom message template for nil validator failures. | +| `number?` | `string` | Custom message template for number validator failures. | +| `path?` | `string` | Custom message template for path validator failures. | +| `socket?` | `string` | Custom message template for socket validator failures. | +| `string?` | `string` | Custom message template for string validator failures. | +| `symlink?` | `string` | Custom message template for symbolic link validator failures. | +| `table?` | `string` | Custom message template for table validator failures. | +| `thread?` | `string` | Custom message template for thread validator failures. | +| `true?` | `string` | Custom message template for true validator failures. | +| `truthy?` | `string` | Custom message template for truthy validator failures. | +| `userdata?` | `string` | Custom message template for userdata validator failures. |