mux.error package on StompyMUX Documentation

mux.error.codes

Mon, 01 Jan 0001 00:00:00 +0000

Provides checked symbols for native mux.* error codes. btech.* symbols are in btech.error.codes, and testing.* symbols are available as testing.error.codes in test suites.

Constants

Symbol	String value	When raised
`mux.error.codes.arg.invalid`	`mux.arg.invalid`	An API argument is invalid, including unknown checked-tree fields and invalid namespace definitions. Plain code strings passed to `new`, `raise`, `is`, and `wrap` are not syntax-validated.
`mux.error.codes.unavailable.checking`	`mux.unavailable.checking`	A runtime-only `mux` operation is used during `@lua/check`.
`mux.error.codes.runtime`	`mux.runtime`	`mux.error.pcall` normalizes a non-error failure, or runtime error logging has no structured code.
`mux.error.codes.state.invalid`	`mux.state.invalid`	A state namespace, key, value, or batch update is invalid.
`mux.error.codes.state.value_too_large`	`mux.state.value_too_large`	A state write exceeds a configured per-value, entry, or object limit.
`mux.error.codes.state.unavailable`	`mux.state.unavailable`	State enumeration occurs outside an active callback or state changes during enumeration.
`mux.error.codes.object.invalid`	`mux.object.invalid`	An object handle or database object is invalid, stale, or unsuitable for the requested operation.
`mux.error.codes.object.unavailable`	`mux.object.unavailable`	An object operation is unavailable or native policy rejects the requested change.
`mux.error.codes.flag.invalid`	`mux.flag.invalid`	A flag constant or lookup in `mux.world.flags` is invalid.
`mux.error.codes.power.invalid`	`mux.power.invalid`	A power constant or lookup in `mux.world.powers` is invalid.
`mux.error.codes.access.invalid`	`mux.access.invalid`	A command-access constant or lookup in `mux.world.access` is invalid.
`mux.error.codes.connection.invalid`	`mux.connection.invalid`	A message, descriptor, Telnet-environment kind, or flow descriptor is invalid.
`mux.error.codes.connection.unavailable`	`mux.connection.unavailable`	Flow support is unavailable or the descriptor already has an active flow.
`mux.error.codes.channel.invalid`	`mux.channel.invalid`	A channel name, membership, or Channel handle is unknown or stale.
`mux.error.codes.channel_flag.invalid`	`mux.channel_flag.invalid`	A constant or lookup in `mux.comsys.flags` is invalid.
`mux.error.codes.text.invalid`	`mux.text.invalid`	Styled text, a style field, or a requested text width is invalid.
`mux.error.codes.module.invalid`	`mux.module.invalid`	A module name is invalid or a requested flow step is absent from its module.
`mux.error.codes.module.unavailable`	`mux.module.unavailable`	A required module cannot be loaded or is unavailable from the current module root.
`mux.error.codes.internal`	`mux.internal`	A native invariant fails, such as a catalog being unavailable, an impossible result kind being returned, or a registry count changing while it is copied. It is also the fallback for an out-of-range native error-code enum.

Examples

if value_size > limit then
 mux.error.raise(
 mux.error.codes.state.value_too_large,
 "state value exceeds the configured limit"
 )
end

if err:is(mux.error.codes.state) then
 -- Handles every mux.state.* failure.
end

Notes

Each leaf and intermediate node has a .code field, and tostring(node) returns that dotted string. The intermediate nodes are derived from the leaves, not native enum members: mux, mux.arg, mux.unavailable, mux.state, mux.object, mux.attribute, mux.flag, mux.power, mux.access, mux.connection, mux.channel, mux.channel_flag, mux.text, and mux.module, and mux.config. They are useful with mux.error.is for a whole-namespace check; for example, mux.error.codes.state matches every mux.state.* code.

Error

Mon, 01 Jan 0001 00:00:00 +0000

