Editing Lua (section)

== C API ==
Lua is intended to be embedded into other applications, and provides a [[C (programming language)|C]] [[Application Programming Interface|API]] for this purpose. The API is divided into two parts: the Lua core and the Lua auxiliary library.<ref name="luarefman">{{cite web |url=https://www.lua.org/manual/5.2/ |title=Lua 5.2 Reference Manual |publisher=Lua.org |access-date=2012-10-23}}</ref> The Lua API's design eliminates the need for manual [[reference counting]] (management) in C code, unlike [[Python (programming language)|Python]]'s API. The API, like the language, is minimalist. Advanced functions are provided by the auxiliary library, which consists largely of [[preprocessor]] [[Macro (computer science)|macros]] which assist with complex table operations.

The Lua C API is [[Stack (data structure)|stack]] based. Lua provides functions to push and pop most simple C data types (integers, floats, etc.) to and from the stack, and functions to manipulate tables through the stack. The Lua stack is somewhat different from a traditional stack; the stack can be indexed directly, for example. Negative indices indicate offsets from the top of the stack. For example, −1<!-- not a hyphen --> is the top (most recently pushed value), while positive indices indicate offsets from the bottom (oldest value). [[Marshalling (computer science)|Marshalling]] data between C and Lua functions is also done using the stack. To call a Lua function, arguments are pushed onto the stack, and then the <code>lua_call</code> is used to call the actual function. When writing a C function to be directly called from Lua, the arguments are read from the stack.

Here is an example of calling a Lua function from C:

<syntaxhighlight lang="c">
#include <stdio.h>
#include <lua.h> // Lua main library (lua_*)
#include <lauxlib.h> // Lua auxiliary library (luaL_*)

int main(void)
{
    // create a Lua state
    lua_State *L = luaL_newstate();

    // load and execute a string
    if (luaL_dostring(L, "function foo (x,y) return x+y end")) {
        lua_close(L);
        return -1;
    }

    // push value of global "foo" (the function defined above)
    // to the stack, followed by integers 5 and 3
    lua_getglobal(L, "foo");
    lua_pushinteger(L, 5);
    lua_pushinteger(L, 3);
    lua_call(L, 2, 1); // call a function with two arguments and one return value
    printf("Result: %d\n", lua_tointeger(L, -1)); // print integer value of item at stack top
    lua_pop(L, 1); // return stack to original state
    lua_close(L); // close Lua state
    return 0;
}
</syntaxhighlight>

Running this example gives:
<syntaxhighlight lang="console">
$ cc -o example example.c -llua
$ ./example
Result: 8
</syntaxhighlight>

The C API also provides some special tables, located at various "pseudo-indices" in the Lua stack. At <code>LUA_GLOBALSINDEX</code> prior to Lua 5.2<ref name="Changes in the API, Lua 5.2 manual">{{cite book |first1=Roberto |last1=Ierusalimschy |first2=Luiz Henrique |last2=de Figueiredo |first3=Waldemar |last3=Celes |date=2011–2013 |url=https://www.lua.org/manual/5.2/manual.html#8.3 |title=Changes in the API |work=Lua 5.2 Reference Manual |publisher=Lua.org |access-date=2014-05-09}}</ref> is the globals table, <code>_G</code> from within Lua, which is the main [[namespace]]. There is also a registry located at <code>LUA_REGISTRYINDEX</code> where C programs can store Lua values for later retrieval.

=== Modules ===
Besides standard library (core) modules it is possible to write extensions using the Lua API. Extension modules are [[Library (computing)#Dynamic linking|shared objects]] which can be used to extend the functions of the interpreter by providing native facilities to Lua scripts. Lua scripts may load extension modules using <code>require</code>,<ref name="luarefman"/> just like modules written in Lua itself, or with <code>package.loadlib</code>.<ref>{{Cite web |title=Lua 5.4 Reference Manual |url=https://www.lua.org/manual/5.4/manual.html#pdf-package.loadlib |first1=Roberto |last1=Ierusalimschy |first2=Luiz Henrique |last2=de Figueiredo |first3=Waldemar |last3=Celes |access-date=2022-06-01 |website=Lua}}</ref> When a C library is loaded via {{ml-lua|foo}} Lua will look for the function <code>luaopen_foo</code> and call it, which acts as any C function callable from Lua and generally returns a table filled with methods. A growing set of modules termed ''rocks'' are available through a [[package management system]] named [[LuaRocks]],<ref>{{cite web |url=https://luarocks.org/ |title=LuaRocks |publisher=luarocks.org |access-date=2009-05-24}}</ref> in the spirit of [[CPAN]], [[RubyGems]] and [[Python eggs]]. Prewritten Lua [[Language binding|bindings]] exist for most popular programming languages, including other scripting languages.<ref>{{cite web |url=http://lua-users.org/wiki/BindingCodeToLua |title=Binding Code To Lua |publisher=Lua-users wiki |access-date=2009-05-24 |url-status=dead |archive-url=https://web.archive.org/web/20090727080345/http://lua-users.org/wiki/BindingCodeToLua |archive-date= Jul 27, 2009}}</ref> For C++, there are a number of template-based approaches and some automatic binding generators.