*lua-stackindex*
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`).

==============================================================================
3.2  Stack Size                                            *lua-apiStackSize*

When you interact with Lua API, you are responsible for ensuring consistency.
In particular, you are responsible for controlling stack overflow. You can
use the function `lua_checkstack` to grow the stack size (see
|lua_checkstack()|).

Whenever Lua calls C, it ensures that at least `LUA_MINSTACK` stack positions
are available. `LUA_MINSTACK` is defined 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:
>lua
    (index < 0 && abs(index) <= top) || (index > 0 && index <= stackspace)
<
Note that 0 is never an acceptable index.

==============================================================================
3.3  Pseudo-Indices                                     *lua-pseudoindex*

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 which are not in the stack. Pseudo-indices are
used to access the thread environment, the function environment, the registry,
and the upvalues of a C function (see |lua-cclosure|).

The thread environment (where global variables live) is always at pseudo-index
`LUA_GLOBALSINDEX`. The environment of the running C function is always at
pseudo-index `LUA_ENVIRONINDEX`.

To access and change the value of global variables, you can use regular table
operations over an environment table. For instance, to access the value of a
global variable, do
>c
       lua_getfield(L, LUA_GLOBALSINDEX, varname);
<

==============================================================================
3.4  C Closures                                         *lua-cclosure*

When a C function is created, it is possible to associate some values with it,
thus creating a C closure; these values are called upvalues and are accessible
to the function whenever it is called (see |lua_pushcclosure()|).

Whenever a C function is called, its upvalues are located at specific
pseudo-indices. These pseudo-indices are produced by the macro
`lua_upvalueindex`. The first value associated with a function is at position
`lua_upvalueindex(1)`, and so on. Any access to `lua_upvalueindex(` `n` `)`,
where `n` is greater than the number of upvalues of the current function,
produces an acceptable (but invalid) index.

==============================================================================
3.5  Registry                                           *lua-registry*

Lua provides a registry, a pre-defined table that can be used by any C code to
store whatever Lua value it needs to store. This table is always located at
pseudo-index `LUA_REGISTRYINDEX`. Any C library can store data into this
table, but it should take care to choose keys different from those used by
other libraries, to avoid collisions.