Debug.traceback

Available since: Gideros 2011.6

Description

Frequently, when an error happens, we want more debug information than only the location where the error occurred. At least, we want a traceback, showing the complete stack of calls leading to the error. When pcall returns its error message, it destroys part of the stack (the part that went from it to the error point). Consequently, if we want a traceback, we must build it before pcall returns. To do that, Lua provides the xpcall function. Besides the function to be called, it receives a second argument, an error handler function. In case of errors, Lua calls that error handler before the stack unwinds, so that it can use the debug library to gather any extra information it wants about the error. Two common error handlers are debug.debug, which gives you a Lua prompt so that you can inspect by yourself what was going on when the error happened (later we will see more about that, when we discuss the debug library); and debug.traceback, which builds an extended error message with a traceback. The latter is the function that the stand-alone interpreter uses to build its error messages. You also can call debug.traceback at any moment to get a traceback of the current execution:

(string), = debug.traceback(messagelevel,)

message: (string) message to debug optional
level: (number) stack level optional
Returns (string) debug traceback