A simple, embedabble CLI debugger for Lua 5.1, Lua 5.2 and LuaJIT 2.0.

Have you ever been working on an embedded Lua project and found yourself in need of a debugger? (I actually have never done a project in Lua, but I'm warming up to the idea now that I have a debugger I like...) The lua-users wiki lists a number of them. While clidebugger was closest to what I wanted, I ran into several compatibility issues. The rest of them are very large libraries that require you to integrate socket libraries or other native libraries and such into your program. I just wanted something simple that would work through stdin/out. I also decided that it sounded fun to try and make my own.

• Simple to "install". Simply copy debugger.lua into your project then load it using local dbg = require().
• Conditional assert-style breakpoints.
• Easy to set it up to break on assert() or error()
• dbg.call() works similar to xpcall() but starts the debugger when an error occurs.
• Works with Lua 5.2, Lua 5.1, LuaJIT 2.0 and probably other versions that I didn't bother to test.
• The regular assortment of commands you'd expect from a debugger: continue, step, next, finish, print/eval expression, move up/down the stack, backtrace, print locals, inline help.
• Evaluate expressions and call functions interactively in the debugger. Inspect locals, upvalues and globals. Even works with varargs ... (Lua 5.2 only).
• Pretty printed output so you get {1 = 3, "a" = 5} instead of table: 0x10010cfa0
• Speed. The debugger hooks are only set when running the step/next/finish commands and shouldn't otherwise affect your program's performance.
• IO could easily be remapped to a socket or window by rewriting the dbg_write() and dbg_read() functions.

First of all, there is nothing to install. Just drop debugger.lua into your project and load it using require(). It couldn't be simpler.

-- MyBuggyProgram.lua

local dbg = require("debugger")

function foo()
	-- Calling dbg() will enter the debugger on the next executable line, right before it calls print().
	-- Once in the debugger, you will be able to step around and inspect things.
	dbg()
	
	-- Maybe you only want to start the debugger on a certain condition.
	-- If you pass a value to dbg(), it works like an assert statement.
	-- The debugger only triggers if it's nil or false.
	dbg(5 == 5) -- Will be ignored
	
	print("Fooooo!!!!")
end

foo()

-- You can also wrap a chunk of code in a dbg.call() block.
-- Any error that occurs will cause the debugger to attach.
-- Then you can inspect the cause.
-- (NOTE: dbg.call() expects a function that takes no parameters)
dbg.call(function()
	-- Put some buggy code in here:
	local err1 = "foo" + 5
	local err2 = (nil).bar
end)

-- Lastly, you can override the standard Lua error() and assert() functions if you want:
-- These variations will enter the debugger instead of throwing an error.
-- dbg.call() is generally more useful though.
local assert = dbg.assert
local error = dbg.error

If you have used other CLI debuggers, debugger.lua should present no surprises. All the commands are a single letter as writting a "real" command parser seemed like a waste of time. debugger.lua is simple, and there are only a small handful of commands anwyay.

[return] - re-run last command
c(ontinue) - contiue execution
s(tep) - step forward by one line (into functions)
n(ext) - step forward by one line (skipping over functions)
p(rint) [expression] - execute the expression and print the result
f(inish) - step forward until exiting the current function
u(p) - move up the stack by one frame
d(own) - move down the stack by one frame
t(race) - print the stack trace
l(ocals) - print the function arguments, locals and upvalues.
h(elp) - print this message

If you've never used a CLI debugger before. Start a nice warm cozy fire, run tutorial.lua and open it up in your favorite editor so you can follow along.

• Lua 5.1 and LuaJIT lack the API to access varargs. The workaround is to do something like local args = {...} and then use unpack(args) when you want to access them. In Lua 5.2, you can simply use ... in your expressions with the print command.
• You can't add breakpoints to a running program or remove them. Currently the only way to set them is by explicitly calling the dbg() function.
• The print command will only print out the first 256 return values of an expression. Darn!
• Untested with Lua versions other than Lua 5.1, Lua 5.2 and LuaJIT 2.0b10.
• Different interpreters (and versions) print out different stack trace information. They all seem to output slightly different variations of mostly the same thing.
• Tail calls are handled silghtly differently in different interpreters. You may find that 1.) stepping into a function that does nothing but a tail call steps you into the tail called function. 2.) The interpreter gives you the wrong name of a tail called function (watch the line numbers). 3.) Stepping out of a tail called function also steps out of the function that performed the tail call. Mostly this is never a problem, but it is a little confusing if you don't know what is going on.
• Coroutines may or may not work as expected... I haven't tested them extensively yet. (Though I certainly will on my current project)

debugger.lua basically does everything I want now, although I have some ideas for enhancements.

• Custom formatters: The built in pretty-printing works fine for most things. It would be nice to be able to register custom formatting functions though.
• Readline support for LuaJIT: Line editing and history would be pretty nice to have. With LuaJIT it might be easy using the FFI.