Lua2.4 Reference Manual (III)

(Part 1)
--------------------------------------
5. API
--------------------------------------
This section describes the Lua API, which is a set of C functions for the interaction between the host Program and the database. API functions can be divided into the following types:
1. Execute the Lua code;
2. convert values between Lua and C;
3. Operation (read/write) Lua object;
4. Call the Lua function;
5. c Functions called by Lua;
6. Reference of the Lua object.

All APIs are declared in the file Lua. h.

-------------------
5.1 execute Lua code
-------------------
A host program can execute the Lua module written in a file or in a string and use the following functions:
Int lua_dofile (char * filename );
Int lua_dostring (char * string );
Both functions return an error code: 0 indicates success, and non-0 indicates failure. Function lua_dofile. If the parameter is null (0) during the call, the standard input is executed as a "File. Lua_dofile can also execute pre-compiled modules. It can check whether the file is text and load it accordingly (see program luac ).

-------------------
5.2 convert values between Lua and C
-------------------
Because Lua does not have a static type system, all the types of values passed between Lua and C are lua_object. It is like an abstract type in C that can save any Lua value. The lua_object type is meaningless outside Lua. For example, comparing two lua_objects makes no sense.

Lua supports automatic memory management and garbage collection. Therefore, a lua_object has a limited scope, which is only valid in the block where it is created. A c function called from Lua is a block, and its parameters are valid only before it ends. A good programming practice is to convert these values (LUA objects) into values in the C language when they are available, and never store lua_object in the C global variables.

When a C code calls Lua code frequently, for example, in a loop, these returned objects are accumulated all the time, which may cause memory problems. To avoid this, nested blocks can be defined in the following functions:
Void lua_beginblock (void );
Void lua_endblock (void );
After the block ends, all new lua_objects in it will be released.

You can use the following function to check the lua_obejct type:
Int lua_type (lua_object object );
There are also the following macros and functions:
Int lua_isnil (lua_object object );
Int lua_isnumber (lua_object object );
Int lua_isstring (lua_object object );
Int lua_istable (lua_object object );
Int lua_isfunction (lua_object object );
Int lua_iscfunction (lua_object object );
Int lua_isuserdata (lua_object object );
All macros return 1 if the object is compatible with the given type, otherwise 0 is returned. The lua_isnumber function can accept numbers and strings that can be converted to numeric values. lua_isstring accepts strings and numeric values (see section 4.2). lua_isfunction accepts Lua and C functions.
The lua_type function can be used to differentiate different types of user data. See the following section.

You can use the following function to convert a lua_object to the c type:
Double lua_getnumber (lua_object object );
Char * lua_getstring (lua_object object );
Char * lua_copystring (lua_object object );
Lua_cfunction lua_getcfunction (lua_object object );
Void * lua_getuserdata (lua_object object );
Lua_getnumber can convert a lua_obejct into a floating point number. This lua_object must be a number or a string that can be converted to a number (see section 4.2); otherwise, this function returns 0.
Lua_getstring converts lua_object into a string (char *). This lua_object must be a string or number; otherwise, the function returns 0 (NULL pointer ). This function does not create a new string, but returns a pointer to the string in the Lua environment. Because Lua has garbage collection, there is no guarantee that this pointer will still be valid after the block ends.

Lua_getcfunction converts lua_object into a C function. The lua_obejct type must be cfunction; otherwise, 0 (NULL pointer) is returned ). The Type lua_cfunction is described in section 5.5.

Lua_getuserdata converts lua_object into a void *. The lua_obejct type must be userdata; otherwise, 0 (NULL pointer) is returned ).

Instead, convert a C type to the lua_obejct type using the following functions:
Void lua_pushnumber (double N );
Void lua_pushstring (char * s );
Void lua_pushcfunction (lua_cfunction F );
Void lua_pushusertag (void * u, int tag );
There is also a macro:
Void lua_pushuserdata (void * U );
These functions all accept a C value, convert it to the corresponding lua_object, and save the result to the top of the Lua stack, where it can be assigned a value to a Lua variable, pass it as a parameter to a Lua function (see below ).
User data can have different tags. Their semantics is defined by the Host Program. Any positive integer can be used as a label for user data. When a user data is returned, you can use lua_type to return its label.

To complete the settings, nil or lua_object can also press the stack and use the following function:
Void lua_pushnil (void );
Void lua_pushobject (lua_object object );

-------------------
5.3 operate Lua objects
-------------------
You can use the following function to read the value of the Lua global variable:
Lua_object lua_getglobal (char * varname );
In Lua, if the global variable value is nil, the return function "getglobal" will be called.

