diff options
Diffstat (limited to 'runtime/doc/luaref.txt')
| -rw-r--r-- | runtime/doc/luaref.txt | 864 |
1 files changed, 397 insertions, 467 deletions
diff --git a/runtime/doc/luaref.txt b/runtime/doc/luaref.txt index 9dbd2d4de5..aafdd5c43e 100644 --- a/runtime/doc/luaref.txt +++ b/runtime/doc/luaref.txt @@ -20,76 +20,10 @@ See |luaref-copyright| for copyright and licenses. - CONTENTS - ============ - - 1 INTRODUCTION........................|luaref-intro| - - 2 THE LANGUAGE........................|luaref-language| - 2.1 Lexical Conventions...............|luaref-langLexConv| - 2.2 Values and Types..................|luaref-langValTypes| - 2.2.1 Coercion........................|luaref-langCoercion| - 2.3 Variables.........................|luaref-langVariables| - 2.4 Statements........................|luaref-langStats| - 2.4.1 Chunks..........................|luaref-langChunks| - 2.4.2 Blocks..........................|luaref-langBlocks| - 2.4.3 Assignment......................|luaref-langAssign| - 2.4.4 Control Structures..............|luaref-langContStructs| - 2.4.5 For Statement...................|luaref-langForStat| - 2.4.6 Function Calls as Statements....|luaref-langFuncStat| - 2.4.7 Local Declarations..............|luaref-langLocalDec| - 2.5 Expressions.......................|luaref-langExpressions| - 2.5.1 Arithmetic Operators............|luaref-langArithOp| - 2.5.2 Relational Operators............|luaref-langRelOp| - 2.5.3 Logical Operators...............|luaref-langLogOp| - 2.5.4 Concatenation...................|luaref-langConcat| - 2.5.5 The Length Operator.............|luaref-langLength| - 2.5.6 Precedence......................|luaref-langPrec| - 2.5.7 Table Constructors..............|luaref-langTableConst| - 2.5.8 Function Calls..................|luaref-langFuncCalls| - 2.5.9 Function Definitions............|luaref-langFuncDefs| - 2.6 Visibility Rules..................|luaref-langVisibRules| - 2.7 Error Handling....................|luaref-langError| - 2.8 Metatables........................|luaref-langMetatables| - 2.9 Environments......................|luaref-langEnvironments| - 2.10 Garbage Collection...............|luaref-langGC| - 2.10.1 Garbage-Collection Metamethods.|luaref-langGCMeta| - 2.10.2 Weak Tables....................|luaref-langWeaktables| - 2.11 Coroutines.......................|luaref-langCoro| - - 3 THE APPLICATION PROGRAM INTERFACE...|luaref-api| - 3.1 The Stack.........................|luaref-apiStack| - 3.2 Stack Size........................|luaref-apiStackSize| - 3.3 Pseudo-Indices....................|luaref-apiPseudoIndices| - 3.4 C Closures........................|luaref-apiCClosures| - 3.5 Registry..........................|luaref-apiRegistry| - 3.6 Error Handling in C...............|luaref-apiError| - 3.7 Functions and Types...............|luaref-apiFunctions| - 3.8 The Debug Interface...............|luaref-apiDebug| - - 4 THE AUXILIARY LIBRARY...............|luaref-aux| - 4.1 Functions and Types...............|luaref-auxFunctions| - - 5 STANDARD LIBRARIES..................|luaref-lib| - 5.1 Basic Functions...................|luaref-libBasic| - 5.2 Coroutine Manipulation............|luaref-libCoro| - 5.3 Modules...........................|luaref-libModule| - 5.4 String Manipulation...............|luaref-libString| - 5.4.1 Patterns........................|luaref-libStringPat| - 5.5 Table Manipulation................|luaref-libTable| - 5.6 Mathematical Functions............|luaref-libMath| - 5.7 Input and Output Facilities.......|luaref-libIO| - 5.8 Operating System Facilities.......|luaref-libOS| - 5.9 The Debug Library.................|luaref-libDebug| - - A BIBLIOGRAPHY........................|luaref-bibliography| - B COPYRIGHT & LICENSES................|luaref-copyright| - C LUAREF DOC..........................|luaref-doc| - +Type |gO| to see the table of contents. ============================================================================== 1 INTRODUCTION *luaref-intro* -============================================================================== Lua is an extension programming language designed to support general procedural programming with data description facilities. It also offers good @@ -120,14 +54,13 @@ Lua means "moon" in Portuguese and is pronounced LOO-ah. ============================================================================== 2 THE LANGUAGE *luaref-language* -============================================================================== This section describes the lexis, the syntax, and the semantics of Lua. In other words, this section describes which tokens are valid, how they can be combined, and what their combinations mean. The language constructs will be explained using the usual extended BNF -notation, in which { `a` } means 0 or more `a`'s, and [ `a` ] means an optional `a`. +notation, in which `{ a }` means 0 or more `a`'s, and `[ a ]` means an optional `a`. ============================================================================== 2.1 Lexical Conventions *luaref-langLexConv* @@ -203,7 +136,7 @@ For convenience, when the opening long bracket is immediately followed by a newline, the newline is not included in the string. As an example, in a system using ASCII (in which `a` is coded as 97, newline is coded as 10, and `1` is coded as 49), the five literals below denote the same string: -> +>lua a = 'alo\n123"' a = "alo\n123\"" a = '\97lo\10\04923"' @@ -292,7 +225,7 @@ parameter passing, and function returns always manipulate references to such values; these operations do not imply any kind of copy. The library function `type` returns a string describing the type of a given -value (see |luaref-type|). +value (see |luaref-type()|). ------------------------------------------------------------------------------ 2.2.1 Coercion *luaref-langCoercion* @@ -303,7 +236,7 @@ string to a number, following the usual conversion rules. Conversely, whenever a number is used where a string is expected, the number is converted to a string, in a reasonable format. For complete control of how numbers are converted to strings, use the `format` function from the string library (see -|luaref-string.format|). +|string.format()|). ============================================================================== 2.3 Variables *luaref-langVariables* @@ -344,13 +277,13 @@ has its own reference to an environment, so that all global variables in this function will refer to this environment table. When a function is created, it inherits the environment from the function that created it. To get the environment table of a Lua function, you call `getfenv` (see -|luaref-getfenv|). To replace it, you call `setfenv` (see |luaref-setfenv|). +|lua_getfenv()|). To replace it, you call `setfenv` (see |luaref-setfenv()|). (You can only manipulate the environment of C functions through the debug library; see |luaref-libDebug|.) An access to a global variable `x` is equivalent to `_env.x`, which in turn is equivalent to -> +>lua gettable_event(_env, "x") < where `_env` is the environment of the running function. (The `_env` variable is @@ -433,13 +366,13 @@ before the adjustment (except when the call is enclosed in parentheses; see The assignment statement first evaluates all its expressions and only then are the assignments performed. Thus the code -> +>lua i = 3 i, a[i] = i+1, 20 < sets `a[3]` to 20, without affecting `a[4]` because the `i` in `a[i]` is evaluated (to 3) before it is assigned 4. Similarly, the line -> +>lua x, y = y, x < exchanges the values of `x` and `y`. @@ -452,7 +385,7 @@ defined or callable in Lua. We use it here only for explanatory purposes.) An assignment to a global variable `x = val` is equivalent to the assignment `_env.x = val`, which in turn is equivalent to -> +>lua settable_event(_env, "x", val) < where `_env` is the environment of the running function. (The `_env` variable is @@ -517,19 +450,20 @@ The `block` is repeated for `name` starting at the value of the first `exp`, unt it passes the second `exp` by steps of the third `exp`. More precisely, a `for` statement like - `for var =` `e1, e2, e3` `do` `block` `end` + `for var = e1, e2, e3 do block end` -is equivalent to the code: +is equivalent to the code: >lua - `do` - `local` `var, limit, step` `= tonumber(e1), tonumber(e2), tonumber(e3)` - `if not (` `var` `and` `limit` `and` `step` `) then error() end` - `while (` `step` `>0 and` `var` `<=` `limit` `)` - `or (` `step` `<=0 and` `var` `>=` `limit` `) do` - `block` - `var` `=` `var` `+` `step` - `end` - `end` + do + local var, limit, step = tonumber(e1), tonumber(e2), tonumber(e3) + if not ( var and limit and step ) then error() end + while ( step >0 and var <= limit ) + or ( step <=0 and var >= limit ) do + block + var = var + step + end + end +< Note the following: @@ -555,18 +489,18 @@ A `for` statement like `for` `var1, ..., varn` `in` `explist` `do` `block` `end` -is equivalent to the code: - - `do` - `local` `f, s, var` `=` `explist` - `while true do` - `local` `var1, ..., varn` `=` `f(s, var)` - `var` `=` `var1` - `if` `var` `== nil then break end` - `block` - `end` - `end` +is equivalent to the code: >lua + do + local f, s, var = explist + while true do + local var1, ..., varn = f(s, var) + var = var1 + if var == nil then break end + block + end + end +< Note the following: - `explist` is evaluated only once. Its results are an iterator function, @@ -634,7 +568,7 @@ they are explained in |luaref-langFuncDefs|. Binary operators comprise arithmetic operators (see |luaref-langArithOp|), relational operators (see |luaref-langRelOp|), logical operators (see |luaref-langLogOp|), and the concatenation operator (see |luaref-langConcat|). -Unary operators comprise the unary minus (see |luaref-labgArithOp|), the unary +Unary operators comprise the unary minus (see |luaref-langArithOp|), the unary `not` (see |luaref-langLogOp|), and the unary length operator (see |luaref-langLength|). @@ -648,7 +582,7 @@ adjusts the result list to one element, discarding all values except the first one. Here are some examples: -> +>lua f() -- adjusted to 0 results g(f(), x) -- f() is adjusted to 1 result g(x, f()) -- g gets x plus all results from f() @@ -681,7 +615,7 @@ or strings that can be converted to numbers (see |luaref-langCoercion|), then al operations have the usual meaning. Exponentiation works for any exponent. For instance, `x^(-0.5)` computes the inverse of the square root of `x`. Modulo is defined as -> +>lua a % b == a - math.floor(a/b)*b < That is, it is the remainder of a division that rounds the quotient towards @@ -808,11 +742,11 @@ key `exp1` and value `exp2`. A field of the form `name = exp` is equivalent to `["name"] = exp`. Finally, fields of the form `exp` are equivalent to `[i] = exp`, where `i` are consecutive numerical integers, starting with 1. Fields in the other formats do not affect this counting. For example, -> +>lua a = { [f(1)] = g; "x", "y"; x = 1, f(x), [30] = 23; 45 } < is equivalent to -> +>lua do local t = {} t[f(1)] = g @@ -868,7 +802,7 @@ argument list is a single new table. A call of the form `f'` `string` `'` As an exception to the free-format syntax of Lua, you cannot put a line break before the `(` in a function call. This restriction avoids some ambiguities in the language. If you write -> +>lua a = f (g).x(a) < @@ -886,7 +820,7 @@ function. Note that a tail call only happens with a particular syntax, where the `return` has one single function call as argument; this syntax makes the calling function return exactly the returns of the called function. So, none of the following examples are tail calls: -> +>lua return (f(x)) -- results adjusted to 1 return 2 * f(x) return x, f(x) -- additional results @@ -967,7 +901,7 @@ expression is used as the last element of a list of expressions, then no adjustment is made (unless the call is enclosed in parentheses). As an example, consider the following definitions: -> +>lua function f(a, b) end function g(a, b, ...) end function r() return 1,2,3 end @@ -1008,7 +942,7 @@ is syntactic sugar for Lua is a lexically scoped language. The scope of variables begins at the first statement after their declaration and lasts until the end of the innermost block that includes the declaration. Consider the following example: -> +>lua x = 10 -- global variable do -- new block local x = x -- new `x`, with value 10 @@ -1033,7 +967,7 @@ function. Notice that each execution of a local statement defines new local variables. Consider the following example: -> +>lua a = {} local x = 20 for i=1,10 do @@ -1050,13 +984,13 @@ them share the same `x`. Because Lua is an embedded extension language, all Lua actions start from C code in the host program calling a function from the Lua library (see -|luaref-lua_pcall|). Whenever an error occurs during Lua compilation or +|lua_pcall()|). Whenever an error occurs during Lua compilation or execution, control returns to C, which can take appropriate measures (such as print an error message). Lua code can explicitly generate an error by calling the `error` function (see -|luaref-error|). If you need to catch errors in Lua, you can use -the `pcall` function (see |luaref-pcall|). +|luaref-error()|). If you need to catch errors in Lua, you can use +the `pcall` function (see |luaref-pcall()|). ============================================================================== 2.8 Metatables *luaref-metatable* *luaref-langMetatables* @@ -1074,10 +1008,10 @@ previous example, the event is "add" and the metamethod is the function that performs the addition. You can query the metatable of any value through the `getmetatable` function -(see |luaref-getmetatable|). +(see |luaref-getmetatable()|). You can replace the metatable of tables through the `setmetatable` function (see -|luaref-setmetatable|). You cannot change the metatable of other types from Lua +|luaref-setmetatable()|). You cannot change the metatable of other types from Lua (except using the debug library); you must use the C API for that. Tables and userdata have individual metatables (although multiple tables and @@ -1109,7 +1043,7 @@ given object, we use the expression metatable(obj)[event] < This should be read as -> +>lua rawget(metatable(obj) or {}, event) < That is, the access to a metamethod does not invoke other metamethods, and the @@ -1123,13 +1057,13 @@ the `+` operation. The function `getbinhandler` below defines how Lua chooses a handler for a binary operation. First, Lua tries the first operand. If its type does not define a handler for the operation, then Lua tries the second operand. -> +>lua function getbinhandler (op1, op2, event) return metatable(op1)[event] or metatable(op2)[event] end < By using this function, the behavior of the `op1 + op2` is -> +>lua function add_event (op1, op2) local o1, o2 = tonumber(op1), tonumber(op2) if o1 and o2 then -- both operands are numeric? @@ -1170,7 +1104,7 @@ with the function `pow` (from the C math library) as the primitive operation. "unm": *__unm()* ------ the unary `-` operation. -> +>lua function unm_event (op) local o = tonumber(op) if o then -- operand is numeric? @@ -1190,7 +1124,7 @@ the unary `-` operation. "concat": *__concat()* --------- the `..` (concatenation) operation. -> +>lua function concat_event (op1, op2) if (type(op1) == "string" or type(op1) == "number") and (type(op2) == "string" or type(op2) == "number") then @@ -1208,7 +1142,7 @@ the `..` (concatenation) operation. "len": *__len()* ------ the `#` operation. -> +>lua function len_event (op) if type(op) == "string" then return strlen(op) -- primitive string length @@ -1233,7 +1167,7 @@ The function `getcomphandler` defines how Lua chooses a metamethod for comparison operators. A metamethod only is selected when both objects being compared have the same type and the same metamethod for the selected operation. -> +>lua function getcomphandler (op1, op2, event) if type(op1) ~= type(op2) then return nil end local mm1 = metatable(op1)[event] @@ -1242,7 +1176,7 @@ operation. end < The "eq" event is defined as follows: -> +>lua function eq_event (op1, op2) if type(op1) ~= type(op2) then -- different types? return false -- different objects @@ -1264,7 +1198,7 @@ The "eq" event is defined as follows: "lt": *__lt()* ----- the `<` operation. -> +>lua function lt_event (op1, op2) if type(op1) == "number" and type(op2) == "number" then return op1 < op2 -- numeric comparison @@ -1285,7 +1219,7 @@ the `<` operation. "le": *__le()* ----- the `<=` operation. -> +>lua function le_event (op1, op2) if type(op1) == "number" and type(op2) == "number" then return op1 <= op2 -- numeric comparison @@ -1313,7 +1247,7 @@ to `not (b < a)`. "index": *__index()* -------- The indexing access `table[key]`. -> +>lua function gettable_event (table, key) local h if type(table) == "table" then @@ -1335,7 +1269,7 @@ The indexing access `table[key]`. "newindex": *__newindex()* ----------- The indexing assignment `table[key] = value`. -> +>lua function settable_event (table, key, value) local h if type(table) == "table" then @@ -1357,7 +1291,7 @@ The indexing assignment `table[key] = value`. "call": *__call()* ------- called when Lua calls a value. -> +>lua function function_event (func, ...) if type(func) == "function" then return func(...) -- primitive call @@ -1385,8 +1319,8 @@ convenience feature for programmers to associate a table to a userdata. Environments associated with threads are called global environments. They are used as the default environment for their threads and non-nested functions -created by the thread (through `loadfile` |luaref-loadfile|, `loadstring` -|luaref-loadstring| or `load` |luaref-load|) and can be directly accessed by C +created by the thread (through `loadfile` |luaref-loadfile()|, `loadstring` +|luaref-loadstring()| or `load` |luaref-load()|) and can be directly accessed by C code (see |luaref-apiPseudoIndices|). Environments associated with C functions can be directly accessed by C code @@ -1399,10 +1333,10 @@ used as the default environment for other Lua functions created by the function. You can change the environment of a Lua function or the running thread by -calling `setfenv` (see |luaref-setenv|). You can get the environment of a Lua -function or the running thread by calling `getfenv` (see |luaref-getfenv|). To -manipulate the environment of other objects (userdata, C functions, other -threads) you must use the C API. +calling `setfenv`. You can get the environment of a Lua function or the +running thread by calling `getfenv` (see |lua_getfenv()|). To manipulate the +environment of other objects (userdata, C functions, other threads) you must +use the C API. ============================================================================== 2.10 Garbage Collection *luaref-langGC* @@ -1432,8 +1366,8 @@ collector too slow and may result in the collector never finishing a cycle. The default, 2, means that the collector runs at "twice" the speed of memory allocation. -You can change these numbers by calling `lua_gc` (see |luaref-lua_gc|) in C or -`collectgarbage` (see |luaref-collectgarbage|) in Lua. Both get percentage +You can change these numbers by calling `lua_gc` (see |lua_gc()|) in C or +`collectgarbage` (see |luaref-collectgarbage()|) in Lua. Both get percentage points as arguments (so an argument of 100 means a real value of 1). With these functions you can also control the collector directly (e.g., stop and restart it). @@ -1452,7 +1386,7 @@ Garbage userdata with a field `__gc` in their metatables are not collected immediately by the garbage collector. Instead, Lua puts them in a list. After the collection, Lua does the equivalent of the following function for each userdata in that list: -> +>lua function gc_event (udata) local h = metatable(udata).__gc if h then @@ -1496,12 +1430,12 @@ multithread systems, however, a coroutine only suspends its execution by explicitly calling a yield function. You create a coroutine with a call to `coroutine.create` (see -|luaref-coroutine.create|). Its sole argument is a function that is the main +|coroutine.create()|). Its sole argument is a function that is the main function of the coroutine. The `create` function only creates a new coroutine and returns a handle to it (an object of type `thread`); it does not start the coroutine execution. -When you first call `coroutine.resume` (see |luaref-coroutine.resume|), +When you first call `coroutine.resume` (see |coroutine.resume()|), passing as its first argument the thread returned by `coroutine.create`, the coroutine starts its execution, at the first line of its main function. Extra arguments passed to `coroutine.resume` are passed on to the coroutine main @@ -1516,7 +1450,7 @@ main function. In case of errors, `coroutine.resume` returns `false` plus an error message. A coroutine yields by calling `coroutine.yield` (see -|luaref-coroutine.yield|). When a coroutine yields, the corresponding +|coroutine.yield()|). When a coroutine yields, the corresponding `coroutine.resume` returns immediately, even if the yield happens inside nested function calls (that is, not in the main function, but in a function directly or indirectly called by the main function). In the case of a yield, @@ -1526,7 +1460,7 @@ its execution from the point where it yielded, with the call to `coroutine.yield` returning any extra arguments passed to `coroutine.resume`. Like `coroutine.create`, the `coroutine.wrap` function (see -|luaref-coroutine.wrap|) also creates a coroutine, but instead of returning +|coroutine.wrap()|) also creates a coroutine, but instead of returning the coroutine itself, it returns a function that, when called, resumes the coroutine. Any arguments passed to this function go as extra arguments to `coroutine.resume`. `coroutine.wrap` returns all the values returned by @@ -1535,7 +1469,7 @@ coroutine. Any arguments passed to this function go as extra arguments to propagated to the caller. As an example, consider the next code: -> +>lua function foo1 (a) print("foo", a) return coroutine.yield(2*a) @@ -1569,7 +1503,6 @@ When you run it, it produces the following output: ============================================================================== 3 THE APPLICATION PROGRAM INTERFACE *luaref-API* -============================================================================== 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 @@ -1595,7 +1528,7 @@ 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. This 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 -|luaref-lua_CFunction|). +|lua_CFunction()|). *luaref-stackindex* For convenience, most query operations in the API do not follow a strict stack @@ -1615,7 +1548,7 @@ if `1 <= abs(index) <= top`). 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 -|luaref-lua_checkstack|). +|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 @@ -1626,7 +1559,7 @@ 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. @@ -1647,7 +1580,7 @@ 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); < @@ -1656,14 +1589,14 @@ global variable, do 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 |luaref-lua_pushcclosure|). +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` (see |luaref-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. +`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 *luaref-registry* *luaref-apiRegistry* @@ -1694,11 +1627,11 @@ Almost any function in the API may raise an error, for instance due to a memory allocation error. The following functions run in protected mode (that is, they create a protected environment to run), so they never raise an error: `lua_newstate`, `lua_close`, `lua_load`, `lua_pcall`, and `lua_cpcall` (see -|luaref-lua_newstate|, |luaref-lua_close|, |luaref-lua_load|, -|luaref-lua_pcall|, and |luaref-lua_cpcall|). +|lua_newstate()|, |lua_close()|, |lua_load()|, +|lua_pcall()|, and |lua_cpcall()|). Inside a C function you can raise an error by calling `lua_error` (see -|luaref-lua_error|). +|lua_error()|). ============================================================================== 3.7 Functions and Types *luaref-apiFunctions* @@ -1706,7 +1639,7 @@ Inside a C function you can raise an error by calling `lua_error` (see Here we list all functions and types from the C API in alphabetical order. lua_Alloc *lua_Alloc()* -> +>c typedef void * (*lua_Alloc) (void *ud, void *ptr, size_t osize, @@ -1715,7 +1648,7 @@ lua_Alloc *lua_Alloc()* The type of the memory-allocation function used by Lua states. The allocator function must provide a functionality similar to `realloc`, but not exactly the same. Its arguments are `ud`, an opaque pointer - passed to `lua_newstate` (see |luaref-lua_newstate|); `ptr`, a pointer + passed to `lua_newstate` (see |lua_newstate()|); `ptr`, a pointer to the block being allocated/reallocated/freed; `osize`, the original size of the block; `nsize`, the new size of the block. `ptr` is `NULL` if and only if `osize` is zero. When `nsize` is zero, the allocator @@ -1729,8 +1662,8 @@ lua_Alloc *lua_Alloc()* Here is a simple implementation for the allocator function. It is used in the auxiliary library by `luaL_newstate` (see - |luaref-luaL_newstate|). -> + |luaL_newstate()|). +>c static void *l_alloc (void *ud, void *ptr, size_t osize, size_t nsize) { (void)ud; (void)osize; /* not used */ @@ -1747,7 +1680,7 @@ lua_Alloc *lua_Alloc()* behaviors. lua_atpanic *lua_atpanic()* -> +>c lua_CFunction lua_atpanic (lua_State *L, lua_CFunction panicf); < Sets a new panic function and returns the old one. @@ -1761,7 +1694,7 @@ lua_atpanic *lua_atpanic()* stack. lua_call *lua_call()* -> +>c void lua_call (lua_State *L, int nargs, int nresults); < Calls a function. @@ -1785,11 +1718,11 @@ lua_call *lua_call()* The following example shows how the host program may do the equivalent to this Lua code: -> +>lua a = f("how", t.x, 14) < Here it is in C: -> +>c lua_getfield(L, LUA_GLOBALSINDEX, "f"); // function to be called lua_pushstring(L, "how"); // 1st argument lua_getfield(L, LUA_GLOBALSINDEX, "t"); // table to be indexed @@ -1804,7 +1737,7 @@ lua_call *lua_call()* practice. lua_CFunction *luaref-cfunction* *lua_CFunction()* -> +>c typedef int (*lua_CFunction) (lua_State *L); < Type for C functions. @@ -1813,7 +1746,7 @@ lua_CFunction *luaref-cfunction* *lua_CFunction()* following protocol, which defines the way parameters and results are passed: a C function receives its arguments from Lua in its stack in direct order (the first argument is pushed first). So, when the - function starts, `lua_gettop(L)` (see |luaref-lua_gettop|) returns the + function starts, `lua_gettop(L)` (see |lua_gettop()|) returns the number of arguments received by the function. The first argument (if any) is at index 1 and its last argument is at index `lua_gettop(L)`. To return values to Lua, a C function just pushes them onto the stack, @@ -1825,7 +1758,7 @@ lua_CFunction *luaref-cfunction* *lua_CFunction()* *luaref-cfunctionexample* As an example, the following function receives a variable number of numerical arguments and returns their average and sum: -> +>c static int foo (lua_State *L) { int n = lua_gettop(L); /* number of arguments */ lua_Number sum = 0; @@ -1844,7 +1777,7 @@ lua_CFunction *luaref-cfunction* *lua_CFunction()* < lua_checkstack *lua_checkstack()* -> +>c int lua_checkstack (lua_State *L, int extra); < Ensures that there are at least `extra` free stack slots in the stack. @@ -1853,7 +1786,7 @@ lua_checkstack *lua_checkstack()* the new size, it is left unchanged. lua_close *lua_close()* -> +>c void lua_close (lua_State *L); < Destroys all objects in the given Lua state (calling the corresponding @@ -1865,7 +1798,7 @@ lua_close *lua_close()* are not needed, to avoid growing too large. lua_concat *lua_concat()* -> +>c void lua_concat (lua_State *L, int n); < Concatenates the `n` values at the top of the stack, pops them, and @@ -1875,35 +1808,35 @@ lua_concat *lua_concat()* usual semantics of Lua (see |luaref-langConcat|). lua_cpcall *lua_cpcall()* -> +>c int lua_cpcall (lua_State *L, lua_CFunction func, void *ud); < Calls the C function `func` in protected mode. `func` starts with only one element in its stack, a light userdata containing `ud`. In case of errors, `lua_cpcall` returns the same error codes as `lua_pcall` (see - |luaref-lua_pcall|), plus the error object on the top of the stack; + |lua_pcall()|), plus the error object on the top of the stack; otherwise, it returns zero, and does not change the stack. All values returned by `func` are discarded. lua_createtable *lua_createtable()* -> +>c void lua_createtable (lua_State *L, int narr, int nrec); < Creates a new empty table and pushes it onto the stack. The new table has space pre-allocated for `narr` array elements and `nrec` non-array elements. This pre-allocation is useful when you know exactly how many elements the table will have. Otherwise you can use the function - `lua_newtable` (see |luaref-lua_newtable|). + `lua_newtable` (see |lua_newtable()|). lua_dump *lua_dump()* -> +>c int lua_dump (lua_State *L, lua_Writer writer, void *data); < Dumps a function as a binary chunk. Receives a Lua function on the top of the stack and produces a binary chunk that, if loaded again, results in a function equivalent to the one dumped. As it produces parts of the chunk, `lua_dump` calls function `writer` (see - |luaref-lua_Writer|) with the given `data` to write them. + |lua_Writer()|) with the given `data` to write them. The value returned is the error code returned by the last call to the writer; 0 means no errors. @@ -1911,7 +1844,7 @@ lua_dump *lua_dump()* This function does not pop the Lua function from the stack. lua_equal *lua_equal()* -> +>c int lua_equal (lua_State *L, int index1, int index2); < Returns 1 if the two values in acceptable indices `index1` and @@ -1920,15 +1853,15 @@ lua_equal *lua_equal()* if any of the indices is non valid. lua_error *lua_error()* -> +>c int lua_error (lua_State *L); < Generates a Lua error. The error message (which can actually be a Lua value of any type) must be on the stack top. This function does a long - jump, and therefore never returns (see |luaref-luaL_error|). + jump, and therefore never returns (see |luaL_error()|). lua_gc *lua_gc()* -> +>c int lua_gc (lua_State *L, int what, int data); < Controls the garbage collector. @@ -1936,46 +1869,46 @@ lua_gc *lua_gc()* This function performs several tasks, according to the value of the parameter `what`: - `LUA_GCSTOP` stops the garbage collector. - `LUA_GCRESTART` restarts the garbage collector. - `LUA_GCCOLLECT` performs a full garbage-collection cycle. - `LUA_GCCOUNT` returns the current amount of memory (in Kbytes) in + - `LUA_GCSTOP` stops the garbage collector. + - `LUA_GCRESTART` restarts the garbage collector. + - `LUA_GCCOLLECT` performs a full garbage-collection cycle. + - `LUA_GCCOUNT` returns the current amount of memory (in Kbytes) in use by Lua. - `LUA_GCCOUNTB` returns the remainder of dividing the current + - `LUA_GCCOUNTB` returns the remainder of dividing the current amount of bytes of memory in use by Lua by 1024. - `LUA_GCSTEP` performs an incremental step of garbage collection. + - `LUA_GCSTEP` performs an incremental step of garbage collection. The step "size" is controlled by `data` (larger values mean more steps) in a non-specified way. If you want to control the step size you must experimentally tune the value of `data`. The function returns 1 if the step finished a garbage-collection cycle. - `LUA_GCSETPAUSE` sets `data` /100 as the new value for the + - `LUA_GCSETPAUSE` sets `data` /100 as the new value for the `pause` of the collector (see |luaref-langGC|). The function returns the previous value of the pause. - `LUA_GCSETSTEPMUL` sets `data` /100 as the new value for the + - `LUA_GCSETSTEPMUL`sets `data` /100 as the new value for the `step` `multiplier` of the collector (see |luaref-langGC|). The function returns the previous value of the step multiplier. lua_getallocf *lua_getallocf()* -> +>c lua_Alloc lua_getallocf (lua_State *L, void **ud); < Returns the memory-allocation function of a given state. If `ud` is not `NULL`, Lua stores in `*ud` the opaque pointer passed to - `lua_newstate` (see |luaref-lua_newstate|). + `lua_newstate` (see |lua_newstate()|). lua_getfenv *lua_getfenv()* -> +>c void lua_getfenv (lua_State *L, int index); < Pushes onto the stack the environment table of the value at the given index. lua_getfield *lua_getfield()* -> +>c void lua_getfield (lua_State *L, int index, const char *k); < Pushes onto the stack the value `t[k]`, where `t` is the value at the @@ -1983,17 +1916,17 @@ lua_getfield *lua_getfield()* metamethod for the "index" event (see |luaref-langMetatables|). lua_getglobal *lua_getglobal()* -> +>c void lua_getglobal (lua_State *L, const char *name); < Pushes onto the stack the value of the global `name`. It is defined as a macro: -> +>c #define lua_getglobal(L,s) lua_getfield(L, LUA_GLOBALSINDEX, s) < lua_getmetatable *lua_getmetatable()* -> +>c int lua_getmetatable (lua_State *L, int index); < Pushes onto the stack the metatable of the value at the given @@ -2002,7 +1935,7 @@ lua_getmetatable *lua_getmetatable()* stack. lua_gettable *lua_gettable()* -> +>c void lua_gettable (lua_State *L, int index); < Pushes onto the stack the value `t[k]`, where `t` is the value at the @@ -2014,7 +1947,7 @@ lua_gettable *lua_gettable()* the "index" event (see |luaref-langMetatables|). lua_gettop *lua_gettop()* -> +>c int lua_gettop (lua_State *L); < Returns the index of the top element in the stack. Because indices @@ -2023,7 +1956,7 @@ lua_gettop *lua_gettop()* 0 means an empty stack). lua_insert *lua_insert()* -> +>c void lua_insert (lua_State *L, int index); < Moves the top element into the given valid index, shifting up the @@ -2031,7 +1964,7 @@ lua_insert *lua_insert()* pseudo-index, because a pseudo-index is not an actual stack position. lua_Integer *lua_Integer()* -> +>c typedef ptrdiff_t lua_Integer; < The type used by the Lua API to represent integral values. @@ -2040,77 +1973,77 @@ lua_Integer *lua_Integer()* type the machine handles "comfortably". lua_isboolean *lua_isboolean()* -> +>c int lua_isboolean (lua_State *L, int index); < Returns 1 if the value at the given acceptable index has type boolean, and 0 otherwise. lua_iscfunction *lua_iscfunction()* -> +>c int lua_iscfunction (lua_State *L, int index); < Returns 1 if the value at the given acceptable index is a C function, and 0 otherwise. lua_isfunction *lua_isfunction()* -> +>c int lua_isfunction (lua_State *L, int index); < Returns 1 if the value at the given acceptable index is a function (either C or Lua), and 0 otherwise. lua_islightuserdata *lua_islightuserdata()* -> +>c int lua_islightuserdata (lua_State *L, int index); < Returns 1 if the value at the given acceptable index is a light userdata, and 0 otherwise. lua_isnil *lua_isnil()* -> +>c int lua_isnil (lua_State *L, int index); < Returns 1 if the value at the given acceptable index is `nil`, and 0 otherwise. lua_isnumber *lua_isnumber()* -> +>c int lua_isnumber (lua_State *L, int index); < Returns 1 if the value at the given acceptable index is a number or a string convertible to a number, and 0 otherwise. lua_isstring *lua_isstring()* -> +>c int lua_isstring (lua_State *L, int index); < Returns 1 if the value at the given acceptable index is a string or a number (which is always convertible to a string), and 0 otherwise. lua_istable *lua_istable()* -> +>c int lua_istable (lua_State *L, int index); < Returns 1 if the value at the given acceptable index is a table, and 0 otherwise. lua_isthread *lua_isthread()* -> +>c int lua_isthread (lua_State *L, int index); < Returns 1 if the value at the given acceptable index is a thread, and 0 otherwise. lua_isuserdata *lua_isuserdata()* -> +>c int lua_isuserdata (lua_State *L, int index); < Returns 1 if the value at the given acceptable index is a userdata (either full or light), and 0 otherwise. lua_lessthan *lua_lessthan()* -> +>c int lua_lessthan (lua_State *L, int index1, int index2); < Returns 1 if the value at acceptable index `index1` is smaller than @@ -2119,7 +2052,7 @@ lua_lessthan *lua_lessthan()* Also returns 0 if any of the indices is non valid. lua_load *lua_load()* -> +>c int lua_load (lua_State *L, lua_Reader reader, void *data, @@ -2136,17 +2069,17 @@ lua_load *lua_load()* This function only loads a chunk; it does not run it. `lua_load` automatically detects whether the chunk is text or binary, - and loads it accordingly (see program `luac`, |luaref-luac|). + and loads it accordingly (see program `luac`). The `lua_load` function uses a user-supplied `reader` function to read - the chunk (see |luaref-lua_Reader|). The `data` argument is an opaque + the chunk (see |lua_Reader()|). The `data` argument is an opaque value passed to the reader function. The `chunkname` argument gives a name to the chunk, which is used for error messages and in debug information (see |luaref-apiDebug|). lua_newstate *lua_newstate()* -> +>c lua_State *lua_newstate (lua_Alloc f, void *ud); < Creates a new, independent state. Returns `NULL` if cannot create the @@ -2156,19 +2089,19 @@ lua_newstate *lua_newstate()* simply passes to the allocator in every call. lua_newtable *lua_newtable()* -> +>c void lua_newtable (lua_State *L); < Creates a new empty table and pushes it onto the stack. It is equivalent to `lua_createtable(L, 0, 0)` (see - |luaref-lua_createtable|). + |lua_createtable()|). lua_newthread *lua_newthread()* -> +>c lua_State *lua_newthread (lua_State *L); < Creates a new thread, pushes it on the stack, and returns a pointer to - a `lua_State` (see |luaref-lua_State|) that represents this new + a `lua_State` (see |lua_State()|) that represents this new thread. The new state returned by this function shares with the original state all global objects (such as tables), but has an independent execution stack. @@ -2177,7 +2110,7 @@ lua_newthread *lua_newthread()* are subject to garbage collection, like any Lua object. lua_newuserdata *lua_newuserdata()* -> +>c void *lua_newuserdata (lua_State *L, size_t size); < This function allocates a new block of memory with the given size, @@ -2195,7 +2128,7 @@ lua_newuserdata *lua_newuserdata()* is collected again then Lua frees its corresponding memory. lua_next *lua_next()* -> +>c int lua_next (lua_State *L, int index); < Pops a key from the stack, and pushes a key-value pair from the table @@ -2205,7 +2138,7 @@ lua_next *lua_next()* *luaref-tabletraversal* A typical traversal looks like this: -> +>c /* table is in the stack at index 't' */ lua_pushnil(L); /* first key */ while (lua_next(L, t) != 0) { @@ -2218,12 +2151,12 @@ lua_next *lua_next()* } < While traversing a table, do not call `lua_tolstring` (see - |luaref-lua_tolstring|) directly on a key, unless you know that the + |lua_tolstring()|) directly on a key, unless you know that the key is actually a string. Recall that `lua_tolstring` `changes` the value at the given index; this confuses the next call to `lua_next`. lua_Number *lua_Number()* -> +>c typedef double lua_Number; < The type of numbers in Lua. By default, it is double, but that can be @@ -2233,7 +2166,7 @@ lua_Number *lua_Number()* another type for numbers (e.g., float or long). lua_objlen *lua_objlen()* -> +>c size_t lua_objlen (lua_State *L, int index); < Returns the "length" of the value at the given acceptable index: for @@ -2242,13 +2175,13 @@ lua_objlen *lua_objlen()* block of memory allocated for the userdata; for other values, it is 0. lua_pcall *lua_pcall()* -> +>c lua_pcall (lua_State *L, int nargs, int nresults, int errfunc); < Calls a function in protected mode. Both `nargs` and `nresults` have the same meaning as in `lua_call` - (see |luaref-lua_call|). If there are no errors during the call, + (see |lua_call()|). If there are no errors during the call, `lua_pcall` behaves exactly like `lua_call`. However, if there is any error, `lua_pcall` catches it, pushes a single value on the stack (the error message), and returns an error code. Like `lua_call`, @@ -2277,19 +2210,19 @@ lua_pcall *lua_pcall()* - `LUA_ERRERR` error while running the error handler function. lua_pop *lua_pop()* -> +>c void lua_pop (lua_State *L, int n); < Pops `n` elements from the stack. lua_pushboolean *lua_pushboolean()* -> +>c void lua_pushboolean (lua_State *L, int b); < Pushes a boolean value with value `b` onto the stack. lua_pushcclosure *lua_pushcclosure()* -> +>c void lua_pushcclosure (lua_State *L, lua_CFunction fn, int n); < Pushes a new C closure onto the stack. @@ -2305,7 +2238,7 @@ lua_pushcclosure *lua_pushcclosure()* pops these values from the stack. lua_pushcfunction *lua_pushcfunction()* -> +>c void lua_pushcfunction (lua_State *L, lua_CFunction f); < Pushes a C function onto the stack. This function receives a pointer @@ -2314,15 +2247,15 @@ lua_pushcfunction *lua_pushcfunction()* Any function to be registered in Lua must follow the correct protocol to receive its parameters and return its results (see - |luaref-lua_CFunction|). + |lua_CFunction()|). `lua_pushcfunction` is defined as a macro: -> +>c #define lua_pushcfunction(L,f) lua_pushcclosure(L,f,0) < lua_pushfstring *lua_pushfstring()* -> +>c const char *lua_pushfstring (lua_State *L, const char *fmt, ...); < Pushes onto the stack a formatted string and returns a pointer to this @@ -2341,13 +2274,13 @@ lua_pushfstring *lua_pushfstring()* character). lua_pushinteger *lua_pushinteger()* -> +>c void lua_pushinteger (lua_State *L, lua_Integer n); < Pushes a number with value `n` onto the stack. lua_pushlightuserdata *lua_pushlightuserdata()* -> +>c void lua_pushlightuserdata (lua_State *L, void *p); < Pushes a light userdata onto the stack. @@ -2359,7 +2292,7 @@ lua_pushlightuserdata *lua_pushlightuserdata()* same C address. lua_pushlstring *lua_pushlstring()* -> +>c void lua_pushlstring (lua_State *L, const char *s, size_t len); < Pushes the string pointed to by `s` with size `len` onto the stack. @@ -2368,19 +2301,19 @@ lua_pushlstring *lua_pushlstring()* returns. The string can contain embedded zeros. lua_pushnil *lua_pushnil()* -> +>c void lua_pushnil (lua_State *L); < Pushes a nil value onto the stack. lua_pushnumber *lua_pushnumber()* -> +>c void lua_pushnumber (lua_State *L, lua_Number n); < Pushes a number with value `n` onto the stack. lua_pushstring *lua_pushstring()* -> +>c void lua_pushstring (lua_State *L, const char *s); < Pushes the zero-terminated string pointed to by `s` onto the stack. @@ -2390,30 +2323,30 @@ lua_pushstring *lua_pushstring()* end at the first zero. lua_pushthread *lua_pushthread()* -> +>c int lua_pushthread (lua_State *L); < Pushes the thread represented by `L` onto the stack. Returns 1 if this thread is the main thread of its state. lua_pushvalue *lua_pushvalue()* -> +>c void lua_pushvalue (lua_State *L, int index); < Pushes a copy of the element at the given valid index onto the stack. lua_pushvfstring *lua_pushvfstring()* -> +>c const char *lua_pushvfstring (lua_State *L, const char *fmt, va_list argp); < - Equivalent to `lua_pushfstring` (see |luaref-pushfstring|), except + Equivalent to `lua_pushfstring` (see |lua_pushfstring()|), except that it receives a `va_list` instead of a variable number of arguments. lua_rawequal *lua_rawequal()* -> +>c int lua_rawequal (lua_State *L, int index1, int index2); < Returns 1 if the two values in acceptable indices `index1` and @@ -2422,14 +2355,14 @@ lua_rawequal *lua_rawequal()* valid. lua_rawget *lua_rawget()* -> +>c void lua_rawget (lua_State *L, int index); < - Similar to `lua_gettable` (see |luaref-lua_gettable|), but does a raw + Similar to `lua_gettable` (see |lua_gettable()|), but does a raw access (i.e., without metamethods). lua_rawgeti *lua_rawgeti()* -> +>c void lua_rawgeti (lua_State *L, int index, int n); < Pushes onto the stack the value `t[n]`, where `t` is the value at the @@ -2437,14 +2370,14 @@ lua_rawgeti *lua_rawgeti()* invoke metamethods. lua_rawset *lua_rawset()* -> +>c void lua_rawset (lua_State *L, int index); < - Similar to `lua_settable` (see |luaref-lua_settable|), but does a raw + Similar to `lua_settable` (see |lua_settable()|), but does a raw assignment (i.e., without metamethods). lua_rawseti *lua_rawseti()* -> +>c void lua_rawseti (lua_State *L, int index, int n); < Does the equivalent of `t[n] = v`, where `t` is the value at the given @@ -2454,12 +2387,12 @@ lua_rawseti *lua_rawseti()* that is, it does not invoke metamethods. lua_Reader *lua_Reader()* -> +>c typedef const char * (*lua_Reader) (lua_State *L, void *data, size_t *size); < - The reader function used by `lua_load` (see |luaref-lua_load|). Every + The reader function used by `lua_load` (see |lua_load()|). Every time it needs another piece of the chunk, `lua_load` calls the reader, passing along its `data` parameter. The reader must return a pointer to a block of memory with a new piece of the chunk and set `size` to @@ -2469,20 +2402,20 @@ lua_Reader *lua_Reader()* zero. lua_register *lua_register()* -> +>c void lua_register (lua_State *L, const char *name, lua_CFunction f); < Sets the C function `f` as the new value of global `name`. It is defined as a macro: -> +>c #define lua_register(L,n,f) \ (lua_pushcfunction(L, f), lua_setglobal(L, n)) < lua_remove *lua_remove()* -> +>c void lua_remove (lua_State *L, int index); < Removes the element at the given valid index, shifting down the @@ -2490,7 +2423,7 @@ lua_remove *lua_remove()* pseudo-index, because a pseudo-index is not an actual stack position. lua_replace *lua_replace()* -> +>c void lua_replace (lua_State *L, int index); < Moves the top element into the given position (and pops it), without @@ -2498,35 +2431,35 @@ lua_replace *lua_replace()* position). lua_resume *lua_resume()* -> +>c int lua_resume (lua_State *L, int narg); < Starts and resumes a coroutine in a given thread. To start a coroutine, you first create a new thread (see - |luaref-lua_newthread|); then you push onto its stack the main + |lua_newthread()|); then you push onto its stack the main function plus any arguments; then you call `lua_resume` (see - |luaref-lua_resume|) with `narg` being the number of arguments. This + |lua_resume()|) with `narg` being the number of arguments. This call returns when the coroutine suspends or finishes its execution. When it returns, the stack contains all values passed to `lua_yield` - (see |luaref-lua_yield|), or all values returned by the body function. + (see |lua_yield()|), or all values returned by the body function. `lua_resume` returns `LUA_YIELD` if the coroutine yields, 0 if the coroutine finishes its execution without errors, or an error code in - case of errors (see |luaref-lua_pcall|). In case of errors, the stack + case of errors (see |lua_pcall()|). In case of errors, the stack is not unwound, so you can use the debug API over it. The error message is on the top of the stack. To restart a coroutine, you put on its stack only the values to be passed as results from `lua_yield`, and then call `lua_resume`. lua_setallocf *lua_setallocf()* -> +>c void lua_setallocf (lua_State *L, lua_Alloc f, void *ud); < Changes the allocator function of a given state to `f` with user data `ud`. lua_setfenv *lua_setfenv()* -> +>c int lua_setfenv (lua_State *L, int index); < Pops a table from the stack and sets it as the new environment for the @@ -2535,7 +2468,7 @@ lua_setfenv *lua_setfenv()* Otherwise it returns 1. lua_setfield *lua_setfield()* -> +>c void lua_setfield (lua_State *L, int index, const char *k); < Does the equivalent to `t[k] = v`, where `t` is the value at the given @@ -2546,24 +2479,24 @@ lua_setfield *lua_setfield()* |luaref-langMetatables|). lua_setglobal *lua_setglobal()* -> +>c void lua_setglobal (lua_State *L, const char *name); < Pops a value from the stack and sets it as the new value of global `name`. It is defined as a macro: -> +>c #define lua_setglobal(L,s) lua_setfield(L, LUA_GLOBALSINDEX, s) < lua_setmetatable *lua_setmetatable()* -> +>c int lua_setmetatable (lua_State *L, int index); < Pops a table from the stack and sets it as the new metatable for the value at the given acceptable index. lua_settable *lua_settable()* -> +>c void lua_settable (lua_State *L, int index); < Does the equivalent to `t[k] = v`, where `t` is the value at the given @@ -2575,7 +2508,7 @@ lua_settable *lua_settable()* (see |luaref-langMetatables|). lua_settop *lua_settop()* -> +>c void lua_settop (lua_State *L, int index); < Accepts any acceptable index, or 0, and sets the stack top to this @@ -2584,7 +2517,7 @@ lua_settop *lua_settop()* elements are removed. lua_State *lua_State()* -> +>c typedef struct lua_State lua_State; < Opaque structure that keeps the whole state of a Lua interpreter. The @@ -2593,10 +2526,10 @@ lua_State *lua_State()* A pointer to this state must be passed as the first argument to every function in the library, except to `lua_newstate` (see - |luaref-lua_newstate|), which creates a Lua state from scratch. + |lua_newstate()|), which creates a Lua state from scratch. lua_status *lua_status()* -> +>c int lua_status (lua_State *L); < Returns the status of the thread `L`. @@ -2606,7 +2539,7 @@ lua_status *lua_status()* suspended. lua_toboolean *lua_toboolean()* -> +>c int lua_toboolean (lua_State *L, int index); < Converts the Lua value at the given acceptable index to a C boolean @@ -2614,21 +2547,21 @@ lua_toboolean *lua_toboolean()* any Lua value different from `false` and `nil`; otherwise it returns 0. It also returns 0 when called with a non-valid index. (If you want to accept only actual boolean values, use `lua_isboolean` - |luaref-lua_isboolean| to test the value's type.) + |lua_isboolean()| to test the value's type.) lua_tocfunction *lua_tocfunction()* -> +>c lua_CFunction lua_tocfunction (lua_State *L, int index); < Converts a value at the given acceptable index to a C function. That value must be a C function; otherwise it returns `NULL`. lua_tointeger *lua_tointeger()* -> +>c lua_Integer lua_tointeger (lua_State *L, int idx); < Converts the Lua value at the given acceptable index to the signed - integral type `lua_Integer` (see |luaref-lua_Integer|). The Lua value + integral type `lua_Integer` (see |lua_Integer()|). The Lua value must be a number or a string convertible to a number (see |luaref-langCoercion|); otherwise, `lua_tointeger` returns 0. @@ -2636,7 +2569,7 @@ lua_tointeger *lua_tointeger()* way. lua_tolstring *lua_tolstring()* -> +>c const char *lua_tolstring (lua_State *L, int index, size_t *len); < Converts the Lua value at the given acceptable index to a C string. If @@ -2644,7 +2577,7 @@ lua_tolstring *lua_tolstring()* Lua value must be a string or a number; otherwise, the function returns `NULL`. If the value is a number, then `lua_tolstring` also `changes the actual value in the stack to a` `string`. (This change - confuses `lua_next` |luaref-lua_next| when `lua_tolstring` is applied + confuses `lua_next` |lua_next()| when `lua_tolstring` is applied to keys during a table traversal.) `lua_tolstring` returns a fully aligned pointer to a string inside the @@ -2655,16 +2588,16 @@ lua_tolstring *lua_tolstring()* value is removed from the stack. lua_tonumber *lua_tonumber()* -> +>c lua_Number lua_tonumber (lua_State *L, int index); < Converts the Lua value at the given acceptable index to the C type - `lua_Number` (see |luaref-lua_Number|). The Lua value must be a number + `lua_Number` (see |lua_Number()|). The Lua value must be a number or a string convertible to a number (see |luaref-langCoercion|); otherwise, `lua_tonumber` returns 0. lua_topointer *lua_topointer()* -> +>c const void *lua_topointer (lua_State *L, int index); < Converts the value at the given acceptable index to a generic C @@ -2676,22 +2609,22 @@ lua_topointer *lua_topointer()* Typically this function is used only for debug information. lua_tostring *lua_tostring()* -> +>c const char *lua_tostring (lua_State *L, int index); < - Equivalent to `lua_tolstring` (see |luaref-lua_tolstring|) with `len` + Equivalent to `lua_tolstring` (see |lua_tolstring()|) with `len` equal to `NULL`. lua_tothread *lua_tothread()* -> +>c lua_State *lua_tothread (lua_State *L, int index); < Converts the value at the given acceptable index to a Lua thread - (represented as `lua_State*` |luaref-lua_State|). This value must be a + (represented as `lua_State*` |lua_State()|). This value must be a thread; otherwise, the function returns `NULL`. lua_touserdata *lua_touserdata()* -> +>c void *lua_touserdata (lua_State *L, int index); < If the value at the given acceptable index is a full userdata, returns @@ -2699,7 +2632,7 @@ lua_touserdata *lua_touserdata()* pointer. Otherwise, it returns `NULL`. lua_type *lua_type()* -> +>c int lua_type (lua_State *L, int index); < Returns the type of the value in the given acceptable index, or @@ -2710,20 +2643,20 @@ lua_type *lua_type()* `LUA_TUSERDATA`, `LUA_TTHREAD`, and `LUA_TLIGHTUSERDATA`. lua_typename *lua_typename()* -> +>c const char *lua_typename (lua_State *L, int tp); < Returns the name of the type encoded by the value `tp`, which must be one the values returned by `lua_type`. lua_Writer *lua_Writer()* -> +>c typedef int (*lua_Writer) (lua_State *L, const void* p, size_t sz, void* ud); < - The writer function used by `lua_dump` (see |luaref-lua_dump|). Every + The writer function used by `lua_dump` (see |lua_dump()|). Every time it produces another piece of chunk, `lua_dump` calls the writer, passing along the buffer to be written (`p`), its size (`sz`), and the `data` parameter supplied to `lua_dump`. @@ -2732,7 +2665,7 @@ lua_Writer *lua_Writer()* means an error and stops `lua_dump` from calling the writer again. lua_xmove *lua_xmove()* -> +>c void lua_xmove (lua_State *from, lua_State *to, int n); < Exchange values between different threads of the `same` global state. @@ -2741,19 +2674,19 @@ lua_xmove *lua_xmove()* onto the stack `to`. lua_yield *lua_yield()* -> +>c int lua_yield (lua_State *L, int nresults); < Yields a coroutine. This function should only be called as the return expression of a C function, as follows: -> +>c return lua_yield (L, nresults); < When a C function calls `lua_yield` in that way, the running coroutine suspends its execution, and the call to `lua_resume` (see - |luaref-lua_resume|) that started this coroutine returns. The + |lua_resume()|) that started this coroutine returns. The parameter `nresults` is the number of values from the stack that are passed as results to `lua_resume`. @@ -2782,50 +2715,52 @@ need "inside information" from the interpreter. lua_Debug *lua_Debug()* - `typedef struct lua_Debug {` - `int event;` - `const char *name; /* (n) */` - `const char *namewhat; /* (n) */` - `const char *what; /* (S) */` - `const char *source; /* (S) */` - `int currentline; /* (l) */` - `int nups; /* (u) number of upvalues */` - `int linedefined; /* (S) */` - `int lastlinedefined; /* (S) */` - `char short_src[LUA_IDSIZE]; /* (S) */` - `/* private part */` - `other fields` - `} lua_Debug;` +>c + typedef struct lua_Debug { + int event; + const char *name; /* (n) */ + const char *namewhat; /* (n) */ + const char *what; /* (S) */ + const char *source; /* (S) */ + int currentline; /* (l) */ + int nups; /* (u) number of upvalues */ + int linedefined; /* (S) */ + int lastlinedefined; /* (S) */ + char short_src[LUA_IDSIZE]; /* (S) */ + /* private part */ + other fields + } lua_Debug; +< A structure used to carry different pieces of information about an active -function. `lua_getstack` (see |luaref-lua_getstack|) fills only the private part +function. `lua_getstack` (see |lua_getstack()|) fills only the private part of this structure, for later use. To fill the other fields of `lua_Debug` with -useful information, call `lua_getinfo` (see |luaref-lua_getinfo|). +useful information, call `lua_getinfo` (see |lua_getinfo()|). The fields of `lua_Debug` have the following meaning: - `source` If the function was defined in a string, then `source` is +- `source` If the function was defined in a string, then `source` is that string. If the function was defined in a file, then `source` starts with a `@` followed by the file name. - `short_src` a "printable" version of `source`, to be used in error messages. - `linedefined` the line number where the definition of the function starts. - `lastlinedefined` the line number where the definition of the function ends. - `what` the string `"Lua"` if the function is a Lua function, +- `short_src` a "printable" version of `source`, to be used in error messages. +- `linedefined` the line number where the definition of the function starts. +- `lastlinedefined` the line number where the definition of the function ends. +- `what` the string `"Lua"` if the function is a Lua function, `"C"` if it is a C function, `"main"` if it is the main part of a chunk, and `"tail"` if it was a function that did a tail call. In the latter case, Lua has no other information about the function. - `currentline` the current line where the given function is executing. +- `currentline` the current line where the given function is executing. When no line information is available, `currentline` is set to -1. - `name` a reasonable name for the given function. Because +- `name` a reasonable name for the given function. Because functions in Lua are first-class values, they do not have a fixed name: some functions may be the value of multiple global variables, while others may be stored only in a table field. The `lua_getinfo` function checks how the function was called to find a suitable name. If it cannot find a name, then `name` is set to `NULL`. - `namewhat` explains the `name` field. The value of `namewhat` can be +- `namewhat` explains the `name` field. The value of `namewhat` can be `"global"`, `"local"`, `"method"`, `"field"`, `"upvalue"`, or `""` (the empty string), according to how the function was called. (Lua uses the empty string when @@ -2833,40 +2768,40 @@ The fields of `lua_Debug` have the following meaning: upvalues of the function. lua_gethook *lua_gethook()* -> +>c lua_Hook lua_gethook (lua_State *L); < Returns the current hook function. lua_gethookcount *lua_gethookcount()* -> +>c int lua_gethookcount (lua_State *L); < Returns the current hook count. lua_gethookmask *lua_gethookmask()* -> +>c int lua_gethookmask (lua_State *L); < Returns the current hook mask. lua_getinfo *lua_getinfo()* -> +>c int lua_getinfo (lua_State *L, const char *what, lua_Debug *ar); < Returns information about a specific function or function invocation. To get information about a function invocation, the parameter `ar` must be a valid activation record that was filled by a previous call - to `lua_getstack` (see |luaref-lua_getstack|) or given as argument to - a hook (see |luaref-lua_Hook|). + to `lua_getstack` (see |lua_getstack()|) or given as argument to + a hook (see |lua_Hook()|). To get information about a function you push it onto the stack and start the `what` string with the character `>`. (In that case, `lua_getinfo` pops the function in the top of the stack.) For instance, to know in which line a function `f` was defined, you can write the following code: -> +>c lua_Debug ar; lua_getfield(L, LUA_GLOBALSINDEX, "f"); /* get global 'f' */ lua_getinfo(L, ">S", &ar); @@ -2891,13 +2826,13 @@ lua_getinfo *lua_getinfo()* `what`). lua_getlocal *lua_getlocal()* -> +>c const char *lua_getlocal (lua_State *L, lua_Debug *ar, int n); < Gets information about a local variable of a given activation record. The parameter `ar` must be a valid activation record that was filled - by a previous call to `lua_getstack` (see |luaref-lua_getstack|) or - given as argument to a hook (see |luaref-lua_Hook|). The index `n` + by a previous call to `lua_getstack` (see |lua_getstack()|) or + given as argument to a hook (see |lua_Hook()|). The index `n` selects which local variable to inspect (1 is the first parameter or active local variable, and so on, until the last active local variable). `lua_getlocal` pushes the variable's value onto the stack @@ -2911,12 +2846,12 @@ lua_getlocal *lua_getlocal()* number of active local variables. lua_getstack *lua_getstack()* -> +>c int lua_getstack (lua_State *L, int level, lua_Debug *ar); < Gets information about the interpreter runtime stack. - This function fills parts of a `lua_Debug` (see |luaref-lua_Debug|) + This function fills parts of a `lua_Debug` (see |lua_Debug()|) structure with an identification of the `activation record` of the function executing at a given level. Level 0 is the current running function, whereas level `n+1` is the function that has called level @@ -2924,7 +2859,7 @@ lua_getstack *lua_getstack()* with a level greater than the stack depth, it returns 0. lua_getupvalue *lua_getupvalue()* -> +>c const char *lua_getupvalue (lua_State *L, int funcindex, int n); < Gets information about a closure's upvalue. (For Lua functions, @@ -2940,7 +2875,7 @@ lua_getupvalue *lua_getupvalue()* string `""` as a name for all upvalues. lua_Hook *lua_Hook()* -> +>c typedef void (*lua_Hook) (lua_State *L, lua_Debug *ar); < Type for debugging hook functions. @@ -2951,7 +2886,7 @@ lua_Hook *lua_Hook()* `LUA_HOOKTAILRET`, `LUA_HOOKLINE`, and `LUA_HOOKCOUNT`. 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` (see - |luaref-lua_getinfo|). For return events, `event` may be + |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`. @@ -2962,7 +2897,7 @@ lua_Hook *lua_Hook()* lua_sethook *lua_sethook()* -> +>c int lua_sethook (lua_State *L, lua_Hook f, int mask, int count); < Sets the debugging hook function. @@ -2991,12 +2926,12 @@ lua_sethook *lua_sethook()* A hook is disabled by setting `mask` to zero. lua_setlocal *lua_setlocal()* -> +>c const char *lua_setlocal (lua_State *L, lua_Debug *ar, int n); < Sets the value of a local variable of a given activation record. Parameters `ar` and `n` are as in `lua_getlocal` (see - |luaref-lua_getlocal|). `lua_setlocal` assigns the value at the top of + |lua_getlocal()|). `lua_setlocal` assigns the value at the top of the stack to the variable and returns its name. It also pops the value from the stack. @@ -3004,13 +2939,13 @@ lua_setlocal *lua_setlocal()* number of active local variables. lua_setupvalue *lua_setupvalue()* -> +>c const char *lua_setupvalue (lua_State *L, int funcindex, int n); < Sets the value of a closure's upvalue. It assigns the value at the top of the stack to the upvalue and returns its name. It also pops the value from the stack. Parameters `funcindex` and `n` are as in the - `lua_getupvalue` (see |luaref-lua_getupvalue|). + `lua_getupvalue` (see |lua_getupvalue()|). Returns `NULL` (and pops nothing) when the index is greater than the number of upvalues. @@ -3018,7 +2953,7 @@ lua_setupvalue *lua_setupvalue()* *luaref-debugexample* As an example, the following function lists the names of all local variables and upvalues for a function at a given level of the stack: -> +>c int listvars (lua_State *L, int level) { lua_Debug ar; int i; @@ -3042,7 +2977,6 @@ lua_setupvalue *lua_setupvalue()* ============================================================================== 4 THE AUXILIARY LIBRARY *luaref-aux* -============================================================================== The auxiliary library provides several convenient functions to interface C with Lua. While the basic API provides the primitive functions for all @@ -3068,46 +3002,46 @@ Here we list all functions and types from the auxiliary library in alphabetical order. luaL_addchar *luaL_addchar()* -> +>c void luaL_addchar (luaL_Buffer *B, char c); < - Adds the character `c` to the buffer `B` (see |luaref-luaL_Buffer|). + Adds the character `c` to the buffer `B` (see |luaL_Buffer()|). luaL_addlstring *luaL_addlstring()* -> +>c void luaL_addlstring (luaL_Buffer *B, const char *s, size_t l); < Adds the string pointed to by `s` with length `l` to the buffer `B` - (see |luaref-luaL_Buffer|). The string may contain embedded zeros. + (see |luaL_Buffer()|). The string may contain embedded zeros. luaL_addsize *luaL_addsize()* -> +>c void luaL_addsize (luaL_Buffer *B, size_t n); < - Adds to the buffer `B` (see |luaref-luaL_Buffer|) a string of length + Adds to the buffer `B` (see |luaL_Buffer()|) a string of length `n` previously copied to the buffer area (see - |luaref-luaL_prepbuffer|). + |luaL_prepbuffer()|). luaL_addstring *luaL_addstring()* -> +>c void luaL_addstring (luaL_Buffer *B, const char *s); < Adds the zero-terminated string pointed to by `s` to the buffer `B` - (see |luaref-luaL_Buffer|). The string may not contain embedded zeros. + (see |luaL_Buffer()|). The string may not contain embedded zeros. luaL_addvalue *luaL_addvalue()* -> +>c void luaL_addvalue (luaL_Buffer *B); < Adds the value at the top of the stack to the buffer `B` (see - |luaref-luaL_Buffer|). Pops the value. + |luaL_Buffer()|). Pops the value. This is the only function on string buffers that can (and must) be called with an extra element on the stack, which is the value to be added to the buffer. luaL_argcheck *luaL_argcheck()* -> +>c void luaL_argcheck (lua_State *L, int cond, int narg, @@ -3120,7 +3054,7 @@ luaL_argcheck *luaL_argcheck()* < luaL_argerror *luaL_argerror()* -> +>c int luaL_argerror (lua_State *L, int narg, const char *extramsg); < Raises an error with the following message, where `func` is retrieved @@ -3132,7 +3066,7 @@ luaL_argerror *luaL_argerror()* functions as `return luaL_argerror(` `args` `)`. luaL_Buffer *luaL_Buffer()* -> +>c typedef struct luaL_Buffer luaL_Buffer; < Type for a `string buffer`. @@ -3142,11 +3076,11 @@ luaL_Buffer *luaL_Buffer()* - First you declare a variable `b` of type `luaL_Buffer`. - Then you initialize it with a call `luaL_buffinit(L, &b)` (see - |luaref-luaL_buffinit|). + |luaL_buffinit()|). - Then you add string pieces to the buffer calling any of the `luaL_add*` functions. - You finish by calling `luaL_pushresult(&b)` (see - |luaref-luaL_pushresult|). This call leaves the final string on the + |luaL_pushresult()|). This call leaves the final string on the top of the stack. During its normal operation, a string buffer uses a variable number of @@ -3156,19 +3090,19 @@ luaL_Buffer *luaL_Buffer()* that is, when you call a buffer operation, the stack is at the same level it was immediately after the previous buffer operation. (The only exception to this rule is `luaL_addvalue` - |luaref-luaL_addvalue|.) After calling `luaL_pushresult` the stack is + |luaL_addvalue()|.) After calling `luaL_pushresult` the stack is back to its level when the buffer was initialized, plus the final string on its top. luaL_buffinit *luaL_buffinit()* -> +>c void luaL_buffinit (lua_State *L, luaL_Buffer *B); < Initializes a buffer `B`. This function does not allocate any space; - the buffer must be declared as a variable (see |luaref-luaL_Buffer|). + the buffer must be declared as a variable (see |luaL_Buffer()|). luaL_callmeta *luaL_callmeta()* -> +>c int luaL_callmeta (lua_State *L, int obj, const char *e); < Calls a metamethod. @@ -3181,49 +3115,49 @@ luaL_callmeta *luaL_callmeta()* 0 (without pushing any value on the stack). luaL_checkany *luaL_checkany()* -> +>c void luaL_checkany (lua_State *L, int narg); < Checks whether the function has an argument of any type (including `nil`) at position `narg`. luaL_checkint *luaL_checkint()* -> +>c int luaL_checkint (lua_State *L, int narg); < Checks whether the function argument `narg` is a number and returns this number cast to an `int`. luaL_checkinteger *luaL_checkinteger()* -> +>c lua_Integer luaL_checkinteger (lua_State *L, int narg); < Checks whether the function argument `narg` is a number and returns - this number cast to a `lua_Integer` (see |luaref-lua_Integer|). + this number cast to a `lua_Integer` (see |lua_Integer()|). luaL_checklong *luaL_checklong()* -> +>c long luaL_checklong (lua_State *L, int narg); < Checks whether the function argument `narg` is a number and returns this number cast to a `long`. luaL_checklstring *luaL_checklstring()* -> +>c const char *luaL_checklstring (lua_State *L, int narg, size_t *l); < Checks whether the function argument `narg` is a string and returns this string; if `l` is not `NULL` fills `*l` with the string's length. luaL_checknumber *luaL_checknumber()* -> +>c lua_Number luaL_checknumber (lua_State *L, int narg); < Checks whether the function argument `narg` is a number and returns - this number (see |luaref-lua_Number|). + this number (see |lua_Number()|). luaL_checkoption *luaL_checkoption()* -> +>c int luaL_checkoption (lua_State *L, int narg, const char *def, @@ -3243,7 +3177,7 @@ luaL_checkoption *luaL_checkoption()* select options.) luaL_checkstack *luaL_checkstack()* -> +>c void luaL_checkstack (lua_State *L, int sz, const char *msg); < Grows the stack size to `top + sz` elements, raising an error if the @@ -3251,53 +3185,53 @@ luaL_checkstack *luaL_checkstack()* the error message. luaL_checkstring *luaL_checkstring()* -> +>c const char *luaL_checkstring (lua_State *L, int narg); < Checks whether the function argument `narg` is a string and returns this string. luaL_checktype *luaL_checktype()* -> +>c void luaL_checktype (lua_State *L, int narg, int t); < Checks whether the function argument `narg` has type `t` (see - |luaref-lua_type|). + |lua_type()|). luaL_checkudata *luaL_checkudata()* -> +>c void *luaL_checkudata (lua_State *L, int narg, const char *tname); < Checks whether the function argument `narg` is a userdata of the type - `tname` (see |luaref-luaL_newmetatable|). + `tname` (see |luaL_newmetatable()|). luaL_dofile *luaL_dofile()* -> +>c int luaL_dofile (lua_State *L, const char *filename); < Loads and runs the given file. It is defined as the following macro: -> +>c (luaL_loadfile(L, filename) || lua_pcall(L, 0, LUA_MULTRET, 0)) < It returns 0 if there are no errors or 1 in case of errors. luaL_dostring *luaL_dostring()* -> +>c int luaL_dostring (lua_State *L, const char *str); < Loads and runs the given string. It is defined as the following macro: -> +>c (luaL_loadstring(L, str) || lua_pcall(L, 0, LUA_MULTRET, 0)) < It returns 0 if there are no errors or 1 in case of errors. luaL_error *luaL_error()* -> +>c int luaL_error (lua_State *L, const char *fmt, ...); < Raises an error. The error message format is given by `fmt` plus any extra arguments, following the same rules of `lua_pushfstring` (see - |luaref-lua_pushfstring|). It also adds at the beginning of the + |lua_pushfstring()|). It also adds at the beginning of the message the file name and the line number where the error occurred, if this information is available. @@ -3305,7 +3239,7 @@ luaL_error *luaL_error()* functions as `return luaL_error(` `args` `)`. luaL_getmetafield *luaL_getmetafield()* -> +>c int luaL_getmetafield (lua_State *L, int obj, const char *e); < Pushes onto the stack the field `e` from the metatable of the object @@ -3313,14 +3247,14 @@ luaL_getmetafield *luaL_getmetafield()* metatable does not have this field, returns 0 and pushes nothing. luaL_getmetatable *luaL_getmetatable()* -> +>c void luaL_getmetatable (lua_State *L, const char *tname); < Pushes onto the stack the metatable associated with name `tname` in - the registry (see |luaref-luaL_newmetatable|). + the registry (see |luaL_newmetatable()|). luaL_gsub *luaL_gsub()* -> +>c const char *luaL_gsub (lua_State *L, const char *s, const char *p, @@ -3331,25 +3265,25 @@ luaL_gsub *luaL_gsub()* returns it. luaL_loadbuffer *luaL_loadbuffer()* -> +>c int luaL_loadbuffer (lua_State *L, const char *buff, size_t sz, const char *name); < Loads a buffer as a Lua chunk. This function uses `lua_load` (see - |luaref-lua_load|) to load the chunk in the buffer pointed to by + |lua_load()|) to load the chunk in the buffer pointed to by `buff` with size `sz`. This function returns the same results as `lua_load`. `name` is the chunk name, used for debug information and error messages. luaL_loadfile *luaL_loadfile()* -> +>c int luaL_loadfile (lua_State *L, const char *filename); < Loads a file as a Lua chunk. This function uses `lua_load` (see - |luaref-lua_load|) to load the chunk in the file named `filename`. If + |lua_load()|) to load the chunk in the file named `filename`. If `filename` is `NULL`, then it loads from the standard input. The first line in the file is ignored if it starts with a `#`. @@ -3359,11 +3293,11 @@ luaL_loadfile *luaL_loadfile()* As `lua_load`, this function only loads the chunk; it does not run it. luaL_loadstring *luaL_loadstring()* -> +>c int luaL_loadstring (lua_State *L, const char *s); < Loads a string as a Lua chunk. This function uses `lua_load` (see - |luaref-lua_load|) to load the chunk in the zero-terminated string + |lua_load()|) to load the chunk in the zero-terminated string `s`. This function returns the same results as `lua_load`. @@ -3372,7 +3306,7 @@ luaL_loadstring *luaL_loadstring()* run it. luaL_newmetatable *luaL_newmetatable()* -> +>c int luaL_newmetatable (lua_State *L, const char *tname); < If the registry already has the key `tname`, returns 0. Otherwise, @@ -3383,27 +3317,27 @@ luaL_newmetatable *luaL_newmetatable()* `tname` in the registry. luaL_newstate *luaL_newstate()* -> +>c lua_State *luaL_newstate (void); < Creates a new Lua state. It calls `lua_newstate` (see - |luaref-lua_newstate|) with an allocator based on the standard C + |lua_newstate()|) with an allocator based on the standard C `realloc` function and then sets a panic function (see - |luaref-lua_atpanic|) that prints an error message to the standard + |lua_atpanic()|) that prints an error message to the standard error output in case of fatal errors. Returns the new state, or `NULL` if there is a memory allocation error. luaL_openlibs *luaL_openlibs()* -> +>c void luaL_openlibs (lua_State *L); < Opens all standard Lua libraries into the given state. See also |luaref-openlibs| for details on how to open individual libraries. luaL_optint *luaL_optint()* -> +>c int luaL_optint (lua_State *L, int narg, int d); < If the function argument `narg` is a number, returns this number cast @@ -3411,17 +3345,17 @@ luaL_optint *luaL_optint()* Otherwise, raises an error. luaL_optinteger *luaL_optinteger()* -> +>c lua_Integer luaL_optinteger (lua_State *L, int narg, lua_Integer d); < If the function argument `narg` is a number, returns this number cast - to a `lua_Integer` (see |luaref-lua_Integer|). If this argument is + to a `lua_Integer` (see |lua_Integer()|). If this argument is absent or is `nil`, returns `d`. Otherwise, raises an error. luaL_optlong *luaL_optlong()* -> +>c long luaL_optlong (lua_State *L, int narg, long d); < If the function argument `narg` is a number, returns this number cast @@ -3429,7 +3363,7 @@ luaL_optlong *luaL_optlong()* Otherwise, raises an error. luaL_optlstring *luaL_optlstring()* -> +>c const char *luaL_optlstring (lua_State *L, int narg, const char *d, @@ -3442,7 +3376,7 @@ luaL_optlstring *luaL_optlstring()* If `l` is not `NULL`, fills the position `*l` with the results' length. luaL_optnumber *luaL_optnumber()* -> +>c lua_Number luaL_optnumber (lua_State *L, int narg, lua_Number d); < If the function argument `narg` is a number, returns this number. If @@ -3450,7 +3384,7 @@ luaL_optnumber *luaL_optnumber()* error. luaL_optstring *luaL_optstring()* -> +>c const char *luaL_optstring (lua_State *L, int narg, const char *d); @@ -3460,24 +3394,24 @@ luaL_optstring *luaL_optstring()* error. luaL_prepbuffer *luaL_prepbuffer()* -> +>c char *luaL_prepbuffer (luaL_Buffer *B); < Returns an address to a space of size `LUAL_BUFFERSIZE` where you can - copy a string to be added to buffer `B` (see |luaref-luaL_Buffer|). + copy a string to be added to buffer `B` (see |luaL_Buffer()|). After copying the string into this space you must call `luaL_addsize` - (see |luaref-luaL_addsize|) with the size of the string to actually + (see |luaL_addsize()|) with the size of the string to actually add it to the buffer. luaL_pushresult *luaL_pushresult()* -> +>c void luaL_pushresult (luaL_Buffer *B); < Finishes the use of buffer `B` leaving the final string on the top of the stack. luaL_ref *luaL_ref()* -> +>c int luaL_ref (lua_State *L, int t); < Creates and returns a `reference`, in the table at index `t`, for the @@ -3486,8 +3420,8 @@ luaL_ref *luaL_ref()* A reference is a unique integer key. As long as you do not manually add integer keys into table `t`, `luaL_ref` ensures the uniqueness of the key it returns. You can retrieve an object referred by reference - `r` by calling `lua_rawgeti(L, t, r)` (see |luaref-lua_rawgeti|). - Function `luaL_unref` (see |luaref-luaL_unref|) frees a reference and + `r` by calling `lua_rawgeti(L, t, r)` (see |lua_rawgeti()|). + Function `luaL_unref` (see |luaL_unref()|) frees a reference and its associated object. If the object at the top of the stack is `nil`, `luaL_ref` returns the @@ -3495,19 +3429,19 @@ luaL_ref *luaL_ref()* different from any reference returned by `luaL_ref`. luaL_Reg *luaL_Reg()* -> +>c typedef struct luaL_Reg { const char *name; lua_CFunction func; } luaL_Reg; < Type for arrays of functions to be registered by `luaL_register` (see - |luaref-luaL_register|). `name` is the function name and `func` is a + |luaL_register()|). `name` is the function name and `func` is a pointer to the function. Any array of `luaL_Reg` must end with a sentinel entry in which both `name` and `func` are `NULL`. luaL_register *luaL_register()* -> +>c void luaL_register (lua_State *L, const char *libname, const luaL_Reg *l); @@ -3515,7 +3449,7 @@ luaL_register *luaL_register()* Opens a library. When called with `libname` equal to `NULL`, it simply registers all - functions in the list `l` (see |luaref-luaL_Reg|) into the table on + functions in the list `l` (see |luaL_Reg()|) into the table on the top of the stack. When called with a non-null `libname`, `luaL_register` creates a new @@ -3528,13 +3462,13 @@ luaL_register *luaL_register()* In any case the function leaves the table on the top of the stack. luaL_typename *luaL_typename()* -> +>c const char *luaL_typename (lua_State *L, int idx); < Returns the name of the type of the value at index `idx`. luaL_typerror *luaL_typerror()* -> +>c int luaL_typerror (lua_State *L, int narg, const char *tname); < Generates an error with a message like the following: @@ -3543,22 +3477,22 @@ luaL_typerror *luaL_typerror()* `expected, got` `rt` `)` where `location` is produced by `luaL_where` (see - |luaref-luaL_where|), `func` is the name of the current function, and + |luaL_where()|), `func` is the name of the current function, and `rt` is the type name of the actual argument. luaL_unref *luaL_unref()* -> +>c void luaL_unref (lua_State *L, int t, int ref); < Releases reference `ref` from the table at index `t` (see - |luaref-luaL_ref|). The entry is removed from the table, so that the + |luaL_ref()|). The entry is removed from the table, so that the referred object can be collected. The reference `ref` is also freed to be used again. If `ref` is `LUA_NOREF` or `LUA_REFNIL`, `luaL_unref` does nothing. luaL_where *luaL_where()* -> +>c void luaL_where (lua_State *L, int lvl); < Pushes onto the stack a string identifying the current position of the @@ -3574,7 +3508,6 @@ luaL_where *luaL_where()* ============================================================================== 5 STANDARD LIBRARIES *luaref-Lib* -============================================================================== The standard libraries provide useful functions that are implemented directly through the C API. Some of these functions provide essential services to the @@ -3601,14 +3534,14 @@ functions as fields of a global table or as methods of its objects. *luaref-openlibs* To have access to these libraries, the C host program should call the `luaL_openlibs` function, which opens all standard libraries (see -|luaref-luaL_openlibs|). Alternatively, the host program can open the libraries +|luaL_openlibs()|). Alternatively, the host program can open the libraries individually by calling `luaopen_base` (for the basic library), `luaopen_package` (for the package 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` and should not be called directly: you must call them -like any other Lua C function, e.g., by using `lua_call` (see |luaref-lua_call|). +like any other Lua C function, e.g., by using `lua_call` (see |lua_call()|). ============================================================================== 5.1 Basic Functions *luaref-libBasic* @@ -3700,15 +3633,15 @@ load({func} [, {chunkname}]) *luaref-load()* information. loadfile([{filename}]) *luaref-loadfile()* - Similar to `load` (see |luaref-load|), but gets the chunk from file + Similar to `load` (see |luaref-load()|), but gets the chunk from file {filename} or from the standard input, if no file name is given. loadstring({string} [, {chunkname}]) *luaref-loadstring()* - Similar to `load` (see |luaref-load|), but gets the chunk from the + Similar to `load` (see |luaref-load()|), but gets the chunk from the given {string}. To load and run a given string, use the idiom -> +>lua assert(loadstring(s))() < @@ -3724,14 +3657,14 @@ next({table} [, {index}]) *luaref-next()* 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` |luaref-ipairs| function.) + numerical `for` or the `ipairs` |luaref-ipairs()| function.) The behavior of `next` is `undefined` if, during the traversal, you assign any value to a non-existent field in the table. You may however modify existing fields. In particular, you may clear existing fields. pairs({t}) *luaref-pairs()* - Returns three values: the `next` |luaref-next| function, the table + Returns three values: the `next` |luaref-next()| function, the table {t}, and `nil`, so that the construction `for k,v in pairs(t) do` `body` `end` @@ -3749,10 +3682,10 @@ pcall({f}, {arg1}, {...}) *luaref-pcall()* print({...}) *luaref-print()* Receives any number of arguments, and prints their values to `stdout`, - using the `tostring` |luaref-tostring| function to convert them to + using the `tostring` |luaref-tostring()| function to convert them to strings. `print` is not intended for formatted output, but only as a quick way to show a value, typically for debugging. For formatted - output, use `string.format` (see |luaref-string.format|). + output, use `string.format` (see |string.format()|). rawequal({v1}, {v2}) *luaref-rawequal()* Checks whether {v1} is equal to {v2}, without invoking any metamethod. @@ -3807,7 +3740,7 @@ tonumber({e} [, {base}]) *luaref-tonumber()* tostring({e}) *luaref-tostring()* Receives an argument of any type and converts it to a string in a reasonable format. For complete control of how numbers are converted, - use `string.format` (see |luaref-string.format|). + use `string.format` (see |string.format()|). *__tostring* If the metatable of {e} has a `"__tostring"` field, `tostring` calls @@ -3823,7 +3756,7 @@ type({v}) *luaref-type()* unpack({list} [, {i} [, {j}]]) *luaref-unpack()* Returns the elements from the given table. This function is equivalent to -> +>lua return list[i], list[i+1], ..., list[j] < except that the above code can be written only for a fixed number of @@ -3836,7 +3769,7 @@ _VERSION *luaref-_VERSION()* `"Lua 5.1"` . xpcall({f}, {err}) *luaref-xpcall()* - This function is similar to `pcall` (see |luaref-pcall|), except that + This function is similar to `pcall` (see |luaref-pcall()|), except that you can set a new error handler. `xpcall` calls function {f} in protected mode, using {err} as the @@ -3901,7 +3834,7 @@ coroutine.yield({...}) *coroutine.yield()* The package library provides basic facilities for loading and building modules in Lua. It exports two of its functions directly in the global environment: -`require` and `module` (see |luaref-require| and |luaref-module|). Everything else is +`require` and `module` (see |luaref-require()| and |luaref-module()|). Everything else is exported in a table `package`. module({name} [, {...}]) *luaref-module()* @@ -3914,7 +3847,7 @@ module({name} [, {...}]) *luaref-module()* `t._PACKAGE` with the package name (the full module name minus last component; see below). Finally, `module` sets `t` as the new environment of the current function and the new value of - `package.loaded[name]`, so that `require` (see |luaref-require|) + `package.loaded[name]`, so that `require` (see |luaref-require()|) returns `t`. If {name} is a compound name (that is, one with components separated @@ -3968,7 +3901,7 @@ require({modname}) *luaref-require()* If there is any error loading or running the module, or if it cannot find any loader for the module, then `require` signals an error. -package.cpath *package.cpath()* +package.cpath *package.cpath* The path used by `require` to search for a C loader. Lua initializes the C path `package.cpath` in the same way it @@ -3985,7 +3918,7 @@ package.loadlib({libname}, {funcname}) *package.loadlib()* Dynamically links the host program with the C library {libname}. Inside this library, looks for a function {funcname} and returns this function as a C function. (So, {funcname} must follow the protocol - (see |luaref-lua_CFunction|)). + (see |lua_CFunction()|)). This is a low-level function. It completely bypasses the package and module system. Unlike `require`, it does not perform any path @@ -3998,7 +3931,7 @@ package.loadlib({libname}, {funcname}) *package.loadlib()* available on some platforms (Windows, Linux, Mac OS X, Solaris, BSD, plus other Unix systems that support the `dlfcn` standard). -package.path *package.path()* +package.path *package.path* The path used by `require` to search for a Lua loader. At start-up, Lua initializes this variable with the value of the @@ -4019,7 +3952,7 @@ package.path *package.path()* order. package.preload *package.preload()* - A table to store loaders for specific modules (see |luaref-require|). + A table to store loaders for specific modules (see |luaref-require()|). package.seeall({module}) *package.seeall()* Sets a metatable for {module} with its `__index` field referring to @@ -4059,7 +3992,7 @@ string.char({...}) *string.char()* string.dump({function}) *string.dump()* Returns a string containing a binary representation of the given - function, so that a later |luaref-loadstring| on this string returns a + function, so that a later |luaref-loadstring()| on this string returns a copy of the function. {function} must be a Lua function without upvalues. @@ -4088,11 +4021,11 @@ string.format({formatstring}, {...}) *string.format()* interpreter: the string is written between double quotes, and all double quotes, newlines, embedded zeros, and backslashes in the string are correctly escaped when written. For instance, the call -> +>lua string.format('%q', 'a string with "quotes" and \n new line') < will produce the string: -> +>lua "a string with \"quotes\" and \ new line" < @@ -4110,7 +4043,7 @@ string.gmatch({s}, {pattern}) *string.gmatch()* in each call. As an example, the following loop -> +>lua s = "hello world from Lua" for w in string.gmatch(s, "%a+") do print(w) @@ -4119,7 +4052,7 @@ string.gmatch({s}, {pattern}) *string.gmatch()* 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: -> +>lua t = {} s = "from=world, to=Lua" for k, v in string.gmatch(s, "(%w+)=(%w+)") do @@ -4127,7 +4060,7 @@ string.gmatch({s}, {pattern}) *string.gmatch()* end < -string.gsub({s}, {pattern}, {repl} [, {n}]) *string.gsu{b}()* +string.gsub({s}, {pattern}, {repl} [, {n}]) *string.gsub()* Returns a copy of {s} in which all occurrences of the {pattern} have been replaced by a replacement string specified by {repl}, which may be a string, a table, or a function. `gsub` also returns, as its @@ -4158,7 +4091,7 @@ string.gsub({s}, {pattern}, {repl} [, {n}]) *string.gsu{b}()* occurrence of `pattern` is replaced. Here are some examples: -> +>lua x = string.gsub("hello world", "(%w+)", "%1 %1") --> x="hello hello world world" @@ -4341,7 +4274,7 @@ table.foreach({table}, {f}) *table.foreach()* returns a non-`nil` value, then the loop is broken, and this value is returned as the final value of `table.foreach`. - See |luaref-next| for extra information about table traversals. + See |luaref-next()| for extra information about table traversals. table.foreachi({table}, {f}) *table.foreachi()* Executes the given {f} over the numerical indices of {table}. For each @@ -4658,7 +4591,7 @@ file:setvbuf({mode} [, {size}]) *luaref-file:setvbuf()* immediately. `"full"` full buffering; output operation is performed only when the buffer is full (or when you explicitly `flush` the file - (see |luaref-io.flush|). + (see |io.flush()|). `"line"` line buffering; output is buffered until a newline is output or there is any input from some special files (such as a terminal device). @@ -4669,7 +4602,7 @@ file:setvbuf({mode} [, {size}]) *luaref-file:setvbuf()* file:write({...}) *luaref-file:write()* Writes the value of each of its arguments to `file`. The arguments must be strings or numbers. To write other values, use `tostring` - |luaref-tostring| or `string.format` |luaref-string.format| before + |luaref-tostring()| or `string.format` |string.format()| before `write`. ============================================================================== @@ -4686,7 +4619,7 @@ os.date([{format} [, {time}]]) *os.date()* according to the given string {format}. If the {time} argument is present, this is the time to be formatted - (see the `os.time` function |luaref-os.time| for a description of this + (see the `os.time` function |os.time()| for a description of this value). Otherwise, `date` formats the current time. If {format} starts with `!`, then the date is formatted in @@ -4744,7 +4677,7 @@ os.time([{table}]) *os.time()* representing the date and time specified by the given table. This table must 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 |luaref-os.date|). + see the `os.date` function |os.date()|). The returned value is a number, whose meaning depends on your system. In POSIX, Windows, and some other systems, this number counts the @@ -4802,7 +4735,7 @@ debug.getinfo([{thread},] {function} [, {what}]) *debug.getinfo()* functions, then `getinfo` returns `nil`. The returned table may contain all the fields returned by - `lua_getinfo` (see |luaref-lua_getinfo|), with the string {what} + `lua_getinfo` (see |lua_getinfo()|), with the string {what} describing which fields to fill in. The default for {what} is to get all information available, except the table of valid lines. If present, the option `f` adds a field named `func` with the function @@ -4821,7 +4754,7 @@ debug.getlocal([{thread},] {level}, {local}) *debug.getlocal()* 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` - |luaref-debug.getinfo| to check whether the level is valid.) + |debug.getinfo()| to check whether the level is valid.) Variable names starting with `(` (open parentheses) represent internal variables (loop control variables, temporaries, and C @@ -4894,12 +4827,11 @@ debug.traceback([{thread},] [{message}] [,{level}]) *debug.traceback()* ============================================================================== A BIBLIOGRAPHY *luaref-bibliography* -============================================================================== This help file is a minor adaptation from this main reference: - R. Ierusalimschy, L. H. de Figueiredo, and W. Celes., - "Lua: 5.1 reference manual", http://www.lua.org/manual/5.1/manual.html + "Lua: 5.1 reference manual", https://www.lua.org/manual/5.1/manual.html Lua is discussed in these references: @@ -4920,8 +4852,7 @@ Lua is discussed in these references: "Proc. of V Brazilian Symposium on Programming Languages" (2001) B-14-B-28. ============================================================================== -B COPYRIGHT & LICENSES *luaref-copyright* -============================================================================== +B COPYRIGHT AND LICENSES *luaref-copyright* This help file has the same copyright and license as Lua 5.1 and the Lua 5.1 manual: @@ -4938,29 +4869,28 @@ furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. -THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR -IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, -FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE -AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER -LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, -OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE -SOFTWARE. + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR + IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, + FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE + AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER + LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, + OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE + SOFTWARE. ============================================================================== C LUAREF DOC *luarefvim* *luarefvimdoc* *luaref-help* *luaref-doc* -============================================================================== This is a Vim help file containing a reference for Lua 5.1, and it is -- with a few exceptions and adaptations -- a copy of the Lua 5.1 Reference Manual (see |luaref-bibliography|). For usage information, refer to -|luaref-docUsage|. For copyright information, see |luaref-copyright|. +|luaref-doc|. For copyright information, see |luaref-copyright|. The main ideas and concepts on how to implement this reference were taken from Christian Habermann's CRefVim project -(http://www.vim.org/scripts/script.php?script_id=614). +(https://www.vim.org/scripts/script.php?script_id=614). Adapted for bundled Nvim documentation; the original plugin can be found at -http://www.vim.org/scripts/script.php?script_id=1291 +https://www.vim.org/scripts/script.php?script_id=1291 ------------------------------------------------------------------------------ vi:tw=78:ts=4:ft=help:norl:et |