免费人成黄页在线观看1024,欧美日韩视频二区三区,99国产精品私拍pans大尺度

Lua - 調(diào)試接口

quasiceo >《待分類1》

2014.01.05

關(guān)注

4 - 調(diào)試接口 The Debug Interface

Lua 沒有內(nèi)置的調(diào)試設(shè)施。它使用一種特殊的接口，這種接口依賴函數(shù)和鉤子（hooks）。該接口允許構(gòu)造不同種類的調(diào)試器，分析器以及其他工具用以從解釋器得到所需的信息。

4.1 - 堆棧及函數(shù)信息 Stack and Function Information

得到解釋程序運(yùn)行時(shí)堆棧信息的主要函數(shù)是：

int lua_getstack (lua_State *L, int level, lua_Debug *ar);

這個(gè)函數(shù)用一個(gè)指定等級(jí)的函數(shù)的 activation record 的標(biāo)示符填充一個(gè) lua_Debug 結(jié)構(gòu)，等級(jí) 0 是當(dāng)前運(yùn)行函數(shù)，然而等級(jí) n+1 是在等級(jí) n 上調(diào)用的函數(shù)。當(dāng)沒有錯(cuò)誤發(fā)生時(shí)，lua_getstack 返回 1；當(dāng)在比棧更深的等級(jí)上調(diào)用的時(shí)候，它返回 0；

lua_Debug 結(jié)構(gòu)被用來攜帶一個(gè)處于活動(dòng)狀態(tài)的函數(shù)的各種信息：

typedef struct lua_Debug { int event; const char *name; /* (n) */ const char *namewhat; /* (n) `global', `local', `field', `method' */ const char *what; /* (S) `Lua' function, `C' function, Lua `main' */ const char *source; /* (S) */ int currentline; /* (l) */ int nups; /* (u) number of upvalues */ int linedefined; /* (S) */ char short_src[LUA_IDSIZE]; /* (S) */ /* private part */ ... } lua_Debug;

lua_getstack 只填充結(jié)構(gòu)的私有部分以備之后使用。要填充 lua_Debug 其他有用信息，調(diào)用

int lua_getinfo (lua_State *L, const char *what, lua_Debug *ar);

這個(gè)函數(shù)發(fā)生錯(cuò)誤是返回 0 （舉個(gè)例子，一個(gè)無效的 what 選項(xiàng)）。what 字符串中的每個(gè)字符選擇填充一些 ar 結(jié)構(gòu)的字段，把上面在 lua_Debug 定義中用圓括號(hào)括起來的字母作為指示： `S′ 填充在 source, linedefined 和 what 字段中；`l′ 填充在 currentline 字段中，等等...。而且，`f′ 將正在運(yùn)?性謁燃渡系暮谷攵顏弧?

想要從一個(gè)不處于活動(dòng)狀態(tài)的函數(shù)那得到信息（就是不在棧上的函數(shù)），你需要將其壓入棧并且用 >′ 作為 what 字符串的開始。舉個(gè)例子，要知道函數(shù) f 定義在第幾行，你需要這樣寫

lua_Debug ar; lua_pushstring(L, "f"); lua_gettable(L, LUA_GLOBALSINDEX); /* get global `f' */ lua_getinfo(L, ">S", &ar); printf("%d/n", ar.linedefined);

lua_Debug 的字段有如下的含義：