Save the value first pressed to the top of the stack to a global variable and use the following function:
Void lua_storeglobal (char * varname );

Tables can also be operated through APIS. functions:
Lua_object lua_getsubscript (void );
It is expected that the stack is a table and an index, and the content of the table at the index is returned. In Lua, if the first object is not a table or the index does not exist in the table, the corresponding rollback function is called.
To save a value to a given index, the program must push the table, index, and value to the stack, and then call the function:
Void lua_storesubscript (void );
The corresponding rollback function will be called, if needed.

Finally, the function
Lua_object lua_createtable (void );
Create a table.

Note: Most functions in the Lua library accept parameters from the stack. Because other functions use the same stack, make sure that you do not call the functions in the Lua database when calling the function's pre-parameter pressure stack. For example, if you want to obtain the value of a [I], a simple solution is:
/* Warning: Wrong code */
Lua_object result;
Lua_pushobject (lua_getglobal ("A");/* Push table */
Lua_pushobject (lua_getglobal ("I");/* Push Index */
Result = luat_getsubscript ();
However, the call to lua_getglobal ("I") changes the stack and invalidates the value of the previous stack. A correct solution is:
Lua_object result;
Lua_object Index = lua_getglobal ("I ");
Lua_pushobject (lua_getglobal ("A");/* Push table */
Lua_pushobject (INDEX);/* Push Index */
Result = luat_getsubscript ();

-------------------
5.4 call the Lua Function
-------------------
In the host program, you can call a function defined by dofile or dostring executed by the module. This uses the following protocol: first, the function parameters are pressed to the Lua stack (see section 5.2). The order of the stack pressure is the same as that of the parameters, that is, the first parameter is first pressed to the stack. Again, do not call other Lua functions during the stack pushing process.
Then, you can use:
Int lua_call (char * functionname );
Or
Int lua_callfunction (lua_object function );
Both functions return an error code: 0 indicates success, and non-0 indicates failure. Finally, the returned value (the Lua function can return multiple values) can be obtained using the following macro:
Lua_object lua_getresult (INT number );
Number is the order of the returned results, starting from 1. When you call a value greater than the actual number of returned results, this function returns lua_noobject.
Two special Lua functions have special functions: Error and setfallback. A c function can generate a Lua error by calling the function:
Void lua_error (char * message );
This function does not return. If you call this c Function in Lua, The Lua execution will be terminated, as if an error occurs in the Lua code. Otherwise, the entire program ends.

The rollback function can be modified using the following function:
Lua_object lua_setfallback (char * Name, lua_cfunction fallback );
The first parameter is the name of the rollback, and the second parameter is the cfunction that will be used as the new rollback function. This function returns the old rollback function lua_object, or nil (the name of the rollback function is invalid) if the function fails ). The old return function value can be used to connect (chaining) The return function.
Section 8.10 provides an example of using C code to call the Lua function.

-------------------
5.5 c Functions
-------------------
Register the C function to Lua and use the following macro:
# Define lua_register (n, f) (lua_pushcfunction (F), lua_storeglobal (n ))
/* Char * n ;*/
/* Lua_cfunction F ;*/
It accepts the name of the function in Lua and a function pointer. The pointer type must be lua_cfunction, which is defined:
Typedef void (* lua_cfunction) (void );
That is, a function pointer with no parameters and no return values.

To interact correctly with Lua, the C function must comply with a protocol that specifies the methods for passing parameters and return values.
To get its parameters, the C function calls:
Lua_object lua_getparam (INT number );
Number returns the first parameter from 1. When a value greater than the actual number of parameters is called, this function returns lua_noobject. With this method, you can write functions with variable parameter numbers.
In order to return values from C to Lua, the C function can push the returned values to the stack in sequence. For details, see section 5.2. Just like the Lua function, a C function called by Lua can return multiple values.

Section 8.9 shows an example of cfunction.

-------------------
5.6 Lua Object Reference
-------------------
As mentioned above, lua_object is volatile ). If a C code needs to save a lua_object outside the block scope, it must create an object reference. The following functions can manage such references:
Int lua_ref (INT lock );
Lua_object lua_getref (INT ref );
Void lua_pushref (INT ref );
Void lua_unref (INT ref );
The lua_ref function creates a reference to the stack top object and returns this reference. If the lock is true, the object will be locked: this means that the object will not be reclaimed. Note that an unlocked reference may be recycled. You can call lua_getref wherever an object is referenced to return the handle of an object. lua_pushref puts the object on the stack. If the object has been recycled, lua_getref returns a lua_noobject and lua_pushobject error.
If a reference is useless, you can call lua_unref to release it.
(To be continued)

Lua2.4 Reference Manual (III)