Programming in Lua : 25.2

This first edition was written for Lua 5.0. While still largely relevant for later versions, there are some differences.
The fourth edition targets Lua 5.3 and is available at Amazon and other bookstores.
By buying the book, you also help to support the Lua project.

Programming in Lua

Part IV. The C API Chapter 25. Extending your Application

25.2 – Calling Lua Functions

A great strength of Lua is that a configuration file can define functions to be called by the application. For instance, you can write an application to plot the graph of a function and use Lua to define the functions to be plotted.

The API protocol to call a function is simple: First, you push the function to be called; second, you push the arguments to the call; then you use lua_pcall to do the actual call; finally, you pop the results from the stack.

As an example, let us assume that our configuration file has a function like

    function f (x, y)
      return (x^2 * math.sin(y))/(1 - x)
    end

and you want to evaluate, in C, z = f(x, y) for given x and y. Assuming that you have already opened the Lua library and run the configuration file, you can encapsulate this call in the following C function:

    /* call a function `f' defined in Lua */
    double f (double x, double y) {
      double z;
    
      /* push functions and arguments */
      lua_getglobal(L, "f");  /* function to be called */
      lua_pushnumber(L, x);   /* push 1st argument */
      lua_pushnumber(L, y);   /* push 2nd argument */
    
      /* do the call (2 arguments, 1 result) */
      if (lua_pcall(L, 2, 1, 0) != 0)
        error(L, "error running function `f': %s",
                 lua_tostring(L, -1));
    
      /* retrieve result */
      if (!lua_isnumber(L, -1))
        error(L, "function `f' must return a number");
      z = lua_tonumber(L, -1);
      lua_pop(L, 1);  /* pop returned value */
      return z;
    }

You call lua_pcall with the number of arguments you are passing and the number of results you want. The fourth argument indicates an error-handling function; we will discuss it in a moment. As in a Lua assignment, lua_pcall adjusts the actual number of results to what you have asked for, pushing nils or discarding extra values as needed. Before pushing the results, lua_pcall removes from the stack the function and its arguments. If a function returns multiple results, the first result is pushed first; so, if there are n results, the first one will be at index -n and the last at index -1.

If there is any error while lua_pcall is running, lua_pcall returns a value different from zero; moreover, it pushes the error message on the stack (but still pops the function and its arguments). Before pushing the message, however, lua_pcall calls the error handler function, if there is one. To specify an error handler function, we use the last argument of lua_pcall. A zero means no error handler function; that is, the final error message is the original message. Otherwise, that argument should be the index in the stack where the error handler function is located. Notice that, in such cases, the handler must be pushed in the stack before the function to be called and its arguments.

For normal errors, lua_pcall returns the error code LUA_ERRRUN. Two special kinds of errors deserve different codes, because they never run the error handler. The first kind is a memory allocation error. For such errors, lua_pcall always returns LUA_ERRMEM. The second kind is an error while Lua is running the error handler itself. In that case it is of little use to call the error handler again, so lua_pcall returns immediately with a code LUA_ERRERR.