An Error is a Lua table that identifies a failure with a stable code and a human-readable message. Native bindings raise these values, and scripts can create them with mux.error.new or mux.error.raise. Use an Error as the second result in the recoverable nil, err convention, or raise it when the current operation cannot continue.

Fields

string code: The dotted error code. It can be compared as a string, but checked symbols from mux.error.codes catch misspellings at lookup time.
string message: A readable description of the failure.
any detail: Optional structured context supplied by the producer. Native argument errors use a table containing argument.
any cause: Optional earlier error or other Lua value. mux.error.wrap stores the normalized wrapped value here.
string traceback: Optional traceback attached by mux.error.pcall when it catches a failure.

Methods

Method	Description
`Error:is`	Tests this error’s code against a leaf or namespace code.
`Error:root`	Returns the deepest table reached through `cause`.

`is`

error:is(code)

string or code node code: A comparison string or a node from mux.error.codes or mux.error.namespace. Plain strings are used verbatim and are not syntax-validated.

Returns true when this error’s code is an exact match or begins with code at a dotted segment boundary.

check

Mon, 01 Jan 0001 00:00:00 +0000

Returns a successful value or raises the supplied failure.

Function

Synopsis

mux.error.check(value, err)

Arguments

any value: The result to test. Any Lua truthy value is returned unchanged.
any err: The Lua value to raise when value is false or nil; normally an Error.

Returns

any value: The original truthy value.

Examples

local record = mux.error.check(load_record(id), err)

Notes

Lua considers only false and nil falsey. check does not normalize the raised value, so use mux.error.new when a structured error is needed.

code_tree

Mon, 01 Jan 0001 00:00:00 +0000

Returns the checked native code tree for a namespace root.

Function

Synopsis

local btech_codes = mux.error.code_tree("btech")

Arguments

string root: A native namespace root: mux, btech, or testing.

Returns

table codes: The cached checked symbol tree for the root. Repeated calls for the same root return the same table object.

Unknown roots raise mux.arg.invalid.

is

Mon, 01 Jan 0001 00:00:00 +0000

Tests whether an error-like value has a matching code.

Function

Synopsis

mux.error.is(value, code)

Arguments

any value: A value to inspect. It matches only when it is a table with a string code field.
string or code node code: A comparison string or a node from mux.error.codes or mux.error.namespace. Plain strings are used verbatim; this function does not validate their syntax.

Returns

boolean matches: true when value.code equals code or begins with code followed by a dotted segment; otherwise false.

Examples

if mux.error.is(err, mux.error.codes.state) then
 -- Matches mux.state.invalid, mux.state.unavailable, and related leaves.
end

Notes

Error:is is the equivalent method on an Error. Prefix matching stops at segment boundaries, so mux.state does not match mux.statement.invalid. Prefer checked code nodes when possible; malformed plain strings simply participate in the same exact-or-prefix comparison.

namespace

Mon, 01 Jan 0001 00:00:00 +0000

Builds a checked code-symbol tree for an author-defined error namespace.

Function

Synopsis

local codes = mux.error.namespace("cargo", { "full", "bay.locked" })

Arguments

string prefix: The first code segment, or a dotted series of lower-case segments. The first segment must not be mux, btech, or testing.
string[] names: An array of leaf names relative to prefix. Every name uses one or more lower-case dotted segments; later segments may also contain digits or _.

Returns

table codes: A code-symbol tree whose leaf and intermediate nodes can be passed wherever mux.error accepts a code.

Examples

local codes = mux.error.namespace("cargo", { "full", "bay.locked" })
mux.error.raise(codes.bay.locked, "the cargo bay is locked")

Notes

The tree follows the same lookup and mutation behavior as mux.error.codes. mux, btech, and testing are reserved first segments; a prefix whose first segment is one of them is rejected.

new

Mon, 01 Jan 0001 00:00:00 +0000

Creates a structured error value without raising it.

Function

Synopsis

mux.error.new({ code = "area.missing", message = "area was not found", detail = {} })

Arguments

