Best practice for returning an error from a lua function returning multiple values

Question

I have a lua function which takes multiple parameters and returns as many values as there are parameters. Each return value corresponds to a parameter. To illustrate, consider a function which reads the value for a key/value pair from a database:

val1, val2, val3 = my_function("key1", "key2", "key3");
val1 = my_function("key1");

What is the best way to return an error from my_function? (e.g. if a supplied "key" is invalid)

I understand one way is to return two values on error, nil and an error string. Is this the best approach? For example:

val1, val2, val3 = my_function("key1", "key2", "key3");
if val1 then
    -- Use val1, val2, and val3.
else
    print("ERROR: " .. val2);
end

Edit

Some additional points:

1. The lua script is being executed from within a C program using lua_pcall().
2. The C program must not abort if the script fails.
3. my_function() is implemented in C.
4. When my_function() fails, it should also return an error code (or message) indicating the reason it failed.

Answer 1

The standard way of throwing errors in Lua is via the error function (manual, api) or via assert (which internally uses error anyway).

Since your function is in C, you should be calling lua_error inside it, to gain the same effect.

But keep in mind that your function now is "insecure". If unmodified, the following code will do the equivalent of "throwing an exception" and thus halting the program, if key1, key2 or key3 are "erroneous":

val1, val2, val3 = my_function("key1", "key2", "key3")

Sometimes it's ok to let the program "just crash" if the inputs are wrong. Depending on your setup, the user will get a message with the last error, and a stack trace, or something along those lines.

If "letting the program crash" is not an option, you can do the equivalent of surrounding it with a "try-catch" block by using the pcall function, and adding a new variable called ok:

ok, val1, val2, val3 = pcall(my_function, "key1", "key2", "key3")
if ok then
  -- Use val1, val2, and val3.
else
  print("ERROR: " .. val1) -- notice that we use val1 here, not val2
end

Notice that you don't have to put pcall exactly on top of my_function. As with exceptions, the error recuperation can happen higher in the call chain: in the function calling my_function, or the function calling that one, etc. For example, if you call my_function from a function called parent, and parent from one called grandParent, you can do this:

-- parent is "insecure" since my_function is "unprotected"
function parent(key1, key2)
  local val1, val2, val3 = my_function(key1, key2, "key3")
  return val1, val2, val3
end

-- grandParent calls parent in a "safe" way
function grandParent()
  local ok, val1, val2, val3 = pcall(parent, "key1", "key2")
  if ok then
    -- Use val1, val2, and val3.
  else
    print("ERROR: " .. val1)
  end
end