Lua The Application Program Interface 

Cours Lua The Application Program Interface, tutoriel & guide de travaux pratiques en pdf.

The Application Program Interface

This section describes the C API for Lua, that is, the set of C functions available to the host program to communicate with Lua. All API functions and related types and constants are declared in the header file lua.h.
Even when we use the term “function”, any facility in the API may be provided as a macro instead. All such macros use each of its arguments exactly once (except for the first argument, which is always a Lua state), and so do not generate hidden side-effects.

States
The Lua library is fully reentrant: it has no global variables. The whole state of the Lua interpreter (global variables, stack, etc.) is stored in a dynamically allocated structure of type lua_State. A pointer to this state must be passed as the first argument to every function in the library, except to lua_open, which creates a Lua state from scratch.
Before calling any API function, you must create a state by calling lua_open:
lua_State *lua_open (void);
To release a state created with lua_open, call lua_close:
void lua_close (lua_State *L);
This function destroys all objects in the given Lua state (calling the corresponding garbage-collection metamethods, if any) and frees all dynamic memory used by that state. On several platforms, you may not need to call this function, because all resources are naturally released when the host program ends. On the other hand, long-running programs, such as a daemon or a web server, might need to release states as soon as they are not needed, to avoid growing too large.

The Stack and Indices
Lua uses a virtual stack to pass values to and from C. Each element in this stack represents a Lua value (nil, number, string, etc.).
Whenever Lua calls C, the called function gets a new stack, which is independent of previous stacks and of stacks of C functions that are still active. That stack initially contains any arguments to the C function, and it is where the C function pushes its results to be returned to the caller (see §3.16).
For convenience, most query operations in the API do not follow a strict stack discipline. Instead, they can refer to any element in the stack by using an index : A positive index represents an absolute stack position (starting at 1); a negative index represents an offset from the top of the stack. More specifically, if the stack has n elements, then index 1 represents the first element (that is, the element that was pushed onto the stack first) and index n represents the last element; index −1 also represents the last element (that is, the element at the top) and index −n represents the first element. We say that an index is valid if it lies between 1 and the stack top (that is, if 1 <= abs(index) <= top).
At any time, you can get the index of the top element by calling lua_gettop:
int lua_gettop (lua_State *L);
Because indices start at 1, the result of lua_gettop is equal to the number of elements in the stack (and so 0 means an empty stack).
When you interact with Lua API, you are responsible for controlling stack overflow. The function
int lua_checkstack (lua_State *L, int extra);
grows the stack size to top + extra elements; it returns false if it cannot grow the stack to that size. This function never shrinks the stack; if the stack is already larger than the new size, it is left unchanged.
Whenever Lua calls C, it ensures that at least LUA_MINSTACK stack positions are available. LUA_MINSTACK is defined in lua.h as 20, so that usually you do not have to worry about stack space unless your code has loops pushing elements onto the stack.
Most query functions accept as indices any value inside the available stack space, that is, indices up to the maximum stack size you have set through lua_checkstack. Such indices are called acceptable indices. More formally, we define an acceptable index as follows:
(index < 0 && abs(index) <= top) || (index > 0 && index <= stackspace)
Note that 0 is never an acceptable index.
Unless otherwise noted, any function that accepts valid indices can also be called with pseudo-indices, which represent some Lua values that are accessible to the C code but are not in the stack. Pseudo-indices are used to access the global environment, the registry, and the upvalues of a C function (see §3.17).

Stack Manipulation
The API offers the following functions for basic stack manipulation:
void lua_settop (lua_State *L, int index);
void lua_pushvalue (lua_State *L, int index);
void lua_remove (lua_State *L, int index);
void lua_insert (lua_State *L, int index);
void lua_replace (lua_State *L, int index);
lua_settop accepts any acceptable index, or 0, and sets the stack top to that index. If the new top is larger than the old one, then the new elements are filled with nil. If index is 0, then all stack elements are removed. A useful macro defined in the lua.h is
#define lua_pop(L,n) lua_settop(L, -(n)-1)
which pops n elements from the stack.
lua_pushvalue pushes onto the stack a copy of the element at the given index. lua_remove removes the element at the given position, shifting down the elements above that position to fill the gap. lua_insert moves the top element into the given position, shifting up the elements above that position to open space. lua_replace moves the top element into the given position, without shifting any element (therefore replacing the value at the given position). All these functions accept only valid indices. (You cannot call lua_remove or lua_insert with pseudo-indices, as they do not represent a stack position.)

1 Introduction 
2 The Language
2.1 Lexical Conventions
2.2 Values and Types
2.3 Variables
2.4 Statements
2.5 Expressions
2.6 Visibility Rules
2.7 Error Handling
2.8 Metatables
2.9 Garbage Collection
2.10 Coroutines
3 The Application Program Interface 
3.1 States
3.2 The Stack and Indices
3.3 Stack Manipulation
3.4 Querying the Stack
3.5 Getting Values from the Stack
3.6 Pushing Values onto the Stack
3.7 Controlling Garbage Collection
3.8 Userdata
3.9 Metatables
3.10 Loading Lua Chunks
3.11 Manipulating Tables
3.12 Manipulating Environments
3.13 Using Tables as Arrays
3.14 Calling Functions
3.15 Protected Calls
3.16 Defining C Functions
3.17 Defining C Closures
3.18 Registry
3.19 Error Handling in C
3.20 Threads
4 The Debug Interface 
4.1 Stack and Function Information
4.2 Manipulating Local Variables and Upvalues
4.3 Hooks
5 Standard Libraries 
5.1 Basic Functions
5.2 Coroutine Manipulation
5.3 String Manipulation
5.4 Table Manipulation
5.5 Mathematical Functions
5.6 Input and Output Facilities
5.7 Operating System Facilities
5.8 The Reflexive Debug Interface
6 Lua Stand-alone 
Index