table fields: An error definition with the required code and message fields, and optional detail and cause fields.
string or code node fields.code: A code string or a node from mux.error.codes or mux.error.namespace. Plain strings are accepted verbatim; this function does not validate their syntax.
string fields.message: A readable description of the error.
any fields.detail: Optional structured context for the failure.
any fields.cause: Optional earlier error or other Lua value.

Returns

Error error: The new structured error value.

Examples

return nil, mux.error.new({
 code = mux.error.codes.state.unavailable,
 message = "state cannot be read outside a callback",
})

Notes

This function copies code, message, and non-nil detail and cause into a new Error; it does not validate the code string or normalize the cause.

pcall

Mon, 01 Jan 0001 00:00:00 +0000

Calls a function and returns either its results or a normalized error with a traceback.

Function

Synopsis

ok, result_or_error = mux.error.pcall(fn, ...)

Arguments

function fn: The function to call.
...: Arguments passed to fn.

Returns

true, ...: On success, true followed by every value returned by fn.
false, Error or caught-error table error: On failure, false and the raised error. A raised table with a string code field is retained; another Lua value is converted to a mux.runtime Error. Every returned failure has string code and traceback fields.

Examples

local ok, value_or_err = mux.error.pcall(read_manifest, id)
if not ok then
 return nil, value_or_err
end

Notes

Unlike Lua’s pcall, this helper makes unstructured failures inspectable by code. A retained table with a string code field is not copied or given the Error metatable. Such a caught-error table is guaranteed only code and traceback; it can omit message, detail, cause, and every Error method, and it can retain arbitrary caller-defined fields. The traceback is reported as Lua traceback unavailable only when the runtime cannot obtain one.

raise

Mon, 01 Jan 0001 00:00:00 +0000

Raises a structured error.

Function

Synopsis

mux.error.raise(code, message [, detail])

Arguments

string or code node code: A code string or a node from mux.error.codes or mux.error.namespace. Plain strings are accepted verbatim; this function does not validate their syntax.
string message: A readable description of the failure.
any detail: Optional structured context stored on the raised Error.

Returns

Nothing; this function raises an Error.

Examples

if cargo.full then
 mux.error.raise(codes.full, "the cargo bay is full", { capacity = 20 })
end

Notes

Use return nil, err rather than raising when the caller is expected to recover from the condition. Prefer a checked code node or a conventionally dotted plain string even though plain strings are not syntax-checked.

wrap

Mon, 01 Jan 0001 00:00:00 +0000

Creates a structured error that preserves an earlier failure as its cause.

Function

Synopsis

mux.error.wrap(err, code, message)

Arguments

any err: The earlier failure. A table with a string code field is retained; another Lua value is normalized to a mux.runtime error before becoming the cause.
string or code node code: A code string or a node from mux.error.codes or mux.error.namespace. Plain strings are accepted verbatim; this function does not validate their syntax.
string message: A readable description of the additional context.

Returns

Error error: A new error with error.cause set to the retained or normalized err.

Examples

local ok, err = mux.error.pcall(write_manifest)
if not ok then
 return nil, mux.error.wrap(err, "cargo.manifest.failed", "could not save manifest")
end

Notes

Use Error:root to retrieve the deepest table-valued cause. wrap does not validate its code string or attach a traceback; mux.error.pcall does attach a traceback when it catches a failure.

mux.error package on StompyMUX Documentation

mux.error.codes

Constants

Examples

Notes

Error

Fields

Methods

is

check

Function

Synopsis

Arguments

Returns

Examples

Notes

code_tree

Function

Synopsis

Arguments

Returns

See Also

is

Function

Synopsis

Arguments

Returns

Examples

Notes

namespace

Function

Synopsis

Arguments

Returns

Examples

Notes

new

Function

Synopsis

Arguments

Returns

Examples

Notes

pcall

Function

Synopsis

Arguments

Returns

Examples

Notes

raise

Function

Synopsis

Arguments

Returns

Examples

Notes

wrap

Function

Synopsis

Arguments

Returns

Examples

Notes

`is`