diff options
Diffstat (limited to 'runtime/doc/luaref.txt')
| -rw-r--r-- | runtime/doc/luaref.txt | 606 |
1 files changed, 299 insertions, 307 deletions
diff --git a/runtime/doc/luaref.txt b/runtime/doc/luaref.txt index aafdd5c43e..467b5760cf 100644 --- a/runtime/doc/luaref.txt +++ b/runtime/doc/luaref.txt @@ -1,5 +1,5 @@ *luaref.txt* Nvim - *luaref* *Lua-Reference* + *luaref* LUA REFERENCE MANUAL @@ -16,14 +16,14 @@ Copyright (c) 2006 Lua.org, PUC-Rio. - See |luaref-doc| for information on this manual. - See |luaref-copyright| for copyright and licenses. + See |lua-ref-doc| for information on this manual. + See |lua-ref-copyright| for copyright and licenses. Type |gO| to see the table of contents. ============================================================================== -1 INTRODUCTION *luaref-intro* +1 INTRODUCTION *luaref-intro* Lua is an extension programming language designed to support general procedural programming with data description facilities. It also offers good @@ -47,13 +47,13 @@ Lua's official web site, www.lua.org. Like any other reference manual, this document is dry in places. For a discussion of the decisions behind the design of Lua, see references at -|luaref-bibliography|. For a detailed introduction to programming in Lua, see +|lua-ref-bibliography|. For a detailed introduction to programming in Lua, see Roberto's book, Programming in Lua. Lua means "moon" in Portuguese and is pronounced LOO-ah. ============================================================================== -2 THE LANGUAGE *luaref-language* +2 THE LANGUAGE *lua-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 @@ -63,9 +63,9 @@ 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`. ============================================================================== -2.1 Lexical Conventions *luaref-langLexConv* +2.1 Lexical Conventions *lua-lexical* - *luaref-names* *luaref-identifiers* + *lua-names* *lua-identifiers* Names (also called identifiers) in Lua can be any string of letters, digits, and underscores, not beginning with a digit. This coincides with the definition of identifiers in most languages. (The definition of letter depends @@ -92,7 +92,7 @@ The following strings denote other tokens: ( ) { } [ ] ; : , . .. ... < - *luaref-literal* + *lua-literal* Literal strings can be delimited by matching single or double quotes, and can contain the following C-like escape sequences: @@ -146,14 +146,14 @@ coded as 49), the five literals below denote the same string: alo 123"]==] < - *luaref-numconstant* + *lua-numconstant* A numerical constant may be written with an optional decimal part and an optional decimal exponent. Lua also accepts integer hexadecimal constants, by prefixing them with `0x`. Examples of valid numerical constants are > 3 3.0 3.1416 314.16e-2 0.31416E1 0xff 0x56 < - *luaref-comment* + *lua-comment* A comment starts with a double hyphen (`--`) anywhere outside a string. If the text immediately after `--` is not an opening long bracket, the comment is a short comment, which runs until the end of the line. Otherwise, it is a long @@ -161,7 +161,7 @@ comment, which runs until the corresponding closing long bracket. Long comments are frequently used to disable code temporarily. ============================================================================== -2.2 Values and Types *luaref-langValTypes* +2.2 Values and Types *lua-values* Lua is a dynamically typed language. This means that variables do not have types; only values do. There are no type definitions in the language. All @@ -171,9 +171,9 @@ All values in Lua are first-class values. This means that all values can be stored in variables, passed as arguments to other functions, and returned as results. - *luaref-types* *luaref-nil* - *luaref-true* *luaref-false* - *luaref-number* *luaref-string* + *lua-types* *lua-nil* + *lua-true* *lua-false* + *lua-number* *lua-string* There are eight basic types in Lua: `nil`, `boolean`, `number`, `string`, `function`, `userdata`, `thread`, and `table`. Nil is the type of the value `nil`, whose main property is to be different from any other value; it usually @@ -184,27 +184,27 @@ numbers. (It is easy to build Lua interpreters that use other internal representations for numbers, such as single-precision float or long integers; see file `luaconf.h`.) String represents arrays of characters. Lua is 8-bit clean: strings may contain any 8-bit character, including embedded zeros -(`\0`) (see |luaref-literal|). +(`\0`) (see |lua-literal|). Lua can call (and manipulate) functions written in Lua and functions written -in C (see |luaref-langFuncCalls|). +in C (see |lua-function|). - *luaref-userdatatype* + *lua-userdatatype* The type userdata is provided to allow arbitrary C data to be stored in Lua variables. This type corresponds to a block of raw memory and has no pre-defined operations in Lua, except assignment and identity test. However, by using metatables, the programmer can define operations for userdata values -(see |luaref-langMetatables|). Userdata values cannot be created or modified -in Lua, only through the C API. This guarantees the integrity of data owned by -the host program. +(see |lua-metatable|). Userdata values cannot be created or modified in Lua, +only through the C API. This guarantees the integrity of data owned by the +host program. - *luaref-thread* + *lua-thread* The type `thread` represents independent threads of execution and it is used to -implement coroutines (see |luaref-langCoro|). Do not confuse Lua threads with +implement coroutines (see |lua-coroutine|). Do not confuse Lua threads with operating-system threads. Lua supports coroutines on all systems, even those that do not support threads. - *luaref-table* + *lua-table* The type `table` implements associative arrays, that is, arrays that can be indexed not only with numbers, but with any value (except `nil`). Tables can be heterogeneous; that is, they can contain values of all types (except @@ -213,11 +213,11 @@ used to represent ordinary arrays, symbol tables, sets, records, graphs, trees, etc. To represent records, Lua uses the field name as an index. The language supports this representation by providing `a.name` as syntactic sugar for `a["name"]`. There are several convenient ways to create tables in Lua -(see |luaref-langTableConst|). +(see |lua-tableconstructor|). Like indices, the value of a table field can be of any type (except `nil`). In particular, because functions are first-class values, table fields may contain -functions. Thus tables may also carry methods (see |luaref-langFuncDefs|). +functions. Thus tables may also carry methods (see |lua-function-define|). Tables, functions, threads and (full) userdata values are objects: variables do not actually contain these values, only references to them. Assignment, @@ -225,10 +225,10 @@ 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 |lua-type()|). ------------------------------------------------------------------------------ -2.2.1 Coercion *luaref-langCoercion* +2.2.1 Coercion *lua-coercion* Lua provides automatic conversion between string and number values at run time. Any arithmetic operation applied to a string tries to convert that @@ -239,7 +239,7 @@ converted to strings, use the `format` function from the string library (see |string.format()|). ============================================================================== -2.3 Variables *luaref-langVariables* +2.3 Variables *lua-variables* Variables are places that store values. There are three kinds of variables in Lua: global variables, local variables, and table fields. @@ -249,12 +249,12 @@ function's formal parameter, which is a particular form of local variable): > var ::= Name < -Name denotes identifiers, as defined in |luaref-langLexConv|. +Name denotes identifiers, as defined in |lua-lexical|. Any variable is assumed to be global unless explicitly declared as a local -(see |luaref-langLocalDec|). Local variables are lexically scoped: local +(see |lua-local|). Local variables are lexically scoped: local variables can be freely accessed by functions defined inside their scope (see -|luaref-langVisibRules|). +|lua-visibility|). Before the first assignment to a variable, its value is `nil`. @@ -265,21 +265,21 @@ Square brackets are used to index a table: The first expression (`prefixexp`) should result in a table value; the second expression (`exp`) identifies a specific entry inside that table. The expression denoting the table to be indexed has a restricted syntax; see -|luaref-langExpressions| for details. +|lua-expressions| for details. The syntax `var.NAME` is just syntactic sugar for `var["NAME"]` : > var ::= prefixexp . Name < All global variables live as fields in ordinary Lua tables, called environment -tables or simply environments (see |luaref-langEnvironments|). Each function +tables or simply environments (see |lua-environments|). Each function 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 -|lua_getfenv()|). To replace it, you call `setfenv` (see |luaref-setfenv()|). +|lua_getfenv()|). To replace it, you call `setfenv` (see |setfenv()|). (You can only manipulate the environment of C functions through the debug -library; see |luaref-libDebug|.) +library; see |lua-lib-debug|.) An access to a global variable `x` is equivalent to `_env.x`, which in turn is equivalent to @@ -291,19 +291,19 @@ not defined in Lua. We use it here only for explanatory purposes.) The meaning of accesses to global variables and table fields can be changed via metatables. An access to an indexed variable `t[i]` is equivalent to a -call `gettable_event(t,i)`. (See |luaref-langMetatables| for a complete -description of the `gettable_event` function. This function is not defined or -callable in Lua. We use it here only for explanatory purposes.) +call `gettable_event(t,i)`. (See |lua-metatable| for a complete description of +the `gettable_event` function. This function is not defined or callable in +Lua. We use it here only for explanatory purposes.) ============================================================================== -2.4 Statements *luaref-langStats* +2.4 Statements *lua-statement* Lua supports an almost conventional set of statements, similar to those in Pascal or C. This set includes assignment, control structures, function calls, and variable declarations. ------------------------------------------------------------------------------ -2.4.1 Chunks *luaref-chunk* *luaref-langChunks* +2.4.1 Chunks *lua-chunk* The unit of execution of Lua is called a chunk. A chunk is simply a sequence of statements, which are executed sequentially. Each statement can be @@ -314,7 +314,7 @@ optionally followed by a semicolon: There are no empty statements and thus `;;` is not legal. Lua handles a chunk as the body of an anonymous function with a variable -number of arguments (see |luaref-langFuncDefs|). As such, chunks can define +number of arguments (see |lua-function-define|). As such, chunks can define local variables, receive arguments, and return values. A chunk may be stored in a file or in a string inside the host program. When a @@ -327,24 +327,24 @@ details. Programs in source and compiled forms are interchangeable; Lua automatically detects the file type and acts accordingly. ------------------------------------------------------------------------------ -2.4.2 Blocks *luaref-block* *luaref-langBlocks* +2.4.2 Blocks *lua-block* A block is a list of statements; syntactically, a block is the same as a chunk: > block ::= chunk < - *luaref-do* *luaref-end* + *lua-do* *lua-end* A block may be explicitly delimited to produce a single statement: > stat ::= do block end < Explicit blocks are useful to control the scope of variable declarations. Explicit blocks are also sometimes used to add a `return` or `break` statement -in the middle of another block (see |luaref-langContStructs|). +in the middle of another block (see |lua-control|). ------------------------------------------------------------------------------ -2.4.3 Assignment *luaref-langAssign* +2.4.3 Assignment *lua-assign* Lua allows multiple assignment. Therefore, the syntax for assignment defines a list of variables on the left side and a list of expressions on the right @@ -354,7 +354,7 @@ side. The elements in both lists are separated by commas: varlist1 ::= var { , var } explist1 ::= exp { , exp } < -Expressions are discussed in |luaref-langExpressions|. +Expressions are discussed in |lua-expressions|. Before the assignment, the list of values is adjusted to the length of the list of variables. If there are more values than needed, the excess values are @@ -362,7 +362,7 @@ thrown away. If there are fewer values than needed, the list is extended with as many `nil`s as needed. If the list of expressions ends with a function call, then all values returned by this call enter in the list of values, before the adjustment (except when the call is enclosed in parentheses; see -|luaref-langExpressions|). +|lua-expressions|). The assignment statement first evaluates all its expressions and only then are the assignments performed. Thus the code @@ -379,9 +379,9 @@ exchanges the values of `x` and `y`. The meaning of assignments to global variables and table fields can be changed via metatables. An assignment to an indexed variable `t[i] = val` is -equivalent to `settable_event(t,i,val)`. (See |luaref-langMetatables| for a -complete description of the `settable_event` function. This function is not -defined or callable in Lua. We use it here only for explanatory purposes.) +equivalent to `settable_event(t,i,val)`. (See |lua-metatable| for a complete +description of the `settable_event` function. This function is not 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 @@ -392,10 +392,10 @@ where `_env` is the environment of the running function. (The `_env` variable is not defined in Lua. We use it here only for explanatory purposes.) ------------------------------------------------------------------------------ -2.4.4 Control Structures *luaref-langContStructs* +2.4.4 Control Structures *lua-control* - *luaref-if* *luaref-then* *luaref-else* *luaref-elseif* - *luaref-while* *luaref-repeat* *luaref-until* + *lua-if* *lua-then* *lua-else* *lua-elseif* + *lua-while* *lua-repeat* *lua-until* The control structures `if`, `while`, and `repeat` have the usual meaning and familiar syntax: > @@ -404,7 +404,7 @@ familiar syntax: stat ::= if exp then block { elseif exp then block } [ else block ] end < -Lua also has a `for` statement, in two flavors (see |luaref-langForStat|). +Lua also has a `for` statement, in two flavors (see |lua-for|). The condition expression of a control structure may return any value. Both `false` and `nil` are considered false. All values different @@ -415,14 +415,14 @@ In the `repeat-until` loop, the inner block does not end at the `until` keyword, but only after the condition. So, the condition can refer to local variables declared inside the loop block. - *luaref-return* + *lua-return* The `return` statement is used to return values from a function or a chunk (which is just a function). Functions and chunks may return more than one value, so the syntax for the `return` statement is `stat ::=` `return` `[explist1]` - *luaref-break* + *lua-break* The `break` statement is used to terminate the execution of a `while`, `repeat`, or `for` loop, skipping to the next statement after the loop: @@ -437,7 +437,7 @@ middle of a block, then an explicit inner block can be used, as in the idioms the last statements in their (inner) blocks. ------------------------------------------------------------------------------ -2.4.5 For Statement *luaref-for* *luaref-langForStat* +2.4.5 For Statement *for* *lua-for* The `for` statement has two forms: one numeric and one generic. @@ -477,8 +477,8 @@ Note the following: after the `for` ends or is broken. If you need this value, assign it to another variable before breaking or exiting the loop. - *luaref-in* -The generic `for` statement works over functions, called iterators. On each + *for-in* +The generic `for` statement works over functions, called |iterator|s. On each iteration, the iterator function is called to produce a new value, stopping when this new value is `nil`. The generic `for` loop has the following syntax: > @@ -513,17 +513,17 @@ Note the following: them to other variables before breaking or exiting the loop. ------------------------------------------------------------------------------ -2.4.6 Function Calls as Statements *luaref-langFuncStat* +2.4.6 Function Calls as Statements *lua-funcstatement* To allow possible side-effects, function calls can be executed as statements: > stat ::= functioncall < In this case, all returned values are thrown away. Function calls are -explained in |luaref-langFuncCalls|. +explained in |lua-function|. ------------------------------------------------------------------------------ -2.4.7 Local Declarations *luaref-local* *luaref-langLocalDec* +2.4.7 Local Declarations *lua-local* Local variables may be declared anywhere inside a block. The declaration may include an initial assignment: @@ -532,18 +532,17 @@ include an initial assignment: namelist ::= Name { , Name } < If present, an initial assignment has the same semantics of a multiple -assignment (see |luaref-langAssign|). Otherwise, all variables are initialized +assignment (see |lua-assign|). Otherwise, all variables are initialized with `nil`. -A chunk is also a block (see |luaref-langChunks|), and so local variables can be +A chunk is also a block (see |lua-chunk|), and so local variables can be declared in a chunk outside any explicit block. The scope of such local variables extends until the end of the chunk. -The visibility rules for local variables are explained in -|luaref-langVisibRules|. +The visibility rules for local variables are explained in |lua-visibility|. ============================================================================== -2.5 Expressions *luaref-langExpressions* +2.5 Expressions *lua-expressions* The basic expressions in Lua are the following: > @@ -558,22 +557,21 @@ The basic expressions in Lua are the following: exp ::= unop exp prefixexp ::= var | functioncall | ( exp ) < -Numbers and literal strings are explained in |luaref-langLexConv|; variables are -explained in |luaref-langVariables|; function definitions are explained in -|luaref-langFuncDefs|; function calls are explained in |luaref-langFuncCalls|; -table constructors are explained in |luaref-langTableConst|. Vararg expressions, +Numbers and literal strings are explained in |lua-lexical|; variables are +explained in |lua-variables|; function definitions are explained in +|lua-function-define|; function calls are explained in |lua-function|; +table constructors are explained in |lua-tableconstructor|. Vararg expressions, denoted by three dots (`...`), can only be used inside vararg functions; -they are explained in |luaref-langFuncDefs|. +they are explained in |lua-function-define|. -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-langArithOp|), the unary -`not` (see |luaref-langLogOp|), and the unary length operator (see -|luaref-langLength|). +Binary operators comprise arithmetic operators (see |lua-arithmetic|), +relational operators (see |lua-relational|), logical operators (see +|lua-logicalop|), and the concatenation operator (see |lua-concat|). +Unary operators comprise the unary minus (see |lua-arithmetic|), the unary +`not` (see |lua-logicalop|), and the unary length operator (see |lua-length|). Both function calls and vararg expressions may result in multiple values. If -the expression is used as a statement (see |luaref-langFuncStat|) +the expression is used as a statement (see |lua-funcstatement|) (only possible for function calls), then its return list is adjusted to zero elements, thus discarding all returned values. If the expression is used as the last (or the only) element of a list of expressions, then no adjustment is @@ -606,12 +604,12 @@ An expression enclosed in parentheses always results in only one value. Thus, return any values.) ------------------------------------------------------------------------------ -2.5.1 Arithmetic Operators *luaref-langArithOp* +2.5.1 Arithmetic Operators *lua-arithmetic* Lua supports the usual arithmetic operators: the binary `+` (addition), `-` (subtraction), `*` (multiplication), `/` (division), `%` (modulo) and `^` (exponentiation); and unary `-` (negation). If the operands are numbers, -or strings that can be converted to numbers (see |luaref-langCoercion|), then all +or strings that can be converted to numbers (see |lua-coercion|), then all 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 @@ -622,7 +620,7 @@ That is, it is the remainder of a division that rounds the quotient towards minus infinity. ------------------------------------------------------------------------------ -2.5.2 Relational Operators *luaref-langRelOp* +2.5.2 Relational Operators *lua-relational* The relational operators in Lua are > @@ -639,9 +637,9 @@ create a new object (a table, userdata, or function), this new object is different from any previously existing object. You can change the way that Lua compares tables and userdata using the "eq" -metamethod (see |luaref-langMetatables|). +metamethod (see |lua-metatable|). -The conversion rules of coercion |luaref-langCoercion| do not apply to +The conversion rules of coercion |lua-coercion| do not apply to equality comparisons. Thus, `"0"==0` evaluates to `false`, and `t[0]` and `t["0"]` denote different entries in a table. @@ -650,19 +648,19 @@ The operator `~=` is exactly the negation of equality (`==`). The order operators work as follows. If both arguments are numbers, then they are compared as such. Otherwise, if both arguments are strings, then their values are compared according to the current locale. Otherwise, Lua tries to -call the "lt" or the "le" metamethod (see |luaref-langMetatables|). +call the "lt" or the "le" metamethod (see |lua-metatable|). ------------------------------------------------------------------------------ -2.5.3 Logical Operators *luaref-langLogOp* +2.5.3 Logical Operators *lua-logicalop* The logical operators in Lua are > and or not < -Like the control structures (see |luaref-langContStructs|), all logical operators +Like the control structures (see |lua-control|), all logical operators consider both `false` and `nil` as false and anything else as true. - *luaref-not* *luaref-and* *luaref-or* + *lua-not* *lua-and* *lua-or* The negation operator `not` always returns `false` or `true`. The conjunction operator `and` returns its first argument if this value is `false` or `nil`; otherwise, `and` returns its second argument. The disjunction @@ -683,15 +681,15 @@ evaluated only if necessary. Here are some examples: (In this manual, `-->` indicates the result of the preceding expression.) ------------------------------------------------------------------------------ -2.5.4 Concatenation *luaref-langConcat* +2.5.4 Concatenation *lua-concat* The string concatenation operator in Lua is denoted by two dots (`..`). If both operands are strings or numbers, then they are converted to strings -according to the rules mentioned in |luaref-langCoercion|. Otherwise, the -"concat" metamethod is called (see |luaref-langMetatables|). +according to the rules mentioned in |lua-coercion|. Otherwise, the +"concat" metamethod is called (see |lua-metatable|). ------------------------------------------------------------------------------ -2.5.5 The Length Operator *luaref-langLength* +2.5.5 The Length Operator *lua-#* *lua-length* The length operator is denoted by the unary operator `#`. The length of a string is its number of bytes (that is, the usual meaning of string length @@ -706,7 +704,7 @@ indices that directly precedes a `nil` value (that is, it may consider any such `nil` value as the end of the array). ------------------------------------------------------------------------------ -2.5.6 Precedence *luaref-langPrec* +2.5.6 Precedence *lua-precedence* Operator precedence in Lua follows the table below, from lower to higher priority: @@ -725,7 +723,7 @@ The concatenation (`..`) and exponentiation (`^`) operators are right associative. All other binary operators are left associative. ------------------------------------------------------------------------------ -2.5.7 Table Constructors *luaref-langTableConst* +2.5.7 Table Constructors *lua-tableconstructor* Table constructors are expressions that create tables. Every time a constructor is evaluated, a new table is created. Constructors can be used to @@ -761,14 +759,14 @@ is equivalent to < If the last field in the list has the form `exp` and the expression is a function call, then all values returned by the call enter the list -consecutively (see |luaref-langFuncCalls|). To avoid this, enclose the function -call in parentheses (see |luaref-langExpressions|). +consecutively (see |lua-function|). To avoid this, enclose the function +call in parentheses (see |lua-expressions|). The field list may have an optional trailing separator, as a convenience for machine-generated code. ------------------------------------------------------------------------------ -2.5.8 Function Calls *luaref-function* *luaref-langFuncCalls* +2.5.8 Function Calls *lua-function* A function call in Lua has the following syntax: > @@ -778,7 +776,7 @@ In a function call, first `prefixexp` and `args` are evaluated. If the value of `prefixexp` has type `function`, then this function is called with the given arguments. Otherwise, the `prefixexp` "call" metamethod is called, having as first parameter the value of `prefixexp`, followed by the original call -arguments (see |luaref-langMetatables|). +arguments (see |lua-metatable|). The form > @@ -810,7 +808,7 @@ Lua would see that as a single statement, `a = f(g).x(a)`. So, if you want two statements, you must add a semi-colon between them. If you actually want to call `f`, you must remove the line break before `(g)`. - *luaref-tailcall* + *lua-tailcall* A call of the form `return` `functioncall` is called a tail call. Lua implements proper tail calls (or proper tail recursion): in a tail call, the called function reuses the stack entry of the calling function. Therefore, @@ -829,7 +827,7 @@ of the following examples are tail calls: < ------------------------------------------------------------------------------ -2.5.9 Function Definitions *luaref-langFuncDefs* +2.5.9 Function Definitions *lua-function-define* The syntax for function definition is > @@ -873,7 +871,7 @@ not to (This only makes a difference when the body of the function contains references to `f`.) - *luaref-closure* + *lua-closure* A function definition is an executable expression, whose value has type `function`. When Lua pre-compiles a chunk, all its function bodies are pre-compiled too. Then, whenever Lua executes the function definition, the @@ -887,7 +885,7 @@ values: > parlist1 ::= namelist [ , ... ] | ... < - *luaref-vararg* + *lua-vararg* When a function is called, the list of arguments is adjusted to the length of the list of parameters, unless the function is a variadic or vararg function, which is indicated by three dots (`...`) at the end of its parameter list. A @@ -922,11 +920,11 @@ vararg expression: g(3, 4, 5, 8) a=3, b=4, ... --> 5 8 g(5, r()) a=5, b=1, ... --> 2 3 < -Results are returned using the `return` statement (see |luaref-langContStructs|). +Results are returned using the `return` statement (see |lua-control|). If control reaches the end of a function without encountering a `return` statement, then the function returns with no results. - *luaref-colonsyntax* + *lua-colonsyntax* The colon syntax is used for defining methods, that is, functions that have an implicit extra parameter `self`. Thus, the statement @@ -937,7 +935,7 @@ is syntactic sugar for `t.a.b.c:f = function (self, (` `params` `)` `body` `end` ============================================================================== -2.6 Visibility Rules *luaref-langVisibRules* +2.6 Visibility Rules *lua-visibility* 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 @@ -959,7 +957,7 @@ block that includes the declaration. Consider the following example: Notice that, in a declaration like `local x = x`, the new `x` being declared is not in scope yet, and so the second `x` refers to the outside variable. - *luaref-upvalue* + *lua-upvalue* Because of the lexical scoping rules, local variables can be freely accessed by functions defined inside their scope. A local variable used by an inner function is called an upvalue, or external local variable, inside the inner @@ -980,7 +978,7 @@ function). Each of these closures uses a different `y` variable, while all of them share the same `x`. ============================================================================== -2.7 Error Handling *luaref-langError* +2.7 Error Handling *lua-errors* 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 @@ -989,11 +987,11 @@ 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()|). +|error()|). If you need to catch errors in Lua, you can use the `pcall` +function (see |pcall()|). ============================================================================== -2.8 Metatables *luaref-metatable* *luaref-langMetatables* +2.8 Metatables *metatable* *lua-metatable* Every value in Lua may have a metatable. This metatable is an ordinary Lua table that defines the behavior of the original table and userdata under @@ -1008,10 +1006,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 |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 +|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 @@ -1037,7 +1035,7 @@ by a Lua function describing how the interpreter executes that operation. The code shown here in Lua is only illustrative; the real behavior is hard coded in the interpreter and it is much more efficient than this simulation. All functions used in these descriptions (`rawget`, `tonumber`, etc.) are -described in |luaref-libBasic|. In particular, to retrieve the metamethod of a +described in |lua-lib-core|. In particular, to retrieve the metamethod of a given object, we use the expression > metatable(obj)[event] @@ -1307,7 +1305,7 @@ called when Lua calls a value. < ============================================================================== -2.9 Environments *luaref-environment* *luaref-langEnvironments* +2.9 Environments *lua-environments* Besides metatables, objects of types thread, function, and userdata have another table associated with them, called their environment. Like metatables, @@ -1319,16 +1317,15 @@ 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 -code (see |luaref-apiPseudoIndices|). +created by the thread (through |loadfile()|, |loadstring()| or |load()|) and +can be directly accessed by C code (see |lua-pseudoindex|). Environments associated with C functions can be directly accessed by C code -(see |luaref-apiPseudoIndices|). They are used as the default environment for +(see |lua-pseudoindex|). They are used as the default environment for other C functions created by the function. Environments associated with Lua functions are used to resolve all accesses to -global variables within the function (see |luaref-langVariables|). They are +global variables within the function (see |lua-variables|). They are used as the default environment for other Lua functions created by the function. @@ -1339,7 +1336,7 @@ environment of other objects (userdata, C functions, other threads) you must use the C API. ============================================================================== -2.10 Garbage Collection *luaref-langGC* +2.10 Garbage Collection *lua-gc* Lua performs automatic memory management. This means that you do not have to worry neither about allocating memory for new objects nor about freeing it @@ -1367,16 +1364,16 @@ 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 |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). +`collectgarbage` (see |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). ------------------------------------------------------------------------------ -2.10.1 Garbage-Collection Metamethods *luaref-langGCMeta* +2.10.1 Garbage-Collection Metamethods *lua-gc-meta* Using the C API, you can set garbage-collector metamethods for userdata (see -|luaref-langMetatables|). These metamethods are also called finalizers. +|lua-metatable|). These metamethods are also called finalizers. Finalizers allow you to coordinate Lua's garbage collection with external resource management (such as closing files, network or database connections, or freeing your own memory). @@ -1400,7 +1397,7 @@ cycle. That is, the first finalizer to be called is the one associated with the userdata created last in the program. ------------------------------------------------------------------------------ -2.10.2 - Weak Tables *luaref-weaktable* *luaref-langWeaktables* +2.10.2 - Weak Tables *lua-weaktable* A weak table is a table whose elements are weak references. A weak reference is ignored by the garbage collector. In other words, if the only references to @@ -1422,7 +1419,7 @@ field `__mode`. Otherwise, the weak behavior of the tables controlled by this metatable is undefined. ============================================================================== -2.11 Coroutines *luaref-coroutine* *luaref-langCoro* +2.11 Coroutines *lua-coroutine* Lua supports coroutines, also called collaborative multithreading. A coroutine in Lua represents an independent thread of execution. Unlike threads in @@ -1502,7 +1499,7 @@ When you run it, it produces the following output: < ============================================================================== -3 THE APPLICATION PROGRAM INTERFACE *luaref-API* +3 THE APPLICATION PROGRAM INTERFACE *lua-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 @@ -1519,7 +1516,7 @@ Lua with a proper definition for the macro `luai_apicheck`,in file `luaconf.h`. ============================================================================== -3.1 The Stack *luaref-stack* *luaref-apiStack* +3.1 The Stack *lua-stack* *lua-apiStack* Lua uses a virtual stack to pass values to and from C. Each element in this stack represents a Lua value (`nil`, number, string, etc.). @@ -1528,9 +1525,9 @@ 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 -|lua_CFunction()|). +|lua_CFunction|). - *luaref-stackindex* + *lua-stackindex* For convenience, most query operations in the API do not follow a strict stack discipline. Instead, they can refer to any element in the stack by using an index: a positive index represents an absolute stack position (starting at 1); @@ -1543,7 +1540,7 @@ We say that an index is valid if it lies between 1 and the stack top (that is, if `1 <= abs(index) <= top`). ============================================================================== -3.2 Stack Size *luaref-apiStackSize* +3.2 Stack Size *lua-apiStackSize* When you interact with Lua API, you are responsible for ensuring consistency. In particular, you are responsible for controlling stack overflow. You can @@ -1565,13 +1562,13 @@ we define an acceptable index as follows: Note that 0 is never an acceptable index. ============================================================================== -3.3 Pseudo-Indices *luaref-pseudoindex* *luaref-apiPseudoIndices* +3.3 Pseudo-Indices *lua-pseudoindex* Unless otherwise noted, any function that accepts valid indices can also be called with pseudo-indices, which represent some Lua values that are accessible to the C code but which are not in the stack. Pseudo-indices are used to access the thread environment, the function environment, the registry, -and the upvalues of a C function (see |luaref-apiCClosures|). +and the upvalues of a C function (see |lua-cclosure|). The thread environment (where global variables live) is always at pseudo-index `LUA_GLOBALSINDEX`. The environment of the running C function is always at @@ -1585,7 +1582,7 @@ global variable, do < ============================================================================== -3.4 C Closures *luaref-cclosure* *luaref-apiCClosures* +3.4 C Closures *lua-cclosure* When a C function is created, it is possible to associate some values with it, thus creating a C closure; these values are called upvalues and are accessible @@ -1599,7 +1596,7 @@ 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* +3.5 Registry *lua-registry* Lua provides a registry, a pre-defined table that can be used by any C code to store whatever Lua value it needs to store. This table is always located at @@ -1614,7 +1611,7 @@ implemented by the auxiliary library, and therefore should not be used for other purposes. ============================================================================== -3.6 Error Handling in C *luaref-apiError* +3.6 Error Handling in C *lua-apiError* Internally, Lua uses the C `longjmp` facility to handle errors. (You can also choose to use exceptions if you use C++; see file `luaconf.h`.) When Lua faces @@ -1634,11 +1631,11 @@ Inside a C function you can raise an error by calling `lua_error` (see |lua_error()|). ============================================================================== -3.7 Functions and Types *luaref-apiFunctions* +3.7 Functions and Types *lua-apiFunctions* Here we list all functions and types from the C API in alphabetical order. -lua_Alloc *lua_Alloc()* +lua_Alloc *lua_Alloc* >c typedef void * (*lua_Alloc) (void *ud, void *ptr, @@ -1736,7 +1733,7 @@ lua_call *lua_call()* to its original configuration. This is considered good programming practice. -lua_CFunction *luaref-cfunction* *lua_CFunction()* +lua_CFunction *lua-cfunction* *lua_CFunction* >c typedef int (*lua_CFunction) (lua_State *L); < @@ -1755,7 +1752,7 @@ lua_CFunction *luaref-cfunction* *lua_CFunction()* be properly discarded by Lua. Like a Lua function, a C function called by Lua can also return many results. - *luaref-cfunctionexample* + *lua-cfunctionexample* As an example, the following function receives a variable number of numerical arguments and returns their average and sum: >c @@ -1805,7 +1802,7 @@ lua_concat *lua_concat()* leaves the result at the top. If `n` is 1, the result is the single string on the stack (that is, the function does nothing); if `n` is 0, the result is the empty string. Concatenation is done following the - usual semantics of Lua (see |luaref-langConcat|). + usual semantics of Lua (see |lua-concat|). lua_cpcall *lua_cpcall()* >c @@ -1836,7 +1833,7 @@ lua_dump *lua_dump()* 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 - |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. @@ -1884,12 +1881,12 @@ lua_gc *lua_gc()* function returns 1 if the step finished a garbage-collection cycle. - `LUA_GCSETPAUSE` sets `data` /100 as the new value for the - `pause` of the collector (see |luaref-langGC|). + `pause` of the collector (see |lua-gc|). The function returns the previous value of the pause. - `LUA_GCSETSTEPMUL`sets `data` /100 as the new value for the `step` `multiplier` of the collector (see - |luaref-langGC|). The function returns the + |lua-gc|). The function returns the previous value of the step multiplier. lua_getallocf *lua_getallocf()* @@ -1913,7 +1910,7 @@ lua_getfield *lua_getfield()* < Pushes onto the stack the value `t[k]`, where `t` is the value at the given valid index `index`. As in Lua, this function may trigger a - metamethod for the "index" event (see |luaref-langMetatables|). + metamethod for the "index" event (see |lua-metatable|). lua_getglobal *lua_getglobal()* >c @@ -1944,7 +1941,7 @@ lua_gettable *lua_gettable()* This function pops the key from the stack (putting the resulting value in its place). As in Lua, this function may trigger a metamethod for - the "index" event (see |luaref-langMetatables|). + the "index" event (see |lua-metatable|). lua_gettop *lua_gettop()* >c @@ -1963,7 +1960,7 @@ lua_insert *lua_insert()* elements above this index to open space. Cannot be called with a pseudo-index, because a pseudo-index is not an actual stack position. -lua_Integer *lua_Integer()* +lua_Integer *lua_Integer* >c typedef ptrdiff_t lua_Integer; < @@ -2072,11 +2069,11 @@ lua_load *lua_load()* and loads it accordingly (see program `luac`). The `lua_load` function uses a user-supplied `reader` function to read - the chunk (see |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|). + error messages and in debug information (see |lua-apiDebug|). lua_newstate *lua_newstate()* >c @@ -2101,7 +2098,7 @@ lua_newthread *lua_newthread()* 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 |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. @@ -2116,7 +2113,7 @@ lua_newuserdata *lua_newuserdata()* This function allocates a new block of memory with the given size, pushes onto the stack a new full userdata with the block address, and returns this address. - *luaref-userdata* + *userdata* Userdata represents C values in Lua. A full userdata represents a block of memory. It is an object (like a table): you must create it, it can have its own metatable, and you can detect when it is being @@ -2136,7 +2133,7 @@ lua_next *lua_next()* no more elements in the table, then `lua_next` returns 0 (and pushes nothing). - *luaref-tabletraversal* + *lua-tabletraversal* A typical traversal looks like this: >c /* table is in the stack at index 't' */ @@ -2155,7 +2152,7 @@ lua_next *lua_next()* 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()* +lua_Number *lua_Number* >c typedef double lua_Number; < @@ -2228,7 +2225,7 @@ lua_pushcclosure *lua_pushcclosure()* Pushes a new C closure onto the stack. When a C function is created, it is possible to associate some values - with it, thus creating a C closure (see |luaref-apiCClosures|); these + with it, thus creating a C closure (see |lua-cclosure|); these values are then accessible to the function whenever it is called. To associate values with a C function, first these values should be pushed onto the stack (when there are multiple values, the first value @@ -2247,7 +2244,7 @@ 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 - |lua_CFunction()|). + |lua_CFunction|). `lua_pushcfunction` is defined as a macro: >c @@ -2284,7 +2281,7 @@ lua_pushlightuserdata *lua_pushlightuserdata()* void lua_pushlightuserdata (lua_State *L, void *p); < Pushes a light userdata onto the stack. - *luaref-lightuserdata* + *lua-lightuserdata* Userdata represents C values in Lua. A light userdata represents a pointer. It is a value (like a number): you do not create it, it has no individual metatable, and it is not collected (as it was never @@ -2386,7 +2383,7 @@ lua_rawseti *lua_rawseti()* This function pops the value from the stack. The assignment is raw; that is, it does not invoke metamethods. -lua_Reader *lua_Reader()* +lua_Reader *lua_Reader* >c typedef const char * (*lua_Reader) (lua_State *L, void *data, @@ -2476,7 +2473,7 @@ lua_setfield *lua_setfield()* This function pops the value from the stack. As in Lua, this function may trigger a metamethod for the "newindex" event (see - |luaref-langMetatables|). + |lua-metatable|). lua_setglobal *lua_setglobal()* >c @@ -2505,7 +2502,7 @@ lua_settable *lua_settable()* This function pops both the key and the value from the stack. As in Lua, this function may trigger a metamethod for the "newindex" event - (see |luaref-langMetatables|). + (see |lua-metatable|). lua_settop *lua_settop()* >c @@ -2516,7 +2513,7 @@ lua_settop *lua_settop()* elements are filled with `nil`. If `index` is 0, then all stack elements are removed. -lua_State *lua_State()* +lua_State *lua_State* >c typedef struct lua_State lua_State; < @@ -2561,9 +2558,9 @@ lua_tointeger *lua_tointeger()* 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 |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. + |lua-coercion|); otherwise, `lua_tointeger` returns 0. If the number is not an integer, it is truncated in some non-specified way. @@ -2592,8 +2589,8 @@ lua_tonumber *lua_tonumber()* 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 |lua_Number()|). The Lua value must be a number - or a string convertible to a number (see |luaref-langCoercion|); + `lua_Number` (see |lua_Number|). The Lua value must be a number + or a string convertible to a number (see |lua-coercion|); otherwise, `lua_tonumber` returns 0. lua_topointer *lua_topointer()* @@ -2620,7 +2617,7 @@ lua_tothread *lua_tothread()* 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*` |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()* @@ -2649,7 +2646,7 @@ lua_typename *lua_typename()* 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()* +lua_Writer *lua_Writer* >c typedef int (*lua_Writer) (lua_State *L, const void* p, @@ -2690,7 +2687,7 @@ lua_yield *lua_yield()* parameter `nresults` is the number of values from the stack that are passed as results to `lua_resume`. - *luaref-stackexample* + *lua-stackexample* As an example of stack manipulation, if the stack starts as `10 20 30 40 50*` (from bottom to top; the `*` marks the top), then > @@ -2706,14 +2703,14 @@ lua_yield *lua_yield()* < ============================================================================== -3.8 The Debug Interface *luaref-apiDebug* +3.8 The Debug Interface *lua-apiDebug* Lua has no built-in debugging facilities. Instead, it offers a special interface by means of functions and hooks. This interface allows the construction of different kinds of debuggers, profilers, and other tools that need "inside information" from the interpreter. -lua_Debug *lua_Debug()* +lua_Debug *lua_Debug* >c typedef struct lua_Debug { @@ -2737,7 +2734,7 @@ 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 |lua_getinfo()|). -The fields of `lua_Debug` have the following meaning: +The fields of `lua_Debug` have the following meaning: - `source` If the function was defined in a string, then `source` is that string. If the function was defined in a file, then @@ -2794,7 +2791,7 @@ lua_getinfo *lua_getinfo()* 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 |lua_getstack()|) or given as argument to - a hook (see |lua_Hook()|). + 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, @@ -2832,7 +2829,7 @@ lua_getlocal *lua_getlocal()* 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 |lua_getstack()|) or - given as argument to a hook (see |lua_Hook()|). The index `n` + 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 @@ -2851,7 +2848,7 @@ lua_getstack *lua_getstack()* < Gets information about the interpreter runtime stack. - This function fills parts of a `lua_Debug` (see |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 @@ -2874,7 +2871,7 @@ lua_getupvalue *lua_getupvalue()* number of upvalues. For C functions, this function uses the empty string `""` as a name for all upvalues. -lua_Hook *lua_Hook()* +lua_Hook *lua_Hook* >c typedef void (*lua_Hook) (lua_State *L, lua_Debug *ar); < @@ -2950,7 +2947,7 @@ lua_setupvalue *lua_setupvalue()* Returns `NULL` (and pops nothing) when the index is greater than the number of upvalues. - *luaref-debugexample* + *lua-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 @@ -2976,7 +2973,7 @@ lua_setupvalue *lua_setupvalue()* < ============================================================================== -4 THE AUXILIARY LIBRARY *luaref-aux* +4 THE AUXILIARY LIBRARY *lua-aux* The auxiliary library provides several convenient functions to interface C with Lua. While the basic API provides the primitive functions for all @@ -2996,7 +2993,7 @@ message is formatted for arguments (e.g., "bad argument #1"), you should not use these functions for other stack values. ============================================================================== -4.1 Functions and Types *luaref-auxFunctions* +4.1 Functions and Types *lua-auxFunctions* Here we list all functions and types from the auxiliary library in alphabetical order. @@ -3005,20 +3002,20 @@ luaL_addchar *luaL_addchar()* >c void luaL_addchar (luaL_Buffer *B, char c); < - Adds the character `c` to the buffer `B` (see |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 |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 |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 |luaL_prepbuffer()|). @@ -3027,14 +3024,14 @@ luaL_addstring *luaL_addstring()* void luaL_addstring (luaL_Buffer *B, const char *s); < Adds the zero-terminated string pointed to by `s` to the buffer `B` - (see |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 - |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 @@ -3065,7 +3062,7 @@ luaL_argerror *luaL_argerror()* This function never returns, but it is an idiom to use it in C functions as `return luaL_argerror(` `args` `)`. -luaL_Buffer *luaL_Buffer()* +luaL_Buffer *luaL_Buffer* >c typedef struct luaL_Buffer luaL_Buffer; < @@ -3099,7 +3096,7 @@ luaL_buffinit *luaL_buffinit()* 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 |luaL_Buffer()|). + the buffer must be declared as a variable (see |luaL_Buffer|). luaL_callmeta *luaL_callmeta()* >c @@ -3133,7 +3130,7 @@ luaL_checkinteger *luaL_checkinteger()* 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 |lua_Integer()|). + this number cast to a `lua_Integer` (see |lua_Integer|). luaL_checklong *luaL_checklong()* >c @@ -3154,7 +3151,7 @@ luaL_checknumber *luaL_checknumber()* lua_Number luaL_checknumber (lua_State *L, int narg); < Checks whether the function argument `narg` is a number and returns - this number (see |lua_Number()|). + this number (see |lua_Number|). luaL_checkoption *luaL_checkoption()* >c @@ -3334,7 +3331,7 @@ luaL_openlibs *luaL_openlibs()* 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. + |lua-openlibs| for details on how to open individual libraries. luaL_optint *luaL_optint()* >c @@ -3351,7 +3348,7 @@ luaL_optinteger *luaL_optinteger()* lua_Integer d); < If the function argument `narg` is a number, returns this number cast - to a `lua_Integer` (see |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()* @@ -3398,7 +3395,7 @@ luaL_prepbuffer *luaL_prepbuffer()* 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 |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 |luaL_addsize()|) with the size of the string to actually add it to the buffer. @@ -3428,7 +3425,7 @@ luaL_ref *luaL_ref()* constant `LUA_REFNIL`. The constant `LUA_NOREF` is guaranteed to be different from any reference returned by `luaL_ref`. -luaL_Reg *luaL_Reg()* +luaL_Reg *luaL_Reg* >c typedef struct luaL_Reg { const char *name; @@ -3449,7 +3446,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 |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 @@ -3507,7 +3504,7 @@ luaL_where *luaL_where()* This function is used to build a prefix for error messages. ============================================================================== -5 STANDARD LIBRARIES *luaref-Lib* +5 STANDARD LIBRARIES *lua-lib* The standard libraries provide useful functions that are implemented directly through the C API. Some of these functions provide essential services to the @@ -3531,7 +3528,7 @@ separate C modules. Currently, Lua has the following standard libraries: Except for the basic and package libraries, each library provides all its functions as fields of a global table or as methods of its objects. - *luaref-openlibs* + *lua-openlibs* To have access to these libraries, the C host program should call the `luaL_openlibs` function, which opens all standard libraries (see |luaL_openlibs()|). Alternatively, the host program can open the libraries @@ -3544,18 +3541,18 @@ 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 |lua_call()|). ============================================================================== -5.1 Basic Functions *luaref-libBasic* +5.1 Basic Functions *lua-lib-core* The basic library provides some core functions to Lua. If you do not include this library in your application, you should check carefully whether you need to provide implementations for some of its facilities. -assert({v} [, {message}]) *luaref-assert()* +assert({v} [, {message}]) *assert()* Issues an error when the value of its argument `v` is false (i.e., `nil` or `false`); otherwise, returns all its arguments. `message` is an error message; when absent, it defaults to "assertion failed!" -collectgarbage({opt} [, {arg}]) *luaref-collectgarbage()* +collectgarbage({opt} [, {arg}]) *collectgarbage()* This function is a generic interface to the garbage collector. It performs different functions according to its first argument, {opt}: @@ -3569,18 +3566,18 @@ collectgarbage({opt} [, {arg}]) *luaref-collectgarbage()* you must experimentally tune the value of {arg}. Returns `true` if the step finished a collection cycle. `"setpause"` sets {arg} /100 as the new value for the `pause` of - the collector (see |luaref-langGC|). + the collector (see |lua-gc|). `"setstepmul"` sets {arg} /100 as the new value for the `step - multiplier` of the collector (see |luaref-langGC|). + multiplier` of the collector (see |lua-gc|). -dofile({filename}) *luaref-dofile()* +dofile({filename}) *dofile()* Opens the named file and executes its contents as a Lua chunk. When called without arguments, `dofile` executes the contents of the standard input (`stdin`). Returns all values returned by the chunk. In case of errors, `dofile` propagates the error to its caller (that is, `dofile` does not run in protected mode). -error({message} [, {level}]) *luaref-error()* +error({message} [, {level}]) *error()* Terminates the last protected function called and returns `message` as the error message. Function {error} never returns. @@ -3592,27 +3589,27 @@ error({message} [, {level}]) *luaref-error()* a level 0 avoids the addition of error position information to the message. -_G *luaref-_G()* +_G *_G* A global variable (not a function) that holds the global environment (that is, `_G._G = _G`). Lua itself does not use this variable; changing its value does not affect any environment, nor vice-versa. (Use `setfenv` to change environments.) -getfenv({f}) *luaref-getfenv()* +getfenv({f}) *getfenv()* Returns the current environment in use by the function. {f} can be a Lua function or a number that specifies the function at that stack level: Level 1 is the function calling `getfenv`. If the given function is not a Lua function, or if {f} is 0, `getfenv` returns the global environment. The default for {f} is 1. -getmetatable({object}) *luaref-getmetatable()* +getmetatable({object}) *getmetatable()* If {object} does not have a metatable, returns `nil`. Otherwise, if the object's metatable has a `"__metatable"` field, returns the associated value. Otherwise, returns the metatable of the given object. -ipairs({t}) *luaref-ipairs()* - Returns three values: an iterator function, the table {t}, and 0, so +ipairs({t}) *ipairs()* + Returns three values: an |iterator| function, the table {t}, and 0, so that the construction `for i,v in ipairs(t) do` `body` `end` @@ -3620,7 +3617,7 @@ ipairs({t}) *luaref-ipairs()* will iterate over the pairs (`1,t[1]`), (`2,t[2]`), ..., up to the first integer key absent from the table. -load({func} [, {chunkname}]) *luaref-load()* +load({func} [, {chunkname}]) *load()* Loads a chunk using function {func} to get its pieces. Each call to {func} must return a string that concatenates with previous results. A return of `nil` (or no value) signals the end of the chunk. @@ -3632,12 +3629,12 @@ load({func} [, {chunkname}]) *luaref-load()* {chunkname} is used as the chunk name for error messages and debug information. -loadfile([{filename}]) *luaref-loadfile()* - Similar to `load` (see |luaref-load()|), but gets the chunk from file +loadfile([{filename}]) *loadfile()* + Similar to `load` (see |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 +loadstring({string} [, {chunkname}]) *loadstring()* + Similar to `load` (see |load()|), but gets the chunk from the given {string}. To load and run a given string, use the idiom @@ -3645,7 +3642,7 @@ loadstring({string} [, {chunkname}]) *luaref-loadstring()* assert(loadstring(s))() < -next({table} [, {index}]) *luaref-next()* +next({table} [, {index}]) *next()* Allows a program to traverse all fields of a table. Its first argument is a table and its second argument is an index in this table. `next` returns the next index of the table and its associated value. When @@ -3655,23 +3652,23 @@ next({table} [, {index}]) *luaref-next()* argument is absent, then it is interpreted as `nil`. In particular, you can use `next(t)` to check whether a table is empty. - 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.) + The order in which the indices are enumerated is not specified, even + for numeric indices. (To traverse a table in numeric order, use a + numerical `for` or the |ipairs()| function.) The behavior of `next` is `undefined` if, during the traversal, you assign any value to a non-existent field in the table. 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 - {t}, and `nil`, so that the construction +pairs({t}) *pairs()* + Returns three values: the |next()| function, the table {t}, and `nil`, + so that the construction `for k,v in pairs(t) do` `body` `end` will iterate over all key-value pairs of table {t}. -pcall({f}, {arg1}, {...}) *luaref-pcall()* +pcall({f}, {arg1}, {...}) *pcall()* Calls function {f} with the given arguments in `protected mode`. This means that any error inside {f} is not propagated; instead, `pcall` catches the error and returns a status code. Its first result is the @@ -3680,34 +3677,34 @@ pcall({f}, {arg1}, {...}) *luaref-pcall()* after this first result. In case of any error, `pcall` returns `false` plus the error message. -print({...}) *luaref-print()* +print({...}) *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` |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 |string.format()|). -rawequal({v1}, {v2}) *luaref-rawequal()* +rawequal({v1}, {v2}) *rawequal()* Checks whether {v1} is equal to {v2}, without invoking any metamethod. Returns a boolean. -rawget({table}, {index}) *luaref-rawget()* +rawget({table}, {index}) *rawget()* Gets the real value of `table[index]`, without invoking any metamethod. {table} must be a table; {index} may be any value. -rawset({table}, {index}, {value}) *luaref-rawset()* +rawset({table}, {index}, {value}) *rawset()* Sets the real value of `table[index]` to {value}, without invoking any metamethod. {table} must be a table, {index} any value different from `nil`, and {value} any Lua value. This function returns {table}. -select({index}, {...}) *luaref-select()* +select({index}, {...}) *select()* If {index} is a number, returns all arguments after argument number {index}. Otherwise, {index} must be the string `"#"`, and `select` returns the total number of extra arguments it received. -setfenv({f}, {table}) *luaref-setfenv()* +setfenv({f}, {table}) *setfenv()* Sets the environment to be used by the given function. {f} can be a Lua function or a number that specifies the function at that stack level: Level 1 is the function calling `setfenv`. `setfenv` returns @@ -3716,7 +3713,7 @@ setfenv({f}, {table}) *luaref-setfenv()* As a special case, when {f} is 0 `setfenv` changes the environment of the running thread. In this case, `setfenv` returns no values. -setmetatable({table}, {metatable}) *luaref-setmetatable()* +setmetatable({table}, {metatable}) *setmetatable()* Sets the metatable for the given table. (You cannot change the metatable of other types from Lua, only from C.) If {metatable} is `nil`, removes the metatable of the given table. If the original @@ -3724,7 +3721,7 @@ setmetatable({table}, {metatable}) *luaref-setmetatable()* This function returns {table}. -tonumber({e} [, {base}]) *luaref-tonumber()* +tonumber({e} [, {base}]) *tonumber()* Tries to convert its argument to a number. If the argument is already a number or a string convertible to a number, then `tonumber` returns this number; otherwise, it returns `nil`. @@ -3734,26 +3731,26 @@ tonumber({e} [, {base}]) *luaref-tonumber()* 10, the letter `A` (in either upper or lower case) represents 10, `B` represents 11, and so forth, with `Z'` representing 35. In base 10 (the default), the number may have a decimal part, as well as an - optional exponent part (see |luaref-langLexConv|). In other bases, + optional exponent part (see |lua-lexical|). In other bases, only unsigned integers are accepted. -tostring({e}) *luaref-tostring()* +tostring({e}) *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 |string.format()|). - *__tostring* + *__tostring* If the metatable of {e} has a `"__tostring"` field, `tostring` calls the corresponding value with {e} as argument, and uses the result of the call as its result. -type({v}) *luaref-type()* +type({v}) *lua-type()* Returns the type of its only argument, coded as a string. The possible results of this function are `"nil"` (a string, not the value `nil`), `"number"`, `"string"`, `"boolean`, `"table"`, `"function"`, `"thread"`, and `"userdata"`. -unpack({list} [, {i} [, {j}]]) *luaref-unpack()* +unpack({list} [, {i} [, {j}]]) *unpack()* Returns the elements from the given table. This function is equivalent to >lua @@ -3761,16 +3758,16 @@ unpack({list} [, {i} [, {j}]]) *luaref-unpack()* < except that the above code can be written only for a fixed number of elements. By default, {i} is 1 and {j} is the length of the list, as - defined by the length operator(see |luaref-langLength|). + defined by the length operator (see |lua-length|). -_VERSION *luaref-_VERSION()* +_VERSION *_VERSION* A global variable (not a function) that holds a string containing the current interpreter version. The current contents of this string is `"Lua 5.1"` . -xpcall({f}, {err}) *luaref-xpcall()* - This function is similar to `pcall` (see |luaref-pcall()|), except that - you can set a new error handler. +xpcall({f}, {err}) *xpcall()* + This function is similar to `pcall` (see |pcall()|), except that you + can set a new error handler. `xpcall` calls function {f} in protected mode, using {err} as the error handler. Any error inside {f} is not propagated; instead, @@ -3782,10 +3779,10 @@ xpcall({f}, {err}) *luaref-xpcall()* `false` plus the result from {err}. ============================================================================== -5.2 Coroutine Manipulation *luaref-libCoro* +5.2 Coroutine Manipulation *lua-lib-coroutine* The operations related to coroutines comprise a sub-library of the basic -library and come inside the table `coroutine`. See |luaref-langCoro| for a +library and come inside the table `coroutine`. See |lua-coroutine| for a general description of coroutines. coroutine.create({f}) *coroutine.create()* @@ -3826,18 +3823,18 @@ coroutine.wrap({f}) *coroutine.wrap()* coroutine.yield({...}) *coroutine.yield()* Suspends the execution of the calling coroutine. The coroutine cannot - be running a C function, a metamethod, or an iterator. Any arguments + be running a C function, a metamethod, or an |iterator|. Any arguments to `yield` are passed as extra results to `resume`. ============================================================================== -5.3 - Modules *luaref-libModule* +5.3 Modules *lua-modules* 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 |require()| and |module()|). Everything else is exported in a table `package`. -module({name} [, {...}]) *luaref-module()* +module({name} [, {...}]) *module()* Creates a module. If there is a table in `package.loaded[name]`, this table is the module. Otherwise, if there is a global table `t` with the given name, this table is the module. Otherwise creates a new @@ -3847,8 +3844,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()|) - returns `t`. + `package.loaded[name]`, so that |require()| returns `t`. If {name} is a compound name (that is, one with components separated by dots), `module` creates (or reuses, if they already exist) tables @@ -3858,7 +3854,7 @@ module({name} [, {...}]) *luaref-module()* This function may receive optional `options` after the module name, where each option is a function to be applied over the module. -require({modname}) *luaref-require()* +require({modname}) *require()* Loads the given module. The function starts by looking into the `package.loaded` table to determine whether {modname} is already loaded. If it is, then `require` returns the value stored at @@ -3901,7 +3897,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 @@ -3914,11 +3910,11 @@ package.loaded *package.loaded()* When you require a module `modname` and `package.loaded[modname]` is not false, `require` simply returns the value stored there. -package.loadlib({libname}, {funcname}) *package.loadlib()* +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 |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 @@ -3931,7 +3927,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 @@ -3952,7 +3948,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 |require()|). package.seeall({module}) *package.seeall()* Sets a metatable for {module} with its `__index` field referring to @@ -3960,7 +3956,7 @@ package.seeall({module}) *package.seeall()* global environment. To be used as an option to function {module}. ============================================================================== -5.4 - String Manipulation *luaref-libString* +5.4 String Manipulation *lua-lib-string* This library provides generic functions for string manipulation, such as finding and extracting substrings, and pattern matching. When indexing a @@ -3992,7 +3988,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 |loadstring()| on this string returns a copy of the function. {function} must be a Lua function without upvalues. @@ -4036,7 +4032,7 @@ string.format({formatstring}, {...}) *string.format()* This function does not accept string values containing embedded zeros. string.gmatch({s}, {pattern}) *string.gmatch()* - Returns an iterator function that, each time it is called, returns the + Returns an |iterator| function that, each time it is called, returns the next captures from {pattern} over string {s}. If {pattern} specifies no captures, then the whole match is produced @@ -4060,7 +4056,7 @@ string.gmatch({s}, {pattern}) *string.gmatch()* end < -string.gsub({s}, {pattern}, {repl} [, {n}]) *string.gsub()* +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 @@ -4101,16 +4097,16 @@ string.gsub({s}, {pattern}, {repl} [, {n}]) *string.gsub()* x = string.gsub("hello world from Lua", "(%w+)%s*(%w+)", "%2 %1") --> x="world hello Lua from" - x = string.gsub("home = `HOME, user = ` USER", "%$(%w+)", os.getenv) + x = string.gsub("home = $HOME, user = $USER", "%$(%w+)", os.getenv) --> x="home = /home/roberto, user = roberto" - x = string.gsub("4+5 = `return 4+5` ", "% `(.-)%` ", function (s) + x = string.gsub("4+5 = $return 4+5$", "%$(.-)%$", function (s) return loadstring(s)() end) --> x="4+5 = 9" local t = {name="lua", version="5.1"} - x = string.gsub(" `name%-` version.tar.gz", "%$(%w+)", t) + x = string.gsub("$name%-$version.tar.gz", "%$(%w+)", t) --> x="lua-5.1.tar.gz" < @@ -4154,7 +4150,7 @@ string.upper({s}) *string.upper()* locale. ------------------------------------------------------------------------------ -5.4.1 Patterns *luaref-patterns* *luaref-libStringPat* +5.4.1 Patterns *lua-patterns A character class is used to represent a set of characters. The following combinations are allowed in describing a character class: @@ -4199,9 +4195,8 @@ instance, `%S` represents all non-space characters. The definitions of letter, space, and other character groups depend on the current locale. In particular, the class `[a-z]` may not be equivalent to `%l`. - *luaref-patternitem* -Pattern Item:~ -------------- +PATTERN ITEM *lua-patternitem* + A pattern item may be - a single character class, which matches any single character in the @@ -4226,17 +4221,15 @@ A pattern item may be `y` where the count reaches 0. For instance, the item `%b()` matches expressions with balanced parentheses. - *luaref-pattern* -Pattern:~ --------- +PATTERN *lua-pattern* + A pattern is a sequence of pattern items. A `^` at the beginning of a pattern anchors the match at the beginning of the subject string. A `$` at the end of a pattern anchors the match at the end of the subject string. At other positions, `^` and `$` have no special meaning and represent themselves. - *luaref-capture* -Captures:~ ---------- +CAPTURES *lua-capture* + A pattern may contain sub-patterns enclosed in parentheses; they describe captures. When a match succeeds, the substrings of the subject string that match captures are stored (captured) for future use. Captures are numbered @@ -4252,7 +4245,7 @@ string `"flaaap"`, there will be two captures: 3 and 5. A pattern cannot contain embedded zeros. Use `%z` instead. ============================================================================== -5.5 Table Manipulation *luaref-libTable* +5.5 Table Manipulation *lua-lib-table* This library provides generic functions for table manipulation. It provides all its functions inside the table `table`. @@ -4268,15 +4261,15 @@ table.concat({table} [, {sep} [, {i} [, {j}]]]) *table.concat()* for {j} is the length of the table. If {i} is greater than {j}, returns the empty string. -table.foreach({table}, {f}) *table.foreach()* +table.foreach({table}, {f}) *table.foreach()* Executes the given {f} over all elements of {table}. For each element, {f} is called with the index and respective value as arguments. If {f} returns a non-`nil` value, then the loop is broken, and this value is returned as the final value of `table.foreach`. - See |luaref-next()| for extra information about table traversals. + See |next()| for extra information about table traversals. -table.foreachi({table}, {f}) *table.foreachi()* +table.foreachi({table}, {f}) *table.foreachi()* Executes the given {f} over the numerical indices of {table}. For each index, {f} is called with the index and respective value as arguments. Indices are visited in sequential order, from 1 to `n`, where `n` is @@ -4288,7 +4281,7 @@ table.insert({table}, [{pos},] {value}) *table.insert()* Inserts element {value} at position {pos} in {table}, shifting up other elements to open space, if necessary. The default value for {pos} is `n+1`, where `n` is the length of the table (see - |luaref-langLength|), so that a call `table.insert(t,x)` inserts `x` + |lua-length|), so that a call `table.insert(t,x)` inserts `x` at the end of table `t`. table.maxn({table}) *table.maxn()* @@ -4296,27 +4289,26 @@ table.maxn({table}) *table.maxn()* zero if the table has no positive numerical indices. (To do its job this function does a linear traversal of the whole table.) -table.remove({table} [, {pos}]) *table.remove()* +table.remove({table} [, {pos}]) *table.remove()* Removes from {table} the element at position {pos}, shifting down other elements to close the space, if necessary. Returns the value of the removed element. The default value for {pos} is `n`, where `n` is - the length of the table (see |luaref-langLength|), so that a call + the length of the table (see |lua-length|), so that a call `table.remove(t)` removes the last element of table `t`. -table.sort({table} [, {comp}]) *table.sort()* +table.sort({table} [, {comp}]) *table.sort()* Sorts table elements in a given order, `in-place`, from `table[1]` to - `table[n]`, where `n` is the length of the table (see - |luaref-langLength|). If {comp} is given, then it must be a function - that receives two table elements, and returns true when the first is - less than the second (so that `not comp(a[i+1],a[i])` will be true - after the sort). If {comp} is not given, then the standard Lua - operator `<` is used instead. + `table[n]`, where `n` is the length of the table (see |lua-length|). + If {comp} is given, then it must be a function that receives two table + elements, and returns true when the first is less than the second (so + that `not comp(a[i+1],a[i])` will be true after the sort). If {comp} + is not given, then the standard Lua operator `<` is used instead. The sort algorithm is `not` stable, that is, elements considered equal by the given order may have their relative positions changed by the sort. ============================================================================== -5.6 Mathematical Functions *luaref-libMath* +5.6 Mathematical Functions *lua-lib-math* This library is an interface to most of the functions of the standard C math library. It provides all its functions inside the table `math`. @@ -4364,7 +4356,7 @@ math.frexp({x}) *math.frexp()* absolute value of `m` is in the range `[0.5, 1)` (or zero when {x} is zero). -math.huge *math.huge()* +math.huge *math.huge* The value `HUGE_VAL`, a value larger than or equal to any other numerical value. @@ -4387,7 +4379,7 @@ math.modf({x}) *math.modf()* Returns two numbers, the integral part of {x} and the fractional part of {x}. -math.pi *math.pi()* +math.pi *math.pi* The value of `pi`. math.pow({x}, {y}) *math.pow()* @@ -4429,7 +4421,7 @@ math.tanh({x}) *math.tanh()* Returns the hyperbolic tangent of {x}. ============================================================================== -5.6 Input and Output Facilities *luaref-libIO* +5.6 Input and Output Facilities *lua-lib-io* The I/O library provides two different styles for file manipulation. The first one uses implicit file descriptors; that is, there are operations to set a @@ -4467,7 +4459,7 @@ io.input([{file}]) *io.input()* an error code. io.lines([{filename}]) *io.lines()* - Opens the given file name in read mode and returns an iterator + Opens the given file name in read mode and returns an |iterator| function that, each time it is called, returns a new line from the file. Therefore, the construction @@ -4527,16 +4519,16 @@ io.type({obj}) *io.type()* io.write({...}) *io.write()* Equivalent to `io.output():write`. -file:close() *luaref-file:close()* +file:close() *file:close()* Closes `file`. Note that files are automatically closed when their handles are garbage collected, but that takes an unpredictable amount of time to happen. -file:flush() *luaref-file:flush()* +file:flush() *file:flush()* Saves any written data to `file`. -file:lines() *luaref-file:lines()* - Returns an iterator function that, each time it is called, returns a +file:lines() *file:lines()* + Returns an |iterator| function that, each time it is called, returns a new line from the file. Therefore, the construction `for line in file:lines() do` `body` `end` @@ -4544,7 +4536,7 @@ file:lines() *luaref-file:lines()* will iterate over all lines of the file. (Unlike `io.lines`, this function does not close the file when the loop ends.) -file:read({...}) *luaref-file:read()* +file:read({...}) *file:read()* Reads the file `file`, according to the given formats, which specify what to read. For each format, the function returns a string (or a number) with the characters read, or `nil` if it cannot read data with @@ -4563,7 +4555,7 @@ file:read({...}) *luaref-file:read()* returning `nil` on end of file. If number is zero, it reads nothing and returns an empty string, or `nil` on end of file. -file:seek([{whence}] [, {offset}]) *luaref-file:seek()* +file:seek([{whence}] [, {offset}]) *file:seek()* Sets and gets the file position, measured from the beginning of the file, to the position given by {offset} plus a base specified by the string {whence}, as follows: @@ -4583,7 +4575,7 @@ file:seek([{whence}] [, {offset}]) *luaref-file:seek()* `file:seek("end")` sets the position to the end of the file, and returns its size. -file:setvbuf({mode} [, {size}]) *luaref-file:setvbuf()* +file:setvbuf({mode} [, {size}]) *file:setvbuf()* Sets the buffering mode for an output file. There are three available modes: @@ -4599,14 +4591,14 @@ file:setvbuf({mode} [, {size}]) *luaref-file:setvbuf()* For the last two cases, {size} specifies the size of the buffer, in bytes. The default is an appropriate size. -file:write({...}) *luaref-file:write()* +file:write({...}) *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` |string.format()| before + |tostring()| or `string.format` |string.format()| before `write`. ============================================================================== -5.8 Operating System Facilities *luaref-libOS* +5.8 Operating System Facilities *lua-lib-os* This library is implemented through table `os`. @@ -4691,7 +4683,7 @@ os.tmpname() *os.tmpname()* removed when no longer needed. ============================================================================== -5.9 The Debug Library *luaref-libDebug* +5.9 The Debug Library *lua-lib-debug* This library provides the functionality of the debug interface to Lua programs. You should exert care when using this library. The functions @@ -4765,7 +4757,7 @@ debug.getmetatable({object}) *debug.getmetatable()* have a metatable. debug.getregistry() *debug.getregistry()* - Returns the registry table (see |luaref-apiRegistry|). + Returns the registry table (see |lua-registry|). debug.getupvalue({func}, {up}) *debug.getupvalue()* This function returns the name and the value of the upvalue with index @@ -4826,7 +4818,7 @@ debug.traceback([{thread},] [{message}] [,{level}]) *debug.traceback()* (default is 1, the function calling `traceback`). ============================================================================== -A BIBLIOGRAPHY *luaref-bibliography* +A BIBLIOGRAPHY *lua-ref-bibliography* This help file is a minor adaptation from this main reference: @@ -4852,7 +4844,7 @@ Lua is discussed in these references: "Proc. of V Brazilian Symposium on Programming Languages" (2001) B-14-B-28. ============================================================================== -B COPYRIGHT AND LICENSES *luaref-copyright* +B COPYRIGHT AND LICENSES *lua-ref-copyright* This help file has the same copyright and license as Lua 5.1 and the Lua 5.1 manual: @@ -4878,12 +4870,12 @@ copies or substantial portions of the Software. SOFTWARE. ============================================================================== -C LUAREF DOC *luarefvim* *luarefvimdoc* *luaref-help* *luaref-doc* +C LUAREF DOC *lua-ref-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-doc|. For copyright information, see |luaref-copyright|. +(see |lua-ref-bibliography|). For usage information, refer to +|lua-ref-doc|. For copyright information, see |lua-ref-copyright|. The main ideas and concepts on how to implement this reference were taken from Christian Habermann's CRefVim project |