libraryDocs / debug

debug

librarysharedsource

The debug library is intended to help you debug your scripts, however it also has several other powerful uses.

[SHARED AND MENU]

Just empty function, do nothing.

Sometimes makes jit happy :>

[SHARED AND MENU]

Sets the metatable for the given value to the given table (which can be nil).

View documents

Fields

Name	Type	Description
`newproxy`	`newproxy`
`fempty`	`fun()`
`setmetatable`	`fun( object: any, metatable: ( metatable \| nil ) )`

Functions

`debug.calledby`	Checks whether any of the given functions is on the call stack, starting from stack_level and walking outward all the w…
`debug.fcall`	Calls the given function or object with the given arguments.
`debug.fempty`
`debug.findmetatable`	Returns the metatable of the given name or nil if not found.
`debug.getf`	Returns the function at the given stack level.
`debug.getfmain`	Returns the main function of the current stack.
`debug.getfname`	Attempts to determine the name and kind of a function, the same way the n option of the standard debug.getinfo does.
`debug.getfsource`	Returns the path to the file that the function is defined in.
`debug.getlocals`	Returns all available local variables at the given stack level (and, optionally, in the given thread/coroutine) as a ta…
`debug.getmetatable`	Returns the metatable of the given value, or nil if it doesn't have one.
`debug.getmetavalue`	Returns the value of the given key in the metatable of the given value.
`debug.getregistry`	Returns the registry table.
`debug.getstack`	Captures the current call stack, starting at stack_level relative to the caller of this function, and returns it as a l…
`debug.getupvalues`	Returns all upvalues of the given function as a table, keyed by upvalue name.
`debug.initmetatable`
`debug.iscf`	Checks if the given function or stack level is a C function.
`debug.registermetatable`	Registers the metatable of the given name and table.
`debug.setregistry`	Sets registry table.

#debug.calledby

sharednodiscardsource

function debug.calledby(stack_level: integer, ...: function): boolean

Checks whether any of the given functions is on the call stack, starting from stack_level and walking outward all the way to the bottom of the stack.

Levels follow the same convention as debug.getinfo, relative to the function that calls debug.calledby: level 1 is that function itself, level 2 is whoever called it, and so on. Levels below 1 are treated as 1, so the check always includes at least the calling function. This function's own stack frame is skipped automatically.

Because the whole remaining stack is scanned, a true result means "one of these functions is somewhere at or above stack_level", not that it is exactly at that level. To test a single level, use debug.getinfo directly.

Only functions that are actually on the stack are seen. Tail calls replace their caller's frame, so a function that was tail-called away won't be found.

Returns false if no functions are given.

lua

local function guarded()
    -- true if `guarded` was reached through `handler` at any depth
    return debug.calledby( 1, handler )
end

Parameters

Name	Type	Description
`stack_level`	`integer`	The stack level to start checking from (`1` = the function calling `calledby`). Values below `1` are treated as `1`.
`...`	`function`	The functions to look for on the call stack.

Returns

Type	Name	Description
`boolean`	`result`	`true` if any of the given functions is on the stack at or above `stack_level`, `false` otherwise.

#debug.fcall

sharedsource

function debug.fcall(f: function | any, ...: any): any

Calls the given function or object with the given arguments.

Parameters

Name	Type	Description
`f`	`function \| any`	The function or object to call.
`...`	`any`	The arguments to pass to the function or object.

Returns

Type	Name	Description
`any`	`...`	The result of execution.

#debug.fempty

source

function debug.fempty()

#debug.findmetatable

sharednodiscardsource

function debug.findmetatable(name: string): metatable | nil

Returns the metatable of the given name or nil if not found.

Parameters

Name	Type	Description
`name`	`string`	The name of the metatable.

Returns

Type	Name	Description
`metatable \| nil`	`meta`	The metatable.

#debug.getf

sharednodiscardsource

function debug.getf(level: integer): function | nil

Returns the function at the given stack level.

Parameters

Name	Type	Description
`level`	`integer`	The stack level.

Returns

Type	Name	Description
`function \| nil`		The function at the given level, or `nil` if the level is invalid.

#debug.getfmain

sharednodiscardsource

function debug.getfmain(stack_level?: integer): function | nil

Returns the main function of the current stack.

Parameters

Name	Type	Description
`stack_level`optional	`integer`	The stack `stack_level` to get the main function from.

Returns

Type	Name	Description
`function \| nil`	`main_fn`	The main function or `nil` if not found.

#debug.getfname

sharednodiscardsource

function debug.getfname(location?: integer): string | nil, "global" | "local" | "method" | "field" | "upvalue" | nil

Attempts to determine the name and kind of a function, the same way the n option of the standard debug.getinfo does.

location can be either a function reference or a stack level (an integer, where 1 is the function that called getfname).

Since Lua functions have no inherent name, this works by inspecting how the function was called or accessed - e.g. as a global, a local variable, a table field, a method, or an upvalue - and can fail to find anything, in which case both results are nil.

Parameters

Name	Type	Description
`location`optional	`integer`	The function or stack level.

Returns

Type	Name	Description
`string \| nil`	`name`	The name of the function, or `nil` if unknown.
`"global" \| "local" \| "method" \| "field" \| "upvalue" \| nil`	`name_what`	The kind of the function, or `nil` if unknown.

#debug.getfsource

