Home Explore Blog CI



neovim

33th chunk of `runtime/doc/luaref.txt`
1d60ff3dbd9ee67d6adbea004bcee2f4764c6eb2a13fdae50000000100000fa5
 errors during the call,
        `lua_pcall` behaves exactly like `lua_call`. However, if there is any
        error, `lua_pcall` catches it, pushes a single value on the stack (the
        error message), and returns an error code. Like `lua_call`,
        `lua_pcall` always removes the function and its arguments from the
        stack.

        If `errfunc` is 0, then the error message returned on the stack is
        exactly the original error message. Otherwise, `errfunc` is the stack
        index of an `error` `handler function`. (In the current
        implementation, this index cannot be a pseudo-index.) In case of
        runtime errors, this function will be called with the error message
        and its return value will be the message returned on the stack by
        `lua_pcall`.

        Typically, the error handler function is used to add more debug
        information to the error message, such as a stack traceback. Such
        information cannot be gathered after the return of `lua_pcall`, since
        by then the stack has unwound.

        The `lua_pcall` function returns 0 in case of success or one of the
        following error codes (defined in `lua.h`):

        - `LUA_ERRRUN`  a runtime error.
        - `LUA_ERRMEM`  memory allocation error. For such errors, Lua does
                      not call the error handler function.
        - `LUA_ERRERR`  error while running the error handler function.

lua_pop                                                              *lua_pop()*
>c
    void lua_pop (lua_State *L, int n);
<
        Pops `n` elements from the stack.

lua_pushboolean                                              *lua_pushboolean()*
>c
    void lua_pushboolean (lua_State *L, int b);
<
        Pushes a boolean value with value `b` onto the stack.

lua_pushcclosure                                            *lua_pushcclosure()*
>c
    void lua_pushcclosure (lua_State *L, lua_CFunction fn, int n);
<
        Pushes a new C closure onto the stack.

        When a C function is created, it is possible to associate some values
        with it, thus creating a C closure (see |lua-cclosure|); these
        values are then accessible to the function whenever it is called. To
        associate values with a C function, first these values should be
        pushed onto the stack (when there are multiple values, the first value
        is pushed first). Then `lua_pushcclosure` is called to create and push
        the C function onto the stack, with the argument `n` telling how many
        values should be associated with the function. `lua_pushcclosure` also
        pops these values from the stack.

lua_pushcfunction                                          *lua_pushcfunction()*
>c
    void lua_pushcfunction (lua_State *L, lua_CFunction f);
<
        Pushes a C function onto the stack. This function receives a pointer
        to a C function and pushes onto the stack a Lua value of type
        `function` that, when called, invokes the corresponding C function.

        Any function to be registered in Lua must follow the correct protocol
        to receive its parameters and return its results (see
        |lua_CFunction|).

        `lua_pushcfunction` is defined as a macro:
>c
            #define lua_pushcfunction(L,f)  lua_pushcclosure(L,f,0)
<

lua_pushfstring                                              *lua_pushfstring()*
>c
    const char *lua_pushfstring (lua_State *L, const char *fmt, ...);
<
        Pushes onto the stack a formatted string and returns a pointer to this
        string. It is similar to the C function `sprintf`, but has some
        important differences:

         - You do not have to allocate space for the result: the result is a
           Lua string and Lua takes care of memory allocation (and
           deallocation, through garbage collection).
         - The conversion specifiers are quite restricted. There are no flags,
           widths, or precisions. The conversion specifiers

Title: Lua C API: Error Handling, Stack Manipulation, and Pushing Values
Summary
This section continues the documentation of the Lua C API. It elaborates on `lua_pcall` error handling and return codes. Then goes on to describe `lua_pop`, which removes elements from the stack. After that, functions for pushing boolean values (`lua_pushboolean`), C closures (`lua_pushcclosure`), and C functions (`lua_pushcfunction`) onto the stack are detailed. Lastly, `lua_pushfstring`'s function is described to push a formatted string onto the stack.