Module std.debug

Additions to the core debug module.

The module table returned by std.debug also contains all of the entries from the core debug table. An hygienic way to import this module, then, is simply to override the core debug locally:

local debug = require 'std.debug'

Metamethods

__call () Equivalent to calling debug.say(1, ...)

Deprecation

DEPRECATED (version, name[, extramsg], fn) Wrap a deprecated function to warn the first time it is called.
DEPRECATIONMSG (version, name[, extramsg], level) Format a deprecation warning message.

Argument Checking These are typecheck's functions, when it is installed

argcheck () Check the type of an argument against an expected type.
argerror () Raise a bad argument error.
argscheck () Wrap a function definition with argument type and arity checking.
extramsg_mismatch () Format a type mismatch error.
extramsg_toomany () Format a too many things error.
parsetypes () Compact permutation list into a list of valid types at each argument.
resulterror () Raise a bad result error.
typesplit () Split a typespec string into a table of normalized type names.

Function Environments

getfenv (fn) Extend debug.getfenv to unwrap functables correctly.
setfenv (fn, env) Extend debug.setfenv to unwrap functables correctly.

Functions

say ([n=1], ...) Print a debugging message to io.stderr.
trace (event) Trace function calls.


Metamethods

__call ()
Equivalent to calling debug.say(1, ...)

See also:

Usage:

    local debug = require 'std.debug'
debug 'oh noes!'

Deprecation

DEPRECATED (version, name[, extramsg], fn)
Wrap a deprecated function to warn the first time it is called. Unless std._debug.deprecate is false, the warning goes to stderr; with std._debug.deprecate set to true, the deprecated function is not defined at all.

Parameters:

  • version string first deprecation release version
  • name string function name for automatic warning message
  • extramsg string additional warning text (optional)
  • fn function deprecated function

Returns:

    function or nil

    a function that warns on its first call, and

    hands off to *fn*; or `nil` if `std._debug.deprecate` is `true`

Usage:

    M.op = DEPRECATED('41', "'std.functional.op'", std.operator)
DEPRECATIONMSG (version, name[, extramsg], level)
Format a deprecation warning message.

Parameters:

  • version string first deprecation release version
  • name string function name for automatic warning message
  • extramsg string additional warning text (optional)
  • level int or false

    call stack level to blame for the warning,

    or `false` to blame nothing

Returns:

    string

    the warning, or an empty string unless

    `std._debug.deprecate` is `nil`

Usage:

    io.stderr:write(DEPRECATIONMSG('42', "multi-argument 'module.fname'", 2))

Argument Checking These are typecheck's functions, when it is installed

Otherwise, argcheck and argscheck check nothing, as when std._debug.argcheck is false, and the rest are not defined.
argcheck ()
Check the type of an argument against an expected type. Same as typecheck.argcheck, when that is installed.
argerror ()
Raise a bad argument error. Same as typecheck.argerror, when that is installed.
argscheck ()
Wrap a function definition with argument type and arity checking. Same as typecheck.argscheck, when that is installed.
extramsg_mismatch ()
Format a type mismatch error. Same as typecheck.extramsg_mismatch, when that is installed.
extramsg_toomany ()
Format a too many things error. Same as typecheck.extramsg_toomany, when that is installed.
parsetypes ()
Compact permutation list into a list of valid types at each argument. Same as typecheck.parsetypes, when that is installed.
resulterror ()
Raise a bad result error. Same as typecheck.resulterror, when that is installed.
typesplit ()
Split a typespec string into a table of normalized type names. Same as typecheck.typesplit, when that is installed.

Function Environments

getfenv (fn)
Extend debug.getfenv to unwrap functables correctly.

Parameters:

  • fn int, function or functable target function, or stack level

Returns:

    table environment of fn
setfenv (fn, env)
Extend debug.setfenv to unwrap functables correctly.

Parameters:

  • fn function or functable target function
  • env table new function environment

Returns:

    function fn

Functions

say ([n=1], ...)
Print a debugging message to io.stderr. Display arguments passed through std.tostring and separated by tab characters when std._debug hinting is true and n is 1 or less; or std._debug.level is a number greater than or equal to n. If std._debug hinting is false or nil, nothing is written.

Parameters:

  • n integer debugging level, smaller is higher priority (default 1)
  • ... objects to print(as for print)

Usage:

    local _debug = require 'std._debug'
_debug.level = 3
say(2, '_debug status level:', _debug.level)
trace (event)
Trace function calls. Use as debug.sethook(trace, 'cr'), which is done automatically when std._debug.call is set. Based on test/trace-calls.lua from the Lua distribution.

Parameters:

  • event string event causing the call

Usage:

    local _debug = require 'std._debug'
_debug.call = true
local debug = require 'std.debug'
generated by LDoc 1.5.0 Last updated 2026-10-22 19:02:37