{"id":17925795,"url":"https://github.com/appgurueu/dbg","last_synced_at":"2025-08-15T13:31:44.722Z","repository":{"id":42431770,"uuid":"510736359","full_name":"appgurueu/dbg","owner":"appgurueu","description":"Debugging on steroids for Minetest mods","archived":false,"fork":false,"pushed_at":"2023-04-01T19:18:06.000Z","size":16,"stargazers_count":5,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2024-10-28T20:57:58.698Z","etag":null,"topics":["debug","lua","minetest","mod","pretty-printing"],"latest_commit_sha":null,"homepage":"","language":"Lua","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/appgurueu.png","metadata":{"files":{"readme":"Readme.md","changelog":null,"contributing":null,"funding":null,"license":"License.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2022-07-05T12:55:51.000Z","updated_at":"2024-08-08T05:36:13.000Z","dependencies_parsed_at":"2023-01-18T14:01:51.287Z","dependency_job_id":null,"html_url":"https://github.com/appgurueu/dbg","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/appgurueu%2Fdbg","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/appgurueu%2Fdbg/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/appgurueu%2Fdbg/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/appgurueu%2Fdbg/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/appgurueu","download_url":"https://codeload.github.com/appgurueu/dbg/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":229915696,"owners_count":18144014,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["debug","lua","minetest","mod","pretty-printing"],"created_at":"2024-10-28T20:57:59.731Z","updated_at":"2024-12-16T06:08:01.708Z","avatar_url":"https://github.com/appgurueu.png","language":"Lua","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Debug (`dbg`)\n\nDebugging on steroids for Minetest mods\n\n## Motivation\n\nLua offers very powerful introspective facilities through its `debug` library, which unfortunately almost always go unused due to their clunky APIs.\n\nCurrent state-of-the-art in Minetest mod debugging appears to be print/log/chat \"debugging\" using serialization or `dump`,\nall of which should be rendered obsolete by `dbg`.\n\n## API\n\n**Optionally depend on `dbg` in `mod.conf` to ensure that it is available for load-time debugging.**\n\n### `dbg()`\n\nShorter alias for `dbg.dd()`.\n\n`debug.debug()` on steroids: Starts a REPL (read-eval-print-loop); equivalent to a breakpoint. Features include:\n\n* Full access to locals \u0026 upvalues of the calling function\n* Own local table `_L` where `local` debug vars get stored\n* Ability to enter expressions (rather than statements)\n* Continuation, which works the same as in the Lua REPL (+ empty lines working)\n* Pretty-printing using `dbg.pp`, including syntax highlighting\n\nEnter `cont` to exit without an error. Use `err` to throw after error debugging sessions (`dbg.error`, `dbg.assert`).\n\nUse EOF (\u003ckbd\u003eCtrl + D\u003c/kbd\u003e on Unix) to exit \u0026 shut down Minetest.\n\n### `dbg.error(message, [level])`\n\nStarts a debugging session at the given (optional) level, printing the error message.\n\n### `dbg.assert(value, [message])`\n\nReturns `value`. Starts an error debugging session if `value` is falsey. Error `message` is optional.\n\n### `dbg.pp(...)`\n\nPretty-prints the given vararg using the default parameters.\n\nIf the argument list of functions is unreliable (see `dbg.getargs_reliable` below),\na question mark (`?`) will be appended to the argument list to indicate this.\n\n### `dbg.ppp(params, ...)`\n\nParameterized pretty-print. Requires a custom pretty-printer parameter table `params`:\n\n* `write = function(str, token_type)`, where `token_type` is optional and may be one of `nil`, `boolean`, `number`, `string`, `reference`, `function` or `type`\n* `upvalues = true`, whether upvalues should be written\n\n### `dbg.vars(level)`\n\nReturns a virtual variable table of locals \u0026 upvalues `vars` for the given stacklevel that supports the following operations:\n\n* Getting: `vars.varname`\n* Setting: `vars.varname = value`\n* Looping: `for varname, value in vars() do ... end`\n\n### `dbg.locals(level)`\n\nReturns a virtual variable table of local values at the given stack level.\n\nLocals include upvalues.\n\n### `dbg.upvals(func)`\n\n`func` may be either a function or a stack level (including `nil`, which defaults to the stack level of the calling function).\n\nReturns a virtual variable table of upvalues at the given stack level.\n\n### `dbg.traceback(level)`\n\nFormats a stack trace starting at `level`. Similar to Lua's builtin `debug.stacktrace`, but shortens paths and accepts no `message` to prepend.\n\n### `dbg.stackinfo(level)`\n\nReturns a list of `info` by repeatedly calling `debug.getinfo` starting with `level` and working down the stack.\n\n### `dbg.getvararg(level)`\n\n**Only available on LuaJIT; on PUC Lua 5.1, `dbg.getvararg` will be `nil`.**\n\nReturns the vararg at the given stack level.\n\n### `dbg.getargs(func)`\n\n**Function parameter list detection doesn't work properly on PUC Lua 5.1; unused params are lost and varargs are turned into `arg`.**\nUse `dbg.getargs_reliable` (boolean) to check for reliability.\n\nReturns a table containing the argument names of `func` in string form\n(example: `{\"x\", \"y\", \"z\", \"...\"}` for `function(x, y, z, ...) end`).\n\n### `dbg.shorten_path(path)`\n\nShortens `path`: If path is a subpath of a mod, it will be shortened to `\"\u003cmodname\u003e:\u003csubpath\u003e\"`.\n\n## Security\n\nDebug deliberately exposes the unrestricted `debug` API globally, as well as the `dbg` wrapper API,\nboth of which can be abused to exit the mod security sandbox.\n\n**Only use `dbg` in environments where you trust all enabled mods.**\n**Adding `dbg` to `secure.trusted_mods` (recommended) or disabling mod security (not recommended) is required.**\n\nThe `/lua` chatcommand must explicitly be enabled on servers by setting `secure.dbg.lua` to `true`;\nif enabled, server owners risk unprivileged users gaining access through MITM attacks.\n\n## Usage\n\n**Prerequisites:** LuaJIT and a terminal with decent ANSI support are highly recommended.\n\n### `/dbg`\n\nCalls `dbg()` to start debugging in the console.\n\n### `/lua \u003ccode\u003e`\n\nExecutes the code and pretty-prints the result(s) to chat.\nOnly available in singleplayer for security reasons (risk of MITM attacks).\n\n---\n\nLinks: [GitHub](https://github.com/appgurueu/dbg), [ContentDB](https://content.minetest.net/packages/LMD/dbg), [Minetest Forums](https://forum.minetest.net/viewtopic.php?f=9\u0026t=28372)\n\nLicense: Written by Lars Müller and licensed under the MIT license (see `License.txt`).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fappgurueu%2Fdbg","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fappgurueu%2Fdbg","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fappgurueu%2Fdbg/lists"}