Creating Solid APIs with Lua

Chapter 5. Detecting Errors

The best way to find a bug is quickly. Sadly, there are many ways to find bugs slowly. Your app could crash long after the bad code executed, or it could crash with no indication as to where in the code the mistake is. This chapter helps you write code that can detect errors as quickly as possible and report a specific code location when things do go wrong.

The C API functions that work with Lua errors are analogous to Lua’s built-in error functions error() and pcall(). So, I’ll begin with a discussion of these two Lua functions and then dive into their C analogues.

Throwing and Catching Errors in Lua

Lua has an error mechanism similar to exceptions. I’ll expand on this analogy, but if exceptions are completely new to you, this chapter gives a self-contained overview of Lua’s error() function.

If you call the error() function in Lua, control flow jumps up the call stack until it finds an error handler. In other languages, this is like a low-level function throwing an exception that is caught higher in the call stack. In Lua, error handlers are set up by wrapping a function call with the pcall() function, which we’ll examine in more detail later in this chapter. If no error handler is present, the error propagates to the top of the call stack universe, escaping into the wild unknown. In that case, Lua invokes a panic, which means that it prints a stack trace and exits the app.

Although the Lua documentation tends to avoid the word “exception,” I’ll ...