{"id":13895993,"url":"https://github.com/orbitalquark/textadept-debugger","last_synced_at":"2025-05-01T18:30:30.009Z","repository":{"id":42376314,"uuid":"301854519","full_name":"orbitalquark/textadept-debugger","owner":"orbitalquark","description":"Language debugging module for Textadept.","archived":false,"fork":false,"pushed_at":"2025-04-24T13:36:44.000Z","size":114,"stargazers_count":9,"open_issues_count":0,"forks_count":1,"subscribers_count":3,"default_branch":"default","last_synced_at":"2025-04-24T14:39:15.645Z","etag":null,"topics":["c","debugger","debugging","gdb","lua","textadept","textadept-module"],"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/orbitalquark.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2020-10-06T21:05:34.000Z","updated_at":"2025-04-24T13:35:15.000Z","dependencies_parsed_at":"2023-12-31T18:24:02.579Z","dependency_job_id":"cf170ed3-105a-463d-b71a-931b09f23be7","html_url":"https://github.com/orbitalquark/textadept-debugger","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/orbitalquark%2Ftextadept-debugger","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/orbitalquark%2Ftextadept-debugger/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/orbitalquark%2Ftextadept-debugger/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/orbitalquark%2Ftextadept-debugger/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/orbitalquark","download_url":"https://codeload.github.com/orbitalquark/textadept-debugger/tar.gz/refs/heads/default","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251924562,"owners_count":21665991,"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":["c","debugger","debugging","gdb","lua","textadept","textadept-module"],"created_at":"2024-08-06T18:02:36.111Z","updated_at":"2025-05-01T18:30:29.992Z","avatar_url":"https://github.com/orbitalquark.png","language":"Lua","readme":"# Debugger\n\nLanguage debugging support for Textadept.\n\nAll this module does is emit debugger events. Submodules that implement debuggers listen\nfor these events and act on them.\n\nInstall this module by copying it into your *~/.textadept/modules/* directory or Textadept's\n*modules/* directory, and then putting the following in your *~/.textadept/init.lua*:\n\n```lua\nlocal debugger = require('debugger')\n```\n\nThere will be a top-level \"Debug\" menu.\n\nCurrently, only debugging Lua scripts should work out of the box, provided [LuaSocket][]\nis installed for the external Lua interpreter invoked. (This module has its own copy of\nLuaSocket that is used by Textadept's internal Lua state only.) Running \"Debug \u003e Go\" will\nrun the current script up to the first breakpoint, while \"Debug \u003e Step Over\" and \"Debug \u003e\nStep Into\" will pause after the current script's first statement.\n\nProject-specific debugging is configured using the [`debugger.project_commands`](#debugger.project_commands) table. For\nexample, in order to use this module to debug a C program via GDB:\n\n```lua\nlocal debugger = require('debugger')\ndebugger.project_commands['/path/to/project'] = function()\n\treturn 'c', '/path/to/exe', 'command line args'\nend\n```\n\nTextadept can debug another instance of [itself][1].\n\n[LuaSocket]: http://w3.impa.br/~diego/software/luasocket/\n[1]: https://github.com/orbitalquark/.textadept/blob/4c936361d45fa8f99e16df0d71fc9306bee216bc/init.lua#L179\n\n## Compiling\n\nReleases include binaries, so building this modules should not be necessary. If you want\nto build manually, use CMake. For example:\n\n```bash\ncmake -S . -B build_dir\ncmake --build build_dir\ncmake --install build_dir\n```\n\n## Key Bindings\n\nWindows and Linux | macOS | Terminal | Command\n-|-|-|-\n**Debug**| | |\nF5 | F5 | F5 | Start debugging\nF10 | F10 | F10 | Step over\nF11 | F11 | F11 | Step into\nShift+F11 | ⇧F11 | S-F11 | Step out\nShift+F5 | ⇧F5 | S-F5 | Stop debugging\nAlt+= | ⌥= | M-= | Inspect variable\nAlt++ | ⌥+ | M-+ | Evaluate expression...\n\n\u003ca id=\"debugger.MARK_BREAKPOINT\"\u003e\u003c/a\u003e\n## `debugger.MARK_BREAKPOINT`\n\nThe marker number for breakpoints.\n\n\u003ca id=\"debugger.MARK_BREAKPOINT_COLOR\"\u003e\u003c/a\u003e\n## `debugger.MARK_BREAKPOINT_COLOR`\n\nThe color of breakpoint markers.\n\n\u003ca id=\"debugger.MARK_CALLSTACK\"\u003e\u003c/a\u003e\n## `debugger.MARK_CALLSTACK`\n\nThe marker number for the current call stack line.\n\n\u003ca id=\"debugger.MARK_DEBUGLINE\"\u003e\u003c/a\u003e\n## `debugger.MARK_DEBUGLINE`\n\nThe marker number for the current debug line.\n\n\u003ca id=\"events.DEBUGGER_BREAKPOINT_ADDED\"\u003e\u003c/a\u003e\n## `events.DEBUGGER_BREAKPOINT_ADDED`\n\nEmitted when a breakpoint is added.\n\nThis is only emitted when the debugger is running and paused (e.g. at a breakpoint).\nBreakpoints added while the debugger is not running are queued up until the debugger starts.\n\nArguments:\n- *lang*: The lexer name of the language to add a breakpoint for.\n- *filename*: The filename to add a breakpoint in.\n- *line*: The 1-based line number to break on.\n\n\u003ca id=\"events.DEBUGGER_BREAKPOINT_REMOVED\"\u003e\u003c/a\u003e\n## `events.DEBUGGER_BREAKPOINT_REMOVED`\n\nEmitted when a breakpoint is removed.\n\nThis is only emitted when the debugger is running and paused (e.g. at a breakpoint).\n\nArguments:\n- *lang*: The lexer name of the language being debugged.\n- *filename*: The filename to remove a breakpoint from.\n- *line*: The 1-based line number to stop breaking on.\n\n\u003ca id=\"events.DEBUGGER_COMMAND\"\u003e\u003c/a\u003e\n## `events.DEBUGGER_COMMAND`\n\nEmitted when a debugger command should be run.\n\nThis is only emitted when the debugger is running and paused (e.g. at a breakpoint).\n\nArguments:\n- *lang*: The lexer name of the language being debugged.\n- *text*: The text of the command to run.\n\n\u003ca id=\"events.DEBUGGER_CONTINUE\"\u003e\u003c/a\u003e\n## `events.DEBUGGER_CONTINUE`\n\nEmitted when a execution should be continued.\n\nThis is only emitted when the debugger is running and paused (e.g. at a breakpoint).\n\nArguments:\n- *lang*: The lexer name of the language being debugged.\n- *...*: Any arguments passed to [`debugger.continue()`](#debugger.continue).\n\n\u003ca id=\"events.DEBUGGER_INSPECT\"\u003e\u003c/a\u003e\n## `events.DEBUGGER_INSPECT`\n\nEmitted when a symbol should be inspected.\n\nDebuggers typically show a symbol's value in a calltip via `view:call_tip_show()`.\nThis is only emitted when the debugger is running and paused (e.g. at a breakpoint).\n\nArguments:\n- *lang*: The lexer name of the language being debugged.\n- *position*: The buffer position of the symbol to inspect. The debugger is responsible for\n\tidentifying the symbol's name, as symbol characters vary from language to language.\n\n\u003ca id=\"events.DEBUGGER_PAUSE\"\u003e\u003c/a\u003e\n## `events.DEBUGGER_PAUSE`\n\nEmitted when execution should be paused.\n\nThis is only emitted when the debugger is running and executing (e.g. not at a breakpoint).\nIf a listener pauses the debugger, it *must* return `true`. Otherwise, it is assumed that\ndebugger could not be paused. Listeners *must not* return `false` (they can return `nil`).\n\nArguments:\n- *lang*: The lexer name of the language being debugged.\n- *...*: Any arguments passed to [`debugger.pause()`](#debugger.pause).\n\n\u003ca id=\"events.DEBUGGER_RESTART\"\u003e\u003c/a\u003e\n## `events.DEBUGGER_RESTART`\n\nEmitted when execution should restart from the beginning.\n\nThis is only emitted when the debugger is running.\n\nArguments:\n- *lang*: The lexer name of the language being debugged.\n- *...*: Any arguments passed to [`debugger.restart()`](#debugger.restart).\n\n\u003ca id=\"events.DEBUGGER_SET_FRAME\"\u003e\u003c/a\u003e\n## `events.DEBUGGER_SET_FRAME`\n\nEmitted when a stack frame should be switched to.\n\nThis is only emitted when the debugger is running and paused (e.g. at a breakpoint).\n\nArguments:\n- *lang*: The lexer name of the language being debugged.\n- *level*: The 1-based stack level number to switch to. This value depends on the stack\n\tlevels given to [`debugger.update_state()`](#debugger.update_state).\n\n\u003ca id=\"events.DEBUGGER_START\"\u003e\u003c/a\u003e\n## `events.DEBUGGER_START`\n\nEmitted when a debugger should be started.\n\nThe debugger should not start executing yet, as there will likely be incoming breakpoint\nand watch add events. Subsequent events will instruct the debugger to begin executing.\nIf a listener creates a debugger, it *must* return `true`. Otherwise, it is assumed that no\ndebugger was created and subsequent debugger functions will not work. Listeners *must not*\nreturn `false` (they can return `nil`).\n\nArguments:\n- *lang*: The lexer name of the language to start debugging.\n- *...*: Any arguments passed to [`debugger.start()`](#debugger.start).\n\n\u003ca id=\"events.DEBUGGER_STEP_INTO\"\u003e\u003c/a\u003e\n## `events.DEBUGGER_STEP_INTO`\n\nEmitted when execution should continue by one line, stepping into functions.\n\nThis is only emitted when the debugger is running and paused (e.g. at a breakpoint).\n\nArguments:\n- *lang*: The lexer name of the language being debugged.\n- *...*: Any arguments passed to [`debugger.step_into()`](#debugger.step_into).\n\n\u003ca id=\"events.DEBUGGER_STEP_OUT\"\u003e\u003c/a\u003e\n## `events.DEBUGGER_STEP_OUT`\n\nEmitted when execution should continue, stepping out of the current function.\n\nThis is only emitted when the debugger is running and paused (e.g. at a breakpoint).\n\nArguments:\n- *lang*: The lexer name of the language being debugged.\n- *...*: Any arguments passed to [`debugger.step_out()`](#debugger.step_out).\n\n\u003ca id=\"events.DEBUGGER_STEP_OVER\"\u003e\u003c/a\u003e\n## `events.DEBUGGER_STEP_OVER`\n\nEmitted when execution should continue by one line, stepping over functions.\n\nThis is only emitted when the debugger is running and paused (e.g. at a breakpoint).\n\nArguments:\n- *lang*: The lexer name of the language being debugged.\n- *...*: Any arguments passed to [`debugger.step_over()`](#debugger.step_over).\n\n\u003ca id=\"events.DEBUGGER_STOP\"\u003e\u003c/a\u003e\n## `events.DEBUGGER_STOP`\n\nEmitted when a debugger should be stopped.\n\nThis is only emitted when the debugger is running.\n\nArguments:\n- *lang*: The lexer name of the language to stop debugging.\n- *...*: Any arguments passed to [`debugger.stop()`](#debugger.stop).\n\n\u003ca id=\"events.DEBUGGER_WATCH_ADDED\"\u003e\u003c/a\u003e\n## `events.DEBUGGER_WATCH_ADDED`\n\nEmitted when a watch is added.\n\nThis is only emitted when the debugger is running and paused (e.g. at a breakpoint). Watches\nadded while the debugger is not running are queued up until the debugger starts.\n\nArguments:\n- *lang*: The lexer name of the language to add a watch for.\n- *expr*: The expression or variable to watch, depending on what the debugger supports.\n- *id*: The expression's ID number.\n- *no_break*: Whether the debugger should not break when the watch's value changes.\n\n\u003ca id=\"events.DEBUGGER_WATCH_REMOVED\"\u003e\u003c/a\u003e\n## `events.DEBUGGER_WATCH_REMOVED`\n\nEmitted when a watch is removed.\n\nThis is only emitted when the debugger is running and paused (e.g. at a breakpoint).\n\nArguments:\n- *lang*: The lexer name of the language being debugged.\n- *expr*: The expression to stop watching.\n- *id*: The expression's ID number.\n\n\u003ca id=\"debugger.aliases\"\u003e\u003c/a\u003e\n## `debugger.aliases`\n\nMap of lexer languages to debugger modules.\n\nThis is for debugger modules that support more than one language (e.g. the gdb module supports\n'c' and 'cpp'). Otherwise, a debugger module should be named after the lexer language\nit debugs and an alias is not necessary.\n\nFields:\n- `c`: \n- `cpp`: \n\n\u003ca id=\"debugger.call_stack\"\u003e\u003c/a\u003e\n## `debugger.call_stack`()\n\nUpdates the buffer containing the call stack.\n\n\u003ca id=\"debugger.continue\"\u003e\u003c/a\u003e\n## `debugger.continue`([*lang*])\n\nContinue debugger execution unless the debugger is already executing (e.g.\nnot at a\nbreakpoint).\nIf no debugger is running, this will start one and then continue execution.\n\nEmits `events.DEBUGGER_CONTINUE`, passing along any arguments given.\n\nParameters:\n- *lang*:  String lexer name of the language to continue executing. The default value\n\tis the name of the current lexer.\n\n\u003ca id=\"debugger.evaluate\"\u003e\u003c/a\u003e\n## `debugger.evaluate`(*text*)\n\nEvaluates text in the current debugger context if the debugger is paused.\n\nThe result (if any) is not returned, but likely printed to the message buffer.\n\nParameters:\n- *text*:  String text to evaluate.\n\n\u003ca id=\"debugger.inspect\"\u003e\u003c/a\u003e\n## `debugger.inspect`(*position*)\n\nInspects the symbol (if any) at a buffer position, unless the debugger is executing (e.g.\nnot\nat a breakpoint).\nEmits `events.DEBUGGER_INSPECT`.\n\nParameters:\n- *position*:  Position to inspect.\n\n\u003ca id=\"debugger.pause\"\u003e\u003c/a\u003e\n## `debugger.pause`(...)\n\nPause debugger execution unless the debugger is already paused (e.g.\nat a breakpoint).\nEmits `events.DEBUGGER_PAUSE`, passing along any additional arguments given.\n\nParameters:\n- *...*: \n\n\u003ca id=\"debugger.project_commands\"\u003e\u003c/a\u003e\n## `debugger.project_commands`\n\nMap of project root directories to functions that return the language of the debugger to\nstart followed by the arguments to pass to that debugger's `events.DEBUGGER_START` handler.\n\nUsage:\n\n```lua\ndebugger.project_commands['/path/to/project'] = 'gdb /path/to/exe'\n```\n\n\u003ca id=\"debugger.remove_breakpoint\"\u003e\u003c/a\u003e\n## `debugger.remove_breakpoint`([*file*=buffer.filename[, *line*]])\n\nRemoves a breakpoint from a line.\n\nEmits `events.DEBUGGER_BREAKPOINT_REMOVED` if the debugger is running.\n\nIf the debugger is executing (e.g. not at a breakpoint), assumes a breakpoint cannot be\nremoved and shows an error message.\n\nParameters:\n- *file*:  String filename of the breakpoint to remove.\n- *line*:  Line number starting from 1 of the breakpoint to remove. If `nil`,\n\tuser is prompted for a breakpoint(s) to remove.\n\n\u003ca id=\"debugger.remove_watch\"\u003e\u003c/a\u003e\n## `debugger.remove_watch`([*id*])\n\nStops watching an expression.\n\nEmits `events.DEBUGGER_WATCH_REMOVED` if the debugger is running.\n\nIf the debugger is executing (e.g. not at a breakpoint), assumes a watch cannot be set and\nshows an error message.\n\nParameters:\n- *id*:  ID number of the expression, as given in the `events.DEBUGGER_WATCH_ADDED`\n\tevent. If `nil`, the user is prompted for one.\n\n\u003ca id=\"debugger.restart\"\u003e\u003c/a\u003e\n## `debugger.restart`(...)\n\nRestarts debugger execution from the beginning.\n\nEmits `events.DEBUGGER_PAUSE`, passing along any additional arguments given.\n\nParameters:\n- *...*: \n\n\u003ca id=\"debugger.set_frame\"\u003e\u003c/a\u003e\n## `debugger.set_frame`([*level*])\n\nPrompts the user to select a stack frame to switch to from the current debugger call stack,\nunless the debugger is executing (e.g.\nnot at a breakpoint).\nEmits `events.DEBUGGER_SET_FRAME`.\n\nParameters:\n- *level*:  Stack frame index starting from 1 to switch to.\n\n\u003ca id=\"debugger.set_watch\"\u003e\u003c/a\u003e\n## `debugger.set_watch`(*expr*[, *no_break*=false])\n\nWatches an expression for changes and breaks on each change.\n\nEmits `events.DEBUGGER_WATCH_ADDED` if the debugger is running, or queues up the event to\nrun in [`debugger.start()`](#debugger.start).\n\nIf the debugger is executing (e.g. not at a breakpoint), assumes a watch cannot be set and\nshows an error message.\n\nParameters:\n- *expr*:  String expression to watch.\n- *no_break*:  Just watch the expression and not break on changes.\n\n\u003ca id=\"debugger.socket\"\u003e\u003c/a\u003e\n## `debugger.socket`\n\nThe LuaSocket module.\n\n\u003ca id=\"debugger.start\"\u003e\u003c/a\u003e\n## `debugger.start`([*lang*])\n\nStarts a debugger and adds any queued breakpoints and watches.\n\nEmits `events.DEBUGGER_START`, passing along any arguments given. If a debugger cannot be\nstarted, the event handler should throw an error.\n\nThis only starts a debugger. [`debugger.continue()`](#debugger.continue), [`debugger.step_into()`](#debugger.step_into), or\n[`debugger.step_over()`](#debugger.step_over) should be called next to begin debugging.\n\nParameters:\n- *lang*:  String lexer name of the language to start debugging. The default value is\n\tthe name of the current lexer.\n\nReturns: whether or not a debugger was started\n\n\u003ca id=\"debugger.step_into\"\u003e\u003c/a\u003e\n## `debugger.step_into`(...)\n\nContinue debugger execution by one line, stepping into functions, unless the debugger is\nalready executing (e.g.\nnot at a breakpoint).\nIf no debugger is running, this will start one and then step.\n\nEmits `events.DEBUGGER_STEP_INTO`, passing along any arguments given.\n\nParameters:\n- *...*: \n\n\u003ca id=\"debugger.step_out\"\u003e\u003c/a\u003e\n## `debugger.step_out`(...)\n\nContinue debugger execution, stepping out of the current function, unless the debugger is\nalready executing (e.g.\nnot at a breakpoint).\nEmits `events.DEBUGGER_STEP_OUT`, passing along any additional arguments given.\n\nParameters:\n- *...*: \n\n\u003ca id=\"debugger.step_over\"\u003e\u003c/a\u003e\n## `debugger.step_over`(...)\n\nContinue debugger execution by one line, stepping over functions, unless the debugger is\nalready executing (e.g.\nnot at a breakpoint).\nIf no debugger is running, this will starts one and then step.\n\nEmits `events.DEBUGGER_STEP_OVER`, passing along any arguments given.\n\nParameters:\n- *...*: \n\n\u003ca id=\"debugger.stop\"\u003e\u003c/a\u003e\n## `debugger.stop`(*lang*)\n\nStops debugging.\n\nDebuggers should call this function when finished.\n\nEmits `events.DEBUGGER_STOP`, passing along any arguments given.\n\nParameters:\n- *lang*: String lexer name of the language to stop debugging. The default value is\n\tthe name of the current lexer.\n\n\u003ca id=\"debugger.toggle_breakpoint\"\u003e\u003c/a\u003e\n## `debugger.toggle_breakpoint`([*file*=buffer.filename[, *line*]])\n\nToggles a breakpoint.\n\nMay emit `events.DEBUGGER_BREAKPOINT_ADDED` and `events.DEBUGGER_BREAKPOINT_REMOVED` depending\non circumstance.\n\nMay show an error message if the debugger is executing (e.g. not at a breakpoint).\n\nParameters:\n- *file*:  String filename of the breakpoint to toggle.\n- *line*:  Line number starting from 1 of the breakpoint to toggle. If `nil`,\n\tthe current line is used.\n\n\u003ca id=\"debugger.update_state\"\u003e\u003c/a\u003e\n## `debugger.update_state`(*state*)\n\nUpdates the running debugger's state and marks the current debug line.\n\nDebuggers need to call this function every time their state changes, typically during\n`DEBUGGER_*` events.\n\nParameters:\n- *state*:  Table with four fields: `file`, `line`, `call_stack`, and `variables`. `file` and\n\t`line` indicate the debugger's current position. `call_stack` is a list of stack frames\n\tand a `pos` field whose value is the 1-based index of the current frame. `variables`\n\tis an optional map of known variables and watches to their values. The debugger can\n\tchoose what kind of variables make sense to put in the map.\n\n\u003ca id=\"debugger.use_status_buffers\"\u003e\u003c/a\u003e\n## `debugger.use_status_buffers`\n\nUse debug status buffers like variables, call stack, etc.\n\nThe default value is `true`.\n\n\u003ca id=\"debugger.variables\"\u003e\u003c/a\u003e\n## `debugger.variables`()\n\nUpdates the buffer containing variables and watches in the current stack frame.\n\nAny variables/watches that have changed since the last updated are marked.\n\n\n\n","funding_links":[],"categories":["Lua"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Forbitalquark%2Ftextadept-debugger","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Forbitalquark%2Ftextadept-debugger","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Forbitalquark%2Ftextadept-debugger/lists"}