sharednodiscardsource

function debug.getfsource(location: function | integer): string | nil

Returns the path to the file that the function is defined in.

Parameters

Name	Type	Description
`location`	`function \| integer`	The function or stack level to get the path from.

Returns

Type	Name	Description
`string \| nil`	`file_path`	The file path or `nil` if not found.

#debug.getlocals

sharednodiscardsource

function debug.getlocals(stack_level?: integer, thread?: thread): table<string, any>, integer

Returns all available local variables at the given stack level (and, optionally, in the given thread/coroutine) as a table keyed by variable name.

Parameters

Name	Type	Description
`stack_level`optional	`integer`	The stack level to inspect, relative to the caller (defaults to the immediate caller's frame). Cannot be negative.
`thread`optional	`thread`	The thread/coroutine to inspect. If omitted, the current thread is used.

Returns

Type	Name	Description
`table<string, any>`	`values`	A table mapping each local variable's name to its current value.
`integer`	`value_count`	The number of locals found.

#debug.getmetatable

sharednodiscardsource

function debug.getmetatable(object: any): metatable | nil

Returns the metatable of the given value, or nil if it doesn't have one.

Unlike the standard getmetatable, this ignores the __metatable field, so it can reach metatables that are protected from normal code.

View documents

Parameters

Name	Type	Description
`object`	`any`	The value to get the metatable of.

Returns

Type	Name	Description
`metatable \| nil`	`metatable`	The metatable of `object`, or `nil` if it has none.

#debug.getmetavalue

sharednodiscardsource

function debug.getmetavalue(value: any, key: string): any | nil

Returns the value of the given key in the metatable of the given value.

Returns nil if not found.

Parameters

Name	Type	Description
`value`	`any`	The value to get the metatable from.
`key`	`string`	The searchable key.

Returns

Type	Name	Description
`any \| nil`	`value`	The value of the given key.

#debug.getregistry

sharedsource

function debug.getregistry()

Returns the registry table.

#debug.getstack

sharednodiscardsource

function debug.getstack(stack_level?: integer, what?: infowhat, head_skip?: integer, tail_skip?: integer, max_levels?: integer): debuginfo[], integer

Captures the current call stack, starting at stack_level relative to the caller of this function, and returns it as a list of debug info tables.

Parameters

Name	Type	Description
`stack_level`optional	`integer`	The level to start capturing from, where `0` is the function that called `getstackinfo`. Default is `0`.
`what`optional	`infowhat`	A string of `debug.getinfo`-style flags selecting which fields to populate per frame. Default is `"Snluf"`.
`head_skip`optional	`integer`	Number of extra frames to skip from the top ( nearest the caller ) before capturing begins. Default is `0`.
`tail_skip`optional	`integer`	Number of frames to drop from the bottom ( nearest the root ) of the captured stack after capturing ends. Default is `0`.
`max_levels`optional	`integer`	Maximum number of frames to read (after `head_skip` is applied). Stack walking stops as soon as this many frames have been collected, so no `debug.getinfo` call is made beyond that point. `tail_skip` is still applied afterward to this (already capped) set. `nil`/`0` means no limit.

Returns

Type	Name	Description
`debuginfo[]`	`stack`	A list of debug info tables, one per captured stack frame, ordered from `stack_level` outward.
`integer`	`stack_size`	The number of entries in `stack` ( equivalent to `#stack` ).

#debug.getupvalues

sharednodiscardsource

function debug.getupvalues(fn: function): table<string, any>, integer

Returns all upvalues of the given function as a table, keyed by upvalue name.

If the function is a C function (or otherwise has no debug info), an empty table and a count of 0 are returned.

Parameters

Name	Type	Description
`fn`	`function`	The function to get upvalues from.

Returns

Type	Name	Description
`table<string, any>`	`values`	A table mapping each upvalue's name to its current value.
`integer`	`value_count`	The number of upvalues found.

#debug.initmetatable

sharedsource

function debug.initmetatable(name: string): metatable

Parameters

Name	Type	Description
`name`	`string`	The name of the metatable.

Returns

Type	Name	Description
`metatable`	`metatable`	The metatable.

#debug.iscf

sharednodiscardsource

function debug.iscf(location: integer | function): boolean

Checks if the given function or stack level is a C function.

Parameters

Name	Type	Description
`location`	`integer \| function`	The function or stack level.

Returns

Type	Name	Description
`boolean`	`iscf`	`true` if the function is a C function, `false` otherwise.

#debug.registermetatable

sharedsource

function debug.registermetatable(name: string, tbl: metatable, do_full_register?: boolean): integer

Registers the metatable of the given name and table.

Parameters

Name	Type	Description
`name`	`string`	The name of the metatable.
`tbl`	`metatable`	The metatable to register.
`do_full_register`optional	`boolean`	`true`, the metatable will be registered, `false` otherwise.

Returns

Type	Name	Description
`integer`	`meta_id`	The ID of the metatable or `-1` if not fully registered.

#debug.setregistry

sharedsource

function debug.setregistry(tbl: table)

Sets registry table.

ATTENTION

This function is extremly dangerous, only reason why this exists is fact that getregistry originally broken by cockpunch and i cannot set locals over debug, so only way to implement 3rd party moudles support is implement this function :c

Parameters

Name	Type	Description
`tbl`	`table`