source 如果函數(shù)在一個(gè)字符串中定義，那么 source 就是那個(gè)字符串。如果函數(shù)定義在一個(gè)文件中，source 開始于一個(gè) `@′ 后面跟隨文件名。

short_src 一個(gè)可打印版的 source，用于錯(cuò)誤信息。

linedefined 函數(shù)定義起始的行號(hào)。

what 如果這是一個(gè)Lua函數(shù)，顯示 "Lua" 字符串， "C" 為C 函數(shù)，"main" 如果這是一個(gè)語句段的main部分，"tail" 如果這是一個(gè)做了尾部調(diào)用的函數(shù)。在后面的情況里，Lua 沒有其他關(guān)于這個(gè)函部的信息。

currentline 代表當(dāng)前函數(shù)執(zhí)行到的行數(shù)。如果沒有行信息可用，currentline 被設(shè)置為 -1。

name 一個(gè)所給函數(shù)合理的函數(shù)名。因?yàn)楹瘮?shù)在Lua中屬于第一類值，它們沒有固定的名字：一些函數(shù)可能是多個(gè)全局變量的值，其他的可能只儲(chǔ)存在一個(gè)表字段里。lua_getinfo 函數(shù)檢測函數(shù)如何被調(diào)用或者是否為一個(gè)全局變量的值以尋找一個(gè)合適的名字。如果找不到合適的名字，name 被設(shè)置為 NULL。

namewhat name 字段的解釋。根據(jù)函數(shù)如何被調(diào)用，namewhat 的值可以是 "global", "local", "method", "field" 或者 "" （空字符串）。（當(dāng)沒有其他可選項(xiàng)的時(shí)候Lua使用空字符串代替）

nups 函數(shù)上值的數(shù)量。

4.2 - 操作局部變量和上值 Manipulating Local Variables and Upvalues

為了更多的操作局部變量和上值，調(diào)試接口使用索引：第一個(gè)參數(shù)或者局部變量索引為 1，以此類推，直到最后一個(gè)活動(dòng)的局部變量。整個(gè)函數(shù)中的活動(dòng)的上值沒有特定的順序。

下面的函數(shù)允許操作一個(gè)所給激活記錄的局部變量：

const char *lua_getlocal (lua_State *L, const lua_Debug *ar, int n); const char *lua_setlocal (lua_State *L, const lua_Debug *ar, int n);

參數(shù) ar 必須是一個(gè)被前一個(gè) lua_getstack 調(diào)用填充的有效的激活記錄或者作為一個(gè)鉤子函數(shù)的參數(shù)（見 4.3）。lua_getlocal 獲得一個(gè)局部變量的索引 n，將變量的值壓入棧，并且返回變量名。lua_setlocal 從棧頂分配一個(gè)值給變量并且返回變量名。當(dāng)索引超過活動(dòng)的局部變量的數(shù)量時(shí)，兩個(gè)函數(shù)都返回 NULL。

以下的函部可以操作所給函數(shù)的上值（不像局部變量，函數(shù)的上值即使在函數(shù)不處于活動(dòng)狀態(tài)的時(shí)候都可以被訪問）：

const char *lua_getupvalue (lua_State *L, int funcindex, int n); const char *lua_setupvalue (lua_State *L, int funcindex, int n);

這些函數(shù)可以作為Lua 函數(shù)使用也可以作為C 函數(shù)使用。（作為Lua 函數(shù)，上值是函數(shù)外部使用的局部變量，因此它被包含在函數(shù)閉包中。）funcindex 指向棧中的一個(gè)函數(shù)。lua_getupvalue 得到一個(gè)上值的索引 n，將上值的值壓入棧，并返回其變量名。lua_setupvalue 從棧頂分配一個(gè)值給上值并返回變量名。當(dāng)索引大于上值數(shù)量時(shí)，兩個(gè)函數(shù)都返回 NULL。對(duì)于C 函數(shù)來說，這些函數(shù)使用空字符串作為所有上值的變量名。

作為一個(gè)例子，下面的函數(shù)列舉了所給等級(jí)的棧中的函數(shù)的所有局部變量名和上值變量名：

int listvars (lua_State *L, int level) { lua_Debug ar; int i; const char *name; if (lua_getstack(L, level, &ar) == 0) return 0; /* failure: no such level in the stack */ i = 1; while ((name = lua_getlocal(L, &ar, i++)) != NULL) { printf("local %d %s/n", i-1, name); lua_pop(L, 1); /* remove variable value */ } lua_getinfo(L, "f", &ar); /* retrieves function */ i = 1; while ((name = lua_getupvalue(L, -1, i++)) != NULL) { printf("upvalue %d %s/n", i-1, name); lua_pop(L, 1); /* remove upvalue value */ } return 1; }4.3 - 鉤子 Hooks

Lua offers a mechanism of hooks, which are user-defined C functionsthat are called during the program execution. A hook may be called infour different events: a call event, when Lua calls a function; a return event, when Lua returns from a function; a line event, when Lua starts executing a new line of code; and a count event, which happens every "count" instructions. Lua identifies these events with the following constants: LUA_HOOKCALL, LUA_HOOKRET (or LUA_HOOKTAILRET, see below), LUA_HOOKLINE, and LUA_HOOKCOUNT.

A hook has type lua_Hook, defined as follows:

typedef void (*lua_Hook) (lua_State *L, lua_Debug *ar);

You can set the hook with the following function:

int lua_sethook (lua_State *L, lua_Hook func, int mask, int count);

func is the hook. mask specifies on which events the hook will be called: It is formed by a disjunction of the constants LUA_MASKCALL, LUA_MASKRET, LUA_MASKLINE, and LUA_MASKCOUNT. The count argument is only meaningful when the mask includes LUA_MASKCOUNT. For each event, the hook is called as explained below:

The call hook is called when the interpreter calls a function. The hook is called just after Lua enters the new function.

The return hook is called when the interpreter returns from a function. The hook is called just before Lua leaves the function.

The line hook is called when the interpreter is aboutto start the execution of a new line of code, or when it jumps back inthe code (even to the same line). (This event only happens while Lua isexecuting a Lua function.)

The count hook is called after the interpreter executes every count instructions. (This event only happens while Lua is executing a Lua function.)

A hook is disabled by setting mask to zero.

You can get the current hook, the current mask, and the current count with the following functions:

lua_Hook lua_gethook (lua_State *L); int lua_gethookmask (lua_State *L); int lua_gethookcount (lua_State *L);

Whenever a hook is called, its ar argument has its field event set to the specific event that triggered the hook. Moreover, for line events, the field currentline is also set. To get the value of any other field in ar, the hook must call lua_getinfo. For return events, event may be LUA_HOOKRET, the normal value, or LUA_HOOKTAILRET. In the latter case, Lua is simulating a return from a function that did a tail call; in this case, it is useless to call lua_getinfo.

While Lua is running a hook, it disables other calls to hooks.Therefore, if a hook calls back Lua to execute a function or a chunk,that execution occurs without any calls to hooks.

The Lua team is grateful to Tecgraf for its continued support to Lua. We thank everyone at Tecgraf,specially the head of the group, Marcelo Gattass. At the risk ofomitting several names, we also thank the following individuals forsupporting, contributing to, and spreading the word about Lua: AlanWatson. André Clinio, André Costa, Antonio Scuri, Asko Kauppi, BretMogilefsky, Cameron Laird, Carlos Cassino, Carlos Henrique Levy,Claudio Terra, David Jeske, Ed Ferguson, Edgar Toernig, Erik Hougaard,Jim Mathies, John Belmonte, John Passaniti, John Roll, Jon Erickson,Jon Kleiser, Mark Ian Barlow, Nick Trout, Noemi Rodriguez, NormanRamsey, Philippe Lhoste, Renata Ratton, Renato Borges, RenatoCerqueira, Reuben Thomas, Stephan Herrmann, Steve Dekorte, ThatcherUlrich, Tomás Gorham, Vincent Penquerc'h. Thank you!

與以前版本的不兼容性 Incompatibilities with Previous Versions

Lua 5.0 是一個(gè)主版本，所有與 Lua 4.0 有一些地方不兼容。

與 v4.0 的不兼容性 Incompatibilities with version 4.0

語言上的變動(dòng)

整個(gè)標(biāo)簽方法模式被元表所替代。The whole tag-method scheme was replaced by metatables.

Function calls written between parentheses result in exactly one value.

A function call as the last in a list constructor (like {a,b,f()}) has all its return values inserted in the list.

The precedence of or is smaller than the precedence of and.

in, false, and true are reserved words.

The old construction for k,v in t, where t is a table, is deprecated (although it is still supported). Use for k,v in pairs(t) instead.

When a literal string of the form [[...]] starts with a newline, this newline is ignored.

Upvalues in the form %var are obsolete; use external local variables instead.

庫的變更

Most library functions now are defined inside tables. There is a compatibility script (compat.lua) that redefines most of them as global names.

In the math library, angles are expressed in radians. With the compatibility script (compat.lua), functions still work in degrees.

The call function is deprecated. Use f(unpack(tab)) instead of call(f, tab) for unprotected calls, or the new pcall function for protected calls.

dofile does not handle errors, but simply propagates them.

dostring is deprecated. Use loadstring instead.

The read option *w is obsolete.

The format option %n$ is obsolete.

API 上的改動(dòng)

lua_open 不再需要堆棧大小作為參數(shù)（堆棧是動(dòng)態(tài)的）。

lua_pushuserdata 已經(jīng)被廢除了。使用 lua_newuserdata 或 lua_pushlightuserdata 來代替它。

Lua 完整語法參考

chunk ::= {stat [`;′]} block ::= chunk stat ::= varlist1 `=′ explist1 | functioncall | do block end | while exp do block end | repeat block until exp | if exp then block {elseif exp then block} [else block] end | return [explist1] | break | for Name `=′ exp `,′ exp [`,′ exp] do block end | for Name {`,′ Name} in explist1 do block end | function funcname funcbody | local function Name funcbody | local namelist [init] funcname ::= Name {`.′ Name} [`:′ Name] varlist1 ::= var {`,′ var} var ::= Name | prefixexp `[′ exp `]′ | prefixexp `.′ Name namelist ::= Name {`,′ Name} init ::= `=′ explist1 explist1 ::= {exp `,′} exp exp ::= nil | false | true | Number | Literal | function | prefixexp | tableconstructor | exp binop exp | unop exp prefixexp ::= var | functioncall | `(′ exp `)′ functioncall ::= prefixexp args | prefixexp `:′ Name args args ::= `(′ [explist1] `)′ | tableconstructor | Literal function ::= function funcbody funcbody ::= `(′ [parlist1] `)′ block end parlist1 ::= Name {`,′ Name} [`,′ `...′] | `...′ tableconstructor ::= `{′ [fieldlist] `}′ fieldlist ::= field {fieldsep field} [fieldsep] field ::= `[′ exp `]′ `=′ exp | name `=′ exp | exp fieldsep ::= `,′ | `;′ binop ::= `+′ | `-′ | `*′ | `/′ | `^′ | `..′ | `<′ | `<=′ | `>′ | `>=′ | `==′ | `~=′ | and | or unop ::= `-′ | not

Lua - 獨(dú)立程序

6 - Lua 獨(dú)立程序 Lua Stand-alone

盡管Lua被設(shè)計(jì)為一種內(nèi)嵌于C 語言宿主程序中的擴(kuò)展語言，它還是經(jīng)常被用作一個(gè)獨(dú)立程序語言。一個(gè)Lua的解釋程序?qū)ua作為一個(gè)獨(dú)立的語言，我們稱之為簡化的 lua，它提供了標(biāo)準(zhǔn)的發(fā)行版本。獨(dú)立的解釋器包含了所有標(biāo)準(zhǔn)庫加上反射性的調(diào)試接口。它的使用方式如下：

lua [options] [script [args]]

options 可以是以下內(nèi)容：

- 將標(biāo)準(zhǔn)輸入（stdin）當(dāng)作文件執(zhí)行；

-e stat 執(zhí)行字符串 stat；

-l file “需要”file 文件；

-i 在運(yùn)行腳本后進(jìn)入交互模式；

-v 打印版本信息；

-- 停止處理選項(xiàng)。

在停止處理選項(xiàng)后，lua 運(yùn)行所給的腳本，傳遞所給參數(shù) args。當(dāng)無參數(shù)調(diào)用時(shí)，lua 就像 stdin 是程序的終結(jié)時(shí) lua -v -i 所表現(xiàn)的一樣，而且還與 lua- 一樣。

Before running any argument, the interpreter checks for an environment variable LUA_INIT. If its format is @filename, then lua executes the file. Otherwise, lua executes the string itself.

All options are handled in order, except -i. For instance, an invocation like

$ lua -e'a=1' -e 'print(a)' script.lua

will first set a to 1, then print a, and finally run the file script.lua. (Here, $ is the shell prompt. Your prompt may be different.)

Before starting to run the script, lua collects all arguments in the command line in a global table called arg. The script name is stored in index 0, the first argument after the script name goes to index 1, and so on. The field ngets the number of arguments after the script name. Any argumentsbefore the script name (that is, the interpreter name plus the options)go to negative indices. For instance, in the call

$ lua -la.lua b.lua t1 t2

the interpreter first runs the file a.lua, then creates a table

arg = { [-2] = "lua", [-1] = "-la.lua", [0] = "b.lua", [1] = "t1", [2] = "t2"; n = 2 }

and finally runs the file b.lua.

在交互模式中，如果你寫入了一個(gè)不完整的語句，解釋器將等待你的完成。

If the global variable _PROMPT is defined as astring, then its value is used as the prompt. Therefore, the prompt canbe changed directly on the command line:

$ lua -e"_PROMPT='myprompt> '" -i

(the outer pair of quotes is for the shell, the inner is for Lua), or in any Lua programs by assigning to _PROMPT. Note the use of -i to enter interactive mode; otherwise, the program would end just after the assignment to _PROMPT.

在Unix系統(tǒng)中，Lua腳本可以用 chmod +x 將其變成可執(zhí)行程序，并且通過 #! 形式，例如

#!/usr/local/bin/lua

（當(dāng)然，Lua解釋器的位置可能有所不同，如果 lua 在你的 PATH 中，那么

#!/usr/bin/env lua

就是一個(gè)更通用的解決方案。）

Lua - 標(biāo)準(zhǔn)庫

5 - 標(biāo)準(zhǔn)庫

The standard libraries provide useful functions that are implementeddirectly through the C API. Some of these functions provide essentialservices to the language (e.g., type and getmetatable);others provide access to "outside" services (e.g., I/O); and otherscould be implemented in Lua itself, but are quite useful or havecritical performance to deserve an implementation in C (e.g., sort).

All libraries are implemented through the official C API and areprovided as separate C modules. Currently, Lua has the followingstandard libraries:

基本庫 basic library;

字符串操作 string manipulation;

表操作 table manipulation;

數(shù)學(xué)函數(shù) （sin, log 等等）mathematical functions (sin, log, etc.);

輸入輸出 input and output;

操作系統(tǒng)機(jī)制 operating system facilities;

調(diào)試機(jī)制 debug facilities.

Except for the basic library, each library provides all its functions as fields of a global table or as methods of its objects.

To have access to these libraries, the C host program must first call the functions luaopen_base (for the basic library), luaopen_string (for the string library), luaopen_table (for the table library), luaopen_math (for the mathematical library), luaopen_io (for the I/O and the Operating System libraries), and luaopen_debug (for the debug library). These functions are declared in lualib.h.

5.1 - 基本函數(shù) Basic Functions

The basic library provides some core functions to Lua. If you do notinclude this library in your application, you should check carefullywhether you need to provide some alternative implementation for some ofits facilities.

assert (v [, message])

Issues an error when the value of its argument v is nil or false; otherwise, returns this value. message is an error message; when absent, it defaults to "assertion failed!"

collectgarbage ([limit])

Sets the garbage-collection threshold to the given limit (in Kbytes)and checks it against the byte counter. If the new threshold is smallerthan the byte counter, then Lua immediately runs the garbage collector(see 2.9). If limit is absent, it defaults to zero (thus forcing a garbage-collection cycle).

dofile (filename)

Opens the named file and executes its contents as a Lua chunk. When called without arguments, dofile executes the contents of the standard input (stdin). Returns any value returned by the chunk. In case of errors, dofile propagates the error to its caller (that is, it does not run in protected mode).

Terminates the last protected function called and returns message as the error message. Function error never returns.

The level argument specifies where the error message points the error. With level 1 (the default), the error position is where the error function was called. Level 2 points the error to where the function that called error was called; and so on.

_G

A global variable (not a function) that holds the global environment (that is, _G._G = _G). Lua itself does not use this variable; changing its value does not affect any environment. (Use setfenv to change environments.)

getfenv (f)

Returns the current environment in use by the function. f can be a Lua function or a number, which specifies the function at that stack level: Level 1 is the function calling getfenv. If the given function is not a Lua function, or if f is 0, getfenv returns the global environment. The default for f is 1.

If the environment has a "__fenv" field, returns the associated value, instead of the environment.

If the object does not have a metatable, returns nil. Otherwise, if the object's metatable has a "__metatable" field, returns the associated value. Otherwise, returns the metatable of the given object.

gcinfo ()

Returns two results: the number of Kbytes of dynamic memory that Luais using and the current garbage collector threshold (also in Kbytes).

ipairs (t)

Returns an iterator function, the table t, and 0, so that the construction

for i,v in ipairs(t) do ... end

will iterate over the pairs (1,t[1]), (2,t[2]), ..., up to the first integer key with a nil value in the table.

loadfile (filename)

Loads a file as a Lua chunk (without running it). If there are noerrors, returns the compiled chunk as a function; otherwise, returns nil plus the error message. The environment of the returned function is the global environment.

loadlib (libname, funcname)

Links the program with the dynamic C library libname. Inside this library, looks for a function funcname and returns this function as a C function.

libname must be the complete file name of the C library, including any eventual path and extension.

This function is not supported by ANSI C. As such, it is onlyavailable on some platforms (Windows, Linux, Solaris, BSD, plus otherUnix systems that support the dlfcn standard).

loadstring (string [, chunkname])

Loads a string as a Lua chunk (without running it). If there are noerrors, returns the compiled chunk as a function; otherwise, returns nil plus the error message. The environment of the returned function is the global environment.

The optional parameter chunkname is the name to be used in error messages and debug information.

To load and run a given string, use the idiom

assert(loadstring(s))()next (table [, index])

Allows a program to traverse all fields of a table. Its firstargument is a table and its second argument is an index in this table. next returns the next index of the table and the value associated with the index. When called with nil as its second argument, next returns the first index of the table and its associated value. When called with the last index, or with nil in an empty table, next returns nil. If the second argument is absent, then it is interpreted as nil.

Lua has no declaration of fields; There is no difference between a field not present in a table or a field with value nil. Therefore, next only considers fields with non-nil values. The order in which the indices are enumerated is not specified, even for numeric indices. (To traverse a table in numeric order, use a numerical for or the ipairs function.)

The behavior of next is undefined if, during the traversal, you assign any value to a non-existent field in the table.

pairs (t)

Returns the next function and the table t (plus a nil), so that the construction

for k,v in pairs(t) do ... end

will iterate over all key-value pairs of table t.

Calls function f with the given arguments in protected mode. That means that any error inside f is not propagated; instead, pcall catches the error and returns a status code. Its first result is the status code (a boolean), which is true if the call succeeds without errors. In such case, pcall also returns all results from the call, after this first result. In case of any error, pcall returns false plus the error message.

print (e1, e2, ...)

Receives any number of arguments, and prints their values in stdout, using the tostringfunction to convert them to strings. This function is not intended forformatted output, but only as a quick way to show a value, typicallyfor debugging. For formatted output, use format (see 5.3).

rawequal (v1, v2)

Checks whether v1 is equal to v2, without invoking any metamethod. Returns a boolean.

rawget (table, index)

Gets the real value of table[index], without invoking any metamethod. table must be a table; index is any value different from nil.

rawset (table, index, value)

Sets the real value of table[index] to value, without invoking any metamethod. table must be a table, index is any value different from nil, and value is any Lua value.

require (packagename)

Loads the given package. The function starts by looking into the table _LOADED to determine whether packagename is already loaded. If it is, then requirereturns the value that the package returned when it was first loaded.Otherwise, it searches a path looking for a file to load.

If the global variable LUA_PATH is a string, this string is the path. Otherwise, require tries the environment variable LUA_PATH. As a last resort, it uses the predefined path "?;?.lua".

The path is a sequence of templates separated by semicolons. For each template, require will change each interrogation mark in the template to packagename, and then will try to load the resulting file name. So, for instance, if the path is

"./?.lua;./?.lc;/usr/local/?/?.lua;/lasttry"

a require "mod" will try to load the files ./mod.lua, ./mod.lc, /usr/local/mod/mod.lua, and /lasttry, in that order.

The function stops the search as soon as it can load a file, and then it runs the file. After that, it associates, in table _LOADED, the package name with the value that the package returned, and returns that value. If the package returns nil (or no value), require converts this value to true. If the package returns false, require also returns false. However, as the mark in table _LOADED is false, any new attempt to reload the file will happen as if the package was not loaded (that is, the package will be loaded again).

If there is any error loading or running the file, or if it cannot find any file in the path, then require signals an error.

While running a file, require defines the global variable _REQUIREDNAME with the package name. The package being loaded always runs within the global environment.

Sets the current environment to be used by the given function. f can be a Lua function or a number, which specifies the function at that stack level: Level 1 is the function calling setfenv.

As a special case, when f is 0 setfenv changes the global environment of the running thread.

If the original environment has a "__fenv" field, setfenv raises an error.

setmetatable (table, metatable)

Sets the metatable for the given table. (You cannot change the metatable of a userdata from Lua.) If metatable is nil, removes the metatable of the given table. If the original metatable has a "__metatable" field, raises an error.

tonumber (e [, base])

Tries to convert its argument to a number. If the argument is already a number or a string convertible to a number, then tonumber returns that number; otherwise, it returns nil.

An optional argument specifies the base to interpret thenumeral. The base may be any integer between 2 and 36, inclusive. Inbases above 10, the letter `A′ (in either upper or lower case) represents 10, `B′ represents 11, and so forth, with `Z′ representing 35. In base 10 (the default), the number may have a decimal part, as well as an optional exponent part (see 2.2.1). In other bases, only unsigned integers are accepted.

tostring (e)

Receives an argument of any type and converts it to a string in areasonable format. For complete control of how numbers are converted,use format (see 5.3).

If the metatable of e has a "__tostring" field, tostring calls the corresponding value with e as argument, and uses the result of the call as its result.

Returns the type of its only argument, coded as a string. The possible results of this function are "nil" (a string, not the value nil), "number", "string", "boolean, "table", "function", "thread", and "userdata".

unpack (list)

Returns all elements from the given list. This function is equivalent to

return list[1], list[2], ..., list[n]

except that the above code can be written only for a fixed n. The number n is the size of the list, as defined for the table.getn function.

_VERSION

A global variable (not a function) that holds a string containingthe current interpreter version. The current content of this string is "Lua 5.0".

xpcall (f, err)

This function is similar to pcall, except that you can set a new error handler.

xpcall calls function f in protected mode, using err as the error handler. Any error inside f is not propagated; instead, xpcall catches the error, calls the errfunction with the original error object, and returns a status code. Itsfirst result is the status code (a boolean), which is true if the callsucceeds without errors. In such case, xpcall also returns all results from the call, after this first result. In case of any error, xpcall returns false plus the result from err.

5.2 - Coroutine Manipulation

The operations related to coroutines comprise a sub-library of the basic library and come inside the table coroutine. See 2.10 for a general description of coroutines.

coroutine.create (f)

Creates a new coroutine, with body f. f must be a Lua function. Returns this new coroutine, an object with type "thread".

coroutine.resume (co, val1, ...)

Starts or continues the execution of coroutine co. The first time you resume a coroutine, it starts running its body. The arguments val1, ... go as the arguments to the body function. If the coroutine has yielded, resume restarts it; the arguments val1, ... go as the results from the yield.

If the coroutine runs without any errors, resume returns true plus any values passed to yield (if the coroutine yields) or any values returned by the body function (if the coroutine terminates). If there is any error, resume returns false plus the error message.

coroutine.status (co)

Returns the status of coroutine co, as a string: "running", if the coroutine is running (that is, it called status); "suspended", if the coroutine is suspended in a call to yield, or if it has not started running yet; and "dead" if the coroutine has finished its body function, or if it has stopped with an error.

coroutine.wrap (f)

Creates a new coroutine, with body f. fmust be a Lua function. Returns a function that resumes the coroutineeach time it is called. Any arguments passed to the function behave asthe extra arguments to resume. Returns the same values returned by resume, except the first boolean. In case of error, propagates the error.

coroutine.yield (val1, ...)

Suspends the execution of the calling coroutine. The coroutinecannot be running neither a C function, nor a metamethod, nor aniterator. Any arguments to yield go as extra results to resume.

5.3 - String Manipulation

This library provides generic functions for string manipulation,such as finding and extracting substrings, and pattern matching. Whenindexing a string in Lua, the first character is at position 1 (notat 0, as in C). Indices are allowed to be negative and are interpretedas indexing backwards, from the end of the string. Thus, the lastcharacter is at position -1, and so on.

The string library provides all its functions inside the table string.

string.byte (s [, i])

Returns the internal numerical code of the i-th character of s, or nil if the index is out of range. If i is absent, then it is assumed to be 1. i may be negative.

Note that numerical codes are not necessarily portable across platforms.

string.char (i1, i2, ...)

Receives 0 or more integers. Returns a string with length equal tothe number of arguments, in which each character has the internalnumerical code equal to its correspondent argument.

Note that numerical codes are not necessarily portable across platforms.

string.dump (function)

Returns a binary representation of the given function, so that a later loadstring on that string returns a copy of the function. function must be a Lua function without upvalues.

string.find (s, pattern [, init [, plain]])

Looks for the first match of pattern in the string s. If it finds one, then find returns the indices of s where this occurrence starts and ends; otherwise, it returns nil. If the pattern specifies captures (see string.gsub below), the captured strings are returned as extra results. A third, optional numerical argument init specifies where to start the search; it may be negative and its default value is 1. A value of true as a fourth, optional argument plain turns off the pattern matching facilities, so the function does a plain "find substring" operation, with no characters in pattern being considered "magic". Note that if plain is given, then init must be given too.

string.len (s)

Receives a string and returns its length. The empty string "" has length 0. Embedded zeros are counted, so "a/000b/000c" has length 5.

string.lower (s)

Receives a string and returns a copy of that string with alluppercase letters changed to lowercase. All other characters are leftunchanged. The definition of what is an uppercase letter depends on thecurrent locale.

string.rep (s, n)

Returns a string that is the concatenation of n copies of the string s.

string.sub (s, i [, j])

Returns the substring of s that starts at i and continues until j; i and j may be negative. If j is absent, then it is assumed to be equal to -1 (which is the same as the string length). In particular, the call string.sub(s,1,j) returns a prefix of s with length j, and string.sub(s, -i) returns a suffix of s with length i.

string.upper (s)

Receives a string and returns a copy of that string with alllowercase letters changed to uppercase. All other characters are leftunchanged. The definition of what is a lowercase letter depends on thecurrent locale.

Returns a formatted version of its variable number of argumentsfollowing the description given in its first argument (which must be astring). The format string follows the same rules as the printf family of standard C functions. The only differences are that the options/modifiers *, l, L, n, p, and h are not supported, and there is an extra option, q. The qoption formats a string in a form suitable to be safely read back bythe Lua interpreter: The string is written between double quotes, andall double quotes, newlines, and backslashes in the string arecorrectly escaped when written. For instance, the call

string.format('%q', 'a string with "quotes" and /n new line')

will produce the string:

"a string with /"quotes/" and / new line"

The options c, d, E, e, f, g, G, i, o, u, X, and x all expect a number as argument, whereas q and s expect a string. The * modifier can be simulated by building the appropriate format string. For example, "%*g" can be simulated with "%"..width.."g".

String values to be formatted with %s cannot contain embedded zeros.

string.gfind (s, pat)

Returns an iterator function that, each time it is called, returns the next captures from pattern pat over string s.

If pat specifies no captures, then the whole match is produced in each call.

As an example, the following loop

s = "hello world from Lua" for w in string.gfind(s, "%a+") do print(w) end

will iterate over all the words from string s, printing one per line. The next example collects all pairs key=value from the given string into a table:

t = {} s = "from=world, to=Lua" for k, v in string.gfind(s, "(%w+)=(%w+)") do t[k] = v endstring.gsub (s, pat, repl [, n])

Returns a copy of s in which all occurrences of the pattern pat have been replaced by a replacement string specified by repl. gsub also returns, as a second value, the total number of substitutions made.

If repl is a string, then its value is used for replacement. Any sequence in repl of the form %n, with n between 1 and 9, stands for the value of the n-th captured substring (see below).

If repl is a function, then this function is calledevery time a match occurs, with all captured substrings passed asarguments, in order; if the pattern specifies no captures, then thewhole match is passed as a sole argument. If the value returned by thisfunction is a string, then it is used as the replacement string;otherwise, the replacement string is the empty string.

The optional last parameter n limits the maximum number of substitutions to occur. For instance, when n is 1 only the first occurrence of pat is replaced.

Here are some examples:

x = string.gsub("hello world", "(%w+)", "%1 %1") --> x="hello hello world world" x = string.gsub("hello world", "(%w+)", "%1 %1", 1) --> x="hello hello world" x = string.gsub("hello world from Lua", "(%w+)%s*(%w+)", "%2 %1") --> x="world hello Lua from" x = string.gsub("home = $HOME, user = $USER", "%$(%w+)", os.getenv) --> x="home = /home/roberto, user = roberto" x = string.gsub("4+5 = $return 4+5$", "%$(.-)%$", function (s) return loadstring(s)() end) --> x="4+5 = 9" local t = {name="lua", version="5.0"} x = string.gsub("$name_$version.tar.gz", "%$(%w+)", function (v) return t[v] end) --> x="lua_5.0.tar.gz"Patterns

A character class is used to represent a set of characters. The following combinations are allowed in describing a character class:

x (where x is not one of the magic characters ^$()%.[]*+-?) --- represents the character x itself.

. --- (a dot) represents all characters.

%a --- represents all letters.

%c --- represents all control characters.

%d --- represents all digits.

%l --- represents all lowercase letters.

%p --- represents all punctuation characters.

%s --- represents all space characters.

%u --- represents all uppercase letters.

%w --- represents all alphanumeric characters.

%x --- represents all hexadecimal digits.

%z --- represents the character with representation 0.

%x (where x is any non-alphanumeric character) --- represents the character x. This is the standard way to escape the magic characters. Any punctuation character (even the non magic) can be preceded by a `%′ when used to represent itself in a pattern.

[set] --- represents the class which is the union of all characters in set. A range of characters may be specified by separating the end characters of the range with a `-′. All classes %x described above may also be used as components in set. All other characters in set represent themselves. For example, [%w_] (or [_%w]) represents all alphanumeric characters plus the underscore, [0-7] represents the octal digits, and [0-7%l%-] represents the octal digits plus the lowercase letters plus the `-′ character.

The interaction between ranges and classes is not defined. Therefore, patterns like [%a-z] or [a-%%] have no meaning.

[^set] --- represents the complement of set, where set is interpreted as above.

For all classes represented by single letters (%a, %c, etc.), the corresponding uppercase letter represents the complement of the class. For instance, %S represents all non-space characters.

The definitions of letter, space, and other character groups depend on the current locale. In particular, the class [a-z] may not be equivalent to %l. The second form should be preferred for portability.

A pattern item may be

a single character class, which matches any single character in the class;

a single character class followed by `*′, whichmatches 0 or more repetitions of characters in the class. Theserepetition items will always match the longest possible sequence;

a single character class followed by `+′, whichmatches 1 or more repetitions of characters in the class. Theserepetition items will always match the longest possible sequence;

a single character class followed by `-′, which also matches 0 or more repetitions of characters in the class. Unlike `*′, these repetition items will always match the shortest possible sequence;

a single character class followed by `?′, which matches 0 or 1 occurrence of a character in the class;

%n, for n between 1 and 9; such item matches a substring equal to the n-th captured string (see below);

%bxy, where x and y are two distinct characters; such item matches strings that start with x, end with y, and where the x and y are balanced. This means that, if one reads the string from left to right, counting +1 for an x and -1 for a y, the ending y is the first y where the count reaches 0. For instance, the item %b() matches s with balanced parentheses.

A pattern is a sequence of pattern items. A `^′ at the beginning of a pattern anchors the match at the beginning of the subject string. A `$′ at the end of a pattern anchors the match at the end of the subject string. At other positions, `^′ and `$′ have no special meaning and represent themselves.

A pattern may contain sub-patterns enclosed in parentheses; they describe captures. When a match succeeds, the substrings of the subject string that match captures are stored (captured) for future use. Captures are numbered according to their left parentheses. For instance, in the pattern "(a*(.)%w(%s*))", the part of the string matching "a*(.)%w(%s*)" is stored as the first capture (and therefore has number 1); the character matching . is captured with number 2, and the part matching %s* has number 3.

As a special case, the empty capture () captures the current string position (a number). For instance, if we apply the pattern "()aa()" on the string "flaaap", there will be two captures: 3 and 5.

A pattern cannot contain embedded zeros. Use %z instead.

5.4 - Table Manipulation

This library provides generic functions for table manipulation. It provides all its functions inside the table table.

Most functions in the table library assume that the tablerepresents an array or a list. For those functions, an importantconcept is the size of the array. There are three ways to specify that size:

the field "n" --- When the table has a field "n" with a numerical value, that value is assumed as its size.

setn --- You can call the table.setn function to explicitly set the size of a table.

implicit size --- Otherwise, the size of the object is one less the first integer index with a nil value.

For more details, see the descriptions of the table.getn and table.setn functions.

table.concat (table [, sep [, i [, j]]])

Returns table[i]..sep..table[i+1] ... sep..table[j]. The default value for sep is the empty string, the default for i is 1, and the default for j is the size of the table. If i is greater than j, returns the empty string.

table.foreach (table, f)

Executes the given f over all elements of table. For each element, f is called with the index and respective value as arguments. If f returns a non-nil value, then the loop is broken, and this value is returned as the final value of foreach.

See the next function for extra information about table traversals.

table.foreachi (table, f)

Executes the given f over the numerical indices of table. For each index, f is called with the index and respective value as arguments. Indices are visited in sequential order, from 1 to n, where n is the size of the table (see 5.4). If f returns a non-nil value, then the loop is broken and this value is returned as the result of foreachi.

Returns the size of a table, when seen as a list. If the table has an n field with a numeric value, this value is the size of the table. Otherwise, if there was a previous call to table.setn over this table, the respective value is returned. Otherwise, the size is one less the first integer index with a nil value.

table.sort (table [, comp])

Sorts table elements in a given order, in-place, from table[1] to table[n], where n is the size of the table (see 5.4). If compis given, then it must be a function that receives two table elements,and returns true when the first is less than the second (so that not comp(a[i+1],a[i]) will be true after the sort). If comp is not given, then the standard Lua operator < is used instead.

The sort algorithm is not stable, that is, elements considered equal by the given order may have their relative positions changed by the sort.

table.insert (table, [pos,] value)

Inserts element value at position pos in table, shifting up other elements to open space, if necessary. The default value for pos is n+1, where n is the size of the table (see 5.4), so that a call table.insert(t,x) inserts x at the end of table t. This function also updates the size of the table by calling table.setn(table, n+1).

table.remove (table [, pos])

Removes from table the element at position pos,shifting down other elements to close the space, if necessary. Returnsthe value of the removed element. The default value for pos is n, where n is the size of the table (see 5.4), so that a call table.remove(t) removes the last element of table t. This function also updates the size of the table by calling table.setn(table, n-1).

table.setn (table, n)

Updates the size of a table. If the table has a field "n" with a numerical value, that value is changed to the given n. Otherwise, it updates an internal state so that subsequent calls to table.getn(table) return n.

5.5 - Mathematical Functions

This library is an interface to most of the functions of thestandard C math library. (Some have slightly different names.) Itprovides all its functions inside the table math. In addition, it registers the global __pow for the binary exponentiation operator ^, so that x^y returns xy. The library provides the following functions:

math.abs math.acos math.asin math.atan math.atan2 math.ceil math.cos math.deg math.exp math.floor math.log math.log10 math.max math.min math.mod math.pow math.rad math.sin math.sqrt math.tan math.frexp math.ldexp math.random math.randomseed

plus a variable math.pi. Most of them are onlyinterfaces to the corresponding functions in the C library. Alltrigonometric functions work in radians (previous versions of Lua useddegrees). The functions math.deg and math.rad convert between radians and degrees.

The function math.max returns the maximum value of its numeric arguments. Similarly, math.min computes the minimum. Both can be used with 1, 2, or more arguments.

The functions math.random and math.randomseed are interfaces to the simple random generator functions rand and srand that are provided by ANSI C. (No guarantees can be given for their statistical properties.) When called without arguments, math.random returns a pseudo-random real number in the range [0,1). When called with a number n, math.random returns a pseudo-random integer in the range [1,n]. When called with two arguments, l and u, math.random returns a pseudo-random integer in the range [l,u]. The math.randomseed function sets a "seed" for the pseudo-random generator: Equal seeds produce equal sequences of numbers.

5.6 - Input and Output Facilities

The I/O library provides two different styles for file manipulation.The first one uses implicit file descriptors, that is, there areoperations to set a default input file and a default output file, andall input/output operations are over those default files. The secondstyle uses explicit file descriptors.

When using implicit file descriptors, all operations are supplied by table io. When using explicit file descriptors, the operation io.open returns a file descriptor and then all operations are supplied as methods by the file descriptor.

The table io also provides three predefined file descriptors with their usual meanings from C: io.stdin, io.stdout, and io.stderr.

A file handle is a userdata containing the file stream (FILE*), with a distinctive metatable created by the I/O library.

Unless otherwise stated, all I/O functions return nil on failure (plus an error message as a second result) and some value different from nil on success.

io.close ([file])

Equivalent to file:close. Without a file, closes the default output file.

io.flush ()

Equivalent to file:flush over the default output file.

io.input ([file])

When called with a file name, it opens the named file (in textmode), and sets its handle as the default input file. When called witha file handle, it simply sets that file handle as the default inputfile. When called without parameters, it returns the current defaultinput file.

In case of errors this function raises the error, instead of returning an error code.

io.lines ([filename])

Opens the given file name in read mode and returns an iteratorfunction that, each time it is called, returns a new line from thefile. Therefore, the construction

for line in io.lines(filename) do ... end

will iterate over all lines of the file. When the iterator function detects the end of file, it returns nil (to finish the loop) and automatically closes the file.

The call io.lines() (without a file name) is equivalent to io.input():lines(), that is, it iterates over the lines of the default input file.

io.open (filename [, mode])

This function opens a file, in the mode specified in the string mode. It returns a new file handle, or, in case of errors, nil plus an error message.

The mode string can be any of the following:

"r" read mode (the default);

"w" write mode;

"a" append mode;

"r+" update mode, all previous data is preserved;

"w+" update mode, all previous data is erased;

"a+" append update mode, previous data is preserved, writing is only allowed at the end of file.

The mode string may also have a b at theend, which is needed in some systems to open the file in binary mode.This string is exactly what is used in the standard C function fopen.

io.output ([file])

Similar to io.input, but operates over the default output file.

io.read (format1, ...)

Equivalent to io.input():read.

io.tmpfile ()

Returns a handle for a temporary file. This file is open in update mode and it is automatically removed when the program ends.

io.type (obj)

Checks whether obj is a valid file handle. Returns the string "file" if obj is an open file handle, "closed file" if obj is a closed file handle, and nil if obj is not a file handle.

io.write (value1, ...)

Equivalent to io.output():write.

file:close ()

Closes file.

file:flush ()

Saves any written data to file.

file:lines ()

Returns an iterator function that, each time it is called, returns a new line from the file. Therefore, the construction

for line in file:lines() do ... end

will iterate over all lines of the file. (Unlike io.lines, this function does not close the file when the loop ends.)

file:read (format1, ...)

Reads the file file, according to the given formats,which specify what to read. For each format, the function returns astring (or a number) with the characters read, or nil if itcannot read data with the specified format. When called withoutformats, it uses a default format that reads the entire next line (seebelow).

The available formats are

"*n" reads a number; this is the only format that returns a number instead of a string.

"*a" reads the whole file, starting at the current position. On end of file, it returns the empty string.

"*l" reads the next line (skipping the end of line), returning nil on end of file. This is the default format.

number reads a string with up to that number of characters, returning nil on end of file. If number is zero, it reads nothing and returns an empty string, or nil on end of file.

file:seek ([whence] [, offset])

Sets and gets the file position, measured from the beginning of the file, to the position given by offset plus a base specified by the string whence, as follows:

"set" base is position 0 (beginning of the file);

"cur" base is current position;

"end" base is end of file;

In case of success, function seek returns the final file position, measured in bytes from the beginning of the file. If this function fails, it returns nil, plus a string describing the error.

The default value for whence is "cur", and for offset is 0. Therefore, the call file:seek() returns the current file position, without changing it; the call file:seek("set") sets the position to the beginning of the file (and returns 0); and the call file:seek("end") sets the position to the end of the file, and returns its size.

file:write (value1, ...)

Writes the value of each of its arguments to the filehandle file. The arguments must be strings or numbers. To write other values, use tostring or string.format before write.

5.7 - Operating System Facilities

This library is implemented through table os.

os.clock ()

Returns an approximation of the amount of CPU time used by the program, in seconds.

os.date ([format [, time]])

Returns a string or a table containing date and time, formatted according to the given string format.

If the time argument is present, this is the time to be formatted (see the os.time function for a description of this value). Otherwise, date formats the current time.

If format starts with `!′, then the date is formatted in Coordinated Universal Time. After that optional character, if format is *t, then date returns a table with the following fields: year (four digits), month (1--12), day (1--31), hour (0--23), min (0--59), sec (0--61), wday (weekday, Sunday is 1), yday (day of the year), and isdst (daylight saving flag, a boolean).

If format is not *t, then date returns the date as a string, formatted according to the same rules as the C function strftime.

When called without arguments, date returns a reasonable date and time representation that depends on the host system and on the current locale (that is, os.date() is equivalent to os.date("%c")).

os.difftime (t2, t1)

Returns the number of seconds from time t1 to time t2. In Posix, Windows, and some other systems, this value is exactly t2-t1.

os.execute (command)

This function is equivalent to the C function system. It passes command to be executed by an operating system shell. It returns a status code, which is system-dependent.

os.exit ([code])

Calls the C function exit, with an optional code, to terminate the host program. The default value for code is the success code.

os.getenv (varname)

Returns the value of the process environment variable varname, or nil if the variable is not defined.

os.remove (filename)

Deletes the file with the given name. If this function fails, it returns nil, plus a string describing the error.

os.rename (oldname, newname)

Renames file named oldname to newname. If this function fails, it returns nil, plus a string describing the error.

os.setlocale (locale [, category])

Sets the current locale of the program. locale is a string specifying a locale; category is an optional string describing which category to change: "all", "collate", "ctype", "monetary", "numeric", or "time"; the default category is "all". The function returns the name of the new locale, or nil if the request cannot be honored.

os.time ([table])

Returns the current time when called without arguments, or a timerepresenting the date and time specified by the given table. This tablemust have fields year, month, and day, and may have fields hour, min, sec, and isdst (for a description of these fields, see the os.date function).

The returned value is a number, whose meaning depends on yoursystem. In Posix, Windows, and some other systems, this number countsthe number of seconds since some given start time (the "epoch"). Inother systems, the meaning is not specified, and the number returned bytime can be used only as an argument to date and difftime.

os.tmpname ()

Returns a string with a file name that can be used for a temporaryfile. The file must be explicitly opened before its use and removedwhen no longer needed.

This function is equivalent to the tmpnamC function, and many people (and even some compilers!) advise againstits use, because between the time you call this function and the timeyou open the file, it is possible for another process to create a filewith the same name.

5.8 - The Reflexive Debug Interface

The debug library provides the functionality of thedebug interface to Lua programs. You should exert care when using thislibrary. The functions provided here should be used exclusively fordebugging and similar tasks, such as profiling. Please resist thetemptation to use them as a usual programming tool: They can be veryslow. Moreover, setlocal and getlocal violate the privacy of local variables and therefore can compromise some otherwise secure code.

All functions in this library are provided inside a debug table.

debug.debug ()

Enters an interactive mode with the user, running each string thatthe user enters. Using simple commands and other debug facilities, theuser can inspect global and local variables, change their values,evaluate s, and so on. A line containing only the word cont finishes this function, so that the caller continues its execution.

Note that commands for debug.debug are not lexically nested with any function, so they have no direct access to local variables.

debug.gethook ()

Returns the current hook settings, as three values: the current hookfunction, the current hook mask, and the current hook count (as set bythe debug.sethook function).

debug.getinfo (function [, what])

This function returns a table with information about a function. Youcan give the function directly, or you can give a number as the valueof function, which means the function running at level function of the call stack: Level 0 is the current function (getinfo itself); level 1 is the function that called getinfo; and so on. If function is a number larger than the number of active functions, then getinfo returns nil.

The returned table contains all the fields returned by lua_getinfo, with the string what describing which fields to fill in. The default for what is to get all information available. If present, the option `f′ adds a field named func with the function itself.

For instance, the debug.getinfo(1,"n").name returns the name of the current function, if a reasonable name can be found, and debug.getinfo(print) returns a table with all available information about the print function.

debug.getlocal (level, local)

This function returns the name and the value of the local variable with index local of the function at level levelof the stack. (The first parameter or local variable has index 1, andso on, until the last active local variable.) The function returns nil if there is no local variable with the given index, and raises an error when called with a level out of range. (You can call debug.getinfo to check whether the level is valid.)

debug.getupvalue (func, up)

This function returns the name and the value of the upvalue with index up of the function func. The function returns nil if there is no upvalue with the given index.

debug.setlocal (level, local, value)

This function assigns the value value to the local variable with index local of the function at level level of the stack. The function returns nil if there is no local variable with the given index, and raises an error when called with a level out of range. (You can call getinfo to check whether the level is valid.)

debug.setupvalue (func, up, value)

This function assigns the value value to the upvalue with index up of the function func. The function returns nil if there is no upvalue with the given index.

debug.sethook (hook, mask [, count])

Sets the given function as a hook. The string mask and the number count describe when the hook will be called. The string mask may have the following characters, with the given meaning:

"c" The hook is called every time Lua calls a function;

"r" The hook is called every time Lua returns from a function;

"l" The hook is called every time Lua enters a new line of code.

With a count different from zero, the hook is called after every count instructions.

When called without arguments, the debug.sethook function turns off the hook.

When the hook is called, its first parameter is always a string describing the event that triggered its call: "call", "return" (or "tail return"), "line", and "count". Moreover, for line events, it also gets as its second parameter the new line number. Inside a hook, you can call getinfo with level 2 to get more information about the running function (level 0 is the getinfo function, and level 1 is the hook function), unless the event is "tail return". In this case, Lua is only simulating the return, and a call to getinfo will return invalid data.

debug.traceback ([message])

Returns a string with a traceback of the call stack. An optional message string is appended at the beginning of the traceback. This function is typically used with xpcall to produce better error messages.