Lua2.4 Reference Manual (5)

(Part 1)
--------------------------------------
7. debugging Interface
--------------------------------------
Lua does not have built-in debugging functions. Instead, functions and hooks provide a special interface to build different types of debuggers, analyzer profiles, and some other tools that require interpreter internal information. This interface is declared in the luadebug. h file.
-------------------
7.1 stack and function Information
-------------------
The main functions for obtaining the interpreter stack information are:
Lua_function lua_stackedfunction (INT level );
It returns a handle (lua_function) that points to a function that is running at a given level. Level 0 is a running function, and level n + 1 is a function that calls level n. When a higher-level call is used, lua_stackedfunction returns lua_noobject.
Type lua_function is just another name of lua_object. However, in this library, a lua_function can be used anywhere where lua_object is needed. The parameters received by lua_function only process the return of lua_stackedfunction.
The other three functions provide additional information about the function:
Void lua_funcinfo (lua_object func, char ** filename, int * linedefined );
Int lua_currentline (lua_function func );
Char * lua_getobjname (lua_object o, char ** name );
Lua_funcinfo provides the defined function file name and row number. If the function is code in the main module, linedefined is 0. If the function is a C function, linedefined is-1, and the file name is "(c )".
Lua_currentline indicates the row number of the currently executed function. It is only valid when the function has debugging options during pre-compilation (see section 4.8. If no row information is available, it returns-1.
Lua_getobjname tries to find a reasonable name for the given function. Because functions are the first type of values in Lua, they do not have a fixed name. Some functions may be values of many global variables, while others may only be saved in the table fields. The lua_getobjname function first checks whether the given function is fallback. If yes, it returns the "fallback" string and sets the name to the name of the rollback function. Otherwise, if the given function is a global variable lua_getobjname, the "Global" string is returned and the name points to the variable name. If the given function is not fallback or a global variable, lua_getobjname returns an empty string and its name is set to null.
-------------------
7.2 local variable operations
-------------------
The following functions can be used to operate local variables on activity records. They only work with debugging information during pre-compilation (see section 4.8 ).
Lua_object lua_getlocal (lua_function func, int local_number, char ** name );
Int lua_setlocal (lua_function func, int local_number );
The first function returns the value of a local variable and sets the name to the name of the local variable. Local_number is the index of a local variable. The first parameter index is 1, and so on until the last active local variable. When you use a local_number value greater than the number of active local variables, or the activity record does not have debugging information, lua_getlocal returns lua_noobject.
The lua_setlocal function uses the value of the previous pressure stack (see section 5.2) to set the local variable local_number. If the function is successful, 1 is returned. If local_number is greater than the number of local variables of the activity, or the activity record does not have debugging information, the function fails and returns 0.
-------------------
7.3 hook (hooks)
-------------------
The Lua interpreter provides two hooks for debugging.
Typedef void (* lua_chfunction) (lua_function func, char * file, int line );
Extern lua_chfunction lua_callhook;
Typedef void (* lua_lhfunction) (INT line );
Extern lua_lhfunction lua_linehook;
The interpreter calls the first one when entering or leaving a function. When you enter a function, its parameters are a handle to the function activity record, and the file and row number defined by the function (the same information is also provided by lua_funcinfo ); when exiting a function, func is lua_noobject, file is "(return)", and line is 0.
The interpreter calls the second one each time it changes the row number of the Code being executed. Its unique parameter is the row number (the same information is also provided by the call of lua_currentline (lua_stackedfunction (0 ). The second hook is called only when the active function contains debugging information during pre-compilation (see section 4.8.
The hook is invalid. If its value is null (0), null is the default value for both hooks.
(To be continued)

Lua2.4 Reference Manual (5)