From 65e82f7c12f95e461363e15c781c3fd4c5d241d3 Mon Sep 17 00:00:00 2001 From: Alexander Gavrilov Date: Fri, 22 Jun 2012 16:36:50 +0400 Subject: [PATCH] Support controllable error presentation verbosity in lua code. Use qerror to squash stack traces and location prefix. --- LUA_API.rst | 88 +++++++++++++----- Lua API.html | 162 ++++++++++++++++++++++----------- library/LuaTools.cpp | 78 ++++++++++++++-- library/lua/dfhack.lua | 4 + library/lua/memscan.lua | 2 +- library/lua/utils.lua | 2 +- scripts/devel/find-offsets.lua | 6 +- scripts/fix/item-occupancy.lua | 3 +- scripts/quicksave.lua | 3 +- 9 files changed, 259 insertions(+), 89 deletions(-) diff --git a/LUA_API.rst b/LUA_API.rst index 5136bba57..e8c413fe7 100644 --- a/LUA_API.rst +++ b/LUA_API.rst @@ -426,13 +426,17 @@ not destroy any objects allocated in this way, so the user should be prepared to catch the error and do the necessary cleanup. -================ -DFHack utilities -================ +========== +DFHack API +========== DFHack utility functions are placed in the ``dfhack`` global tree. -Currently it defines the following features: +Native utilities +================ + +Input & Output +-------------- * ``dfhack.print(args...)`` @@ -474,23 +478,9 @@ Currently it defines the following features: If the interactive console is not accessible, returns *nil, error*. -* ``dfhack.pcall(f[,args...])`` - - Invokes f via xpcall, using an error function that attaches - a stack trace to the error. The same function is used by SafeCall - in C++, and dfhack.safecall. - - The returned error is a table with separate ``message`` and - ``stacktrace`` string fields; it implements ``__tostring``. - -* ``safecall(f[,args...])``, ``dfhack.safecall(f[,args...])`` - - Just like pcall, but also prints the error using printerr before - returning. Intended as a convenience function. - -* ``dfhack.saferesume(coroutine[,args...])`` - Compares to coroutine.resume like dfhack.safecall vs pcall. +Miscellaneous +------------- * ``dfhack.run_script(name[,args...])`` @@ -511,6 +501,36 @@ Currently it defines the following features: to group operations together in one big critical section. A plugin can choose to run all lua code inside a C++-side suspend lock. + +Exception handling +------------------ + +* ``dfhack.error(msg[,level[,verbose]])`` + + Throws a dfhack exception object with location and stack trace. + The verbose parameter controls whether the trace is printed by default. + +* ``qerror(msg[,level])`` + + Calls ``dfhack.error()`` with ``verbose`` being *false*. Intended to + be used for user-caused errors in scripts, where stack traces are not + desirable. + +* ``dfhack.pcall(f[,args...])`` + + Invokes f via xpcall, using an error function that attaches + a stack trace to the error. The same function is used by SafeCall + in C++, and dfhack.safecall. + +* ``safecall(f[,args...])``, ``dfhack.safecall(f[,args...])`` + + Just like pcall, but also prints the error using printerr before + returning. Intended as a convenience function. + +* ``dfhack.saferesume(coroutine[,args...])`` + + Compares to coroutine.resume like dfhack.safecall vs pcall. + * ``dfhack.call_with_finalizer(num_cleanup_args,always,cleanup_fn[,cleanup_args...],fn[,args...])`` Invokes ``fn`` with ``args``, and after it returns or throws an @@ -535,9 +555,33 @@ Currently it defines the following features: Calls ``fn(obj,args...)``, then finalizes with ``obj:delete()``. +* ``dfhack.exception`` + + Metatable of error objects used by dfhack. The objects have the + following properties: + + ``err.where`` + The location prefix string, or *nil*. + ``err.message`` + The base message string. + ``err.stacktrace`` + The stack trace string, or *nil*. + ``err.cause`` + A different exception object, or *nil*. + ``err.thread`` + The coroutine that has thrown the exception. + ``err.verbose`` + Boolean, or *nil*; specifies if where and stacktrace should be printed. + ``tostring(err)``, or ``err:tostring([verbose])`` + Converts the exception to string. + +* ``dfhack.exception.verbose`` + + The default value of the ``verbose`` argument of ``err:tostring()``. + Persistent configuration storage -================================ +-------------------------------- This api is intended for storing configuration options in the world itself. It probably should be restricted to data that is world-dependent. @@ -579,7 +623,7 @@ functions can just copy values in memory without doing any actual I/O. However, currently every entry has a 180+-byte dead-weight overhead. Material info lookup -==================== +-------------------- A material info record has fields: diff --git a/Lua API.html b/Lua API.html index 1c4dc4059..47cf08ab6 100644 --- a/Lua API.html +++ b/Lua API.html @@ -333,30 +333,36 @@ ul.auto-toc {
  • Recursive table assignment
    • -
  • DFHack utilities