https://github.com/ignacio/StackTracePlus
StackTracePlus provides enhanced stack traces for Lua.
https://github.com/ignacio/StackTracePlus
Last synced: 6 months ago
JSON representation
StackTracePlus provides enhanced stack traces for Lua.
- Host: GitHub
- URL: https://github.com/ignacio/StackTracePlus
- Owner: ignacio
- License: mit
- Created: 2010-11-04T18:13:09.000Z (about 15 years ago)
- Default Branch: master
- Last Pushed: 2023-07-24T00:50:55.000Z (over 2 years ago)
- Last Synced: 2025-06-08T11:51:26.285Z (7 months ago)
- Language: Lua
- Homepage:
- Size: 38.1 KB
- Stars: 198
- Watchers: 18
- Forks: 27
- Open Issues: 11
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- my-awesome-lua - StackTracePlus - Drop-in upgrade to Lua's stack traces which adds local context and improves readability. (Resources / Debugging)
- awesome-lua - StackTracePlus - Drop-in upgrade to Lua's stack traces which adds local context and improves readability. (Resources / Debugging and Profiling)
README
# StackTracePlus #
[](https://travis-ci.org/ignacio/StackTracePlus)
[](https://coveralls.io/github/ignacio/StackTracePlus?branch=master)
StackTracePlus provides enhanced stack traces for [Lua 5.1, Lua 5.2, Lua 5.3][1], [LuaJIT][2] and [OpenResty][4].
StackTracePlus can be used as a replacement for debug.traceback. It gives detailed information about locals, tries to guess
function names when they're not available, etc, so, instead of
lua5.1.exe: D:\trunk_git\sources\stacktraceplus\test\test.lua:10: attempt to concatenate a nil value
stack traceback:
D:\trunk_git\sources\stacktraceplus\test\test.lua:10: in function
(tail call): ?
D:\trunk_git\sources\stacktraceplus\test\test.lua:15: in main chunk
[C]: ?
you'll get
lua5.1.exe: D:\trunk_git\sources\stacktraceplus\test\test.lua:10: attempt to concatenate a nil value
Stack Traceback
===============
(2) C function 'function: 00A8F418'
(3) Lua function 'g' at file 'D:\trunk_git\sources\stacktraceplus\test\test.lua:10' (best guess)
Local variables:
fun = table module
str = string: "hey"
tb = table: 027DCBE0 {dummy:1, blah:true, foo:bar}
(*temporary) = nil
(*temporary) = string: "text"
(*temporary) = string: "attempt to concatenate a nil value"
(4) tail call
(5) main chunk of file 'D:\trunk_git\sources\stacktraceplus\test\test.lua' at line 15
(6) C function 'function: 002CA480'
## Usage #
StackTracePlus can be used as a replacement for `debug.traceback`, as an `xpcall` error handler or even from C code. Note that
only the Lua 5.1 interpreter and OpenResty allows the traceback function to be replaced "on the fly". Interpreters for LuaJIT, Lua 5.2 and 5.3 always calls luaL_traceback internally so there is no easy way to override that.
```lua
local STP = require "StackTracePlus"
debug.traceback = STP.stacktrace
function test()
local s = "this is a string"
local n = 42
local t = { foo = "bar" }
local co = coroutine
local cr = coroutine.create
error("an error")
end
test()
```
That script will output (only with Lua 5.1):
lua5.1: example.lua:11: an error
Stack Traceback
===============
(2) C function 'function: 006B5758'
(3) global C function 'error'
(4) Lua global 'test' at file 'example.lua:11'
Local variables:
s = string: "this is a string"
n = number: 42
t = table: 006E5220 {foo:bar}
co = coroutine table
cr = C function: 003C7080
(5) main chunk of file 'example.lua' at line 14
(6) C function 'function: 00637B30'
**StackTracePlus** is aware of the usual Lua libraries, like *coroutine*, *table*, *string*, *io*, etc and functions like
*print*, *pcall*, *assert*, and so on.
You can also make STP aware of your own tables and functions by calling *add_known_function* and *add_known_table*.
```lua
local STP = require "StackTracePlus"
debug.traceback = STP.stacktrace
local my_table = {
f = function() end
}
function my_function()
end
function test(data, func)
local s = "this is a string"
error("an error")
end
STP.add_known_table(my_table, "A description for my_table")
STP.add_known_function(my_function, "A description for my_function")
test( my_table, my_function )
```
Will output:
lua5.1: ..\test\example2.lua:13: an error
Stack Traceback
===============
(2) C function 'function: 0073AAA8'
(3) global C function 'error'
(4) Lua global 'test' at file '..\test\example2.lua:13'
Local variables:
data = A description for my_table
func = Lua function 'A description for my_function' (defined at line 7 of chunk ..\test\example2.lua)
s = string: "this is a string"
(5) main chunk of file '..\test\example2.lua' at line 19
(6) C function 'function: 00317B30'
## Installation #
The easiest way to install is with [LuaRocks][3].
- luarocks install stacktraceplus
If you don't want to use LuaRocks, just copy StackTracePlus.lua to Lua's path.
## License #
**StackTracePlus** is available under the MIT license.
[1]: http://www.lua.org/
[2]: http://luajit.org/
[3]: https://luarocks.org/
[4]: https://openresty.org/