diff options
| author | Anton Bobov <abobov@gmail.com> | 2013-10-03 09:48:51 +0600 |
|---|---|---|
| committer | Anton Bobov <abobov@gmail.com> | 2013-10-03 09:53:41 +0600 |
| commit | a909de07c5f982968cb8cd0f2101ac052f4a0034 (patch) | |
| tree | 99111641ac662d8b437d885befe50ff1a3f3dbf9 /files/.vim/doc/lua51refvim.txt | |
| parent | ede4983c110a5947fa034857a5e37bdbb03ab49a (diff) | |
Vim plugins cleaning up.
Diffstat (limited to 'files/.vim/doc/lua51refvim.txt')
| -rw-r--r-- | files/.vim/doc/lua51refvim.txt | 5617 |
1 files changed, 0 insertions, 5617 deletions
diff --git a/files/.vim/doc/lua51refvim.txt b/files/.vim/doc/lua51refvim.txt deleted file mode 100644 index e80d613..0000000 --- a/files/.vim/doc/lua51refvim.txt +++ /dev/null @@ -1,5617 +0,0 @@ -*luarefvim.txt* Lua 5.1 Reference Manual for Vim - Vim version 7.0 - - - *luaref* *Lua-Reference* - Lua Reference for Vim - ========================= - Version 0.2.0 - November, 25th, 2006 - - (c) 2006 by Luis Carvalho - <lexcarvalho at gmail dot com> - - Adapted from "Lua: 5.1 reference manual" - R. Ierusalimschy, L. H. de Figueiredo, W. Celes - Copyright (c) 2006 Lua.org, PUC-Rio. - - - See |lrv-doc| for information on this manual. - See |lrv-copyright| for copyright and licenses. - - - CONTENTS - ============ - - 1 INTRODUCTION........................|lrv-intro| - - 2 THE LANGUAGE........................|lrv-language| - 2.1 Lexical Conventions...............|lrv-langLexConv| - 2.2 Values and Types..................|lrv-langValTypes| - 2.2.1 Coercion........................|lrv-langCoercion| - 2.3 Variables.........................|lrv-langVariables| - 2.4 Statements........................|lrv-langStats| - 2.4.1 Chunks..........................|lrv-langChunks| - 2.4.2 Blocks..........................|lrv-langBlocks| - 2.4.3 Assignment......................|lrv-langAssign| - 2.4.4 Control Structures..............|lrv-langContStructs| - 2.4.5 For Statement...................|lrv-langForStat| - 2.4.6 Function Calls as Statements....|lrv-langFuncStat| - 2.4.7 Local Declarations..............|lrv-langLocalDec| - 2.5 Expressions.......................|lrv-langExpressions| - 2.5.1 Arithmetic Operators............|lrv-langArithOp| - 2.5.2 Relational Operators............|lrv-langRelOp| - 2.5.3 Logical Operators...............|lrv-langLogOp| - 2.5.4 Concatenation...................|lrv-langConcat| - 2.5.5 The Length Operator.............|lrv-langLength| - 2.5.6 Precedence......................|lrv-langPrec| - 2.5.7 Table Constructors..............|lrv-langTableConst| - 2.5.8 Function Calls..................|lrv-langFuncCalls| - 2.5.9 Function Definitions............|lrv-langFuncDefs| - 2.6 Visibility Rules..................|lrv-langVisibRules| - 2.7 Error Handling....................|lrv-langError| - 2.8 Metatables........................|lrv-langMetatables| - 2.9 Environments......................|lrv-langEnvironments| - 2.10 Garbage Collection...............|lrv-langGC| - 2.10.1 Garbage-Collection Metamethods.|lrv-langGCMeta| - 2.10.2 Weak Tables....................|lrv-langWeaktables| - 2.11 Coroutines.......................|lrv-langCoro| - - 3 THE APPLICATION PROGRAM INTERFACE...|lrv-api| - 3.1 The Stack.........................|lrv-apiStack| - 3.2 Stack Size........................|lrv-apiStackSize| - 3.3 Pseudo-Indices....................|lrv-apiPseudoIndices| - 3.4 C Closures........................|lrv-apiCClosures| - 3.5 Registry..........................|lrv-apiRegistry| - 3.6 Error Handling in C...............|lrv-apiError| - 3.7 Functions and Types...............|lrv-apiFunctions| - 3.8 The Debug Interface...............|lrv-apiDebug| - - 4 THE AUXILIARY LIBRARY...............|lrv-aux| - 4.1 Functions and Types...............|lrv-auxFunctions| - - 5 STANDARD LIBRARIES..................|lrv-lib| - 5.1 Basic Functions...................|lrv-libBasic| - 5.2 Coroutine Manipulation............|lrv-libCoro| - 5.3 Modules...........................|lrv-libModule| - 5.4 String Manipulation...............|lrv-libString| - 5.4.1 Patterns........................|lrv-libStringPat| - 5.5 Table Manipulation................|lrv-libTable| - 5.6 Mathematical Functions............|lrv-libMath| - 5.7 Input and Output Facilities.......|lrv-libIO| - 5.8 Operating System Facilities.......|lrv-libOS| - 5.9 The Debug Library.................|lrv-libDebug| - - 6 LUA STAND-ALONE.....................|lrv-LuaSA| - - A INDEX...............................|lrv-index| - B BIBLIOGRAPHY........................|lrv-bibliography| - C COPYRIGHT & LICENSES................|lrv-copyright| - D LUAREFVIM DOC.......................|lrv-doc| - D.1 Installation.......................|lrv-docInstall| - D.2 Usage..............................|lrv-docUsage| - - -============================================================================== -1 INTRODUCTION *lrv-intro* -============================================================================== - -Lua is an extension programming language designed to support general -procedural programming with data description facilities. It also offers good -support for object-oriented programming, functional programming, and -data-driven programming. Lua is intended to be used as a powerful, -light-weight scripting language for any program that needs one. Lua is -implemented as a library, written in@clean@C (that is, in the common subset -of ANSI C and C++). - -Being an extension language, Lua has no notion of a "main" program: it only -works@embedded@in a host client, called the@embedding program@or simply -the@host@. This host program can invoke functions to execute a piece of Lua -code, can write and read Lua variables, and can register C functions to be -called by Lua code. Through the use of C functions, Lua can be augmented to -cope with a wide range of different domains, thus creating customized -programming languages sharing a syntactical framework. - -The Lua distribution includes a sample host program called$lua$, which uses -the Lua library to offer a complete, stand-alone Lua interpreter. - -Lua is free software, and is provided as usual with no guarantees, as stated -in its license. The implementation described in this manual is available at -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 -|lrv-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 *lrv-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@. -Non-terminals are shown in@italics@, keywords are shown in#bold#, and other -terminal symbols are shown in$typewriter$color, enclosed in single quotes. - - -============================================================================== -2.1 Lexical Conventions *lrv-langLexConv* - - - *lrv-names* *lrv-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 -on the current locale: any character considered alphabetic by the current -locale can be used in an identifier.) Identifiers are used to name variables -and table fields. - -The following@keywords@are reserved and cannot be used as names: -> - and break do else elseif - end false for function if - in local nil not or - repeat return then true until while -< -Lua is a case-sensitive language:$and$is a reserved word, but$And$and$AND$are -two different, valid names. As a convention, names starting with an underscore -followed by uppercase letters (such as$_VERSION$) are reserved for internal -global variables used by Lua. - -The following strings denote other tokens: -> - + - * / % ^ # - == ~= <= >= < > = - ( ) { } [ ] - ; : , . .. ... -> - *lrv-literal* -@Literal strings@can be delimited by matching single or double quotes, and can -contain the following C-like escape sequences: - - #o#$\a$: bell - #o#$\b$: backspace - #o#$\f$: form feed - #o#$\n$: newline - #o#$\r$: carriage return - #o#$\t$: horizontal tab - #o#$\v$: vertical tab - #o#$\\$: backslash - #o#$\"$: quotation mark (double quote) - #o#$\'$: apostrophe (single quote) - -Moreover, a backslash followed by a real newline results in a newline in the -string. A character in a string may also be specified by its numerical value -using the escape sequence$`\ddd'$, where@ddd@is a sequence of up to three -decimal digits. (Note that if a numerical escape is to be followed by a digit, -it must be expressed using exactly three digits.) Strings in Lua may contain -any 8-bit value, including embedded zeros, which can be specified as$`\0'$. - -To put a double (single) quote, a newline, a backslash, or an embedded zero -inside a literal string enclosed by double (single) quotes you must use an -escape sequence. Any other character may be directly inserted into the -literal. (Some control characters may cause problems for the file system, but -Lua has no problem with them.) - -Literal strings can also be defined using a long format enclosed by -@long brackets@. We define an@opening long bracket of level n@as an opening -square bracket followed by@n@ equal signs followed by another opening square -bracket. So, an opening long bracket of level 0 is written as$[[$, an opening -long bracket of level 1 is written as$[=[$, and so on. -A@closing long bracket@is defined similarly; for instance, a closing long -bracket of level 4 is written as$]====]$. A long string starts with an opening -long bracket of any level and ends at the first closing long bracket of the -same level. Literals in this bracketed form may run for several lines, do not -interpret any escape sequences, and ignore long brackets of any other level. -They may contain anything except a closing bracket of the proper level. - -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: -> - a = 'alo\n123"' - a = "alo\n123\"" - a = '\97lo\10\04923"' - a = [[alo - 123"]] - a = [==[ - alo - 123"]==] -> - *lrv-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 -> - *lrv-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 comment@, which runs until the corresponding closing long bracket. Long -comments are frequently used to disable code temporarily. - -============================================================================== -2.2 Values and Types *lrv-langValTypes* - - -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 -values carry their own type. - -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. - - *lrv-types* *lrv-nil* *lrv-true* *lrv-false* *lrv-number* *lrv-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 -represents the absence of a useful value.@Boolean@is the type of the -values#false#and#true#. Both#nil#and#false#make a condition false; any other -value makes it true.@Number@represents real (double-precision floating-point) -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 |lrv-literal|). - -Lua can call (and manipulate) functions written in Lua and functions written -in C (see |lrv-langFuncCalls|). - - *lrv-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 |lrv-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. - - *lrv-thread* -The type@thread@represents independent threads of execution and it is used to -implement coroutines (see |lrv-langCoro|). Do not confuse Lua threads with -operating-system threads. Lua supports coroutines on all systems, even those -that do not support threads. - - *lrv-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#nil#). Tables are the sole data structuring mechanism in Lua; they may -be 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 -|lrv-langTableConst|). - -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 |lrv-langFuncDefs|). - -Tables, functions, threads and (full) userdata values are@objects@: variables -do not actually@contain@these values, only@references@to them. Assignment, -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 |lrv-type|). - - ------------------------------------------------------------------------------- -2.2.1 Coercion *lrv-langCoercion* - -Lua provides automatic conversion between string and number values at run -time. Any arithmetic operation applied to a string tries to convert that -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 -|lrv-string.format|). - - -============================================================================== -2.3 Variables *lrv-langVariables* - - -Variables are places that store values. There are three kinds of variables in -Lua: global variables, local variables, and table fields. - -A single name can denote a global variable or a local variable (or a -function's formal parameter, which is a particular form of local variable): -> - var ::= Name -> -Name denotes identifiers, as defined in |lrv-langLexConv|. - -Any variable is assumed to be global unless explicitly declared as a local -(see |lrv-langLocalDec|). Local variables are@lexically scoped@: local -variables can be freely accessed by functions defined inside their scope (see -|lrv-langVisibRules|). - -Before the first assignment to a variable, its value is#nil#. - -Square brackets are used to index a table: - - $var ::= prefixexp$#`['#$exp$#`]'# - -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 -|lrv-langExpressions| 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 |lrv-langEnvironments|). -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 |lrv-getfenv|). To replace it, you call$setfenv$(see -|lrv-setfenv|). (You can only manipulate the environment of C functions -through the debug library; see |lrv-libDebug|.) - -An access to a global variable$x$is equivalent to$_env.x$, which in turn is -equivalent to -> - gettable_event(_env, "x") -> -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.) - -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 |lrv-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.) - - -============================================================================== -2.4 Statements *lrv-langStats* - - -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 *lrv-chunk* *lrv-langChunks* - - -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 -optionally followed by a semicolon: - - $chunk ::= {stat [$#`;'#$]}$ - -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 |lrv-langFuncDefs|). 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 -chunk is executed, first it is pre-compiled into instructions for a virtual -machine, and then the compiled code is executed by an interpreter for the -virtual machine. - -Chunks may also be pre-compiled into binary form; see program$luac$for -details. Programs in source and compiled forms are interchangeable; Lua -automatically detects the file type and acts accordingly. - - ------------------------------------------------------------------------------- -2.4.2 Blocks *lrv-block* *lrv-langBlocks* - - -A block is a list of statements; syntactically, a block is the same as a -chunk: -> - block ::= chunk -> - *lrv-do* *lrv-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 |lrv-langContStructs|). - - ------------------------------------------------------------------------------- -2.4.3 Assignment *lrv-langAssign* - - -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 -side. The elements in both lists are separated by commas: - - $stat ::= varlist1$#`='#$explist1$ - $varlist1 ::= var {$#`,'#$var }$ - $explist1 ::= exp {$#`,'#$exp }$ - -Expressions are discussed in |lrv-langExpressions|. - -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 -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 -|lrv-langExpressions|). - -The assignment statement first evaluates all its expressions and only then are -the assignments performed. Thus the code -> - 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 -> - x, y = y, x -> -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 |lrv-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.) - -An assignment to a global variable$x = val$is equivalent to the -assignment$_env.x = val$, which in turn is equivalent to -> - settable_event(_env, "x", val) -> -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 *lrv-langContStructs* - - *lrv-if* *lrv-then* *lrv-else* *lrv-elseif* - *lrv-while* *lrv-repeat* *lrv-until* -The control structures#if#,#while#, and#repeat#have the usual meaning and -familiar syntax: - - $stat ::=$#while#$exp$#do#$block$#end# - $stat ::=$#repeat#$block$#until#$exp$ - $stat ::=$#if#$exp$#then#$block {$#elseif#$exp$#then#$block }$ - $[$#else#$block ]$#end# - -Lua also has a#for#statement, in two flavors (see |lrv-langForStat|). - -The condition expression of a control structure may return any value. -Both#false#and#nil#are considered false. All values different -from#nil#and#false#are considered true (in particular, the number 0 and the -empty string are also true). - -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. - - *lrv-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]$ - - *lrv-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: - - $stat ::=$#break# - -A#break#ends the innermost enclosing loop. - -The#return#and#break#statements can only be written as the@last@statement of a -block. If it is really necessary to#return#or#break#in the middle of a block, -then an explicit inner block can be used, as in the idioms -$`do return end'$and$`do break end'$, because now#return#and#break#are the -last statements in their (inner) blocks. - - ------------------------------------------------------------------------------- -2.4.5 For Statement *lrv-for* *lrv-langForStat* - - -The#for#statement has two forms: one numeric and one generic. - -The numeric#for#loop repeats a block of code while a control variable runs -through an arithmetic progression. It has the following syntax: - - $stat ::=$#for#$Name$#`='#$exp$#`,'#$exp [$#`,'#$exp ]$#do#$block$#end# - -The@block@is repeated for@name@starting at the value of the first@exp@, until -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$ - -is equivalent to the code: - - $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: - - #o#All three control expressions are evaluated only once, before the loop - starts. They must all result in numbers. - #o#@var@,@limit@and@step@are invisible variables. The names are here for - explanatory purposes only. - #o#If the third expression (the step) is absent, then a step of 1 is used. - #o#You can use#break#to exit a#for#loop. - #o#The loop variable$var$is local to the loop; you cannot use its value - after the#for#ends or is broken. If you need this value, assign it to - another variable before breaking or exiting the loop. - - *lrv-in* -The generic#for#statement works over functions, called@iterators@. 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: - - $stat ::=$#for#$namelist$#in#$explist1$#do#$block$#end# - $namelist ::= Name {$#`,'#$Name }$ - -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$ - -Note the following: - - #o#@explist@is evaluated only once. Its results are an@iterator@function, - a@state@, and an initial value for the first@iterator variable@. - #o#@f@,@s@, and@var@are invisible variables. The names are here for - explanatory purposes only. - #o#You can use#break#to exit a#for#loop. - #o#The loop variables@var1, ..., varn@are local to the loop; you cannot use - their values after the#for#ends. If you need these values, then assign - them to other variables before breaking or exiting the loop. - - ------------------------------------------------------------------------------- -2.4.6 Function Calls as Statements *lrv-langFuncStat* - - -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 |lrv-langFuncCalls|. - - ------------------------------------------------------------------------------- -2.4.7 Local Declarations *lrv-local* *lrv-langLocalDec* - - -Local variables may be declared anywhere inside a block. The declaration may -include an initial assignment: - - $stat ::=$#local#$namelist [$#`='#$explist1 ]$ - $namelist ::= Name {$#`,'#$Name }$ - -If present, an initial assignment has the same semantics of a multiple -assignment (see |lrv-langAssign|). Otherwise, all variables are initialized -with#nil#. - -A chunk is also a block (see |lrv-langChunks|), 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 -|lrv-langVisibRules|. - - -============================================================================== -2.5 Expressions *lrv-langExpressions* - - -The basic expressions in Lua are the following: - - $exp ::= prefixexp$ - $exp ::=$#nil#$|$#false#$|$#true# - $exp ::= Number$ - $exp ::= String$ - $exp ::= function$ - $exp ::= tableconstructor$ - $exp ::=$#`...'# - $exp ::= exp binop exp$ - $exp ::= unop exp$ - $prefixexp ::= var | functioncall |$#`('#$exp$#`)'# - -Numbers and literal strings are explained in |lrv-langLexConv|; variables are -explained in |lrv-langVariables|; function definitions are explained in -|lrv-langFuncDefs|; function calls are explained in |lrv-langFuncCalls|; -table constructors are explained in |lrv-langTableConst|. Vararg expressions, -denoted by three dots ($`...'$), can only be used inside vararg functions; -they are explained in |lrv-langFuncDefs|. - -Binary operators comprise arithmetic operators (see |lrv-langArithOp|), -relational operators (see |lrv-langRelOp|), logical operators (see -|lrv-langLogOp|), and the concatenation operator (see |lrv-langConcat|). -Unary operators comprise the unary minus (see |lrv-labgArithOp|), the unary -#not# (see |lrv-langLogOp|), and the unary@length operator@(see -|lrv-langLength|). - -Both function calls and vararg expressions may result in multiple values. If -the expression is used as a statement (see |lrv-langFuncStat|) -(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 -made (unless the call is enclosed in parentheses). In all other contexts, Lua -adjusts the result list to one element, discarding all values except the first -one. - -Here are some examples: -> - 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() - a,b,c = f(), x -- f() is adjusted to 1 result (c gets nil) - a,b = ... -- a gets the first vararg parameter, b gets - -- the second (both a and b may get nil if there - -- is no corresponding vararg parameter) - - a,b,c = x, f() -- f() is adjusted to 2 results - a,b,c = f() -- f() is adjusted to 3 results - return f() -- returns all results from f() - return ... -- returns all received vararg parameters - return x,y,f() -- returns x, y, and all results from f() - {f()} -- creates a list with all results from f() - {...} -- creates a list with all vararg parameters - {f(), nil} -- f() is adjusted to 1 result -> -An expression enclosed in parentheses always results in only one value. Thus, -$(f(x,y,z))$is always a single value, even if$f$returns several values. -(The value of$(f(x,y,z))$is the first value returned by$f$or#nil#if$f$does not -return any values.) - - ------------------------------------------------------------------------------- -2.5.1 Arithmetic Operators *lrv-langArithOp* - - -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 |lrv-langCoercion|), 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 -> - a % b == a - math.floor(a/b)*b -> -That is, it is the remainder of a division that rounds the quotient towards -minus infinity. - - ------------------------------------------------------------------------------- -2.5.2 Relational Operators *lrv-langRelOp* - - -The relational operators in Lua are -> - == ~= < > <= >= -> -These operators always result in#false#or#true#. - -Equality ($==$) first compares the type of its operands. If the types are -different, then the result is#false#. Otherwise, the values of the operands -are compared. Numbers and strings are compared in the usual way. Objects -(tables, userdata, threads, and functions) are compared by@reference@: two -objects are considered equal only if they are the@same@object. Every time you -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 |lrv-langMetatables|). - -The conversion rules of coercion |lrv-langCoercion|@do not@apply to equality -comparisons. Thus,$"0"==0$evaluates to#false#, and$t[0]$and$t["0"]$denote -different entries in a table. - -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 |lrv-langMetatables|). - - ------------------------------------------------------------------------------- -2.5.3 Logical Operators *lrv-langLogOp* - - -The logical operators in Lua are -> - and or not -> -Like the control structures (see |lrv-langContStructs|), all logical operators -consider both#false#and#nil#as false and anything else as true. - - *lrv-not* *lrv-and* *lrv-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 -operator#or#returns its first argument if this value is different -from#nil#and#false#; otherwise,#or#returns its second argument. -Both#and#and#or#use short-cut evaluation, that is, the second operand is -evaluated only if necessary. Here are some examples: -> - 10 or 20 --> 10 - 10 or error() --> 10 - nil or "a" --> "a" - nil and 10 --> nil - false and error() --> false - false and nil --> false - false or nil --> nil - 10 and 20 --> 20 -> -(In this manual,$-->$indicates the result of the preceding expression.) - - ------------------------------------------------------------------------------- -2.5.4 Concatenation *lrv-langConcat* - - -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 |lrv-langCoercion|. Otherwise, the -"concat" metamethod is called (see |lrv-langMetatables|). - - ------------------------------------------------------------------------------- -2.5.5 The Length Operator *lrv-langLength* - - -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 -when each character is one byte). - -The length of a table$t$is defined to be any integer index$n$such that$t[n]$is -not#nil#and$t[n+1]$is#nil#; moreover, if$t[1]$is#nil#,$n$may be zero. For a -regular array, with non-nil values from 1 to a given$n$, its length is exactly -that$n$, the index of its last value. If the array has "holes" (that -is,#nil#values between other non-nil values), then$#t$may be any of the -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 *lrv-langPrec* - - -Operator precedence in Lua follows the table below, from lower to higher -priority: -> - or - and - < > <= >= ~= == - .. - + - - * / - not # - (unary) - ^ -> -As usual, you can use parentheses to change the precedences in an expression. -The concatenation ($`..'$) and exponentiation ($`^'$) operators are right -associative. All other binary operators are left associative. - - ------------------------------------------------------------------------------- -2.5.7 Table Constructors *lrv-langTableConst* - - -Table constructors are expressions that create tables. Every time a -constructor is evaluated, a new table is created. Constructors can be used to -create empty tables, or to create a table and initialize some of its fields. -The general syntax for constructors is - - $tableconstructor ::=$#`{'#$[ fieldlist ]$#`}'# - $fieldlist ::= field { fieldsep field } [ fieldsep ]$ - $field ::=$#`['#$exp$#`]' `='#$exp | Name$#`='#$exp | exp$ - $fieldsep ::=$ #`,'#$|$ #`;'# - -Each field of the form$[exp1] = exp2$adds to the new table an entry with -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, -> - a = { [f(1)] = g; "x", "y"; x = 1, f(x), [30] = 23; 45 } -> -is equivalent to -> - do - local t = {} - t[f(1)] = g - t[1] = "x" -- 1st exp - t[2] = "y" -- 2nd exp - t.x = 1 -- temp["x"] = 1 - t[3] = f(x) -- 3rd exp - t[30] = 23 - t[4] = 45 -- 4th exp - a = t - end -> -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 |lrv-langFuncCalls|). To avoid this, enclose the function -call in parentheses (see |lrv-langExpressions|). - -The field list may have an optional trailing separator, as a convenience for -machine-generated code. - - ------------------------------------------------------------------------------- -2.5.8 Function Calls *lrv-function* *lrv-langFuncCalls* - - -A function call in Lua has the following syntax: -> - functioncall ::= prefixexp args -> -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 |lrv-langMetatables|). - -The form - - $functioncall ::= prefixexp$#`:'#$Name args$ - -can be used to call "methods". A call$v:name($@args@$)$is syntactic sugar -for$v.name(v,$@args@$)$, except that$v$is evaluated only once. - -Arguments have the following syntax: - - $args ::= $#`('#$[ explist1 ]$#`)'# - $args ::= tableconstructor$ - $args ::= String$ - -All argument expressions are evaluated before the call. A call of the -form$f{$@fields@$}$is syntactic sugar for $f({$@fields@$})$, that is, the -argument list is a single new table. A call of the form$f'$@string@$'$ -(or$f"$@string@$"$or$f[[$@string@$]]$) is syntactic sugar for -$f('$@string@$')$, that is, the argument list is a single literal 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 -> - a = f - (g).x(a) -> -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)$. - - *lrv-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, -there is no limit on the number of nested tail calls that a program can -execute. However, a tail call erases any debug information about the calling -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: -> - return (f(x)) -- results adjusted to 1 - return 2 * f(x) - return x, f(x) -- additional results - f(x); return -- results discarded - return x or f(x) -- results adjusted to 1 -> - ------------------------------------------------------------------------------- -2.5.9 Function Definitions *lrv-langFuncDefs* - - -The syntax for function definition is - - $function ::=$#function#$funcbody$ - $funcbody ::=$#`('#$[ parlist1 ]$#`)'#$block$#end# - -The following syntactic sugar simplifies function definitions: - - $stat ::=$#function#$funcname funcbody$ - $stat ::=$#local function#$Name funcbody$ - $funcname ::= Name {$#`.'#$Name } [$#`:'#$Name ]$ - -The statement - - $function f ()$@body@$end$ - -translates to - - $f = function ()$@body@$end$ - -The statement - - $function t.a.b.c.f ()$@body@$end$ - -translates to - - $t.a.b.c.f = function ()$@body@$end$ - -The statement - - $local function f ()$@body@$end$ - -translates to - - $local f; f = function f ()$@body@$end$ - -@not@to - - $local f = function f ()$@body@$end$ - -(This only makes a difference when the body of the function contains -references to$f$.) - - *lrv-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 -function is@instantiated@(or@closed@). This function instance (or@closure@) -is the final value of the expression. Different instances of the same -function may refer to different external local variables and may have -different environment tables. - -Parameters act as local variables that are initialized with the argument -values: - - $parlist1 ::= namelist [$#`,' `...'#$] |$#`...'# - - *lrv-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 vararg function does not adjust its argument list; instead, it collects all -extra arguments and supplies them to the function through a@vararg expression@, -which is also written as three dots. The value of this expression is a list of -all actual extra arguments, similar to a function with multiple results. If a -vararg expression is used inside another expression or in the middle of a list -of expressions, then its return list is adjusted to one element. If the -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: -> - function f(a, b) end - function g(a, b, ...) end - function r() return 1,2,3 end -> -Then, we have the following mapping from arguments to parameters and to the -vararg expression: -> - CALL PARAMETERS - - f(3) a=3, b=nil - f(3, 4) a=3, b=4 - f(3, 4, 5) a=3, b=4 - f(r(), 10) a=1, b=10 - f(r()) a=1, b=2 - - g(3) a=3, b=nil, ... --> (nothing) - g(3, 4) a=3, b=4, ... --> (nothing) - 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 |lrv-langContStructs|). -If control reaches the end of a function without encountering -a#return#statement, then the function returns with no results. - - *lrv-colonsyntax* -The@colon@syntax is used for defining@methods@, that is, functions that have -an implicit extra parameter$self$. Thus, the statement - - $function t.a.b.c:f ($@params@$)$@body@$end$ - -is syntactic sugar for - - $t.a.b.c:f = function (self, ($@params@$)$@body@$end$ - - -============================================================================== -2.6 Visibility Rules *lrv-langVisibRules* - - -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: -> - x = 10 -- global variable - do -- new block - local x = x -- new `x', with value 10 - print(x) --> 10 - x = x+1 - do -- another block - local x = x+1 -- another `x' - print(x) --> 12 - end - print(x) --> 11 - end - print(x) --> 10 (the global one) -> -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. - - *lrv-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 -function. - -Notice that each execution of a#local#statement defines new local variables. -Consider the following example: -> - a = {} - local x = 20 - for i=1,10 do - local y = 0 - a[i] = function () y=y+1; return x+y end - end -> -The loop creates ten closures (that is, ten instances of the anonymous -function). Each of these closures uses a different$y$variable, while all of -them share the same$x$. - - -============================================================================== -2.7 Error Handling *lrv-langError* - - -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 -|lrv-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 -|lrv-error|). If you need to catch errors in Lua, you can use -the$pcall$function (see |lrv-pcall|). - - -============================================================================== -2.8 Metatables *lrv-metatable* *lrv-langMetatables* - - -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 -certain special operations. You can change several aspects of the behavior of -an object by setting specific fields in its metatable. For instance, when a -non-numeric value is the operand of an addition, Lua checks for a function in -the field$"__add"$in its metatable. If it finds one, Lua calls that function -to perform the addition. - -We call the keys in a metatable@events@and the values@metamethods@. In the -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 |lrv-getmetatable|). - -You can replace the metatable of tables through the$setmetatable$function (see -|lrv-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 -userdata can share a same table as their metatable); values of all other types -share one single metatable per type. So, there is one single metatable for all -numbers, and for all strings, etc. - -A metatable may control how an object behaves in arithmetic operations, order -comparisons, concatenation, length operation, and indexing. A metatable can -also define a function to be called when a userdata is garbage collected. For -each of those operations Lua associates a specific key called an@event@. When -Lua performs one of those operations over a value, it checks whether this -value has a metatable with the corresponding event. If so, the value -associated with that key (the@metamethod@) controls how Lua will perform the -operation. - -Metatables control the operations listed next. Each operation is identified by -its corresponding name. The key for each operation is a string with its name -prefixed by two underscores,$'__'$; for instance, the key for operation "add" -is the string$"__add"$. The semantics of these operations is better explained -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 |lrv-libBasic|. In particular, to retrieve the metamethod of a -given object, we use the expression -> - metatable(obj)[event] -> -This should be read as -> - rawget(metatable(obj) or {}, event) -> -That is, the access to a metamethod does not invoke other metamethods, and the -access to objects with no metatables does not fail (it simply results -in#nil#). - -$"add":$ *lrv-__add* --------- -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. -> - 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 -> - function add_event (op1, op2) - local o1, o2 = tonumber(op1), tonumber(op2) - if o1 and o2 then -- both operands are numeric? - return o1 + o2 -- `+' here is the primitive `add' - else -- at least one of the operands is not numeric - local h = getbinhandler(op1, op2, "__add") - if h then - -- call the handler with both operands - return h(op1, op2) - else -- no handler available: default behavior - error(...) - end - end - end -> -$"sub":$ *lrv-__sub* --------- -the$-$operation. Behavior similar to the "add" operation. - -$"mul":$ *lrv-__mul* --------- -the$*$operation. Behavior similar to the "add" operation. - -$"div":$ *lrv-__div* --------- -the$/$operation. Behavior similar to the "add" operation. - -$"mod":$ *lrv-__mod* --------- -the$%$operation. Behavior similar to the "add" operation, with the -operation$o1 - floor(o1/o2)*o2$as the primitive operation. - -$"pow":$ *lrv-__pow* --------- -the$^$(exponentiation) operation. Behavior similar to the "add" operation, -with the function$pow$(from the C math library) as the primitive operation. - -$"unm":$ *lrv-__unm* --------- -the unary$-$operation. -> - function unm_event (op) - local o = tonumber(op) - if o then -- operand is numeric? - return -o -- '-' here is the primitive 'unm' - else -- the operand is not numeric. - -- Try to get a handler from the operand - local h = metatable(op).__unm - if h then - -- call the handler with the operand - return h(op) - else -- no handler available: default behavior - error(...) - end - end - end -> -$"concat":$ *lrv-__concat* ------------ -the$..$(concatenation) operation. -> - function concat_event (op1, op2) - if (type(op1) == "string" or type(op1) == "number") and - (type(op2) == "string" or type(op2) == "number") then - return op1 .. op2 -- primitive string concatenation - else - local h = getbinhandler(op1, op2, "__concat") - if h then - return h(op1, op2) - else - error(...) - end - end - end -> -$"len":$ *lrv-__len* ------------ -the$#$operation. -> - function len_event (op) - if type(op) == "string" then - return strlen(op) -- primitive string length - elseif type(op) == "table" then - return #op -- primitive table length - else - local h = metatable(op).__len - if h then - -- call the handler with the operand - return h(op) - else -- no handler available: default behavior - error(...) - end - end - end -> -$"eq":$ *lrv-__eq* -------- -the$==$operation. - -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. -> - function getcomphandler (op1, op2, event) - if type(op1) ~= type(op2) then return nil end - local mm1 = metatable(op1)[event] - local mm2 = metatable(op2)[event] - if mm1 == mm2 then return mm1 else return nil end - end -> -The "eq" event is defined as follows: -> - function eq_event (op1, op2) - if type(op1) ~= type(op2) then -- different types? - return false -- different objects - end - if op1 == op2 then -- primitive equal? - return true -- objects are equal - end - -- try metamethod - local h = getcomphandler(op1, op2, "__eq") - if h then - return h(op1, op2) - else - return false - end - end -> -$a ~= b$is equivalent to$not (a == b)$. - -$"lt":$ *lrv-__lt* -------- -the$<$operation. -> - function lt_event (op1, op2) - if type(op1) == "number" and type(op2) == "number" then - return op1 < op2 -- numeric comparison - elseif type(op1) == "string" and type(op2) == "string" then - return op1 < op2 -- lexicographic comparison - else - local h = getcomphandler(op1, op2, "__lt") - if h then - return h(op1, op2) - else - error(...); - end - end - end -> -$a > b$is equivalent to$b < a$. - -$"le":$ *lrv-__le* -------- -the$<=$operation. -> - function le_event (op1, op2) - if type(op1) == "number" and type(op2) == "number" then - return op1 <= op2 -- numeric comparison - elseif type(op1) == "string" and type(op2) == "string" then - return op1 <= op2 -- lexicographic comparison - else - local h = getcomphandler(op1, op2, "__le") - if h then - return h(op1, op2) - else - h = getcomphandler(op1, op2, "__lt") - if h then - return not h(op2, op1) - else - error(...); - end - end - end - end -> -$a >= b$is equivalent to$b <= a$. Note that, in the absence of a "le" -metamethod, Lua tries the "lt", assuming that$a <= b$is equivalent -to$not (b < a)$. - -$"index":$ *lrv-__index* ----------- -The indexing access$table[key]$. -> - function gettable_event (table, key) - local h - if type(table) == "table" then - local v = rawget(table, key) - if v ~= nil then return v end - h = metatable(table).__index - if h == nil then return nil end - else - h = metatable(table).__index - if h == nil then - error(...); - end - end - if type(h) == "function" then - return h(table, key) -- call the handler - else return h[key] -- or repeat operation on it - end -> -$"newindex":$ *lrv-__newindex* -------------- -The indexing assignment$table[key] = value$. -> - function settable_event (table, key, value) - local h - if type(table) == "table" then - local v = rawget(table, key) - if v ~= nil then rawset(table, key, value); return end - h = metatable(table).__newindex - if h == nil then rawset(table, key, value); return end - else - h = metatable(table).__newindex - if h == nil then - error(...); - end - end - if type(h) == "function" then - return h(table, key,value) -- call the handler - else h[key] = value -- or repeat operation on it - end -> -$"call":$ *lrv-__call* ---------- -called when Lua calls a value. -> - function function_event (func, ...) - if type(func) == "function" then - return func(...) -- primitive call - else - local h = metatable(func).__call - if h then - return h(func, ...) - else - error(...) - end - end - end -> - -============================================================================== -2.9 Environments *lrv-environment* *lrv-langEnvironments* - - -Besides metatables, objects of types thread, function, and userdata have -another table associated with them, called their@environment@. Like -metatables, environments are regular tables and multiple objects can share the -same environment. - -Environments associated with userdata have no meaning for Lua. It is only a -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$|lrv-loadfile|, -$loadstring$|lrv-loadstring| or$load$|lrv-load|) and can be directly accessed -by C code (see |lrv-apiPseudoIndices|). - - -Environments associated with C functions can be directly accessed by C code -(see |lrv-apiPseudoIndices|). 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 |lrv-langVariables|). They are 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 |lrv-setenv|). You can get the environment of a Lua -function or the running thread by calling$getfenv$(see |lrv-getfenv|). To -manipulate the environment of other objects (userdata, C functions, other -threads) you must use the C API. - - -============================================================================== -2.10 Garbage Collection *lrv-langGC* - - -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 -when the objects are no longer needed. Lua manages memory automatically by -running a@garbage collector@from time to time to collect all@dead objects@ -(that is, these objects that are no longer accessible from Lua). All objects -in Lua are subject to automatic management: tables, userdata, functions, -threads, and strings. - -Lua implements an incremental mark-and-sweep collector. It uses two numbers to -control its garbage-collection cycles: the@garbage-collector pause@and the -@garbage-collector step multiplier@. - -The garbage-collector pause controls how long the collector waits before -starting a new cycle. Larger values make the collector less aggressive. Values -smaller than 1 mean the collector will not wait to start a new cycle. A value -of 2 means that the collector waits for the total memory in use to double -before starting a new cycle. - -The step multiplier controls the relative speed of the collector relative to -memory allocation. Larger values make the collector more aggressive but also -increase the size of each incremental step. Values smaller than 1 make the -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 |lrv-lua_gc|) in C or -$collectgarbage$(see |lrv-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 *lrv-langGCMeta* - - -Using the C API, you can set garbage-collector metamethods for userdata (see -|lrv-langMetatables|). 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). - - *lrv-__gc* -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: -> - function gc_event (udata) - local h = metatable(udata).__gc - if h then - h(udata) - end - end -> -At the end of each garbage-collection cycle, the finalizers for userdata are -called in@reverse@order of their creation, among these collected in that -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 *lrv-weaktable* *lrv-langWeaktables* - - -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 -an object are weak references, then the garbage collector will collect this -object. - - *lrv-__mode* -A weak table can have weak keys, weak values, or both. A table with weak keys -allows the collection of its keys, but prevents the collection of its values. -A table with both weak keys and weak values allows the collection of both keys -and values. In any case, if either the key or the value is collected, the -whole pair is removed from the table. The weakness of a table is controlled by -the value of the$__mode$field of its metatable. If the$__mode$field is a -string containing the character$'k'$, the keys in the table are weak. -If$__mode$contains$'v'$, the values in the table are weak. - -After you use a table as a metatable, you should not change the value of its -field$__mode$. Otherwise, the weak behavior of the tables controlled by this -metatable is undefined. - - -============================================================================== -2.11 Coroutines *lrv-coroutine* *lrv-langCoro* - - -Lua supports coroutines, also called@collaborative multithreading@. -A coroutine in Lua represents an independent thread of execution. Unlike -threads in 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 -|lrv-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 |lrv-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 function. After -the coroutine starts running, it runs until it terminates or@yields@. - -A coroutine can terminate its execution in two ways: normally, when its main -function returns (explicitly or implicitly, after the last instruction); and -abnormally, if there is an unprotected error. In the first case, -$coroutine.resume$returns#true#, plus any values returned by the coroutine -main function. In case of errors,$coroutine.resume$returns#false#plus an error -message. - -A coroutine yields by calling$coroutine.yield$(see |lrv-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,$coroutine.resume$also -returns#true#, plus any values passed to$coroutine.yield$. The next time you -resume the same coroutine, it continues 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 |lrv-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$coroutine.resume$, except -the first one (the boolean error code). Unlike$coroutine.resume$, -$coroutine.wrap$does not catch errors; any error is propagated to the caller. - -As an example, consider the next code: -> - function foo1 (a) - print("foo", a) - return coroutine.yield(2*a) - end - - co = coroutine.create(function (a,b) - print("co-body", a, b) - local r = foo1(a+1) - print("co-body", r) - local r, s = coroutine.yield(a+b, a-b) - print("co-body", r, s) - return b, "end" - end) - - print("main", coroutine.resume(co, 1, 10)) - print("main", coroutine.resume(co, "r")) - print("main", coroutine.resume(co, "x", "y")) - print("main", coroutine.resume(co, "x", "y")) -> -When you run it, it produces the following output: -> - co-body 1 10 - foo 2 - main true 4 - co-body r - main true 11 -9 - co-body x y - main true 10 end - main false cannot resume dead coroutine -> - -============================================================================== -3 THE APPLICATION PROGRAM INTERFACE *lrv-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 -related types and constants are declared in the header file$lua.h$. - -Even when we use the term "function", any facility in the API may be provided -as a@macro@instead. All such macros use each of its arguments exactly once -(except for the first argument, which is always a Lua state), and so do not -generate hidden side-effects. - -As in most C libraries, the Lua API functions do not check their arguments for -validity or consistency. However, you can change this behavior by compiling -Lua with a proper definition for the macro$luai_apicheck$,in file$luaconf.h$. - - -============================================================================== -3.1 The Stack *lrv-stack* *lrv-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.). - -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 -|lrv-lua_CFunction|). - - *lrv-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); a negative index represents an@offset@from the top of the stack. -More specifically, if the stack has@n@elements, then index 1 represents the -first element (that is, the element that was pushed onto the stack first) and -index@n@represents the last element; index@-1@also represents the last element -(that is, the element at the top) and index@-n@represents the first element. -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 *lrv-apiStackSize* - - -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 -|lrv-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 have -to worry about stack space unless your code has loops pushing elements onto -the stack. - -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: -> - (index < 0 && abs(index) <= top) || (index > 0 && index <= stackspace) -> -Note that 0 is never an acceptable index. - - -============================================================================== -3.3 Pseudo-Indices *lrv-pseudoindex* *lrv-apiPseudoIndices* - - -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 |lrv-apiCClosures|). - -The thread environment (where global variables live) is always at pseudo-index -$LUA_GLOBALSINDEX$. The environment of the running C function is always at -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 -> - lua_getfield(L, LUA_GLOBALSINDEX, varname); -> - -============================================================================== -3.4 C Closures *lrv-cclosure* *lrv-apiCClosures* - - -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 |lrv-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 |lrv-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 *lrv-registry* *lrv-apiRegistry* - - -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 pseudo-index$LUA_REGISTRYINDEX$. Any C library can store data into -this table, but it should take care to choose keys different from those used -by other libraries, to avoid collisions. Typically, you should use as key a -string containing your library name or a light userdata with the address of a -C object in your code. - -The integer keys in the registry are used by the reference mechanism, -implemented by the auxiliary library, and therefore should not be used for -other purposes. - - -============================================================================== -3.6 Error Handling in C *lrv-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 -any error (such as memory allocation errors, type errors, syntax errors, and -runtime errors) it@raises@an error; that is, it does a long jump. -A@protected environment@uses$setjmp$to set a recover point; any error jumps to -the most recent active recover point. - -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 -|lrv-lua_newstate|, |lrv-lua_close|, |lrv-lua_load|, |lrv-lua_pcall|, and -|lrv-lua_cpcall|). - -Inside a C function you can raise an error by calling$lua_error$ (see -|lrv-lua_error|). - - -============================================================================== -3.7 Functions and Types *lrv-apiFunctions* - - -Here we list all functions and types from the C API in alphabetical order. - - -$lua_Alloc$ *lrv-lua_Alloc* ------------ -> - typedef void * (*lua_Alloc) (void *ud, - void *ptr, - size_t osize, - size_t nsize); -> -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 |lrv-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 must return$NULL$; if$osize$is not zero, -it should free the block pointed to by$ptr$. When$nsize$is not zero, the -allocator returns$NULL$if and only if it cannot fill the request. -When$nsize$is not zero and$osize$is zero, the allocator should behave -like$malloc$. When$nsize$and$osize$are not zero, the allocator behaves like -$realloc$. Lua assumes that the allocator never fails when$osize >= nsize$. - -Here is a simple implementation for the allocator function. It is used in the -auxiliary library by$luaL_newstate$(see |lrv-luaL_newstate|). -> - static void *l_alloc (void *ud, void *ptr, size_t osize, - size_t nsize) { - (void)ud; (void)osize; /* not used */ - if (nsize == 0) { - free(ptr); - return NULL; - } - else - return realloc(ptr, nsize); - } -> -This code assumes that$free(NULL)$has no effect and that -$realloc(NULL, size)$is equivalent to$malloc(size)$. ANSI C ensures both -behaviors. - - -$lua_atpanic$ *lrv-lua_atpanic* -------------- -> - lua_CFunction lua_atpanic (lua_State *L, lua_CFunction panicf); -> -Sets a new panic function and returns the old one. - -If an error happens outside any protected environment, Lua calls a@panic@ -@function@and then calls$exit(EXIT_FAILURE)$, thus exiting the host -application. Your panic function may avoid this exit by never returning (e.g., -doing a long jump). - -The panic function can access the error message at the top of the stack. - - -$lua_call$ *lrv-lua_call* ----------- -> - void lua_call (lua_State *L, int nargs, int nresults); -> -Calls a function. - -To call a function you must use the following protocol: first, the function to -be called is pushed onto the stack; then, the arguments to the function are -pushed in direct order; that is, the first argument is pushed first. Finally -you call$lua_call$;$nargs$is the number of arguments that you pushed onto the -stack. All arguments and the function value are popped from the stack when the -function is called. The function results are pushed onto the stack when the -function returns. The number of results is adjusted to$nresults$, unless -$nresults$is$LUA_MULTRET$. In this case,@all@results from the function are -pushed. Lua takes care that the returned values fit into the stack space. The -function results are pushed onto the stack in direct order (the first result -is pushed first), so that after the call the last result is on the top of the -stack. - -Any error inside the called function is propagated upwards (with a$longjmp$). - -The following example shows how the host program may do the equivalent to this -Lua code: -> - a = f("how", t.x, 14) -> -Here it is in 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 */ - lua_getfield(L, -1, "x"); /* push result of t.x (2nd arg) */ - lua_remove(L, -2); /* remove 't' from the stack */ - lua_pushinteger(L, 14); /* 3rd argument */ - lua_call(L, 3, 1); /* call 'f' with 3 arguments and 1 result */ - lua_setfield(L, LUA_GLOBALSINDEX, "a"); /* set global 'a' */ -> -Note that the code above is "balanced": at its end, the stack is back to its -original configuration. This is considered good programming practice. - - -$lua_CFunction$ *lrv-cfunction* *lrv-lua_CFunction* ---------------- -> - typedef int (*lua_CFunction) (lua_State *L); -> -Type for C functions. - -In order to communicate properly with Lua, a C function must use the 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 |lrv-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, in direct order (the first result is pushed first), and -returns the number of results. Any other value in the stack below the results -will be properly discarded by Lua. Like a Lua function, a C function called by -Lua can also return many results. - - *lrv-cfunctionexample* -As an example, the following function receives a variable number of numerical -arguments and returns their average and sum: -> - static int foo (lua_State *L) { - int n = lua_gettop(L); /* number of arguments */ - lua_Number sum = 0; - int i; - for (i = 1; i <= n; i++) { - if (!lua_isnumber(L, i)) { - lua_pushstring(L, "incorrect argument"); - lua_error(L); - } - sum += lua_tonumber(L, i); - } - lua_pushnumber(L, sum/n); /* first result */ - lua_pushnumber(L, sum); /* second result */ - return 2; /* number of results */ - } -> - -$lua_checkstack$ *lrv-lua_checkstack* ----------------- -> - int lua_checkstack (lua_State *L, int extra); -> -Ensures that there are at least$extra$free stack slots in the stack. It -returns false if it cannot grow the stack to that size. This function never -shrinks the stack; if the stack is already larger than the new size, it is -left unchanged. - - -$lua_close$ *lrv-lua_close* ------------ -> - void lua_close (lua_State *L); -> -Destroys all objects in the given Lua state (calling the corresponding -garbage-collection metamethods, if any) and frees all dynamic memory used by -this state. On several platforms, you may not need to call this function, -because all resources are naturally released when the host program ends. On -the other hand, long-running programs, such as a daemon or a web server, might -need to release states as soon as they are not needed, to avoid growing too -large. - - -$lua_concat$ *lrv-lua_concat* ------------- -> - void lua_concat (lua_State *L, int n); -> -Concatenates the$n$values at the top of the stack, pops them, and 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 -|lrv-langConcat|). - - -$lua_cpcall$ *lrv-lua_cpcall* ------------- -> - 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 |lrv-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$ *lrv-lua_createtable* ------------------ -> - 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 -|lrv-lua_newtable|). - - -$lua_dump$ *lrv-lua_dump* ----------- -> - 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 |lrv-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. - -This function does not pop the Lua function from the stack. - - -$lua_equal$ *lrv-lua_equal* ------------ -> - int lua_equal (lua_State *L, int index1, int index2); -> -Returns 1 if the two values in acceptable indices$index1$and$index2$are equal, -following the semantics of the Lua$==$operator (that is, may call -metamethods). Otherwise returns 0. Also returns 0 if any of the indices is non -valid. - - -$lua_error$ *lrv-lua_error* ------------ -> - 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 |lrv-luaL_error|). - - -$lua_gc$ *lrv-lua_gc* --------- -> - int lua_gc (lua_State *L, int what, int data); -> -Controls the garbage collector. - -This function performs several tasks, according to the value of the parameter -$what$: - - #o#$LUA_GCSTOP$: stops the garbage collector. - #o#$LUA_GCRESTART$: restarts the garbage collector. - #o#$LUA_GCCOLLECT$: performs a full garbage-collection cycle. - #o#$LUA_GCCOUNT$: returns the current amount of memory (in Kbytes) in use by - Lua. - #o#$LUA_GCCOUNTB$: returns the remainder of dividing the current amount of - bytes of memory in use by Lua by 1024. - #o#$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. - #o#$LUA_GCSETPAUSE$: sets$data$/100 as the new value for the@pause@of the - collector (see |lrv-langGC|). The function returns the previous value of - the pause. - #o#$LUA_GCSETSTEPMUL$: sets$data$/100 as the new value for the@step@ - @multiplier@ of the collector (see |lrv-langGC|). The function returns - the previous value of the step multiplier. - - -$lua_getallocf$ *lrv-lua_getallocf* ---------------- -> - 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 -|lrv-lua_newstate|). - - -$lua_getfenv$ *lrv-lua_getfenv* -------------- -> - void lua_getfenv (lua_State *L, int index); -> -Pushes onto the stack the environment table of the value at the given index. - - -$lua_getfield$ *lrv-lua_getfield* --------------- -> - 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 given valid -index$index$. As in Lua, this function may trigger a metamethod for the -"index" event (see |lrv-langMetatables|). - - -$lua_getglobal$ *lrv-lua_getglobal* ---------------- -> - 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: -> - #define lua_getglobal(L,s) lua_getfield(L, LUA_GLOBALSINDEX, s) -> - -$lua_getmetatable$ *lrv-lua_getmetatable* ------------------- -> - int lua_getmetatable (lua_State *L, int index); -> -Pushes onto the stack the metatable of the value at the given acceptable -index. If the index is not valid, or if the value does not have a metatable, -the function returns 0 and pushes nothing on the stack. - - -$lua_gettable$ *lrv-lua_gettable* --------------- -> - void lua_gettable (lua_State *L, int index); -> -Pushes onto the stack the value$t[k]$, where$t$is the value at the given valid -index$index$and$k$is the value at the top of the stack. - -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 |lrv-langMetatables|). - - -$lua_gettop$ *lrv-lua_gettop* ------------- -> - int lua_gettop (lua_State *L); -> -Returns the index of the top element in the stack. Because indices start -at 1, this result is equal to the number of elements in the stack (and so -0 means an empty stack). - - -$lua_insert$ *lrv-lua_insert* ------------- -> - void lua_insert (lua_State *L, int index); -> -Moves the top element into the given valid index, shifting up the 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$ *lrv-lua_Integer* -------------- -> - typedef ptrdiff_t lua_Integer; -> -The type used by the Lua API to represent integral values. - -By default it is a$ptrdiff_t$, which is usually the largest integral type the -machine handles "comfortably". - - -$lua_isboolean$ *lrv-lua_isboolean* ---------------- -> - 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$ *lrv-lua_iscfunction* ------------------ -> - 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$ *lrv-lua_isfunction* ----------------- -> - 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$ *lrv-lua_islightuserdata* ---------------------- -> - 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$ *lrv-lua_isnil* ------------ -> - 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$ *lrv-lua_isnumber* --------------- -> - 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$ *lrv-lua_isstring* --------------- -> - 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$ *lrv-lua_istable* -------------- -> - 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$ *lrv-lua_isthread* --------------- -> - 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$ *lrv-lua_isuserdata* ----------------- -> - 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$ *lrv-lua_lessthan* --------------- -> - int lua_lessthan (lua_State *L, int index1, int index2); -> -Returns 1 if the value at acceptable index$index1$is smaller than the value at -acceptable index$index2$, following the semantics of the Lua$<$operator (that -is, may call metamethods). Otherwise returns 0. Also returns 0 if any of the -indices is non valid. - - -$lua_load$ *lrv-lua_load* ----------- -> - int lua_load (lua_State *L, - lua_Reader reader, - void *data, - const char *chunkname); -> -Loads a Lua chunk. If there are no errors,$lua_load$pushes the compiled chunk -as a Lua function on top of the stack. Otherwise, it pushes an error message. -The return values of$lua_load$are: - - #o##0#: no errors; - #o#$LUA_ERRSYNTAX$: syntax error during pre-compilation; - #o#$LUA_ERRMEM$: memory allocation error. - -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$, |lrv-luac|). - -The$lua_load$function uses a user-supplied$reader$function to read the chunk -(see |lrv-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 |lrv-apiDebug|). - - -$lua_newstate$ *lrv-lua_newstate* --------------- -> - lua_State *lua_newstate (lua_Alloc f, void *ud); -> -Creates a new, independent state. Returns$NULL$if cannot create the state (due -to lack of memory). The argument$f$is the allocator function; Lua does all -memory allocation for this state through this function. The second argument, -$ud$, is an opaque pointer that Lua simply passes to the allocator in every -call. - - -$lua_newtable$ *lrv-lua_newtable* --------------- -> - 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 |lrv-lua_createtable|). - - -$lua_newthread$ *lrv-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 |lrv-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. - -There is no explicit function to close or to destroy a thread. Threads are -subject to garbage collection, like any Lua object. - - -$lua_newuserdata$ *lrv-lua_newuserdata* ------------------ -> - void *lua_newuserdata (lua_State *L, size_t size); -> -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. - - *lrv-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 collected. A full userdata -is only equal to itself (under raw equality). - -When Lua collects a full userdata with a$gc$metamethod, Lua calls the -metamethod and marks the userdata as finalized. When this userdata is -collected again then Lua frees its corresponding memory. - - -$lua_next$ *lrv-lua_next* ----------- -> - int lua_next (lua_State *L, int index); -> -Pops a key from the stack, and pushes a key-value pair from the table at the -given index (the "next" pair after the given key). If there are no more -elements in the table, then$lua_next$returns 0 (and pushes nothing). - - *lrv-tabletraversal* -A typical traversal looks like this: -> - /* table is in the stack at index 't' */ - lua_pushnil(L); /* first key */ - while (lua_next(L, t) != 0) { - /* uses 'key' (at index -2) and 'value' (at index -1) */ - printf("%s - %s\n", - lua_typename(L, lua_type(L, -2)), - lua_typename(L, lua_type(L, -1))); - /* removes 'value'; keeps 'key' for next iteration */ - lua_pop(L, 1); - } -> -While traversing a table, do not call$lua_tolstring$(see |lrv-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$ *lrv-lua_Number* ------------- -> - typedef double lua_Number; -> -The type of numbers in Lua. By default, it is double, but that can be changed -in$luaconf.h$. - -Through the configuration file you can change Lua to operate with another type -for numbers (e.g., float or long). - - -$lua_objlen$ *lrv-lua_objlen* ------------- -> - size_t lua_objlen (lua_State *L, int index); -> -Returns the "length" of the value at the given acceptable index: for strings, -this is the string length; for tables, this is the result of the length -operator ($'#'$); for userdata, this is the size of the block of memory -allocated for the userdata; for other values, it is 0. - - -$lua_pcall$ *lrv-lua_pcall* ------------ -> - 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 -|lrv-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$,$lua_pcall$always removes the function and its arguments -from the stack. - -If$errfunc$is 0, then the error message returned on the stack is exactly the -original error message. Otherwise,$errfunc$is the stack index of an@error@ -@handler function@. (In the current implementation, this index cannot be a -pseudo-index.) In case of runtime errors, this function will be called with -the error message and its return value will be the message returned on the -stack by$lua_pcall$. - -Typically, the error handler function is used to add more debug information to -the error message, such as a stack traceback. Such information cannot be -gathered after the return of$lua_pcall$, since by then the stack has unwound. - -The$lua_pcall$function returns 0 in case of success or one of the following -error codes (defined in$lua.h$): - - #o#$LUA_ERRRUN$: a runtime error. - #o#$LUA_ERRMEM$: memory allocation error. For such errors, Lua does not call - the error handler function. - #o#$LUA_ERRERR$: error while running the error handler function. - - -$lua_pop$ *lrv-lua_pop* ---------- -> - void lua_pop (lua_State *L, int n); -> -Pops$n$elements from the stack. - - -$lua_pushboolean$ *lrv-lua_pushboolean* ------------------ -> - void lua_pushboolean (lua_State *L, int b); -> -Pushes a boolean value with value$b$onto the stack. - - -$lua_pushcclosure$ *lrv-lua_pushcclosure* ------------------- -> - void lua_pushcclosure (lua_State *L, lua_CFunction fn, int n); -> -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 |lrv-apiCClosures|); 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 is pushed first). Then$lua_pushcclosure$is -called to create and push the C function onto the stack, with the argument -$n$telling how many values should be associated with the function. -$lua_pushcclosure$also pops these values from the stack. - - -$lua_pushcfunction$ *lrv-lua_pushcfunction* -------------------- -> - void lua_pushcfunction (lua_State *L, lua_CFunction f); -> -Pushes a C function onto the stack. This function receives a pointer to a C -function and pushes onto the stack a Lua value of type$function$that, when -called, invokes the corresponding C function. - -Any function to be registered in Lua must follow the correct protocol to -receive its parameters and return its results (see |lrv-lua_CFunction|). - -$lua_pushcfunction$is defined as a macro: -> - #define lua_pushcfunction(L,f) lua_pushcclosure(L,f,0) -> - -$lua_pushfstring$ *lrv-lua_pushfstring* ------------------ -> - const char *lua_pushfstring (lua_State *L, const char *fmt, ...); -> -Pushes onto the stack a formatted string and returns a pointer to this string. -It is similar to the C function$sprintf$, but has some important differences: - - #o# You do not have to allocate space for the result: the result is a Lua - string and Lua takes care of memory allocation (and deallocation, - through garbage collection). - #o# The conversion specifiers are quite restricted. There are no flags, - widths, or precisions. The conversion specifiers can only be$'%%'$ - (inserts a$'%'$in the string),$'%s'$(inserts a zero-terminated string, - with no size restrictions),$'%f'$(inserts a$lua_Number$),$'%p'$(inserts - a pointer as a hexadecimal numeral),$'%d'$(inserts an$int$), and$'%c'$ - (inserts an$int$as a character). - - -$lua_pushinteger$ *lrv-lua_pushinteger* ------------------ -> - void lua_pushinteger (lua_State *L, lua_Integer n); -> -Pushes a number with value$n$onto the stack. - - -$lua_pushlightuserdata$ *lrv-lua_pushlightuserdata* ------------------------ -> - void lua_pushlightuserdata (lua_State *L, void *p); -> -Pushes a light userdata onto the stack. - - *lrv-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 created). A light userdata -is equal to "any" light userdata with the same C address. - - -$lua_pushlstring$ *lrv-lua_pushlstring* ------------------ -> - 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. Lua makes (or -reuses) an internal copy of the given string, so the memory at$s$can be freed -or reused immediately after the function returns. The string can contain -embedded zeros. - - -$lua_pushnil$ *lrv-lua_pushnil* -------------- -> - void lua_pushnil (lua_State *L); -> -Pushes a nil value onto the stack. - - -$lua_pushnumber$ *lrv-lua_pushnumber* ----------------- -> - void lua_pushnumber (lua_State *L, lua_Number n); -> -Pushes a number with value$n$onto the stack. - - -$lua_pushstring$ *lrv-lua_pushstring* ----------------- -> - void lua_pushstring (lua_State *L, const char *s); -> -Pushes the zero-terminated string pointed to by$s$onto the stack. Lua makes -(or reuses) an internal copy of the given string, so the memory at$s$can be -freed or reused immediately after the function returns. The string cannot -contain embedded zeros; it is assumed to end at the first zero. - - -$lua_pushthread$ *lrv-lua_pushthread* ----------------- -> - 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$ *lrv-lua_pushvalue* ---------------- -> - void lua_pushvalue (lua_State *L, int index); -> -Pushes a copy of the element at the given valid index onto the stack. - - -$lua_pushvfstring$ *lrv-lua_pushvfstring* ------------------- -> - const char *lua_pushvfstring (lua_State *L, - const char *fmt, - va_list argp); -> -Equivalent to$lua_pushfstring$(see |lrv-pushfstring|), except that it -receives a$va_list$instead of a variable number of arguments. - - -$lua_rawequal$ *lrv-lua_rawequal* --------------- -> - int lua_rawequal (lua_State *L, int index1, int index2); -> -Returns 1 if the two values in acceptable indices$index1$and$index2$are -primitively equal (that is, without calling metamethods). Otherwise -returns 0. Also returns 0 if any of the indices are non valid. - - -$lua_rawget$ *lrv-lua_rawget* ------------- -> - void lua_rawget (lua_State *L, int index); -> -Similar to$lua_gettable$(see |lrv-lua_gettable|), but does a raw access -(i.e., without metamethods). - - -$lua_rawgeti$ *lrv-lua_rawgeti* -------------- -> - 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 given valid -index$index$. The access is raw; that is, it does not invoke metamethods. - - -$lua_rawset$ *lrv-lua_rawset* ------------- -> - void lua_rawset (lua_State *L, int index); -> -Similar to$lua_settable$(see |lrv-lua_settable|), but does a raw assignment -(i.e., without metamethods). - - -$lua_rawseti$ *lrv-lua_rawseti* -------------- -> - 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 valid -index$index$and$v$is the value at the top of the stack. - -This function pops the value from the stack. The assignment is raw; that is, -it does not invoke metamethods. - - -$lua_Reader$ *lrv-lua_Reader* ------------- -> - typedef const char * (*lua_Reader) (lua_State *L, - void *data, - size_t *size); -> -The reader function used by$lua_load$(see |lrv-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 the block size. The block must exist until -the reader function is called again. To signal the end of the chunk, the -reader must return$NULL$. The reader function may return pieces of any size -greater than zero. - - -$lua_register$ *lrv-lua_register* --------------- -> - 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: -> - #define lua_register(L,n,f) \ - (lua_pushcfunction(L, f), lua_setglobal(L, n)) -> - -$lua_remove$ *lrv-lua_remove* ------------- -> - void lua_remove (lua_State *L, int index); -> -Removes the element at the given valid index, shifting down the elements above -this index to fill the gap. Cannot be called with a pseudo-index, because a -pseudo-index is not an actual stack position. - - -$lua_replace$ *lrv-lua_replace* -------------- -> - void lua_replace (lua_State *L, int index); -> -Moves the top element into the given position (and pops it), without shifting -any element (therefore replacing the value at the given position). - - -$lua_resume$ *lrv-lua_resume* ------------- -> - 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 |lrv-lua_newthread|); -then you push onto its stack the main function plus any arguments; then you -call$lua_resume$(see |lrv-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 |lrv-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 -|lrv-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$ *lrv-lua_setallocf* ---------------- -> - 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$ *lrv-lua_setfenv* -------------- -> - int lua_setfenv (lua_State *L, int index); -> -Pops a table from the stack and sets it as the new environment for the value -at the given index. If the value at the given index is neither a function nor -a thread nor a userdata,$lua_setfenv$returns 0. Otherwise it returns 1. - - -$lua_setfield$ *lrv-lua_setfield* --------------- -> - 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 valid -index$index$and$v$is the value at the top of the stack. - -This function pops the value from the stack. As in Lua, this function may -trigger a metamethod for the "newindex" event (see |lrv-langMetatables|). - - -$lua_setglobal$ *lrv-lua_setglobal* ---------------- -> - 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: -> - #define lua_setglobal(L,s) lua_setfield(L, LUA_GLOBALSINDEX, s) -> - -$lua_setmetatable$ *lrv-lua_setmetatable* ------------------- -> - 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$ *lrv-lua_settable* --------------- -> - void lua_settable (lua_State *L, int index); -> -Does the equivalent to$t[k] = v$, where$t$is the value at the given valid -index$index$,$v$is the value at the top of the stack, and$k$is the value just -below the top. - -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 -|lrv-langMetatables|). - - -$lua_settop$ *lrv-lua_settop* ------------- -> - void lua_settop (lua_State *L, int index); -> -Accepts any acceptable index, or 0, and sets the stack top to this index. If -the new top is larger than the old one, then the new elements are filled with -#nil#. If$index$is 0, then all stack elements are removed. - - -$lua_State$ *lrv-lua_State* ------------ -> - typedef struct lua_State lua_State; -> -Opaque structure that keeps the whole state of a Lua interpreter. The Lua -library is fully reentrant: it has no global variables. All information about -a state is kept in this structure. - -A pointer to this state must be passed as the first argument to every function -in the library, except to$lua_newstate$(see |lrv-lua_newstate|), which -creates a Lua state from scratch. - - -$lua_status$ *lrv-lua_status* ------------- -> - int lua_status (lua_State *L); -> -Returns the status of the thread$L$. - -The status can be 0 for a normal thread, an error code if the thread finished -its execution with an error, or$LUA_YIELD$if the thread is suspended. - - -$lua_toboolean$ *lrv-lua_toboolean* ---------------- -> - int lua_toboolean (lua_State *L, int index); -> -Converts the Lua value at the given acceptable index to a C boolean value -(0 or 1). Like all tests in Lua,$lua_toboolean$returns 1 for 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$|lrv-lua_isboolean| to test the value's type.) - - -$lua_tocfunction$ *lrv-lua_tocfunction* ------------------ -> - 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$ *lrv-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 |lrv-lua_Integer|). The Lua value must be a number or a -string convertible to a number (see |lrv-langCoercion|); otherwise, -$lua_tointeger$returns 0. - -If the number is not an integer, it is truncated in some non-specified way. - - -$lua_tolstring$ *lrv-lua_tolstring* ---------------- -> - 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$len$is -not$NULL$, it also sets$*len$with the string length. The 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$|lrv-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 Lua -state. This string always has a zero ($'\0'$) after its last character (as -in C), but may contain other zeros in its body. Because Lua has garbage -collection, there is no guarantee that the pointer returned by$lua_tolstring$ -will be valid after the corresponding value is removed from the stack. - - -$lua_tonumber$ *lrv-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 |lrv-lua_Number|). The Lua value must be a number or a string convertible -to a number (see |lrv-langCoercion|); otherwise,$lua_tonumber$returns 0. - - -$lua_topointer$ *lrv-lua_topointer* ---------------- -> - const void *lua_topointer (lua_State *L, int index); -> -Converts the value at the given acceptable index to a generic C pointer -($void*$). The value may be a userdata, a table, a thread, or a function; -otherwise,$lua_topointer$returns$NULL$. Different objects will give different -pointers. There is no way to convert the pointer back to its original value. - -Typically this function is used only for debug information. - - -$lua_tostring$ *lrv-lua_tostring* --------------- -> - const char *lua_tostring (lua_State *L, int index); -> -Equivalent to$lua_tolstring$(see |lrv-lua_tolstring|) with$len$equal to$NULL$. - - -$lua_tothread$ *lrv-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*$|lrv-lua_State|). This value must be a thread; otherwise, the -function returns$NULL$. - - -$lua_touserdata$ *lrv-lua_touserdata* ----------------- -> - void *lua_touserdata (lua_State *L, int index); -> -If the value at the given acceptable index is a full userdata, returns its -block address. If the value is a light userdata, returns its pointer. -Otherwise, it returns$NULL$. - - -$lua_type$ *lrv-lua_type* ----------- -> - int lua_type (lua_State *L, int index); -> -Returns the type of the value in the given acceptable index, or$LUA_TNONE$for -a non-valid index (that is, an index to an "empty" stack position). The types -returned by$lua_type$are coded by the following constants defined in$lua.h$: -$LUA_TNIL$,$LUA_TNUMBER$,$LUA_TBOOLEAN$,$LUA_TSTRING$,$LUA_TTABLE$, -$LUA_TFUNCTION$,$LUA_TUSERDATA$,$LUA_TTHREAD$, and$LUA_TLIGHTUSERDATA$. - - -$lua_typename$ *lrv-lua_typename* --------------- -> - 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$ *lrv-lua_Writer* ------------- -> - typedef int (*lua_Writer) (lua_State *L, - const void* p, - size_t sz, - void* ud); -> -The writer function used by$lua_dump$(see |lrv-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$. - -The writer returns an error code: 0 means no errors; any other value means an -error and stops$lua_dump$from calling the writer again. - - -$lua_xmove$ *lrv-lua_xmove* ------------ -> - void lua_xmove (lua_State *from, lua_State *to, int n); -> -Exchange values between different threads of the@same@global state. - -This function pops$n$values from the stack$from$, and pushes them onto the -stack$to$. - - -$lua_yield$ *lrv-lua_yield* ------------ -> - 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: -> - 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 |lrv-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$. - - - *lrv-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 -> - lua_pushvalue(L, 3) --> 10 20 30 40 50 30* - lua_pushvalue(L, -1) --> 10 20 30 40 50 30 30* - lua_remove(L, -3) --> 10 20 30 40 30 30* - lua_remove(L, 6) --> 10 20 30 40 30* - lua_insert(L, 1) --> 30 10 20 30 40* - lua_insert(L, -1) --> 30 10 20 30 40* (no effect) - lua_replace(L, 2) --> 30 40 20 30* - lua_settop(L, -3) --> 30 40* - lua_settop(L, 6) --> 30 40 nil nil nil nil* -> - -============================================================================== -3.8 The Debug Interface *lrv-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$ *lrv-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;$ - - -A structure used to carry different pieces of information about an active -function.$lua_getstack$(see |lrv-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 |lrv-lua_getinfo|). - -The fields of$lua_Debug$ have the following meaning: - - #o#$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. - #o#$short_src$: a "printable" version of$source$, to be used in error - messages. - #o#$linedefined$: the line number where the definition of the function - starts. - #o#$lastlinedefined$: the line number where the definition of the function - ends. - #o#$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. - #o#$currentline$: the current line where the given function is executing. - When no line information is available,$currentline$is set to -1. - #o#$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$. - #o#$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 no other option seems to apply.) - #o#$nups$: the number of upvalues of the function. - - -$lua_gethook$ *lrv-lua_gethook* -------------- -> - lua_Hook lua_gethook (lua_State *L); -> -Returns the current hook function. - - -$lua_gethookcount$ *lrv-lua_gethookcount* ------------------- -> - int lua_gethookcount (lua_State *L); -> -Returns the current hook count. - - -$lua_gethookmask$ *lrv-lua_gethookmask* -> - int lua_gethookmask (lua_State *L); -> -Returns the current hook mask. - - -$lua_getinfo$ *lrv-lua_getinfo* -------------- -> - 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 |lrv-lua_getstack|) or given as argument to a hook (see |lrv-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: -> - lua_Debug ar; - lua_getfield(L, LUA_GLOBALSINDEX, "f"); /* get global 'f' */ - lua_getinfo(L, ">S", &ar); - printf("%d\n", ar.linedefined); -> -Each character in the string$what$selects some fields of the structure$ar$to -be filled or a value to be pushed on the stack: - - #o#$'n'$: fills in the field$name$and$namewhat$; - #o#$'S'$: fills in the fields$source$,$short_src$,$linedefined$, - $lastlinedefined$, and$what$; - #o#$'l'$: fills in the field$currentline$; - #o#$'u'$: fills in the field$nups$; - #o#$'f'$: pushes onto the stack the function that is running at the given - level; - #o#$'L'$: pushes onto the stack a table whose indices are the numbers of the - lines that are valid on the function. (A@valid line@is a line with some - associated code, that is, a line where you can put a break point. - Non-valid lines include empty lines and comments.) - -This function returns 0 on error (for instance, an invalid option in$what$). - - -$lua_getlocal$ *lrv-lua_getlocal* --------------- -> - 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 |lrv-lua_getstack|) or given as argument to a hook -(see |lrv-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 and returns its name. - -Variable names starting with$'('$(open parentheses) represent internal -variables (loop control variables, temporaries, and C function locals). - -Returns$NULL$(and pushes nothing) when the index is greater than the number of -active local variables. - - -$lua_getstack$ *lrv-lua_getstack* --------------- -> - 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 |lrv-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@n@. When there are no errors,$lua_getstack$ -returns 1; when called with a level greater than the stack depth, it -returns 0. - - -$lua_getupvalue$ *lrv-lua_getupvalue* ----------------- -> - const char *lua_getupvalue (lua_State *L, int funcindex, int n); -> -Gets information about a closure's upvalue. (For Lua functions, upvalues are -the external local variables that the function uses, and that are consequently -included in its closure.)$lua_getupvalue$gets the index$n$of an upvalue, -pushes the upvalue's value onto the stack, and returns its name.$funcindex$ -points to the closure in the stack. (Upvalues have no particular order, as -they are active through the whole function. So, they are numbered in an -arbitrary order.) - -Returns$NULL$(and pushes nothing) when the index is greater than the number of -upvalues. For C functions, this function uses the empty string$""$as a name -for all upvalues. - - -$lua_Hook$ *lrv-lua_Hook* ----------- -> - typedef void (*lua_Hook) (lua_State *L, lua_Debug *ar); -> -Type for debugging hook functions. - - -Whenever a hook is called, its$ar$argument has its field$event$set to the -specific event that triggered the hook. Lua identifies these events with the -following constants:$LUA_HOOKCALL$,$LUA_HOOKRET$,$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 |lrv-lua_getinfo|). For return events,$event$may be -$LUA_HOOKRET$, the normal value, or$LUA_HOOKTAILRET$. In the latter case, Lua -is simulating a return from a function that did a tail call; in this case, it -is useless to call$lua_getinfo$. - -While Lua is running a hook, it disables other calls to hooks. Therefore, if a -hook calls back Lua to execute a function or a chunk, this execution occurs -without any calls to hooks. - - -$lua_sethook$ *lrv-lua_sethook* -------------- -> - int lua_sethook (lua_State *L, lua_Hook f, int mask, int count); -> -Sets the debugging hook function. - -Argument$f$is the hook function.$mask$specifies on which events the hook will -be called: it is formed by a bitwise@or@of the constants$LUA_MASKCALL$, -$LUA_MASKRET$,$LUA_MASKLINE$, and$LUA_MASKCOUNT$. The$count$argument is only -meaningful when the mask includes$LUA_MASKCOUNT$. For each event, the hook is -called as explained below: - - #o##The call hook#: is called when the interpreter calls a function. The - hook is called just after Lua enters the new function, before the - function gets its arguments. - #o##The return hook#: is called when the interpreter returns from a - function. The hook is called just before Lua leaves the function. You - have no access to the values to be returned by the function. - #o##The line hook#: is called when the interpreter is about to start the - execution of a new line of code, or when it jumps back in the code (even - to the same line). (This event only happens while Lua is executing a Lua - function.) - #o##The count hook#: is called after the interpreter executes every$count$ - instructions. (This event only happens while Lua is executing a Lua - function.) - -A hook is disabled by setting$mask$to zero. - - -$lua_setlocal$ *lrv-lua_setlocal* --------------- -> - 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 |lrv-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. - -Returns$NULL$(and pops nothing) when the index is greater than the number of -active local variables. - - -$lua_setupvalue$ *lrv-lua_setupvalue* ----------------- -> - 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 -|lrv-lua_getupvalue|). - -Returns$NULL$(and pops nothing) when the index is greater than the number of -upvalues. - - - *lrv-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: -> - int listvars (lua_State *L, int level) { - lua_Debug ar; - int i; - const char *name; - if (lua_getstack(L, level, &ar) == 0) - return 0; /* failure: no such level in the stack */ - i = 1; - while ((name = lua_getlocal(L, &ar, i++)) != NULL) { - printf("local %d %s\n", i-1, name); - lua_pop(L, 1); /* remove variable value */ - } - lua_getinfo(L, "f", &ar); /* retrieves function */ - i = 1; - while ((name = lua_getupvalue(L, -1, i++)) != NULL) { - printf("upvalue %d %s\n", i-1, name); - lua_pop(L, 1); /* remove upvalue value */ - } - return 1; - } -> - -============================================================================== -4 THE AUXILIARY LIBRARY *lrv-aux* -============================================================================== - - -The@auxiliary library@provides several convenient functions to interface C -with Lua. While the basic API provides the primitive functions for all -interactions between C and Lua, the auxiliary library provides higher-level -functions for some common tasks. - -All functions from the auxiliary library are defined in header file$lauxlib.h$ -and have a prefix$luaL_$. - -All functions in the auxiliary library are built on top of the basic API, and -so they provide nothing that cannot be done with this API. - -Several functions in the auxiliary library are used to check C function -arguments. Their names are always$luaL_check*$or$luaL_opt*$. All of these -functions raise an error if the check is not satisfied. Because the error -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 *lrv-auxFunctions* - - -Here we list all functions and types from the auxiliary library in -alphabetical order. - - -$luaL_addchar$ *lrv-luaL_addchar* --------------- -> - void luaL_addchar (luaL_Buffer *B, char c); -> -Adds the character$c$to the buffer$B$(see |lrv-luaL_Buffer|). - - -$luaL_addlstring$ *lrv-luaL_addlstring* ------------------ -> - 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 -|lrv-luaL_Buffer|). The string may contain embedded zeros. - - -$luaL_addsize$ *lrv-luaL_addsize* --------------- -> - void luaL_addsize (luaL_Buffer *B, size_t n); -> -Adds to the buffer$B$(see |lrv-luaL_Buffer|) a string of length$n$previously -copied to the buffer area (see |lrv-luaL_prepbuffer|). - - -$luaL_addstring$ *lrv-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 -|lrv-luaL_Buffer|). The string may not contain embedded zeros. - - -$luaL_addvalue$ *lrv-luaL_addvalue* ---------------- -> - void luaL_addvalue (luaL_Buffer *B); -> -Adds the value at the top of the stack to the buffer$B$(see -|lrv-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$ *lrv-luaL_argcheck* ---------------- -> - void luaL_argcheck (lua_State *L, - int cond, - int narg, - const char *extramsg); -> -Checks whether$cond$is true. If not, raises an error with the following -message, where$func$is retrieved from the call stack: -> - bad argument #<narg> to <func> (<extramsg>) -> - -$luaL_argerror$ *lrv-luaL_argerror* ---------------- -> - int luaL_argerror (lua_State *L, int narg, const char *extramsg); -> -Raises an error with the following message, where$func$is retrieved from the -call stack: -> - bad argument #<narg> to <func> (<extramsg>) -> -This function never returns, but it is an idiom to use it in C functions as -$return luaL_argerror($@args@$)$. - - -$luaL_Buffer$ *lrv-luaL_Buffer* -------------- -> - typedef struct luaL_Buffer luaL_Buffer; -> -Type for a@string buffer@. - -A string buffer allows C code to build Lua strings piecemeal. Its pattern of -use is as follows: - - #o# First you declare a variable$b$of type$luaL_Buffer$. - #o# Then you initialize it with a call$luaL_buffinit(L, &b)$(see - |lrv-luaL_buffinit|). - #o# Then you add string pieces to the buffer calling any of the$luaL_add*$ - functions. - #o# You finish by calling$luaL_pushresult(&b)$(see |lrv-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 stack -slots. So, while using a buffer, you cannot assume that you know where the top -of the stack is. You can use the stack between successive calls to buffer -operations as long as that use is balanced; 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$|lrv-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$ *lrv-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 |lrv-luaL_Buffer|). - - -$luaL_callmeta$ *lrv-luaL_callmeta* ---------------- -> - int luaL_callmeta (lua_State *L, int obj, const char *e); -> -Calls a metamethod. - -If the object at index$obj$has a metatable and this metatable has a field$e$, -this function calls this field and passes the object as its only argument. In -this case this function returns 1 and pushes onto the stack the value returned -by the call. If there is no metatable or no metamethod, this function returns -0 (without pushing any value on the stack). - - -$luaL_checkany$ *lrv-luaL_checkany* ---------------- -> - 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$ *lrv-luaL_checkint* ---------------- -> - 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$ *lrv-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 |lrv-lua_Integer|). - - -$luaL_checklong$ *lrv-luaL_checklong* ----------------- -> - 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$ *lrv-luaL_checklstring* -------------------- -> - 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$ *lrv-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 |lrv-lua_Number|). - - -$luaL_checkoption$ *lrv-luaL_checkoption* ------------------- -> - int luaL_checkoption (lua_State *L, - int narg, - const char *def, - const char *const lst[]); -> -Checks whether the function argument$narg$is a string and searches for this -string in the array$lst$(which must be NULL-terminated). Returns the index in -the array where the string was found. Raises an error if the argument is not a -string or if the string cannot be found. - -If$def$is not$NULL$, the function uses$def$as a default value when there is no -argument$narg$or if this argument is#nil#. - -This is a useful function for mapping strings to C enums. (The usual -convention in Lua libraries is to use strings instead of numbers to select -options.) - - -$luaL_checkstack$ *lrv-luaL_checkstack* ------------------ -> - void luaL_checkstack (lua_State *L, int sz, const char *msg); -> -Grows the stack size to$top + sz$elements, raising an error if the stack -cannot grow to that size.$msg$is an additional text to go into the error -message. - - -$luaL_checkstring$ *lrv-luaL_checkstring* ------------------- -> - const char *luaL_checkstring (lua_State *L, int narg); -> -Checks whether the function argument$narg$is a string and returns this string. - - -$luaL_checktype$ *lrv-luaL_checktype* ----------------- -> - void luaL_checktype (lua_State *L, int narg, int t); -> -Checks whether the function argument$narg$has type$t$(see |lrv-lua_type|). - - -$luaL_checkudata$ *lrv-luaL_checkudata* ------------------ -> - 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 |lrv-luaL_newmetatable|). - - -$luaL_dofile$ *lrv-luaL_dofile* -------------- -> - int luaL_dofile (lua_State *L, const char *filename); -> -Loads and runs the given file. It is defined as the following macro: -> - (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$ *lrv-luaL_dostring* ---------------- -> - int luaL_dostring (lua_State *L, const char *str); -> -Loads and runs the given string. It is defined as the following macro: -> - (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$ *lrv-luaL_error* ------------- -> - 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 -|lrv-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. - -This function never returns, but it is an idiom to use it in C functions as -$return luaL_error($@args@$)$. - - -$luaL_getmetafield$ *lrv-luaL_getmetafield* -------------------- -> - int luaL_getmetafield (lua_State *L, int obj, const char *e); -> -Pushes onto the stack the field$e$from the metatable of the object at index -$obj$. If the object does not have a metatable, or if the metatable does not -have this field, returns 0 and pushes nothing. - - -$luaL_getmetatable$ *lrv-luaL_getmetatable* -------------------- -> - void luaL_getmetatable (lua_State *L, const char *tname); -> -Pushes onto the stack the metatable associated with name$tname$in the registry -(see |lrv-luaL_newmetatable|). - - -$luaL_gsub$ *lrv-luaL_gsub* ------------ -> - const char *luaL_gsub (lua_State *L, - const char *s, - const char *p, - const char *r); -> -Creates a copy of string$s$by replacing any occurrence of the string$p$with -the string$r$. Pushes the resulting string on the stack and returns it. - - -$luaL_loadbuffer$ *lrv-luaL_loadbuffer* ------------------ -> - 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 -|lrv-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$ *lrv-luaL_loadfile* ---------------- -> - int luaL_loadfile (lua_State *L, const char *filename); -> -Loads a file as a Lua chunk. This function uses$lua_load$(see |lrv-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$#$. - -This function returns the same results as$lua_load$, but it has an extra error -code$LUA_ERRFILE$if it cannot open/read the file. - -As$lua_load$, this function only loads the chunk; it does not run it. - - -$luaL_loadstring$ *lrv-luaL_loadstring* ------------------ -> - int luaL_loadstring (lua_State *L, const char *s); -> -Loads a string as a Lua chunk. This function uses$lua_load$(see -|lrv-lua_load|) to load the chunk in the zero-terminated string$s$. - -This function returns the same results as$lua_load$. - -Also as$lua_load$, this function only loads the chunk; it does not run it. - - -$luaL_newmetatable$ *lrv-luaL_newmetatable* -------------------- -> - int luaL_newmetatable (lua_State *L, const char *tname); -> -If the registry already has the key$tname$, returns 0. Otherwise, creates a -new table to be used as a metatable for userdata, adds it to the registry with -key$tname$, and returns 1. - -In both cases pushes onto the stack the final value associated with$tname$in -the registry. - - -$luaL_newstate$ *lrv-luaL_newstate* ---------------- -> - lua_State *luaL_newstate (void); -> -Creates a new Lua state. It calls$lua_newstate$(see |lrv-lua_newstate|) with an -allocator based on the standard C$realloc$function and then sets a panic -function (see |lrv-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$ *lrv-luaL_openlibs* ---------------- -> - void luaL_openlibs (lua_State *L); -> -Opens all standard Lua libraries into the given state. See also -|lrv-openlibs| for details on how to open individual libraries. - - -$luaL_optint$ *lrv-luaL_optint* -------------- -> - int luaL_optint (lua_State *L, int narg, int d); -> -If the function argument$narg$is a number, returns this number cast to an -$int$. If this argument is absent or is#nil#, returns$d$. Otherwise, raises an -error. - - -$luaL_optinteger$ *lrv-luaL_optinteger* ------------------ -> - 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 |lrv-lua_Integer|). If this argument is absent or is#nil#, -returns$d$. Otherwise, raises an error. - - -$luaL_optlong$ *lrv-luaL_optlong* --------------- -> - long luaL_optlong (lua_State *L, int narg, long d); -> -If the function argument$narg$is a number, returns this number cast to a -$long$. If this argument is absent or is#nil#, returns$d$. Otherwise, raises -an error. - - -$luaL_optlstring$ *lrv-luaL_optlstring* ------------------ -> - const char *luaL_optlstring (lua_State *L, - int narg, - const char *d, - size_t *l); -> -If the function argument$narg$is a string, returns this string. If this -argument is absent or is#nil#, returns$d$. Otherwise, raises an error. - -If$l$is not$NULL$, fills the position$*l$with the results's length. - - -$luaL_optnumber$ *lrv-luaL_optnumber* ----------------- -> - lua_Number luaL_optnumber (lua_State *L, int narg, lua_Number d); -> -If the function argument$narg$is a number, returns this number. If this -argument is absent or is#nil#, returns$d$. Otherwise, raises an error. - - -$luaL_optstring$ *lrv-luaL_optstring* ----------------- -> - const char *luaL_optstring (lua_State *L, - int narg, - const char *d); -> -If the function argument$narg$is a string, returns this string. If this -argument is absent or is#nil#, returns$d$. Otherwise, raises an error. - - -$luaL_prepbuffer$ *lrv-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 |lrv-luaL_Buffer|). After copying the -string into this space you must call$luaL_addsize$(see |lrv-luaL_addsize|) -with the size of the string to actually add it to the buffer. - - -$luaL_pushresult$ *lrv-luaL_pushresult* ------------------ -> - void luaL_pushresult (luaL_Buffer *B); -> -Finishes the use of buffer$B$leaving the final string on the top of the stack. - - -$luaL_ref$ *lrv-luaL_ref* ----------- -> - int luaL_ref (lua_State *L, int t); -> -Creates and returns a@reference@, in the table at index$t$, for the object at -the top of the stack (and pops the object). - -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 |lrv-lua_rawgeti|). Function$luaL_unref$(see -|lrv-luaL_unref|) frees a reference and its associated object. - -If the object at the top of the stack is#nil#,$luaL_ref$returns the constant -$LUA_REFNIL$. The constant$LUA_NOREF$is guaranteed to be different from any -reference returned by$luaL_ref$. - - -$luaL_Reg$ *lrv-luaL_Reg* ----------- -> - typedef struct luaL_Reg { - const char *name; - lua_CFunction func; - } luaL_Reg; -> -Type for arrays of functions to be registered by$luaL_register$ (see -|lrv-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$ *lrv-luaL_register* ---------------- -> - void luaL_register (lua_State *L, - const char *libname, - const luaL_Reg *l); -> -Opens a library. - -When called with$libname$equal to$NULL$, it simply registers all functions in -the list$l$(see |lrv-luaL_Reg|) into the table on the top of the stack. - -When called with a non-null$libname$,$luaL_register$creates a new table$t$, -sets it as the value of the global variable$libname$, sets it as the value of -$package.loaded[libname]$, and registers on it all functions in the list$l$. -If there is a table in$package.loaded[libname]$or in variable$libname$, reuses -this table instead of creating a new one. - -In any case the function leaves the table on the top of the stack. - - -$luaL_typename$ *lrv-luaL_typename* ---------------- -> - const char *luaL_typename (lua_State *L, int idx); -> -Returns the name of the type of the value at index$idx$. - - -$luaL_typerror$ *lrv-luaL_typerror* ---------------- -> - int luaL_typerror (lua_State *L, int narg, const char *tname); -> -Generates an error with a message like the following: - - @location@$: bad argument$@narg@$to$@'func'@$($@tname@$expected, got$@rt@$)$ - -where@location@is produced by$luaL_where$ (see |lrv-luaL_where|),@func@is the -name of the current function, and@rt@is the type name of the actual argument. - - -$luaL_unref$ *lrv-luaL_unref* ------------- -> - void luaL_unref (lua_State *L, int t, int ref); -> -Releases reference$ref$from the table at index$t$(see |lrv-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$ *lrv-luaL_where* ------------- -> - void luaL_where (lua_State *L, int lvl); -> -Pushes onto the stack a string identifying the current position of the control -at level$lvl$in the call stack. Typically this string has the following -format: - - @chunkname:currentline:@ - -Level 0 is the running function, level 1 is the function that called the -running function, etc. - -This function is used to build a prefix for error messages. - - -============================================================================== -5 STANDARD LIBRARIES *lrv-Lib* -============================================================================== - - -The standard libraries provide useful functions that are implemented directly -through the C API. Some of these functions provide essential services to the -language (e.g.,$type$and$getmetatable$); others provide access to "outside" -services (e.g., I/O); and others could be implemented in Lua itself, but are -quite useful or have critical performance requirements that deserve an -implementation in C (e.g.,$sort$). - -All libraries are implemented through the official C API and are provided as -separate C modules. Currently, Lua has the following standard libraries: - - #o# basic library; - #o# package library; - #o# string manipulation; - #o# table manipulation; - #o# mathematical functions (sin, log, etc.); - #o# input and output; - #o# operating system facilities; - #o# debug facilities. - -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. - - *lrv-openlibs* -To have access to these libraries, the C host program should call the -$luaL_openlibs$function, which opens all standard libraries (see -|lrv-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 |lrv-lua_call|). - - -============================================================================== -5.1 Basic Functions *lrv-libBasic* - - -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])$ *lrv-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])$ *lrv-collectgarbage* ------------------------------- -This function is a generic interface to the garbage collector. It performs -different functions according to its first argument,$opt$: - - #o##"stop"#: stops the garbage collector. - #o##"restart"#: restarts the garbage collector. - #o##"collect"#: performs a full garbage-collection cycle. - #o##"count"#: returns the total memory in use by Lua (in Kbytes). - #o##"step"#: performs a garbage-collection step. The step "size" is - controlled by$arg$(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$arg$. Returns#true#if the step finished a collection cycle. - #o##"setpause"#: sets$arg$/100 as the new value for the@pause@of the - collector (see |lrv-langGC|). - #o##"setstepmul"#: sets$arg$/100 as the new value for the@step multiplier@of - the collector (see |lrv-langGC|). - - -$dofile (filename)$ *lrv-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])$ *lrv-error* ---------------------------- -Terminates the last protected function called and returns$message$as the error -message. Function$error$never returns. - -Usually,$error$adds some information about the error position at the beginning -of the message. The$level$argument specifies how to get the error position. -With level 1 (the default), the error position is where the$error$function was -called. Level 2 points the error to where the function that called$error$was -called; and so on. Passing a level 0 avoids the addition of error position -information to the message. - - -$_G$ *lrv-_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)$ *lrv-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)$ *lrv-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)$ *lrv-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$ - -will iterate over the pairs ($1,t[1]$), ($2,t[2]$), ..., up to the first -integer key absent from the table. - - -$load (func [, chunkname])$ *lrv-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. - -If there are no errors, returns the compiled chunk as a function; otherwise, -returns#nil#plus the error message. The environment of the returned function -is the global environment. - -$chunkname$is used as the chunk name for error messages and debug information. - - -$loadfile ([filename])$ *lrv-loadfile* ------------------------ -Similar to$load$(see |lrv-load|), but gets the chunk from file$filename$or -from the standard input, if no file name is given. - - -$loadstring (string [, chunkname])$ *lrv-loadstring* ------------------------------------ -Similar to$load$(see |lrv-load|), but gets the chunk from the given string. - -To load and run a given string, use the idiom -> - assert(loadstring(s))() -> - -$next (table [, index])$ *lrv-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 called with#nil#as its -second argument,$next$returns an initial index and its associated value. When -called with the last index, or with#nil#in an empty table,$next$returns#nil#. -If the second argument is absent, then it is interpreted as#nil#. 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$|lrv-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)$ *lrv-pairs* ------------ -Returns three values: the$next$|lrv-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, ...)$ *lrv-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 status code (a boolean), which -is#true#if the call succeeds without errors. In such case,$pcall$also returns -all results from the call, after this first result. In case of any error, -$pcall$returns#false#plus the error message. - - -$print (...)$ *lrv-print* -------------- -Receives any number of arguments, and prints their values to$stdout$, using -the$tostring$|lrv-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 -|lrv-string.format|). - - -$rawequal (v1, v2)$ *lrv-rawequal* -------------------- -Checks whether$v1$is equal to$v2$, without invoking any metamethod. Returns a -boolean. - - -$rawget (table, index)$ *lrv-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)$ *lrv-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, ...)$ *lrv-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)$ *lrv-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 the given function. - -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)$ *lrv-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 metatable has -a$"__metatable"$field, raises an error. - -This function returns$table$. - - -$tonumber (e [, base])$ *lrv-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#. - -An optional argument specifies the base to interpret the numeral. The base may -be any integer between 2 and 36, inclusive. In bases above 10, the -letter$'A'$(in either upper or lower case) represents 10,$'B'$represents 11, -and so forth, with$'Z'$representing 35. In base 10 (the default), the number -may have a decimal part, as well as an optional exponent part (see -|lrv-langLexConv|). In other bases, only unsigned integers are accepted. - - -$tostring (e)$ *lrv-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 |lrv-string.format|). - - *lrv-__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)$ *lrv-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]])$ *lrv-unpack* ---------------------------- -Returns the elements from the given table. This function is equivalent to -> - return list[i], list[i+1], ..., list[j] -> -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 |lrv-langLength|). - - -$_VERSION$ *lrv-_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)$ *lrv-xpcall* ------------------ -This function is similar to$pcall$(see |lrv-pcall|), except that you can set a -new error handler. - -$xpcall$calls function$f$in protected mode, using$err$as the error handler. -Any error inside$f$is not propagated; instead,$xpcall$catches the error, calls -the$err$function with the original error object, and returns a status code. -Its first result is the status code (a boolean), which is true if the call -succeeds without errors. In this case,$xpcall$also returns all results from -the call, after this first result. In case of any error,$xpcall$returns#false# -plus the result from$err$. - - -============================================================================== -5.2 Coroutine Manipulation *lrv-libCoro* - - -The operations related to coroutines comprise a sub-library of the basic -library and come inside the table$coroutine$. See |lrv-langCoro| for a general -description of coroutines. - - -$coroutine.create (f)$ *lrv-coroutine.create* ----------------------- -Creates a new coroutine, with body$f$.$f$must be a Lua function. Returns this -new coroutine, an object with type$"thread"$. - - -$coroutine.resume (co [, val1, ...])$ *lrv-coroutine.resume* -------------------------------------- -Starts or continues the execution of coroutine$co$. The first time you resume -a coroutine, it starts running its body. The values$val1$, ... are passed as -arguments to the body function. If the coroutine has yielded,$resume$restarts -it; the values$val1$, ... are passed as the results from the yield. - -If the coroutine runs without any errors,$resume$returns#true#plus any values -passed to$yield$(if the coroutine yields) or any values returned by the body -function (if the coroutine terminates). If there is any error,$resume$returns -#false#plus the error message. - - -$coroutine.running ()$ *lrv-coroutine.running* ----------------------- -Returns the running coroutine, or#nil#when called by the main thread. - - -$coroutine.status (co)$ *lrv-coroutine.status* ------------------------ -Returns the status of coroutine$co$, as a string:$"running"$, if the coroutine -is running (that is, it called$status$);$"suspended"$, if the coroutine is -suspended in a call to$yield$, or if it has not started running yet; -$"normal"$if the coroutine is active but not running (that is, it has resumed -another coroutine); and$"dead"$if the coroutine has finished its body -function, or if it has stopped with an error. - - -$coroutine.wrap (f)$ *lrv-coroutine.wrap* --------------------- -Creates a new coroutine, with body$f$.$f$must be a Lua function. Returns a -function that resumes the coroutine each time it is called. Any arguments -passed to the function behave as the extra arguments to$resume$. Returns the -same values returned by$resume$, except the first boolean. In case of error, -propagates the error. - - -$coroutine.yield (...)$ *lrv-coroutine.yield* ------------------------ -Suspends the execution of the calling coroutine. The coroutine cannot be -running a C function, a metamethod, or an iterator. Any arguments to$yield$are -passed as extra results to$resume$. - - -============================================================================== -5.3 - Modules *lrv-libModule* - - -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 |lrv-require| and |lrv-module|). Everything else is -exported in a table$package$. - - -$module (name [, ...])$ *lrv-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 table$t$and sets it as the value -of the global$name$and the value of$package.loaded[name]$. This function also -initializes$t._NAME$with the given name,$t._M$with the module ($t$itself), and -$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 -|lrv-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 for each component. -For instance, if$name$is$a.b.c$, then$module$stores the module table in field -$c$of field$b$of global$a$. - -This function may receive optional@options@after the module name, where each -option is a function to be applied over the module. - - -$require (modname)$ *lrv-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$package.loaded[modname]$. -Otherwise, it tries to find a@loader@for the module. - -To find a loader, first$require$queries$package.preload[modname]$. If it has a -value, this value (which should be a function) is the loader. Otherwise -$require$searches for a Lua loader using the path stored in$package.path$. -If that also fails, it searches for a C loader using the path stored in -$package.cpath$. If that also fails, it tries an@all-in-one@loader (see -below). - -When loading a C library,$require$first uses a dynamic link facility to link -the application with the library. Then it tries to find a C function inside -this library to be used as the loader. The name of this C function is the -string$"luaopen_"$concatenated with a copy of the module name where each dot -is replaced by an underscore. Moreover, if the module name has a hyphen, its -prefix up to (and including) the first hyphen is removed. For instance, if the -module name is$a.v1-b.c$, the function name will be$luaopen_b_c$. - -If$require$finds neither a Lua library nor a C library for a module, it calls -the@all-in-one loader@. This loader searches the C path for a library for the -root name of the given module. For instance, when requiring$a.b.c$, it will -search for a C library for$a$. If found, it looks into it for an open function -for the submodule; in our example, that would be$luaopen_a_b_c$. With this -facility, a package can pack several C submodules into one single library, -with each submodule keeping its original open function. - -Once a loader is found,$require$calls the loader with a single argument, -$modname$. If the loader returns any value,$require$assigns the returned value -to$package.loaded[modname]$. If the loader returns no value and has not -assigned any value to$package.loaded[modname]$, then$require$assigns#true#to -this entry. In any case,$require$returns the final value of -$package.loaded[modname]$. - -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$ *lrv-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 initializes the -Lua path$package.path$, using the environment variable$LUA_CPATH$(plus another -default path defined in$luaconf.h$). - - -$package.loaded$ *lrv-package.loaded* ----------------- -A table used by$require$to control which modules are already 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)$ *lrv-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 |lrv-lua_CFunction|)). - -This is a low-level function. It completely bypasses the package and module -system. Unlike$require$, it does not perform any path searching and does not -automatically adds extensions.$libname$must be the complete file name of the -C library, including if necessary a path and extension.$funcname$must be the -exact name exported by the C library (which may depend on the C compiler and -linker used). - -This function is not supported by ANSI C. As such, it is only available on -some platforms (Windows, Linux, Mac OS X, Solaris, BSD, plus other Unix -systems that support the$dlfcn$standard). - - -$package.path$ *lrv-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 environment -variable$LUA_PATH$or with a default path defined in$luaconf.h$, if the -environment variable is not defined. Any$";;"$in the value of the environment -variable is replaced by the default path. - -A path is a sequence of@templates@separated by semicolons. For each template, -$require$will change each interrogation mark in the template by$filename$, -which is$modname$with each dot replaced by a "directory separator" (such as -$"/"$ in Unix); then it will try to load the resulting file name. So, for -instance, if the Lua path is -> - "./?.lua;./?.lc;/usr/local/?/init.lua" -> -the search for a Lua loader for module$foo$will try to load the files -$./foo.lua$,$./foo.lc$, and$/usr/local/foo/init.lua$, in that order. - - -$package.preload$ *lrv-package.preload* ------------------ -A table to store loaders for specific modules (see |lrv-require|). - - -$package.seeall (module)$ *lrv-package.seeall* -------------------------- -Sets a metatable for$module$with its$__index$field referring to the global -environment, so that this module inherits values from the global environment. -To be used as an option to function$module$. - - -============================================================================== -5.4 - String Manipulation *lrv-libString* - - -This library provides generic functions for string manipulation, such as -finding and extracting substrings, and pattern matching. When indexing a -string in Lua, the first character is at position 1 (not at 0, as in C). -Indices are allowed to be negative and are interpreted as indexing backwards, -from the end of the string. Thus, the last character is at position -1, and -so on. - -The string library provides all its functions inside the table$string$. -It also sets a metatable for strings where the$__index$field points to the -$string$table. Therefore, you can use the string functions in object-oriented -style. For instance,$string.byte(s, i)$can be written as$s:byte(i)$. - - - -$string.byte (s [, i [, j]])$ *lrv-string.byte* ------------------------------ -Returns the internal numerical codes of the characters$s[i]$,$s[i+1]$,..., -$s[j]$. The default value for$i$is 1; the default value for$j$is$i$. - -Note that numerical codes are not necessarily portable across platforms. - - -$string.char (...)$ *lrv-string.char* -------------------- -Receives zero or more integers. Returns a string with length equal to the -number of arguments, in which each character has the internal numerical code -equal to its correspondent argument. - -Note that numerical codes are not necessarily portable across platforms. - - -$string.dump (function)$ *lrv-string.dump* ------------------------- -Returns a string containing a binary representation of the given function, so -that a later$loadstring$on this string returns a copy of the function. -$function$must be a Lua function without upvalues. - - -$string.find (s, pattern [, init [, plain]])$ *lrv-string.find* ---------------------------------------------- -Looks for the first match of$pattern$in the string$s$. If it finds a match, -then$find$returns the indices of$s$where this occurrence starts and ends; -otherwise, it returns#nil#. A third, optional numerical argument$init$ -specifies where to start the search; its default value is 1 and may be -negative. A value of#true#as a fourth, optional argument$plain$turns off the -pattern matching facilities, so the function does a plain "find substring" -operation, with no characters in$pattern$being considered "magic". Note that -if$plain$is given, then$init$must be given as well. - - -If the pattern has captures, then in a successful match the captured values -are also returned, after the two indices. - - -$string.format (formatstring, ...)$ *lrv-string.format* ------------------------------------ -Returns a formatted version of its variable number of arguments following the -description given in its first argument (which must be a string). The format -string follows the same rules as the$printf$family of standard C functions. -The only differences are that the options/modifiers$*$,$l$,$L$,$n$,$p$, and$h$ -are not supported and that there is an extra option,$q$. The$q$option formats -a string in a form suitable to be safely read back by the Lua 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 -> - string.format('%q', 'a string with "quotes" and \n new line') -> -will produce the string: -> - "a string with \"quotes\" and \ - new line" -> -The options$c$,$d$,$E$,$e$,$f$,$g$,$G$,$i$,$o$,$u$,$X$, and$x$all expect a -number as argument, whereas$q$and$s$expect a string. - -This function does not accept string values containing embedded zeros. - - -$string.gmatch (s, pattern)$ *lrv-string.gmatch* ----------------------------- -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 in each -call. - -As an example, the following loop -> - s = "hello world from Lua" - for w in string.gmatch(s, "%a+") do - print(w) - end -> -will iterate over all the words from string$s$, printing one per line. -The next example collects all pairs$key=value$from the given string into a -table: -> - t = {} - s = "from=world, to=Lua" - for k, v in string.gmatch(s, "(%w+)=(%w+)") do - t[k] = v - end -> - -$string.gsub (s, pattern, repl [, n])$ *lrv-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 second value, the total number of -substitutions made. - -If$repl$is a string, then its value is used for replacement. The character$%$ -works as an escape character: any sequence in$repl$of the form$%n$, with@n@ -between 1 and 9, stands for the value of the@n@-th captured substring (see -below). The sequence$%0$stands for the whole match. The sequence$%%$stands for -a single$%$. - -If$repl$is a table, then the table is queried for every match, using the first -capture as the key; if the pattern specifies no captures, then the whole match -is used as the key. - -If$repl$is a function, then this function is called every time a match occurs, -with all captured substrings passed as arguments, in order; if the pattern -specifies no captures, then the whole match is passed as a sole argument. - -If the value returned by the table query or by the function call is a string -or a number, then it is used as the replacement string; otherwise, if it is -#false#or#nil#, then there is no replacement (that is, the original match is -kept in the string). - -The optional last parameter$n$limits the maximum number of substitutions to -occur. For instance, when$n$is 1 only the first occurrence of$pattern$is -replaced. - -Here are some examples: -> - x = string.gsub("hello world", "(%w+)", "%1 %1") - --> x="hello hello world world" - - x = string.gsub("hello world", "%w+", "%0 %0", 1) - --> x="hello hello world" - - x = string.gsub("hello world from Lua", "(%w+)%s*(%w+)", "%2 %1") - --> x="world hello Lua from" - - x = string.gsub("home = $HOME, user = $USER", "%$(%w+)", os.getenv) - --> x="home = /home/roberto, user = roberto" - - x = string.gsub("4+5 = $return 4+5$", "%$(.-)%$", function (s) - return loadstring(s)() - end) - --> x="4+5 = 9" - - local t = {name="lua", version="5.1"} - x = string.gsub("$name%-$version.tar.gz", "%$(%w+)", t) - --> x="lua-5.1.tar.gz" -> - -$string.len (s)$ *lrv-string.len* ----------------- -Receives a string and returns its length. The empty string$""$has length 0. -Embedded zeros are counted, so$"a\000b\000c"$has length 5. - - -$string.lower (s)$ *lrv-string.lower* ------------------- -Receives a string and returns a copy of this string with all uppercase letters -changed to lowercase. All other characters are left unchanged. The definition -of what an uppercase letter is depends on the current locale. - - -$string.match (s, pattern [, init])$ *lrv-string.match* ------------------------------------- -Looks for the first@match@of$pattern$in the string$s$. If it finds one, then -$match$returns the captures from the pattern; otherwise it returns#nil#. -If$pattern$specifies no captures, then the whole match is returned. A third, -optional numerical argument$init$specifies where to start the search; its -default value is 1 and may be negative. - - -$string.rep (s, n)$ *lrv-string.rep* -------------------- -Returns a string that is the concatenation of$n$copies of the string$s$. - - -$string.reverse (s)$ *lrv-string.reverse* --------------------- -Returns a string that is the string$s$reversed. - - -$string.sub (s, i [, j])$ *lrv-string.sub* -------------------------- -Returns the substring of$s$that starts at$i$and continues until$j$;$i$and$j$ -may be negative. If$j$is absent, then it is assumed to be equal to@-1@(which -is the same as the string length). In particular, the call$string.sub(s,1,j)$ -returns a prefix of$s$with length$j$, and$string.sub(s,-i)$returns a suffix -of$s$with length$i$. - - -$string.upper (s)$ *lrv-string.upper* ------------------- -Receives a string and returns a copy of that string with all lowercase letters -changed to uppercase. All other characters are left unchanged. The definition -of what a lowercase letter is depends on the current locale. - - ------------------------------------------------------------------------------- -5.4.1 Patterns *lrv-patterns* *lrv-libStringPat* - - -A@character class@is used to represent a set of characters. The following -combinations are allowed in describing a character class: - - #o#@x@: (where@x@is not one of@the magic characters@ ^$()%.[]*+-? ) - represents the character@x@itself. - #o#$.$: (a dot) represents all characters. - #o#$%a$: represents all letters. - #o#$%c$: represents all control characters. - #o#$%d$: represents all digits. - #o#$%l$: represents all lowercase letters. - #o#$%p$: represents all punctuation characters. - #o#$%s$: represents all space characters. - #o#$%u$: represents all uppercase letters. - #o#$%w$: represents all alphanumeric characters. - #o#$%x$: represents all hexadecimal digits. - #o#$%z$: represents the character with representation 0. - #o#$%x$(where@x@is any non-alphanumeric character) represents the - character@x@. This is the standard way to escape the magic characters. - Any punctuation character (even the non-magic) can be preceded by a - $'%'$when used to represent itself in a pattern. - - #o#$[set]$: represents the class which is the union of all characters in - @set@. A range of characters may be specified by separating the end - characters of the range with a$'-'$. All classes$%x$described above may - also be used as components in@set@. All other characters in@set@ - represent themselves. For example,$[%w_]$(or$[_%w]$) represents all - alphanumeric characters plus the underscore,$[0-7]$represents the octal - digits, and$[0-7%l%-]$represents the octal digits plus the lowercase - letters plus the$'-'$character. - - The interaction between ranges and classes is not defined. Therefore, - patterns like$[%a-z]$or$[a-%%]$have no meaning. - - #o#$[^set]$: represents the complement of@set@, where@set@is interpreted - as above. - -For all classes represented by single letters ($%a$,$%c$, etc.), the -corresponding uppercase letter represents the complement of the class. For -instance,$%S$represents all non-space characters. - -The definitions of letter, space, and other character groups depend on the -current locale. In particular, the class$[a-z]$may not be equivalent to$%l$. - - *lrv-patternitem* -Pattern Item:~ -------------- -A@pattern item@may be - - #o# a single character class, which matches any single character in the - class; - #o# a single character class followed by$'*'$, which matches 0 or more - repetitions of characters in the class. These repetition items will - always match the longest possible sequence; - #o# a single character class followed by$'+'$, which matches 1 or more - repetitions of characters in the class. These repetition items will - always match the longest possible sequence; - #o# a single character class followed by$'-'$, which also matches 0 or - more repetitions of characters in the class. Unlike$'*'$, these - repetition items will always match the@shortest@possible sequence; - #o# a single character class followed by$'?'$, which matches 0 or 1 - occurrences of a character in the class; - #o#$%n$, for@n@between 1 and 9; such item matches a substring equal to the - @n@-th captured string (see below); - #o#$%bxy$, where@x@and@y@are two distinct characters; such item matches - strings that start with@x@, end with@y@, and where the@x@and@y@ - are@balanced@. This means that, if one reads the string from left to - right, counting@+1@for an@x@and@-1@for a@y@, the ending@y@is the first - @y@where the count reaches 0. For instance, the item$%b()$matches - expressions with balanced parentheses. - - *lrv-pattern* -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. - - *lrv-capture* -Captures:~ ---------- -A pattern may contain sub-patterns enclosed in parentheses; they describe -@captures@. When a match succeeds, the substrings of the subject string that -match captures are stored (@captured@) for future use. Captures are numbered -according to their left parentheses. For instance, in the pattern -$"(a*(.)%w(%s*))"$, the part of the string matching$"a*(.)%w(%s*)"$is -stored as the first capture (and therefore has number 1); the character -matching$.$is captured with number 2, and the part matching$%s*$has number 3. - -As a special case, the empty capture$()$captures the current string position -(a number). For instance, if we apply the pattern$"()aa()"$on the -string$"flaaap"$, there will be two captures: 3 and 5. - -A pattern cannot contain embedded zeros. Use$%z$instead. - - -============================================================================== -5.5 Table Manipulation *lrv-libTable* - - -This library provides generic functions for table manipulation. It provides -all its functions inside the table$table$. - -Most functions in the table library assume that the table represents an array -or a list. For those functions, when we talk about the "length" of a table we -mean the result of the length operator. - - -$table.concat (table [, sep [, i [, j]]])$ *lrv-table.concat* ------------------------------------------- -Given an array where all elements are strings or numbers, returns -$table[i]..sep..table[i+1] ... sep..table[j]$. The default value for$sep$is -the empty string, the default for$i$is 1, and the default for$j$is the length -of the table. If$i$is greater than$j$, returns the empty string. - - -$table.foreach (table, f)$ *lrv-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 |lrv-next| for extra information about table traversals. - - -$table.foreachi (table, f)$ *lrv-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 the length of the -table. If$f$returns a non-#nil#value, then the loop is broken and this value -is returned as the result of$table.foreachi$. - - -$table.insert (table, [pos,] value)$ *lrv-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 |lrv-langLength|), so that a call$table.insert(t,x)$ -inserts$x$at the end of table$t$. - - -$table.maxn (table)$ *lrv-table.maxn* --------------------- -Returns the largest positive numerical index of the given table, or 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])$ *lrv-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 -|lrv-langLength|), so that a call$table.remove(t)$removes the last element of -table$t$. - - -$table.sort (table [, comp])$ *lrv-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 |lrv-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. - -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 *lrv-libMath* - - -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$. - - -$math.abs (x)$ *lrv-math.abs* --------------- -Returns the absolute value of$x$. - - -$math.acos (x)$ *lrv-math.acos* ---------------- -Returns the arc cosine of$x$(in radians). - - -$math.asin (x)$ *lrv-math.asin* ---------------- -Returns the arc sine of$x$(in radians). - - -$math.atan (x)$ *lrv-math.atan* ---------------- -Returns the arc tangent of$x$(in radians). - - -$math.atan2 (x, y)$ *lrv-math.atan2* -------------------- -Returns the arc tangent of$x/y$(in radians), but uses the signs of both -parameters to find the quadrant of the result. (It also handles correctly the -case of$y$being zero.) - - -$math.ceil (x)$ *lrv-math.ceil* ---------------- -Returns the smallest integer larger than or equal to$x$. - - -$math.cos (x)$ *lrv-math.cos* --------------- -Returns the cosine of$x$(assumed to be in radians). - - -$math.cosh (x)$ *lrv-math.cosh* ---------------- -Returns the hyperbolic cosine of$x$. - - -$math.deg (x)$ *lrv-math.deg* --------------- -Returns the angle$x$(given in radians) in degrees. - - -$math.exp (x)$ *lrv-math.exp* --------------- -Returns the value$e^x$. - - -$math.floor (x)$ *lrv-math.floor* ----------------- -Returns the largest integer smaller than or equal to$x$. - - -$math.fmod (x, y)$ *lrv-math.fmod* ------------------- -Returns the remainder of the division of$x$by$y$. - - -$math.frexp (x)$ *lrv-math.frexp* ----------------- -Returns$m$and$e$such that$x = m * 2^e$,$e$is an integer and the absolute value -of$m$is in the range@[0.5, 1)@(or zero when$x$is zero). - - -$math.huge$ *lrv-math.huge* ------------ -The value$HUGE_VAL$, a value larger than or equal to any other numerical -value. - - -$math.ldexp (m, e)$ *lrv-math.ldexp* -------------------- -Returns$m * 2^e$($e$should be an integer). - - -$math.log (x)$ *lrv-math.log* --------------- -Returns the natural logarithm of$x$. - - -$math.log10 (x)$ *lrv-math.log10* ----------------- -Returns the base-10 logarithm of$x$. - - -$math.max (x, ...)$ *lrv-math.max* -------------------- -Returns the maximum value among its arguments. - - -$math.min (x, ...)$ *lrv-math.min* -------------------- -Returns the minimum value among its arguments. - - -$math.modf (x)$ *lrv-math.modf* ---------------- -Returns two numbers, the integral part of$x$and the fractional part of$x$. - - -$math.pi$ *lrv-math.pi* ---------- -The value of@pi@. - - -$math.pow (x, y)$ *lrv-math.pow* ------------------ -Returns$x^y$. (You can also use the expression$x^y$to compute this value.) - - -$math.rad (x)$ *lrv-math.rad* --------------- -Returns the angle$x$(given in degrees) in radians. - - -$math.random ([m [, n]])$ *lrv-math.random* -------------------------- -This function is an interface to the simple pseudo-random generator function -$rand$provided by ANSI C. (No guarantees can be given for its statistical -properties.) - -When called without arguments, returns a pseudo-random real number in the -range@[0,1)@. When called with a number$m$,$math.random$returns a -pseudo-random integer in the range@[1, m]@. When called with two numbers$m$ -and$n$,$math.random$returns a pseudo-random integer in the range@[m, n]@. - - -$math.randomseed (x)$ *lrv-math.randomseed* ---------------------- -Sets$x$as the "seed" for the pseudo-random generator: equal seeds produce -equal sequences of numbers. - - -$math.sin (x)$ *lrv-math.sin* --------------- -Returns the sine of$x$(assumed to be in radians). - - -$math.sinh (x)$ *lrv-math.sinh* ---------------- -Returns the hyperbolic sine of$x$. - - -$math.sqrt (x)$ *lrv-math.sqrt* ---------------- -Returns the square root of$x$. (You can also use the expression$x^0.5$to -compute this value.) - - -$math.tan (x)$ *lrv-math.tan* --------------- -Returns the tangent of$x$(assumed to be in radians). - - -$math.tanh (x)$ *lrv-math.tanh* ---------------- -Returns the hyperbolic tangent of$x$. - - -============================================================================== -5.6 Input and Output Facilities *lrv-libIO* - - -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 -default input file and a default output file, and all input/output operations -are over these default files. The second style uses explicit file -descriptors. - -When using implicit file descriptors, all operations are supplied by -table$io$. When using explicit file descriptors, the operation$io.open$returns -a file descriptor and then all operations are supplied as methods of the file -descriptor. - -The table$io$also provides three predefined file descriptors with their usual -meanings from C:$io.stdin$,$io.stdout$, and$io.stderr$. - -Unless otherwise stated, all I/O functions return#nil#on failure (plus an -error message as a second result) and some value different from#nil#on -success. - - -$io.close ([file])$ *lrv-io.close* -------------------- -Equivalent to$file:close$. Without a$file$, closes the default output file. - - -$io.flush ()$ *lrv-io.flush* -------------- -Equivalent to$file:flush$over the default output file. - - -$io.input ([file])$ *lrv-io.input* -------------------- -When called with a file name, it opens the named file (in text mode), and sets -its handle as the default input file. When called with a file handle, it -simply sets this file handle as the default input file. When called without -parameters, it returns the current default input file. - -In case of errors this function raises the error, instead of returning an -error code. - - -$io.lines ([filename])$ *lrv-io.lines* ------------------------ -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 - - $for line in io.lines(filename) do$@body@$end$ - -will iterate over all lines of the file. When the iterator function detects -the end of file, it returns#nil#(to finish the loop) and automatically closes -the file. - -The call$io.lines()$(without a file name) is equivalent to -$io.input():lines()$; that is, it iterates over the lines of the default input -file. In this case it does not close the file when the loop ends. - - -$io.open (filename [, mode])$ *lrv-io.open* ------------------------------ -This function opens a file, in the mode specified in the string$mode$. It -returns a new file handle, or, in case of errors,#nil#plus an error message. - -The$mode$string can be any of the following: - - #o#@"r"@: read mode (the default); - #o#@"w"@: write mode; - #o#@"a"@: append mode; - #o#@"r+"@: update mode, all previous data is preserved; - #o#@"w+"@: update mode, all previous data is erased; - #o#@"a+"@: append update mode, previous data is preserved, writing is only - allowed at the end of file. - -The$mode$string may also have a$'b'$at the end, which is needed in some -systems to open the file in binary mode. This string is exactly what is used -in the standard C function$fopen$. - - -$io.output ([file])$ *lrv-io.output* --------------------- -Similar to$io.input$, but operates over the default output file. - - -$io.popen (prog [, mode])$ *lrv-io.popen* --------------------------- -Starts program$prog$in a separated process and returns a file handle that you -can use to read data from this program (if$mode$is$"r"$, the default) or to -write data to this program (if$mode$is$"w"$). - -This function is system dependent and is not available on all platforms. - - -$io.read (...)$ *lrv-io.read* ---------------- -Equivalent to$io.input():read$. - - -$io.tmpfile ()$ *lrv-io.tmpfile* ---------------- -Returns a handle for a temporary file. This file is opened in update mode and -it is automatically removed when the program ends. - - -$io.type (obj)$ *lrv-io.type* ---------------- -Checks whether$obj$is a valid file handle. Returns the string$"file"$if$obj$is -an open file handle,$"closed file"$if$obj$is a closed file handle, or#nil#if -$obj$is not a file handle. - - -$io.write (...)$ *lrv-io.write* ----------------- -Equivalent to$io.output():write$. - - -$file:close ()$ *lrv-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 ()$ *lrv-file:flush* ---------------- -Saves any written data to$file$. - - -$file:lines ()$ *lrv-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$ - -will iterate over all lines of the file. (Unlike$io.lines$, this function does -not close the file when the loop ends.) - - -$file:read (...)$ *lrv-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 the specified format. When -called without formats, it uses a default format that reads the entire next -line (see below). - -The available formats are - - #o##"*n"#: reads a number; this is the only format that returns a number - instead of a string. - #o##"*a"#: reads the whole file, starting at the current position. On end of - file, it returns the empty string. - #o##"*l"#: reads the next line (skipping the end of line), returning#nil#on - end of file. This is the default format. - #o#@number@: reads a string with up to that number of characters, returning - #nil#on end of file. If number is zero, it reads nothing and returns an - empty string, or#nil#on end of file. - - -$file:seek ([whence] [, offset])$ *lrv-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: - - #o##"set"#: base is position 0 (beginning of the file); - #o##"cur"#: base is current position; - #o##"end"#: base is end of file; - -In case of success, function$seek$returns the final file position, measured in -bytes from the beginning of the file. If this function fails, it returns#nil#, -plus a string describing the error. - -The default value for$whence$is$"cur"$, and for$offset$is 0. Therefore, the -call$file:seek()$returns the current file position, without changing it; the -call$file:seek("set")$sets the position to the beginning of the file (and -returns 0); and the call$file:seek("end")$sets the position to the end of the -file, and returns its size. - - -$file:setvbuf (mode [, size])$ *lrv-file:setvbuf* ------------------------------- -Sets the buffering mode for an output file. There are three available modes: - - #o##"no"#: no buffering; the result of any output operation appears - immediately. - #o##"full"#: full buffering; output operation is performed only when the - buffer is full (or when you explicitly$flush$the file (see - |lrv-io.flush|). - #o##"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). - -For the last two cases,$size$specifies the size of the buffer, in bytes. -The default is an appropriate size. - - -$file:write (...)$ *lrv-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$|lrv-tostring| or -$string.format$|lrv-string.format| before$write$. - - -============================================================================== -5.8 Operating System Facilities *lrv-libOS* - - -This library is implemented through table$os$. - - -$os.clock ()$ *lrv-os.clock* -------------- -Returns an approximation of the amount in seconds of CPU time used by the -program. - - -$os.date ([format [, time]])$ *lrv-os.date* ------------------------------ -Returns a string or a table containing date and time, formatted according to -the given string$format$. - -If the$time$argument is present, this is the time to be formatted (see the -$os.time$function |lrv-os.time| for a description of this value). Otherwise, -$date$formats the current time. - -If$format$starts with$'!'$,then the date is formatted in Coordinated Universal -Time. After this optional character, if$format$is the string$"*t"$, then$date$ -returns a table with the following fields:$year$(four digits),$month$(1-12), -$day$(1-31),$hour$(0-23),$min$(0-59),$sec$(0-61),$wday$(weekday, Sunday is 1), -$yday$(day of the year), and$isdst$(daylight saving flag, a boolean). - -If$format$is not$"*t"$, then$date$returns the date as a string, formatted -according to the same rules as the C function$strftime$. - -When called without arguments,$date$returns a reasonable date and time -representation that depends on the host system and on the current locale (that -is,$os.date()$is equivalent to$os.date("%c")$). - - -$os.difftime (t2, t1)$ *lrv-os.difftime* ----------------------- -Returns the number of seconds from time$t1$to time$t2$. In POSIX, Windows, and -some other systems, this value is exactly$t2 - t1$. - - -$os.execute ([command])$ *lrv-os.execute* ----------------------- -This function is equivalent to the C function$system$. It passes$command$to be -executed by an operating system shell. It returns a status code, which is -system-dependent. If$command$is absent, then it returns nonzero if a shell is -available and zero otherwise. - - -$os.exit ([code])$ *lrv-os.exit* ------------------- -Calls the C function$exit$, with an optional$code$, to terminate the host -program. The default value for$code$is the success code. - - -$os.getenv (varname)$ *lrv-os.getenv* ---------------------- -Returns the value of the process environment variable$varname$, or#nil#if the -variable is not defined. - - -$os.remove (filename)$ *lrv-os.remove* ----------------------- -Deletes the file with the given name. Directories must be empty to be removed. -If this function fails, it returns#nil#, plus a string describing the error. - - -$os.rename (oldname, newname)$ *lrv-os.rename* ------------------------------- -Renames file named$oldname$to$newname$. If this function fails, it returns -#nil#, plus a string describing the error. - - -$os.setlocale (locale [, category])$ *lrv-os.setlocale* ------------------------------------- -Sets the current locale of the program.$locale$is a string specifying a -locale;$category$is an optional string describing which category to change: -$"all"$,$"collate"$,$"ctype"$,$"monetary"$,$"numeric"$, or$"time"$; the -default category is$"all"$. The function returns the name of the new locale, -or#nil#if the request cannot be honored. - - -$os.time ([table])$ *lrv-os.time* -------------------- -Returns the current time when called without arguments, or a 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 |lrv-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 number of -seconds since some given start time (the "epoch"). In other systems, the -meaning is not specified, and the number returned by$time$can be used only as -an argument to$date$and$difftime$. - - -$os.tmpname ()$ *lrv-os.tmpname* ---------------- -Returns a string with a file name that can be used for a temporary file. The -file must be explicitly opened before its use and explicitly removed when no -longer needed. - - -============================================================================== -5.9 The Debug Library *lrv-libDebug* - - -This library provides the functionality of the debug interface to Lua -programs. You should exert care when using this library. The functions -provided here should be used exclusively for debugging and similar tasks, such -as profiling. Please resist the temptation to use them as a usual programming -tool: they can be very slow. Moreover, several of its functions violate some -assumptions about Lua code (e.g., that variables local to a function cannot be -accessed from outside or that userdata metatables cannot be changed by Lua -code) and therefore can compromise otherwise secure code. - -All functions in this library are provided inside the$debug$table. All -functions that operate over a thread have an optional first argument which is -the thread to operate over. The default is always the current thread. - - -$debug.debug ()$ *lrv-debug.debug* ----------------- -Enters an interactive mode with the user, running each string that the user -enters. Using simple commands and other debug facilities, the user can inspect -global and local variables, change their values, evaluate expressions, and so -on. A line containing only the word$cont$finishes this function, so that the -caller continues its execution. - -Note that commands for$debug.debug$are not lexically nested within any -function, and so have no direct access to local variables. - - -$debug.getfenv (o)$ *lrv-debug.getfenv* -------------------- -Returns the environment of object$o$. - - -$debug.gethook ([thread])$ *lrv-debug.gethook* --------------------------- -Returns the current hook settings of the thread, as three values: the current -hook function, the current hook mask, and the current hook count (as set by -the$debug.sethook$function). - - -$debug.getinfo ([thread,] function [, what])$ *lrv-debug.getinfo* ---------------------------------------------- -Returns a table with information about a function. You can give the function -directly, or you can give a number as the value of$function$, which means the -function running at level$function$of the call stack of the given thread: -level 0 is the current function ($getinfo$itself); level 1 is the function -that called$getinfo$; and so on. If$function$is a number larger than the -number of active functions, then$getinfo$returns#nil#. - -The returned table may contain all the fields returned by$lua_getinfo$(see -|lrv-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 itself. If present, the option$'L'$adds a field named$activelines$ -with the table of valid lines. - -For instance, the expression$debug.getinfo(1,"n").name$returns the name of the -current function, if a reasonable name can be found, and$debug.getinfo(print)$ -returns a table with all available information about the$print$function. - - -$debug.getlocal ([thread,] level, local)$ *lrv-debug.getlocal* ------------------------------------------ -This function returns the name and the value of the local variable with index -$local$of the function at level$level$of the stack. (The first parameter or -local variable has index 1, and so on, until the last active local variable.) -The function returns#nil#if there is no local variable with the given index, -and raises an error when called with a$level$out of range. (You can call -$debug.getinfo$|lrv-debug.getinfo| to check whether the level is valid.) - -Variable names starting with$'('$(open parentheses) represent internal -variables (loop control variables, temporaries, and C function locals). - - -$debug.getmetatable (object)$ *lrv-debug.getmetatable* ------------------------------ -Returns the metatable of the given$object$or#nil#if it does not have a -metatable. - - -$debug.getregistry ()$ *lrv-debug.getregistry* ----------------------- -Returns the registry table (see |lrv-apiRegistry|). - - -$debug.getupvalue (func, up)$ *lrv-debug.getupvalue* ------------------------------ -This function returns the name and the value of the upvalue with index$up$of -the function$func$. The function returns#nil#if there is no upvalue with the -given index. - - -$debug.setfenv (object, table)$ *lrv-debug.setfenv* -------------------------------- -Sets the environment of the given$object$to the given$table$. Returns$object$. - - -$debug.sethook ([thread,] hook, mask [, count])$ *lrv-debug.sethook* ------------------------------------------------- -Sets the given function as a hook. The string$mask$and the number$count$ -describe when the hook will be called. The string mask may have the following -characters, with the given meaning: - - #o#@"c"@: The hook is called every time Lua calls a function; - #o#@"r"@: The hook is called every time Lua returns from a function; - #o#@"l"@: The hook is called every time Lua enters a new line of code. - -With a$count$different from zero, the hook is called after every$count$ -instructions. - -When called without arguments, the$debug.sethook$turns off the hook. - -When the hook is called, its first parameter is a string describing the -event that triggered its call:$"call"$,$"return"$(or$"tail return"$),$"line"$, -and$"count"$. For line events, the hook also gets the new line number as its -second parameter. Inside a hook, you can call$getinfo$with level 2 to get -more information about the running function (level 0 is the$getinfo$function, -and level 1 is the hook function), unless the event is$"tail return"$. In this -case, Lua is only simulating the return, and a call to$getinfo$will return -invalid data. - - -$debug.setlocal ([thread,] level, local, value)$ *lrv-debug.setlocal* ------------------------------------------------- -This function assigns the value$value$to the local variable with index$local$ -of the function at level$level$of the stack. The function returns#nil#if there -is no local variable with the given index, and raises an error when called -with a$level$out of range. (You can call$getinfo$to check whether the level is -valid.) Otherwise, it returns the name of the local variable. - - -$debug.setmetatable (object, table)$ *lrv-debug.setmetatable* ------------------------------------- -Sets the metatable for the given$object$to the given$table$(which can be -#nil#). - - -$debug.setupvalue (func, up, value)$ *lrv-debug.setupvalue* ------------------------------------- -This function assigns the value$value$to the upvalue with index$up$of the -function$func$. The function returns#nil#if there is no upvalue with the given -index. Otherwise, it returns the name of the upvalue. - - -$debug.traceback ([thread,] [message] [,level])$ *lrv-debug.traceback* ------------------------------------------------- -Returns a string with a traceback of the call stack. An optional$message$ -string is appended at the beginning of the traceback. An optional$level$number -tells at which level to start the traceback (default is 1, the function -calling$traceback$). - - -============================================================================== -6 LUA STAND-ALONE *lrv-lua* *lrv-LuaSA* -============================================================================== - - -Although Lua has been designed as an extension language, to be embedded in a -host C program, it is also frequently used as a stand-alone language. An -interpreter for Lua as a stand-alone language, called simply$lua$, is provided -with the standard distribution. The stand-alone interpreter includes all -standard libraries, including the debug library. Its usage is: -> - lua [options] [script [args]] -> -The options are: - - #o#$-e$@stat@: executes string@stat@; - #o#$-l$@mod@: "requires"@mod@; - #o#$-i$: enters interactive mode after running@script@; - #o#$-v$: prints version information; - #o#$--$: stops handling options; - #o#$-$: executes$stdin$as a file and stops handling options. - -After handling its options,$lua$runs the given@script@, passing to it the -given@args@as string arguments. When called without arguments,$lua$behaves -as$lua -v -i$when the standard input ($stdin$) is a terminal, and as -$lua -$otherwise. - -Before running any argument, the interpreter checks for an environment -variable$LUA_INIT$. If its format is$@filename$, then$lua$executes the file. -Otherwise,$lua$executes the string itself. - -All options are handled in order, except$-i$. For instance, an invocation -like -> - $ lua -e'a=1' -e 'print(a)' script.lua -> -will first set$a$to 1, then print the value of$a$(which is$'1'$), and finally -run the file$script.lua$with no arguments. (Here, '$' is the shell prompt. -Your prompt may be different.) - -Before starting to run the script,$lua$collects all arguments in the command -line in a global table called$arg$. The script name is stored in index 0, the -first argument after the script name goes to index 1, and so on. Any arguments -before the script name (that is, the interpreter name plus the options) go to -negative indices. For instance, in the call -> - $ lua -la b.lua t1 t2 -> -the interpreter first runs the file$a.lua$, then creates a table -> - arg = { [-2] = "lua", [-1] = "-la", - [0] = "b.lua", - [1] = "t1", [2] = "t2" } -> -and finally runs the file$b.lua$. The script is called with$arg[1]$,$arg[2]$, -... as arguments; it can also access these arguments with the vararg expression -$'...'$. - -In interactive mode, if you write an incomplete statement, the interpreter -waits for its completion by issuing a different prompt. - -If the global variable$_PROMPT$contains a string, then its value is used as -the prompt. Similarly, if the global variable$_PROMPT2$contains a string, its -value is used as the secondary prompt (issued during incomplete statements). -Therefore, both prompts can be changed directly on the command line. For -instance, -> - $ lua -e"_PROMPT='myprompt> '" -i -> -(the outer pair of quotes is for the shell, the inner pair is for Lua), or in -any Lua programs by assigning to$_PROMPT$. Note the use of$-i$to enter -interactive mode; otherwise, the program would just end silently right after -the assignment to$_PROMPT$. - -To allow the use of Lua as a script interpreter in Unix systems, the -stand-alone interpreter skips the first line of a chunk if it starts with$#$. -Therefore, Lua scripts can be made into executable programs by using$chmod +x$ -and the$#!$form, as in -> - #!/usr/local/bin/lua -> -(Of course, the location of the Lua interpreter may be different in your -machine. If$lua$is in your$PATH$, then -> - #!/usr/bin/env lua -> -is a more portable solution.) - - -============================================================================== -A BIBLIOGRAPHY *lrv-bibliography* -============================================================================== - -This help file is a minor adaptation from this main reference: - - #o# R. Ierusalimschy, L. H. de Figueiredo, and W. Celes., - "Lua: 5.1 reference manual",$http://www.lua.org/manual/5.1/manual.html$ - -Lua is discussed in these references: - - #o#R. Ierusalimschy, L. H. de Figueiredo, and W. Celes., - "Lua --- an extensible extension language". - @Software: Practice & Experience@#26##6 (1996) 635-652. - - #o#L. H. de Figueiredo, R. Ierusalimschy, and W. Celes., - "The design and implementation of a language for extending applications". - @Proc. of XXI Brazilian Seminar on Software and Hardware@(1994) 273-283. - - #o#L. H. de Figueiredo, R. Ierusalimschy, and W. Celes., - "Lua: an extensible embedded language". - @Dr. Dobb's Journal@#21##12 (Dec 1996) 26-33. - - #o#R. Ierusalimschy, L. H. de Figueiredo, and W. Celes., - "The evolution of an extension language: a history of Lua". - @Proc. of V Brazilian Symposium on Programming Languages@(2001) B-14-B-28. - - -============================================================================== -B COPYRIGHT & LICENSES *lrv-copyright* -============================================================================== - - -This help file has the same copyright and license as Lua 5.1 and the Lua 5.1 - manual: - -Copyright (c) 1994-2006 Lua.org, PUC-Rio. - -Permission is hereby granted, free of charge, to any person obtaining a copy -of this software and associated documentation files (the "Software"), to deal -in the Software without restriction, including without limitation the rights -to use, copy, modify, merge, publish, distribute, sublicense, and/or sell -copies of the Software, and to permit persons to whom the Software is -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. - - -============================================================================== -C LUAREFVIM DOC *luarefvim* *luarefvimdoc* *lrv-help* *lrv-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 |lrv-bibliography|). For usage information, refer to |lrv-docUsage|; for -instalation, refer to |lrv-docInstall|. - -This manual is composed of three parts: this file,$luarefvim.txt$, that is, -the manual itself; a plugin file, $luarefvim.vim$, defining key bindings; and -a help file syntax extension, $help.vim$. See |lrv-docInstall| for more -information on these files. For copyright information, see |lrv-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$). - - -============================================================================== -C.1 Installation *lrv-docInstall* - - -This reference consists of three files: the manual itself,$luarefvim.txt$, -a plugin file,$luarefvim.vim$, to load key bindings, and a help file syntax -extension$help.vim$. To install luarefvim, copy these files to their -respective locations: - - +-----------------+----------------+ - |# file #|# location #| - + ----------------+----------------+ - |$ luarefvim.txt $|$ doc $| - |$ luarefvim.vim $|$ plugin $| - |$ help.vim $|$ after/syntax $| - +-----------------+----------------+ - -where #location# is relative to 'runtimepath', that is, $HOME/.vim for a local -Un*x install or $HOME/vimfiles for a local Win32 install, for example. -Finally, to generate the tags, change dir to$doc$above (where you installed -$luarefvim.txt$), start Vim, and issue$:helptags .$For more information on -installing help files, call$:help add-local-help$. - - -============================================================================== -C.2 Usage *lrv-docUsage* - - -The usage is really simple, and similar to CRefVim: - - +----------+--------------+----------------------------------------+ - |# edit #|# key #| | - |# mode #|# sequence #|# action #| - +----------+--------------+----------------------------------------+ - |@ normal @| <Leader>lr | reference for word under cursor | - |@ visual @| <Leader>lr | reference for visually selected text | - |$ any $| <Leader>lc | manual's table of contents | - +----------+--------------+----------------------------------------+ - -Since by default <Leader> is mapped to$'\'$, just pressing$\lc$would bring the -table of contents, for example.$lr$stands for@(l)ua (r)eference@, while$lc$ -stands for@(l)ua (c)ontents@. - - ------------------------------------------------------------------------------- - vi:tw=78:ts=4:ft=help:norl:noai - |