diff options
Diffstat (limited to 'doc/manual.html')
| -rw-r--r-- | doc/manual.html | 4612 |
1 files changed, 0 insertions, 4612 deletions
diff --git a/doc/manual.html b/doc/manual.html deleted file mode 100644 index 2a92d2aa..00000000 --- a/doc/manual.html +++ /dev/null @@ -1,4612 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN"> -<html> - -<head> -<TITLE>Lua: 5.0 reference manual</TITLE> -</head> - -<body BGCOLOR="#FFFFFF"> - -<hr> -<h1> -<A HREF="http://www.lua.org/home.html"><IMG SRC="logo.gif" ALT="Lua" BORDER=0></A> -Lua 5.0 Reference Manual -</h1> - -by Roberto Ierusalimschy, Luiz Henrique de Figueiredo, Waldemar Celes -<p> -<small> -<a HREF="http://www.lua.org/copyright.html">Copyright</a> -© 2003 Tecgraf, PUC-Rio. All rights reserved. -</small> -<hr> - -<p> -<p> -<!-- ====================================================================== --> - - - -<a name="1"><h1>1 - Introduction</h1></a> - -<p>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 -configuration language for any program that needs one. -Lua is implemented as a library, written in <em>clean</em> C -(that is, in the common subset of ANSI C and C++). - -<p>Being an extension language, Lua has no notion of a "main" program: -it only works <em>embedded</em> in a host client, -called the <em>embedding program</em> or simply the <em>host</em>. -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. - -<p>The Lua distribution includes a stand-alone embedding program, -<code>lua</code>, that uses the Lua library to offer a complete Lua interpreter. - -<p>Lua is free software, -and is provided as usual with no guarantees, -as stated in its copyright notice. -The implementation described in this manual is available -at Lua's official web site, <code>www.lua.org</code>. - -<p>Like any other reference manual, -this document is dry in places. -For a discussion of the decisions behind the design of Lua, -see the papers below, -which are available at Lua's web site. -<ul> -<li> -R. Ierusalimschy, L. H. de Figueiredo, and W. Celes. -Lua---an extensible extension language. -<em>Software: Practice & Experience</em> <b>26</b> #6 (1996) 635-652. -<li> -L. H. de Figueiredo, R. Ierusalimschy, and W. Celes. -The design and implementation of a language for extending applications. -<em>Proceedings of XXI Brazilian Seminar on Software and Hardware</em> (1994) 273-283. -<li> -L. H. de Figueiredo, R. Ierusalimschy, and W. Celes. -Lua: an extensible embedded language. -<em>Dr. Dobb's Journal</em> <b>21</b> #12 (Dec 1996) 26-33. -<li> -R. Ierusalimschy, L. H. de Figueiredo, and W. Celes. -The evolution of an extension language: a history of Lua, -<em>Proceedings of V Brazilian Symposium on Programming Languages</em> (2001) B-14-B-28. -</ul> - -<p>Lua means "moon" in Portuguese and is pronounced LOO-ah. - -<p> -<a name="language"><a name="2"><h1>2 - The Language</h1></a></a> - -<p>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. - -<p>The language constructs will be explained using the usual extended BNF, -in which -{<em>a</em>} means 0 or more <em>a</em>'s, and -[<em>a</em>] means an optional <em>a</em>. -Non-terminals are shown in <em>italics</em>, -keywords are shown in <b>bold</b>, -and other terminal symbols are shown in <code>typewriter</code> font, -enclosed in single quotes. - -<p><a name="lexical"><a name="2.1"><h2>2.1 - Lexical Conventions</h2></a></a> - -<p><em>Identifiers</em> 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.) - -<p>The following <em>keywords</em> are reserved -and cannot be used as identifiers: - -<PRE> - and break do else elseif - end false for function if - in local nil not or - repeat return then true until while -</PRE> - -<p>Lua is a case-sensitive language: -<code>and</code> is a reserved word, but <code>And</code> and <code>AND</code> -are two different, valid identifiers. -As a convention, identifiers starting with an underscore followed by -uppercase letters (such as <code>_VERSION</code>) -are reserved for internal variables used by Lua. - -<p>The following strings denote other tokens: -<PRE> - + - * / ^ = - ~= <= >= < > == - ( ) { } [ ] - ; : , . .. ... -</PRE> - -<p><em>Literal strings</em> -can be delimited by matching single or double quotes, -and can contain the following C-like escape sequences: -<ul> -<li><b><code>\a</code></b> --- bell -<li><b><code>\b</code></b> --- backspace -<li><b><code>\f</code></b> --- form feed -<li><b><code>\n</code></b> --- newline -<li><b><code>\r</code></b> --- carriage return -<li><b><code>\t</code></b> --- horizontal tab -<li><b><code>\v</code></b> --- vertical tab -<li><b><code>\\</code></b> --- backslash -<li><b><code>\"</code></b> --- quotation mark -<li><b><code>\'</code></b> --- apostrophe -<li><b><code>\[</code></b> --- left square bracket -<li><b><code>\]</code></b> --- right square bracket -</ul> -Moreover, a `<code>\</code><em>newline</em>´ -(that is, 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 `<code>\</code><em>ddd</em>´, -where <em>ddd</em> is a sequence of up to three decimal digits. -Strings in Lua may contain any 8-bit value, including embedded zeros, -which can be specified as `<code>\0</code>´. - -<p>Literal strings can also be delimited by matching double square brackets -<code>[[</code> · · · <code>]]</code>. -Literals in this bracketed form may run for several lines, -may contain nested <code>[[</code> · · · <code>]]</code> pairs, -and do not interpret any escape sequences. -For convenience, -when the opening `<code>[[</code>´ is immediately followed by a newline, -the newline is not included in the string. -As an example, in a system using ASCII -(in which `<code>a</code>´ is coded as 97, -newline is coded as 10, and `<code>1</code>´ is coded as 49), -the four literals below denote the same string: -<PRE> - (1) "alo\n123\"" - (2) '\97lo\10\04923"' - (3) [[alo - 123"]] - (4) [[ - alo - 123"]] -</PRE> - -<p><em>Numerical constants</em> may be written with an optional decimal part -and an optional decimal exponent. -Examples of valid numerical constants are -<PRE> - 3 3.0 3.1416 314.16e-2 0.31416E1 -</PRE> - -<p><em>Comments</em> start anywhere outside a string with a -double hyphen (<code>--</code>). -If the text immediately after <code>--</code> is different from <code>[[</code>, -the comment is a <em>short comment</em>, -which runs until the end of the line. -Otherwise, it is a <em>long comment</em>, -which runs until the corresponding <code>]]</code>. -Long comments may run for several lines -and may contain nested <code>[[</code> · · · <code>]]</code> pairs. - -<p>For convenience, -the first line of a chunk is skipped if it starts with <code>#</code>. -This facility allows the use of Lua as a script interpreter -in Unix systems (see <a href="#lua-sa">6</a>). - -<p><a name="TypesSec"><a name="2.2"><h2>2.2 - Values and Types</h2></a></a> - -<p>Lua is a <em>dynamically typed language</em>. -That means that -variables do not have types; only values do. -There are no type definitions in the language. -All values carry their own type. - -<p>There are eight basic types in Lua: -<em>nil</em>, <em>boolean</em>, <em>number</em>, -<em>string</em>, <em>function</em>, <em>userdata</em>, <em>thread</em>, and <em>table</em>. -<em>Nil</em> is the type of the value <B>nil</B>, -whose main property is to be different from any other value; -usually it represents the absence of a useful value. -<em>Boolean</em> is the type of the values <B>false</B> and <B>true</B>. -In Lua, both <B>nil</B> and <B>false</B> make a condition false; -any other value makes it true. -<em>Number</em> 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.) -<em>String</em> represents arrays of characters. - -Lua is 8-bit clean: -Strings may contain any 8-bit character, -including embedded zeros (<code>'\0'</code>) (see <a href="#lexical">2.1</a>). - -<p>Functions are <em>first-class values</em> in Lua. -That means that functions can be stored in variables, -passed as arguments to other functions, and returned as results. -Lua can call (and manipulate) functions written in Lua and -functions written in C -(see <a href="#functioncall">2.5.7</a>). - -<p>The type <em>userdata</em> 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 <em>metatables</em>, -the programmer can define operations for userdata values -(see <a href="#metatable">2.8</a>). -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. - -<p>The type <em>thread</em> represents independent threads of execution -and it is used to implement coroutines. - -<p>The type <em>table</em> implements associative arrays, -that is, arrays that can be indexed not only with numbers, -but with any value (except <B>nil</B>). -Moreover, -tables can be <em>heterogeneous</em>, -that is, they can contain values of all types (except <B>nil</B>). -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 <code>a.name</code> as syntactic sugar for <code>a["name"]</code>. -There are several convenient ways to create tables in Lua -(see <a href="#tableconstructor">2.5.6</a>). - -<p>Like indices, -the value of a table field can be of any type (except <B>nil</B>). -In particular, -because functions are first class values, -table fields may contain functions. -Thus tables may also carry <em>methods</em> (see <a href="#func-def">2.5.8</a>). - -<p>Tables, functions, and userdata values are <em>objects</em>: -variables do not actually <em>contain</em> these values, -only <em>references</em> to them. -Assignment, parameter passing, and function returns -always manipulate references to such values; -these operations do not imply any kind of copy. - -<p>The library function <code>type</code> returns a string describing the type -of a given value (see <a href="#pdf-type">5.1</a>). - -<p><a name="coercion"><a name="2.2.1"><h3>2.2.1 - Coercion</h3></a></a> - -<p>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 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 <code>format</code> function from the string library (see <a href="#format">5.3</a>). - -<p><a name="variables"><a name="2.3"><h2>2.3 - Variables</h2></a></a> - -<p>Variables are places that store values. - -There are three kinds of variables in Lua: -global variables, local variables, and table fields. - -<p>A single name can denote a global variable or a local variable -(or a formal parameter of a function, -which is a particular form of local variable): -<pre> - var ::= Name -</pre> -Variables are assumed to be global unless explicitly declared local -(see <a href="#localvar">2.4.7</a>). -Local variables are <em>lexically scoped</em>: -Local variables can be freely accessed by functions -defined inside their scope (see <a href="#visibility">2.6</a>). - -<p>Before the first assignment to a variable, its value is <B>nil</B>. - -<p>Square brackets are used to index a table: -<pre> - var ::= prefixexp `<b>[</b>´ exp `<b>]</b>´ -</pre> -The first expression (<em>prefixexp</em>)should result in a table value; -the second expression (<em>exp</em>) -identifies a specific entry inside that table. -The expression denoting the table to be indexed has a restricted syntax; -see <a href="#expressions">2.5</a> for details. - -<p>The syntax <code>var.NAME</code> is just syntactic sugar for -<code>var["NAME"]</code>: -<pre> - var ::= prefixexp `<b>.</b>´ Name -</pre> - -<p>The meaning of accesses to global variables -and table fields can be changed via metatables. -An access to an indexed variable <code>t[i]</code> is equivalent to -a call <code>gettable_event(t,i)</code>. -(See <a href="#metatable">2.8</a> for a complete description of the -<code>gettable_event</code> function. -This function is not defined or callable in Lua. -We use it here only for explanatory purposes.) - -<p>All global variables live as fields in ordinary Lua tables, -called <em>environment tables</em> or simply <em>environments</em>. -Functions written in C and exported to Lua (<em>C functions</em>) -all share a common <em>global environment</em>. -Each function written in Lua (a <em>Lua function</em>) -has its own reference to an environment, -so that all global variables in that function -will refer to that environment table. -When a function is created, -it inherits the environment from the function that created it. -To change or get the environment table of a Lua function, -you call <code>setfenv</code> or <code>getfenv</code> (see <a href="#setfenv">5.1</a>). - -<p>An access to a global variable <code>x</code> -is equivalent to <code>_env.x</code>, -which in turn is equivalent to -<PRE> - gettable_event(_env, "x") -</PRE> -where <code>_env</code> is the environment of the running function. -(The <code>_env</code> variable is not defined in Lua. -We use it here only for explanatory purposes.) - -<p><a name="stats"><a name="2.4"><h2>2.4 - Statements</h2></a></a> - -<p>Lua supports an almost conventional set of statements, -similar to those in Pascal or C. -This set includes -assignment, control structures, procedure calls, -table constructors, and variable declarations. - -<p><a name="chunks"><a name="2.4.1"><h3>2.4.1 - Chunks</h3></a></a> - -<p>The unit of execution of Lua is called a <em>chunk</em>. -A chunk is simply a sequence of statements, -which are executed sequentially. -Each statement can be optionally followed by a semicolon: -<pre> - chunk ::= {stat [`<b>;</b>´]} -</pre> - -<p>Lua handles a chunk as the body of an anonymous function (see <a href="#func-def">2.5.8</a>). -As such, chunks can define local variables and return values. - -<p>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 opcodes for -a virtual machine, -and then the compiled code is executed -by an interpreter for the virtual machine. - -<p>Chunks may also be pre-compiled into binary form; -see program <code>luac</code> for details. -Programs in source and compiled forms are interchangeable; -Lua automatically detects the file type and acts accordingly. - - -<p><a name="2.4.2"><h3>2.4.2 - Blocks</h3></a> -A block is a list of statements; -syntactically, a block is equal to a chunk: -<pre> - block ::= chunk -</pre> - -<p>A block may be explicitly delimited to produce a single statement: -<pre> - stat ::= <b>do</b> block <b>end</b> -</pre> -Explicit blocks are useful -to control the scope of variable declarations. -Explicit blocks are also sometimes used to -add a <b>return</b> or <b>break</b> statement in the middle -of another block (see <a href="#control">2.4.4</a>). - - -<p><a name="assignment"><a name="2.4.3"><h3>2.4.3 - Assignment</h3></a></a> - -<p>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: -<pre> - stat ::= varlist1 `<b>=</b>´ explist1 - varlist1 ::= var {`<b>,</b>´ var} - explist1 ::= exp {`<b>,</b>´ exp} -</pre> -Expressions are discussed in <a href="#expressions">2.5</a>. - -<p>Before the assignment, -the list of values is <em>adjusted</em> 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 <B>nil</B>'s as needed. -If the list of expressions ends with a function call, -then all values returned by that function call enter in the list of values, -before the adjustment -(except when the call is enclosed in parentheses; see <a href="#expressions">2.5</a>). - -<p>The assignment statement first evaluates all its expressions -and only then are the assignments performed. -Thus the code -<PRE> - i = 3 - i, a[i] = i+1, 20 -</PRE> -sets <code>a[3]</code> to 20, without affecting <code>a[4]</code> -because the <code>i</code> in <code>a[i]</code> is evaluated (to 3) -before it is assigned 4. -Similarly, the line -<PRE> - x, y = y, x -</PRE> -exchanges the values of <code>x</code> and <code>y</code>. - -<p>The meaning of assignments to global variables -and table fields can be changed via metatables. -An assignment to an indexed variable <code>t[i] = val</code> is equivalent to -<code>settable_event(t,i,val)</code>. -(See <a href="#metatable">2.8</a> for a complete description of the -<code>settable_event</code> function. -This function is not defined or callable in Lua. -We use it here only for explanatory purposes.) - -<p>An assignment to a global variable <code>x = val</code> -is equivalent to the assignment -<code>_env.x = val</code>, -which in turn is equivalent to -<PRE> - settable_event(_env, "x", val) -</PRE> -where <code>_env</code> is the environment of the running function. -(The <code>_env</code> variable is not defined in Lua. -We use it here only for explanatory purposes.) - -<p><a name="control"><a name="2.4.4"><h3>2.4.4 - Control Structures</h3></a></a> -The control structures -<b>if</b>, <b>while</b>, and <b>repeat</b> have the usual meaning and -familiar syntax: - - - -<pre> - stat ::= <b>while</b> exp <b>do</b> block <b>end</b> - stat ::= <b>repeat</b> block <b>until</b> exp - stat ::= <b>if</b> exp <b>then</b> block {<b>elseif</b> exp <b>then</b> block} [<b>else</b> block] <b>end</b> -</pre> -Lua also has a <b>for</b> statement, in two flavors (see <a href="#for">2.4.5</a>). - -<p>The condition expression <em>exp</em> of a -control structure may return any value. -Both <B>false</B> and <B>nil</B> are considered false. -All values different from <B>nil</B> and <B>false</B> are considered true -(in particular, the number 0 and the empty string are also true). - -<p>The <b>return</b> statement is used to return values -from a function or from a chunk. - -Functions and chunks may return more than one value, -so the syntax for the <b>return</b> statement is -<pre> - stat ::= <b>return</b> [explist1] -</pre> - -<p>The <b>break</b> statement can be used to terminate the execution of a -<b>while</b>, <b>repeat</b>, or <b>for</b> loop, -skipping to the next statement after the loop: - -<pre> - stat ::= <b>break</b> -</pre> -A <b>break</b> ends the innermost enclosing loop. - -<p>For syntactic reasons, <b>return</b> and <b>break</b> -statements can only be written as the <em>last</em> statement of a block. -If it is really necessary to <b>return</b> or <b>break</b> in the -middle of a block, -then an explicit inner block can be used, -as in the idioms -`<code>do return end</code>´ and -`<code>do break end</code>´, -because now <b>return</b> and <b>break</b> are the last statements in -their (inner) blocks. -In practice, -those idioms are only used during debugging. - -<p><a name="for"><a name="2.4.5"><h3>2.4.5 - For Statement</h3></a></a> - -<p>The <b>for</b> statement has two forms: -one numeric and one generic. - - -<p>The numeric <b>for</b> loop repeats a block of code while a -control variable runs through an arithmetic progression. -It has the following syntax: -<pre> - stat ::= <b>for</b> Name `<b>=</b>´ exp `<b>,</b>´ exp [`<b>,</b>´ exp] <b>do</b> block <b>end</b> -</pre> -The <em>block</em> is repeated for <em>name</em> starting at the value of -the first <em>exp</em>, until it passes the second <em>exp</em> by steps of the -third <em>exp</em>. -More precisely, a <b>for</b> statement like -<PRE> - for var = e1, e2, e3 do block end -</PRE> -is equivalent to the code: -<PRE> - 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 -</PRE> -Note the following: -<ul> -<li> All three control expressions are evaluated only once, -before the loop starts. -They must all result in numbers. -<li> <code>_limit</code> and <code>_step</code> are invisible variables. -The names are here for explanatory purposes only. -<li> The behavior is <em>undefined</em> if you assign to <code>var</code> inside -the block. -<li> If the third expression (the step) is absent, then a step of 1 is used. -<li> You can use <b>break</b> to exit a <b>for</b> loop. -<li> The loop variable <code>var</code> is local to the statement; -you cannot use its value after the <b>for</b> ends or is broken. -If you need the value of the loop variable <code>var</code>, -then assign it to another variable before breaking or exiting the loop. -</ul> - -<p>The generic <b>for</b> statement works over functions, -called <em>iterators</em>. -For each iteration, it calls its iterator function to produce a new value, -stopping when the new value is <B>nil</B>. -The generic <b>for</b> loop has the following syntax: -<pre> - stat ::= <b>for</b> Name {`<b>,</b>´ Name} <b>in</b> explist1 <b>do</b> block <b>end</b> -</pre> -A <b>for</b> statement like -<PRE> - for var_1, ..., var_n in explist do block end -</PRE> -is equivalent to the code: -<PRE> - do - local _f, _s, var_1 = explist - local var_2, ... , var_n - while true do - var_1, ..., var_n = _f(_s, var_1) - if var_1 == nil then break end - block - end - end -</PRE> -Note the following: -<ul> -<li> <code>explist</code> is evaluated only once. -Its results are an <em>iterator</em> function, -a <em>state</em>, and an initial value for the first <em>iterator variable</em>. -<li> <code>_f</code> and <code>_s</code> are invisible variables. -The names are here for explanatory purposes only. -<li> The behavior is <em>undefined</em> if you assign to -<code>var_1</code> inside the block. -<li> You can use <b>break</b> to exit a <b>for</b> loop. -<li> The loop variables <code>var_i</code> are local to the statement; -you cannot use their values after the <b>for</b> ends. -If you need these values, -then assign them to other variables before breaking or exiting the loop. -</ul> - -<p><a name="funcstat"><a name="2.4.6"><h3>2.4.6 - Function Calls as Statements</h3></a></a> -To allow possible side-effects, -function calls can be executed as statements: -<pre> - stat ::= functioncall -</pre> -In this case, all returned values are thrown away. -Function calls are explained in <a href="#functioncall">2.5.7</a>. - -<p><a name="localvar"><a name="2.4.7"><h3>2.4.7 - Local Declarations</h3></a></a> -Local variables may be declared anywhere inside a block. -The declaration may include an initial assignment: -<pre> - stat ::= <b>local</b> namelist [`<b>=</b>´ explist1] - namelist ::= Name {`<b>,</b>´ Name} -</pre> -If present, an initial assignment has the same semantics -of a multiple assignment (see <a href="#assignment">2.4.3</a>). -Otherwise, all variables are initialized with <B>nil</B>. - -<p>A chunk is also a block (see <a href="#chunks">2.4.1</a>), -so local variables can be declared in a chunk outside any explicit block. -Such local variables die when the chunk ends. - -<p>The visibility rules for local variables are explained in <a href="#visibility">2.6</a>. - -<p><a name="expressions"><a name="2.5"><h2>2.5 - Expressions</h2></a></a> - -<p> -The basic expressions in Lua are the following: -<pre> - exp ::= prefixexp - exp ::= <b>nil</b> | <b>false</b> | <b>true</b> - exp ::= Number - exp ::= Literal - exp ::= function - exp ::= tableconstructor - prefixexp ::= var | functioncall | `<b>(</b>´ exp `<b>)</b>´ -</pre> - -<p>Numbers and literal strings are explained in <a href="#lexical">2.1</a>; -variables are explained in <a href="#variables">2.3</a>; -function definitions are explained in <a href="#func-def">2.5.8</a>; -function calls are explained in <a href="#functioncall">2.5.7</a>; -table constructors are explained in <a href="#tableconstructor">2.5.6</a>. - - -<p>An expression enclosed in parentheses always results in only one value. -Thus, -<code>(f(x,y,z))</code> is always a single value, -even if <code>f</code> returns several values. -(The value of <code>(f(x,y,z))</code> is the first value returned by <code>f</code> -or <B>nil</B> if <code>f</code> does not return any values.) - -<p>Expressions can also be built with arithmetic operators, relational operators, -and logical operators, all of which are explained below. - -<p><a name="2.5.1"><h3>2.5.1 - Arithmetic Operators</h3></a> -Lua supports the usual arithmetic operators: -the binary <code>+</code> (addition), -<code>-</code> (subtraction), <code>*</code> (multiplication), -<code>/</code> (division), and <code>^</code> (exponentiation); -and unary <code>-</code> (negation). -If the operands are numbers, or strings that can be converted to -numbers (see <a href="#coercion">2.2.1</a>), -then all operations except exponentiation have the usual meaning. -Exponentiation calls a global function <code>__pow</code>; -otherwise, an appropriate metamethod is called (see <a href="#metatable">2.8</a>). -The standard mathematical library defines function <code>__pow</code>, -giving the expected meaning to exponentiation -(see <a href="#mathlib">5.5</a>). - -<p><a name="rel-ops"><a name="2.5.2"><h3>2.5.2 - Relational Operators</h3></a></a> -The relational operators in Lua are -<PRE> - == ~= < > <= >= -</PRE> -These operators always result in <B>false</B> or <B>true</B>. - -<p>Equality (<code>==</code>) first compares the type of its operands. -If the types are different, then the result is <B>false</B>. -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 <em>reference</em>: -Two objects are considered equal only if they are the <em>same</em> object. -Every time you create a new object (a table, userdata, or function), -this new object is different from any previously existing object. - -<p>You can change the way that Lua compares tables and userdata -using the "eq" metamethod (see <a href="#metatable">2.8</a>). - -<p>The conversion rules of <a href="#coercion">2.2.1</a> -<em>do not</em> apply to equality comparisons. -Thus, <code>"0"==0</code> evaluates to <B>false</B>, -and <code>t[0]</code> and <code>t["0"]</code> denote different -entries in a table. - - -<p>The operator <code>~=</code> is exactly the negation of equality (<code>==</code>). - -<p>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 <a href="#metatable">2.8</a>). - -<p><a name="2.5.3"><h3>2.5.3 - Logical Operators</h3></a> -The logical operators in Lua are - -<PRE> - and or not -</PRE> -Like the control structures (see <a href="#control">2.4.4</a>), -all logical operators consider both <B>false</B> and <B>nil</B> as false -and anything else as true. - - -<p>The operator <b>not</b> always return <B>false</B> or <B>true</B>. - -<p>The conjunction operator <b>and</b> returns its first argument -if this value is <B>false</B> or <B>nil</B>; -otherwise, <b>and</b> returns its second argument. -The disjunction operator <b>or</b> returns its first argument -if this value is different from <B>nil</B> and <B>false</B>; -otherwise, <b>or</b> returns its second argument. -Both <b>and</b> and <b>or</b> use short-cut evaluation, -that is, -the second operand is evaluated only if necessary. -For example, -<PRE> - 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 -</PRE> - -<p><a name="concat"><a name="2.5.4"><h3>2.5.4 - Concatenation</h3></a></a> -The string concatenation operator in Lua is -denoted by two dots (`<code>..</code>´). -If both operands are strings or numbers, then they are converted to -strings according to the rules mentioned in <a href="#coercion">2.2.1</a>. -Otherwise, the "concat" metamethod is called (see <a href="#metatable">2.8</a>). - -<p><a name="2.5.5"><h3>2.5.5 - Precedence</h3></a> -Operator precedence in Lua follows the table below, -from lower to higher priority: -<PRE> - or - and - < > <= >= ~= == - .. - + - - * / - not - (unary) - ^ -</PRE> -You can use parentheses to change the precedences in an expression. -The concatenation (`<code>..</code>´) and exponentiation (`<code>^</code>´) -operators are right associative. -All other binary operators are left associative. - -<p><a name="tableconstructor"><a name="2.5.6"><h3>2.5.6 - Table Constructors</h3></a></a> -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 -<pre> - tableconstructor ::= `<b>{</b>´ [fieldlist] `<b>}</b>´ - fieldlist ::= field {fieldsep field} [fieldsep] - field ::= `<b>[</b>´ exp `<b>]</b>´ `<b>=</b>´ exp | Name `<b>=</b>´ exp | exp - fieldsep ::= `<b>,</b>´ | `<b>;</b>´ -</pre> - -<p>Each field of the form <code>[exp1] = exp2</code> adds to the new table an entry -with key <code>exp1</code> and value <code>exp2</code>. -A field of the form <code>name = exp</code> is equivalent to -<code>["name"] = exp</code>. -Finally, fields of the form <code>exp</code> are equivalent to -<code>[i] = exp</code>, where <code>i</code> are consecutive numerical integers, -starting with 1. -Fields in the other formats do not affect this counting. -For example, -<PRE> - a = {[f(1)] = g; "x", "y"; x = 1, f(x), [30] = 23; 45} -</PRE> -is equivalent to -<PRE> - do - local temp = {} - temp[f(1)] = g - temp[1] = "x" -- 1st exp - temp[2] = "y" -- 2nd exp - temp.x = 1 -- temp["x"] = 1 - temp[3] = f(x) -- 3rd exp - temp[30] = 23 - temp[4] = 45 -- 4th exp - a = temp - end -</PRE> - -<p>If the last field in the list has the form <code>exp</code> -and the expression is a function call, -then all values returned by the call enter the list consecutively -(see <a href="#functioncall">2.5.7</a>). -To avoid this, -enclose the function call in parentheses (see <a href="#expressions">2.5</a>). - -<p>The field list may have an optional trailing separator, -as a convenience for machine-generated code. - -<p><a name="functioncall"><a name="2.5.7"><h3>2.5.7 - Function Calls</h3></a></a> -A function call in Lua has the following syntax: -<pre> - functioncall ::= prefixexp args -</pre> -In a function call, -first <em>prefixexp</em> and <em>args</em> are evaluated. -If the value of <em>prefixexp</em> has type <em>function</em>, -then that function is called -with the given arguments. -Otherwise, its "call" metamethod is called, -having as first parameter the value of <em>prefixexp</em>, -followed by the original call arguments -(see <a href="#metatable">2.8</a>). - -<p>The form -<pre> - functioncall ::= prefixexp `<b>:</b>´ Name args -</pre> -can be used to call "methods". -A call <code>v:name(...)</code> -is syntactic sugar for <code>v.name(v,...)</code>, -except that <code>v</code> is evaluated only once. - -<p>Arguments have the following syntax: -<pre> - args ::= `<b>(</b>´ [explist1] `<b>)</b>´ - args ::= tableconstructor - args ::= Literal -</pre> -All argument expressions are evaluated before the call. -A call of the form <code>f{...}</code> is syntactic sugar for -<code>f({...})</code>, that is, -the argument list is a single new table. -A call of the form <code>f'...'</code> -(or <code>f"..."</code> or <code>f[[...]]</code>) is syntactic sugar for -<code>f('...')</code>, that is, -the argument list is a single literal string. - -<p>Because a function can return any number of results -(see <a href="#control">2.4.4</a>), -the number of results must be adjusted before they are used. -If the function is called as a statement (see <a href="#funcstat">2.4.6</a>), -then its return list is adjusted to zero elements, -thus discarding all returned values. -If the function is called inside another expression -or in the middle of a list of expressions, -then its return list is adjusted to one element, -thus discarding all returned values except the first one. -If the function is called as the last element of a list of expressions, -then no adjustment is made -(unless the call is enclosed in parentheses). - -<p>Here are some examples: -<PRE> - f() -- adjusted to 0 results - g(f(), x) -- f() is adjusted to 1 result - g(x, f()) -- g gets x plus all values returned by f() - a,b,c = f(), x -- f() is adjusted to 1 result (and c gets nil) - 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 values returned by f() - return x,y,f() -- returns x, y, and all values returned by f() - {f()} -- creates a list with all values returned by f() - {f(), nil} -- f() is adjusted to 1 result -</PRE> - -<p>If you enclose a function call in parentheses, -then it is adjusted to return exactly one value: -<PRE> - return x,y,(f()) -- returns x, y, and the first value from f() - {(f())} -- creates a table with exactly one element -</PRE> - -<p>As an exception to the free-format syntax of Lua, -you cannot put a line break before the `<code>(</code>´ in a function call. -That restriction avoids some ambiguities in the language. -If you write -<PRE> - a = f - (g).x(a) -</PRE> -Lua would read that as <code>a = f(g).x(a)</code>. -So, if you want two statements, you must add a semi-colon between them. -If you actually want to call <code>f</code>, -you must remove the line break before <code>(g)</code>. - -<p>A call of the form <code>return</code> <em>functioncall</em> is called -a <em>tail call</em>. -Lua implements <em>proper tail calls</em> -(or <em>proper tail recursion</em>): -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 <b>return</b> has one single function call as argument; -this syntax makes the calling function returns exactly -the returns of the called function. -So, all the following examples are not tails calls: -<PRE> - 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 -</PRE> - -<p><a name="func-def"><a name="2.5.8"><h3>2.5.8 - Function Definitions</h3></a></a> - -<p>The syntax for function definition is -<pre> - function ::= <b>function</b> funcbody - funcbody ::= `<b>(</b>´ [parlist1] `<b>)</b>´ block <b>end</b> -</pre> - -<p>The following syntactic sugar simplifies function definitions: -<pre> - stat ::= <b>function</b> funcname funcbody - stat ::= <b>local</b> <b>function</b> Name funcbody - funcname ::= Name {`<b>.</b>´ Name} [`<b>:</b>´ Name] -</pre> -The statement -<PRE> - function f () ... end -</PRE> -translates to -<PRE> - f = function () ... end -</PRE> -The statement -<PRE> - function t.a.b.c.f () ... end -</PRE> -translates to -<PRE> - t.a.b.c.f = function () ... end -</PRE> -The statement -<PRE> - local function f () ... end -</PRE> -translates to -<PRE> - local f; f = function () ... end -</PRE> - -<p>A function definition is an executable expression, -whose value has type <em>function</em>. -When Lua pre-compiles a chunk, -all its function bodies are pre-compiled too. -Then, whenever Lua executes the function definition, -the function is <em>instantiated</em> (or <em>closed</em>). -This function instance (or <em>closure</em>) -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. - -<p>Parameters act as local variables that are -initialized with the argument values: -<pre> - parlist1 ::= namelist [`<b>,</b>´ `<b>...</b>´] - parlist1 ::= `<b>...</b>´ -</pre> -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 <em>vararg function</em>, -which is -indicated by three dots (`<code>...</code>´) at the end of its parameter list. -A vararg function does not adjust its argument list; -instead, it collects all extra arguments into an implicit parameter, -called <code>arg</code>. -The value of <a name="vararg"><code>arg</code></a> is a table, -with a field <code>n</code> that holds the number of extra arguments -and with the extra arguments at positions 1, 2, ..., <code>n</code>. - -<p>As an example, consider the following definitions: -<PRE> - function f(a, b) end - function g(a, b, ...) end - function r() return 1,2,3 end -</PRE> -Then, we have the following mapping from arguments to parameters: -<PRE> - 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, arg={n=0} - g(3, 4) a=3, b=4, arg={n=0} - g(3, 4, 5, 8) a=3, b=4, arg={5, 8; n=2} - g(5, r()) a=5, b=1, arg={2, 3; n=2} -</PRE> - -<p>Results are returned using the <b>return</b> statement (see <a href="#control">2.4.4</a>). -If control reaches the end of a function -without encountering a <b>return</b> statement, -then the function returns with no results. - -<p>The <em>colon</em> syntax -is used for defining <em>methods</em>, -that is, functions that have an implicit extra parameter <code>self</code>. -Thus, the statement -<PRE> - function t.a.b.c:f (...) ... end -</PRE> -is syntactic sugar for -<PRE> - t.a.b.c.f = function (self, ...) ... end -</PRE> - -<p><a name="visibility"><a name="2.6"><h2>2.6 - Visibility Rules</h2></a></a> - - -<p>Lua is a lexically scoped language. -The scope of variables begins at the first statement <em>after</em> -their declaration and lasts until the end of the innermost block that -includes the declaration. -For instance: -<PRE> - 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) -</PRE> -Notice that, in a declaration like <code>local x = x</code>, -the new <code>x</code> being declared is not in scope yet, -and so the second <code>x</code> refers to the outside variable. - -<p>Because of the lexical scoping rules, -local variables can be freely accessed by functions -defined inside their scope. -For instance: -<PRE> - local counter = 0 - function inc (x) - counter = counter + x - return counter - end -</PRE> -A local variable used by an inner function is called -an <em>upvalue</em>, or <em>external local variable</em>, -inside the inner function. - -<p>Notice that each execution of a <b>local</b> statement -defines new local variables. -Consider the following example: -<PRE> - a = {} - local x = 20 - for i=1,10 do - local y = 0 - a[i] = function () y=y+1; return x+y end - end -</PRE> -The loop creates ten closures -(that is, ten instances of the anonymous function). -Each of these closures uses a different <code>y</code> variable, -while all of them share the same <code>x</code>. - -<p><a name="error"><a name="2.7"><h2>2.7 - Error Handling</h2></a></a> - -<p>Because Lua is an extension language, -all Lua actions start from C code in the host program -calling a function from the Lua library (see <a href="#lua_pcall">3.15</a>). -Whenever an error occurs during Lua compilation or execution, -control returns to C, -which can take appropriate measures -(such as print an error message). - -<p>Lua code can explicitly generate an error by calling the -<code>error</code> function (see <a href="#pdf-error">5.1</a>). -If you need to catch errors in Lua, -you can use the <code>pcall</code> function (see <a href="#pdf-pcall">5.1</a>). - -<p><a name="metatable"><a name="2.8"><h2>2.8 - Metatables</h2></a></a> - -<p>Every table and userdata object in Lua may have a <em>metatable</em>. -This <em>metatable</em> 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 an object is the operand of an addition, -Lua checks for a function in the field <code>"__add"</code> in its metatable. -If it finds one, -Lua calls that function to perform the addition. - -<p>We call the keys in a metatable <em>events</em> -and the values <em>metamethods</em>. -In the previous example, the event is <code>"add"</code> -and the metamethod is the function that performs the addition. - -<p>You can query and change the metatable of an object -through the <code>set/getmetatable</code> -functions (see <a href="#pdf-getmetatable">5.1</a>). - -<p>A metatable may control how an object behaves in arithmetic operations, -order comparisons, concatenation, 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 <em>event</em>. -When Lua performs one of those operations over a table or a userdata, -it checks whether that object has a metatable with the corresponding event. -If so, the value associated with that key (the <em>metamethod</em>) -controls how Lua will perform the operation. - -<p>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 <code>"__add"</code>. -The semantics of these operations is better explained by a Lua function -describing how the interpreter executes that operation. - -<p>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 -(<code>rawget</code>, <code>tonumber</code>, etc.) -are described in <a href="#predefined">5.1</a>. -In particular, to retrieve the metamethod of a given object, -we use the expression -<PRE> - metatable(obj)[event] -</PRE> -This should be read as -<PRE> - rawget(metatable(obj) or {}, event) -</PRE> -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 <B>nil</B>). - -<p><ul> - -<p><li><b>"add":</b> -the <code>+</code> operation. - -<p>The function <code>getbinhandler</code> 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. -<PRE> - function getbinhandler (op1, op2, event) - return metatable(op1)[event] or metatable(op2)[event] - end -</PRE> -Using that function, -the behavior of the <code>op1 + op2</code> is -<PRE> - 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 -</PRE> - -<p><li><b>"sub":</b> -the <code>-</code> operation. -Behavior similar to the "add" operation. - -<p><li><b>"mul":</b> -the <code>*</code> operation. -Behavior similar to the "add" operation. - -<p><li><b>"div":</b> -the <code>/</code> operation. -Behavior similar to the "add" operation. - -<p><li><b>"pow":</b> -the <code>^</code> (exponentiation) operation. -<PRE> - function pow_event (op1, op2) - local o1, o2 = tonumber(op1), tonumber(op2) - if o1 and o2 then -- both operands are numeric? - return __pow(o1, o2) -- call global `__pow' - else -- at least one of the operands is not numeric - local h = getbinhandler(op1, op2, "__pow") - if h then - -- call the handler with both operands - return h(op1, op2) - else -- no handler available: default behavior - error("...") - end - end - end -</PRE> - -<p><li><b>"unm":</b> -the unary <code>-</code> operation. -<PRE> - 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 and nil - return h(op, nil) - else -- no handler available: default behavior - error("...") - end - end - end -</PRE> - -<p><li><b>"concat":</b> -the <code>..</code> (concatenation) operation. -<PRE> - 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 -</PRE> - -<p><li><b>"eq":</b> -the <code>==</code> operation. -The function <code>getcomphandler</code> 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. -<PRE> - 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 -</PRE> -The "eq" event is defined as follows: -<PRE> - 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 -</PRE> -<code>a ~= b</code> is equivalent to <code>not (a == b)</code>. - -<p><li><b>"lt":</b> -the <code><</code> operation. -<PRE> - 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 -</PRE> -<code>a > b</code> is equivalent to <code>b < a</code>. - -<p><li><b>"le":</b> -the <code><=</code> operation. -<PRE> - 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 -</PRE> -<code>a >= b</code> is equivalent to <code>b <= a</code>. -Note that, in the absence of a "le" metamethod, -Lua tries the "lt", assuming that <code>a <= b</code> is -equivalent to <code>not (b < a)</code>. - -<p><li><b>"index":</b> -The indexing access <code>table[key]</code>. -<PRE> - 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 -</PRE> - -<p><li><b>"newindex":</b> -The indexing assignment <code>table[key] = value</code>. -<PRE> - 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 -</PRE> - -<p><li><b>"call":</b> -called when Lua calls a value. -<PRE> - function function_event (func, ...) - if type(func) == "function" then - return func(unpack(arg)) -- primitive call - else - local h = metatable(func).__call - if h then - return h(func, unpack(arg)) - else - error("...") - end - end - end -</PRE> - -<p></ul> - -<p><a name="GC"><a name="2.9"><h2>2.9 - Garbage Collection</h2></a></a> - -<p>Lua does automatic memory management. -That means that -you do not have to worry about allocating memory for new objects -and freeing it when the objects are no longer needed. -Lua manages memory automatically by running -a <em>garbage collector</em> from time to time -to collect all <em>dead objects</em> -(that is, those objects that are no longer accessible from Lua). -All objects in Lua are subject to automatic management: -tables, userdata, functions, threads, and strings. - -<p>Lua uses two numbers to control its garbage-collection cycles. -One number counts how many bytes of dynamic memory Lua is using; -the other is a threshold. -When the number of bytes crosses the threshold, -Lua runs the garbage collector, -which reclaims the memory of all dead objects. -The byte counter is adjusted, -and then the threshold is reset to twice the new value of the byte counter. - -<p>Through the C API, you can query those numbers -and change the threshold (see <a href="#GC-API">3.7</a>). -Setting the threshold to zero actually forces an immediate -garbage-collection cycle, -while setting it to a huge number effectively stops the garbage collector. -Using Lua code you have a more limited control over garbage-collection cycles, -through the <code>gcinfo</code> and <code>collectgarbage</code> functions -(see <a href="#predefined">5.1</a>). - -<p><a name="2.9.1"><h3>2.9.1 - Garbage-Collection Metamethods</h3></a> - -<p>Using the C API, -you can set garbage-collector metamethods for userdata (see <a href="#metatable">2.8</a>). -These metamethods are also called <em>finalizers</em>. -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). - -<p>Free userdata with a field <code>__gc</code> 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: -<PRE> - function gc_event (udata) - local h = metatable(udata).__gc - if h then - h(udata) - end - end -</PRE> - -<p>At the end of each garbage-collection cycle, -the finalizers for userdata are called in <em>reverse</em> -order of their creation, -among those collected in that cycle. -That is, the first finalizer to be called is the one associated -with the userdata created last in the program. - -<p><a name="weak-table"><a name="2.9.2"><h3>2.9.2 - Weak Tables</h3></a></a> - -<p>A <em>weak table</em> is a table whose elements are -<em>weak references</em>. -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 that object. - -<p>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 -<code>__mode</code> field of its metatable. -If the <code>__mode</code> field is a string containing the character `<code>k</code>´, -the keys in the table are weak. -If <code>__mode</code> contains `<code>v</code>´, -the values in the table are weak. - -<p>After you use a table as a metatable, -you should not change the value of its field <code>__mode</code>. -Otherwise, the weak behavior of the tables controlled by this -metatable is undefined. - -<p><a name="coroutine"><a name="2.10"><h2>2.10 - Coroutines</h2></a></a> - -<p>Lua supports coroutines, -also called <em>semi-coroutines</em> -or <em>collaborative multithreading</em>. -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. - -<p>You create a coroutine with a call to <code>coroutine.create</code>. -Its sole argument is a function -that is the main function of the coroutine. -The <code>create</code> function only creates a new coroutine and -returns a handle to it (an object of type <em>thread</em>); -it does not start the coroutine execution. - -<p>When you first call <code>coroutine.resume</code>, -passing as its first argument the thread returned by <code>coroutine.create</code>, -the coroutine starts its execution, -at the first line of its main function. -Extra arguments passed to <code>coroutine.resume</code> are given as -parameters for the coroutine main function. -After the coroutine starts running, -it runs until it terminates or <em>yields</em>. - -<p>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, <code>coroutine.resume</code> returns <B>true</B>, -plus any values returned by the coroutine main function. -In case of errors, <code>coroutine.resume</code> returns <B>false</B> -plus an error message. - -<p>A coroutine yields by calling <code>coroutine.yield</code>. -When a coroutine yields, -the corresponding <code>coroutine.resume</code> 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, <code>coroutine.resume</code> also returns <B>true</B>, -plus any values passed to <code>coroutine.yield</code>. -The next time you resume the same coroutine, -it continues its execution from the point where it yielded, -with the call to <code>coroutine.yield</code> returning any extra -arguments passed to <code>coroutine.resume</code>. - -<p>The <code>coroutine.wrap</code> function creates a coroutine -like <code>coroutine.create</code>, -but instead of returning the coroutine itself, -it returns a function that, when called, resumes the coroutine. -Any arguments passed to that function -go as extra arguments to resume. -The function returns all the values returned by resume, -except the first one (the boolean error code). -Unlike <code>coroutine.resume</code>, -this function does not catch errors; -any error is propagated to the caller. - -<p>As an example, -consider the next code: -<PRE> -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) - -a, b = coroutine.resume(co, 1, 10) -print("main", a, b) -a, b, c = coroutine.resume(co, "r") -print("main", a, b, c) -a, b, c = coroutine.resume(co, "x", "y") -print("main", a, b, c) -a, b = coroutine.resume(co, "x", "y") -print("main", a, b) -</PRE> -When you run it, it produces the following output: -<PRE> -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 -</PRE> - -<p> -<a name="API"><a name="3"><h1>3 - The Application Program Interface</h1></a></a> - - -<p>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 <code>lua.h</code>. - -<p>Even when we use the term "function", -any facility in the API may be provided as a <em>macro</em> 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. - -<p><a name="mangstate"><a name="3.1"><h2>3.1 - States</h2></a></a> - -<p>The Lua library is fully reentrant: -it has no global variables. - -The whole state of the Lua interpreter -(global variables, stack, etc.) -is stored in a dynamically allocated structure of type <code>lua_State</code>. - -A pointer to this state must be passed as the first argument to -every function in the library, except to <code>lua_open</code>, -which creates a Lua state from scratch. - -<p>Before calling any API function, -you must create a state by calling <code>lua_open</code>: -<PRE> - lua_State *lua_open (void); -</PRE> - - -<p>To release a state created with <code>lua_open</code>, call <code>lua_close</code>: -<PRE> - void lua_close (lua_State *L); -</PRE> - -This function destroys all objects in the given Lua state -(calling the corresponding garbage-collection metamethods, if any) -and frees all dynamic memory used by that 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. - -<p><a name="3.2"><h2>3.2 - The Stack and Indices</h2></a> - -<p>Lua uses a <em>virtual stack</em> to pass values to and from C. -Each element in this stack represents a Lua value -(<B>nil</B>, number, string, etc.). - -<p>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. -That 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 <a href="#LuacallC">3.16</a>) -to be returned to the caller. - -<p>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 <em>index</em>: -A positive index represents an <em>absolute</em> stack position -(starting at 1); -a negative index represents an <em>offset</em> from the top of the stack. -More specifically, if the stack has <em>n</em> elements, -then index 1 represents the first element -(that is, the element that was pushed onto the stack first) -and -index <em>n</em> represents the last element; -index <em>-1</em> also represents the last element -(that is, the element at the top) -and index <em>-n</em> represents the first element. -We say that an index is <em>valid</em> -if it lies between 1 and the stack top -(that is, if <code>1 <= abs(index) <= top</code>). - - -<p>At any time, you can get the index of the top element by calling -<code>lua_gettop</code>: -<PRE> - int lua_gettop (lua_State *L); -</PRE> -Because indices start at 1, -the result of <code>lua_gettop</code> is equal to the number of elements in the stack -(and so 0 means an empty stack). - -<p>When you interact with Lua API, -<em>you are responsible for controlling stack overflow</em>. -The function -<PRE> - int lua_checkstack (lua_State *L, int extra); -</PRE> - -grows the stack size to <code>top + extra</code> elements; -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. - -<p>Whenever Lua calls C, -it ensures that at least <code>LUA_MINSTACK</code> stack positions are available. -<code>LUA_MINSTACK</code> is defined in <code>lua.h</code> as 20, -so that usually you do not have to worry about stack space -unless your code has loops pushing elements onto the stack. - -<p>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 <code>lua_checkstack</code>. -Such indices are called <em>acceptable indices</em>. -More formally, we define an <em>acceptable index</em> -as follows: -<PRE> - (index < 0 && abs(index) <= top) || (index > 0 && index <= stackspace) -</PRE> -Note that 0 is never an acceptable index. - -<p>Unless otherwise noted, -any function that accepts valid indices can also be called with -<em>pseudo-indices</em>, -which represent some Lua values that are accessible to the C code -but are not in the stack. -Pseudo-indices are used to access the global environment, -the registry, and the upvalues of a C function (see <a href="#c-closure">3.17</a>). - -<p><a name="3.3"><h2>3.3 - Stack Manipulation</h2></a> -The API offers the following functions for basic stack manipulation: -<PRE> - void lua_settop (lua_State *L, int index); - void lua_pushvalue (lua_State *L, int index); - void lua_remove (lua_State *L, int index); - void lua_insert (lua_State *L, int index); - void lua_replace (lua_State *L, int index); -</PRE> - - - -<p><code>lua_settop</code> accepts any acceptable index, -or 0, -and sets the stack top to that index. -If the new top is larger than the old one, -then the new elements are filled with <B>nil</B>. -If <code>index</code> is 0, then all stack elements are removed. -A useful macro defined in the <code>lua.h</code> is -<PRE> - #define lua_pop(L,n) lua_settop(L, -(n)-1) -</PRE> - -which pops <code>n</code> elements from the stack. - -<p><code>lua_pushvalue</code> pushes onto the stack a copy of the element -at the given index. -<code>lua_remove</code> removes the element at the given position, -shifting down the elements above that position to fill the gap. -<code>lua_insert</code> moves the top element into the given position, -shifting up the elements above that position to open space. -<code>lua_replace</code> moves the top element into the given position, -without shifting any element (therefore replacing the value at -the given position). -All these functions accept only valid indices. -(You cannot call <code>lua_remove</code> or <code>lua_insert</code> with -pseudo-indices, as they do not represent a stack position.) - -<p>As an example, if the stack starts as <code>10 20 30 40 50*</code> -(from bottom to top; the `<code>*</code>´ marks the top), -then -<PRE> - 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* -</PRE> - -<p><a name="3.4"><h2>3.4 - Querying the Stack</h2></a> - -<p>To check the type of a stack element, -the following functions are available: -<PRE> - int lua_type (lua_State *L, int index); - int lua_isnil (lua_State *L, int index); - int lua_isboolean (lua_State *L, int index); - int lua_isnumber (lua_State *L, int index); - int lua_isstring (lua_State *L, int index); - int lua_istable (lua_State *L, int index); - int lua_isfunction (lua_State *L, int index); - int lua_iscfunction (lua_State *L, int index); - int lua_isuserdata (lua_State *L, int index); - int lua_islightuserdata (lua_State *L, int index); -</PRE> - - - - - -These functions can be called with any acceptable index. - -<p><code>lua_type</code> returns the type of a value in the stack, -or <code>LUA_TNONE</code> for a non-valid index -(that is, if that stack position is "empty"). -The types returned by <code>lua_type</code> are coded by the following constants -defined in <code>lua.h</code>: -<code>LUA_TNIL</code>, -<code>LUA_TNUMBER</code>, -<code>LUA_TBOOLEAN</code>, -<code>LUA_TSTRING</code>, -<code>LUA_TTABLE</code>, -<code>LUA_TFUNCTION</code>, -<code>LUA_TUSERDATA</code>, -<code>LUA_TTHREAD</code>, -<code>LUA_TLIGHTUSERDATA</code>. -The following function translates these constants to strings: -<PRE> - const char *lua_typename (lua_State *L, int type); -</PRE> - - -<p>The <code>lua_is*</code> functions return 1 if the object is compatible -with the given type, and 0 otherwise. -<code>lua_isboolean</code> is an exception to this rule: -It succeeds only for boolean values -(otherwise it would be useless, -as any value has a boolean value). -They always return 0 for a non-valid index. -<code>lua_isnumber</code> accepts numbers and numerical strings; -<code>lua_isstring</code> accepts strings and numbers (see <a href="#coercion">2.2.1</a>); -<code>lua_isfunction</code> accepts both Lua functions and C functions; -and <code>lua_isuserdata</code> accepts both full and light userdata. -To distinguish between Lua functions and C functions, -you can use <code>lua_iscfunction</code>. -To distinguish between full and light userdata, -you can use <code>lua_islightuserdata</code>. -To distinguish between numbers and numerical strings, -you can use <code>lua_type</code>. - -<p>The API also contains functions to compare two values in the stack: -<PRE> - int lua_equal (lua_State *L, int index1, int index2); - int lua_rawequal (lua_State *L, int index1, int index2); - int lua_lessthan (lua_State *L, int index1, int index2); -</PRE> - -<code>lua_equal</code> and <code>lua_lessthan</code> -are equivalent to their counterparts in Lua (see <a href="#rel-ops">2.5.2</a>). -<code>lua_rawequal</code> compares the values for primitive equality, -without metamethods. -These functions return 0 (false) if any of the indices are non-valid. - -<p><a name="lua-to"><a name="3.5"><h2>3.5 - Getting Values from the Stack</h2></a></a> - -<p>To translate a value in the stack to a specific C type, -you can use the following conversion functions: -<PRE> - int lua_toboolean (lua_State *L, int index); - lua_Number lua_tonumber (lua_State *L, int index); - const char *lua_tostring (lua_State *L, int index); - size_t lua_strlen (lua_State *L, int index); - lua_CFunction lua_tocfunction (lua_State *L, int index); - void *lua_touserdata (lua_State *L, int index); - lua_State *lua_tothread (lua_State *L, int index); - void *lua_topointer (lua_State *L, int index); -</PRE> - - - -These functions can be called with any acceptable index. -When called with a non-valid index, -they act as if the given value had an incorrect type. - -<p><code>lua_toboolean</code> converts the Lua value at the given index -to a C "boolean" value (0 or 1). -Like all tests in Lua, <code>lua_toboolean</code> returns 1 for any Lua value -different from <B>false</B> and <B>nil</B>; -otherwise it returns 0. -It also returns 0 when called with a non-valid index. -(If you want to accept only real boolean values, -use <code>lua_isboolean</code> to test the type of the value.) - -<p><code>lua_tonumber</code> converts the Lua value at the given index -to a number (by default, <code>lua_Number</code> is <code>double</code>). - -The Lua value must be a number or a string convertible to number -(see <a href="#coercion">2.2.1</a>); otherwise, <code>lua_tonumber</code> returns 0. - -<p><code>lua_tostring</code> converts the Lua value at the given index to a string -(<code>const char*</code>). -The Lua value must be a string or a number; -otherwise, the function returns <code>NULL</code>. -If the value is a number, -then <code>lua_tostring</code> also -<em>changes the actual value in the stack to a string</em>. -(This change confuses <code>lua_next</code> -when <code>lua_tostring</code> is applied to keys.) -<code>lua_tostring</code> returns a fully aligned pointer -to a string inside the Lua state. -This string always has a zero (<code>'\0'</code>) -after its last character (as in C), -but may contain other zeros in its body. -If you do not know whether a string may contain zeros, -you can use <code>lua_strlen</code> to get its actual length. -Because Lua has garbage collection, -there is no guarantee that the pointer returned by <code>lua_tostring</code> -will be valid after the corresponding value is removed from the stack. -If you need the string after the current function returns, -then you should duplicate it or put it into the registry (see <a href="#registry">3.18</a>). - -<p><code>lua_tocfunction</code> converts a value in the stack to a C function. -This value must be a C function; -otherwise, <code>lua_tocfunction</code> returns <code>NULL</code>. -The type <code>lua_CFunction</code> is explained in <a href="#LuacallC">3.16</a>. - -<p><code>lua_tothread</code> converts a value in the stack to a Lua thread -(represented as <code>lua_State *</code>). -This value must be a thread; -otherwise, <code>lua_tothread</code> returns <code>NULL</code>. - -<p><code>lua_topointer</code> converts a value in the stack to a generic -C pointer (<code>void *</code>). -The value may be a userdata, a table, a thread, or a function; -otherwise, <code>lua_topointer</code> returns <code>NULL</code>. -Lua ensures that different objects of the -same type return different pointers. -There is no direct way to convert the pointer back to its original value. -Typically this function is used for debug information. - -<p><code>lua_touserdata</code> is explained in <a href="#userdata">3.8</a>. - -<p><a name="pushing"><a name="3.6"><h2>3.6 - Pushing Values onto the Stack</h2></a></a> - -<p>The API has the following functions to -push C values onto the stack: -<PRE> - void lua_pushboolean (lua_State *L, int b); - void lua_pushnumber (lua_State *L, lua_Number n); - void lua_pushlstring (lua_State *L, const char *s, size_t len); - void lua_pushstring (lua_State *L, const char *s); - void lua_pushnil (lua_State *L); - void lua_pushcfunction (lua_State *L, lua_CFunction f); - void lua_pushlightuserdata (lua_State *L, void *p); -</PRE> - -<p> - - -These functions receive a C value, -convert it to a corresponding Lua value, -and push the result onto the stack. -In particular, <code>lua_pushlstring</code> and <code>lua_pushstring</code> -make an internal copy of the given string. -<code>lua_pushstring</code> can only be used to push proper C strings -(that is, strings that end with a zero and do not contain embedded zeros); -otherwise, you should use the more general <code>lua_pushlstring</code>, -which accepts an explicit size. - -<p>You can also push "formatted" strings: -<PRE> - const char *lua_pushfstring (lua_State *L, const char *fmt, ...); - const char *lua_pushvfstring (lua_State *L, const char *fmt, va_list argp); -</PRE> - -These functions push onto the stack a formatted string -and return a pointer to that string. -They are similar to <code>sprintf</code> and <code>vsprintf</code>, -but with some important differences: -<ul> -<li> You do not have to allocate the space for the result: -The result is a Lua string and Lua takes care of memory allocation -(and deallocation, through garbage collection). -<li> The conversion specifiers are quite restricted. -There are no flags, widths, or precisions. -The conversion specifiers can be simply -`<code>%%</code>´ (inserts a `<code>%</code>´ in the string), -`<code>%s</code>´ (inserts a zero-terminated string, with no size restrictions), -`<code>%f</code>´ (inserts a <code>lua_Number</code>), -`<code>%d</code>´ (inserts an <code>int</code>), and -`<code>%c</code>´ (inserts an <code>int</code> as a character). -</ul> - -<p>The function -<PRE> - void lua_concat (lua_State *L, int n); -</PRE> - -concatenates the <code>n</code> values at the top of the stack, -pops them, and leaves the result at the top. -If <code>n</code> is 1, the result is that single string -(that is, the function does nothing); -if <code>n</code> is 0, the result is the empty string. -Concatenation is done following the usual semantics of Lua -(see <a href="#concat">2.5.4</a>). - -<p><a name="GC-API"><a name="3.7"><h2>3.7 - Controlling Garbage Collection</h2></a></a> - -<p>Lua uses two numbers to control its garbage collection: -the <em>count</em> and the <em>threshold</em> (see <a href="#GC">2.9</a>). -The first counts the amount of memory in use by Lua; -when the count reaches the threshold, -Lua runs its garbage collector. -After the collection, the count is updated -and the threshold is set to twice the count value. - -<p>You can access the current values of these two numbers through the -following functions: -<PRE> - int lua_getgccount (lua_State *L); - int lua_getgcthreshold (lua_State *L); -</PRE> - -Both return their respective values in Kbytes. -You can change the threshold value with -<PRE> - void lua_setgcthreshold (lua_State *L, int newthreshold); -</PRE> - -Again, the <code>newthreshold</code> value is given in Kbytes. -When you call this function, -Lua sets the new threshold and checks it against the byte counter. -If the new threshold is less than the byte counter, -then Lua immediately runs the garbage collector. -In particular -<code>lua_setgcthreshold(L,0)</code> forces a garbage collection. -After the collection, -a new threshold is set according to the previous rule. - -<p><a name="userdata"><a name="3.8"><h2>3.8 - Userdata</h2></a></a> - -<p>Userdata represents C values in Lua. -Lua supports two types of userdata: -<em>full userdata</em> and <em>light userdata</em>. - -<p>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). - -<p>A light userdata represents a pointer. -It is a value (like a number): -You do not create it, it has no metatables, -it is not collected (as it was never created). -A light userdata is equal to "any" -light userdata with the same C address. - -<p>In Lua code, there is no way to test whether a userdata is full or light; -both have type <code>userdata</code>. -In C code, <code>lua_type</code> returns <code>LUA_TUSERDATA</code> for full userdata, -and <code>LUA_TLIGHTUSERDATA</code> for light userdata. - -<p>You can create a new full userdata with the following function: -<PRE> - void *lua_newuserdata (lua_State *L, size_t size); -</PRE> - -This function allocates a new block of memory with the given size, -pushes on the stack a new userdata with the block address, -and returns this address. - -<p>To push a light userdata into the stack you use -<code>lua_pushlightuserdata</code> (see <a href="#pushing">3.6</a>). - -<p><code>lua_touserdata</code> (see <a href="#lua-to">3.5</a>) retrieves the value of a userdata. -When applied on a full userdata, it returns the address of its block; -when applied on a light userdata, it returns its pointer; -when applied on a non-userdata value, it returns <code>NULL</code>. - -<p>When Lua collects a full userdata, -it calls the userdata's <code>gc</code> metamethod, if any, -and then it frees the userdata's corresponding memory. - -<p><a name="3.9"><h2>3.9 - Metatables</h2></a> - -<p>The following functions allow you to manipulate the metatables -of an object: -<PRE> - int lua_getmetatable (lua_State *L, int index); - int lua_setmetatable (lua_State *L, int index); -</PRE> - -<code>lua_getmetatable</code> pushes on the stack the metatable of a given object. -If the index is not valid, -or if the object does not have a metatable, -<code>lua_getmetatable</code> returns 0 and pushes nothing on the stack. - -<p><code>lua_setmetatable</code> pops a table from the stack and -sets it as the new metatable for the given object. -<code>lua_setmetatable</code> returns 0 when it cannot -set the metatable of the given object -(that is, when the object is neither a userdata nor a table); -even then it pops the table from the stack. - -<p><a name="3.10"><h2>3.10 - Loading Lua Chunks</h2></a> - -<p>You can load a Lua chunk with <code>lua_load</code>: -<PRE> - typedef const char * (*lua_Chunkreader) - (lua_State *L, void *data, size_t *size); - - int lua_load (lua_State *L, lua_Chunkreader reader, void *data, - const char *chunkname); -</PRE> - -The return values of <code>lua_load</code> are: -<ul> -<li> 0 --- no errors; -<li> <code>LUA_ERRSYNTAX</code> --- -syntax error during pre-compilation. -<li> <code>LUA_ERRMEM</code> --- -memory allocation error. -</ul> -If there are no errors, -<code>lua_load</code> pushes the compiled chunk as a Lua -function on top of the stack. -Otherwise, it pushes an error message. - -<p><code>lua_load</code> automatically detects whether the chunk is text or binary, -and loads it accordingly (see program <code>luac</code>). - -<p><code>lua_load</code> uses a user-supplied <em>reader</em> function to read the chunk. -Everytime it needs another piece of the chunk, -<code>lua_load</code> calls the reader, -passing along its <code>data</code> parameter. -The reader must return a pointer to a block of memory -with a new piece of the chunk -and set <code>size</code> to the block size. -To signal the end of the chunk, the reader returns <code>NULL</code>. -The reader function may return pieces of any size greater than zero. - -<p>In the current implementation, -the reader function cannot call any Lua function; -to ensure that, it always receives <code>NULL</code> as the Lua state. - -<p>The <em>chunkname</em> is used for error messages -and debug information (see <a href="#debugI">4</a>). - -<p>See the auxiliary library (<code>lauxlib.c</code>) -for examples of how to use <code>lua_load</code> -and for some ready-to-use functions to load chunks -from files and strings. - -<p><a name="3.11"><h2>3.11 - Manipulating Tables</h2></a> - -<p>Tables are created by calling -the function -<PRE> - void lua_newtable (lua_State *L); -</PRE> - -This function creates a new, empty table and pushes it onto the stack. - -<p>To read a value from a table that resides somewhere in the stack, -call -<PRE> - void lua_gettable (lua_State *L, int index); -</PRE> - -where <code>index</code> points to the table. -<code>lua_gettable</code> pops a key from the stack -and returns (on the stack) the contents of the table at that key. -The table is left where it was in the stack. -As in Lua, this function may trigger a metamethod -for the "index" event (see <a href="#metatable">2.8</a>). -To get the real value of any table key, -without invoking any metamethod, -use the <em>raw</em> version: -<PRE> - void lua_rawget (lua_State *L, int index); -</PRE> - - -<p>To store a value into a table that resides somewhere in the stack, -you push the key and then the value onto the stack, -and call -<PRE> - void lua_settable (lua_State *L, int index); -</PRE> - -where <code>index</code> points to the table. -<code>lua_settable</code> pops from the stack both the key and the value. -The table is left where it was in the stack. -As in Lua, this operation may trigger a metamethod -for the "settable" or "newindex" events. -To set the real value of any table index, -without invoking any metamethod, -use the <em>raw</em> version: -<PRE> - void lua_rawset (lua_State *L, int index); -</PRE> - - -<p>You can traverse a table with the function -<PRE> - int lua_next (lua_State *L, int index); -</PRE> - -where <code>index</code> points to the table to be traversed. -The function pops a key from the stack, -and pushes a key-value pair from the table -(the "next" pair after the given key). -If there are no more elements, then <code>lua_next</code> returns 0 -(and pushes nothing). -Use a <B>nil</B> key to signal the start of a traversal. - -<p>A typical traversal looks like this: -<PRE> - /* table is in the stack at index `t' */ - lua_pushnil(L); /* first key */ - while (lua_next(L, t) != 0) { - /* `key' is 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))); - lua_pop(L, 1); /* removes `value'; keeps `key' for next iteration */ - } -</PRE> - -<p>While traversing a table, -do not call <code>lua_tostring</code> directly on a key, -unless you know that the key is actually a string. -Recall that <code>lua_tostring</code> <em>changes</em> the value at the given index; -this confuses the next call to <code>lua_next</code>. - -<p><a name="globals"><a name="3.12"><h2>3.12 - Manipulating Environments</h2></a></a> - -<p>All global variables are kept in ordinary Lua tables, -called environments. -The initial environment is called the global environment. -This table is always at pseudo-index <code>LUA_GLOBALSINDEX</code>. - -<p>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 -<PRE> - lua_pushstring(L, varname); - lua_gettable(L, LUA_GLOBALSINDEX); -</PRE> - -<p>You can change the global environment of a Lua thread using <code>lua_replace</code>. - -<p>The following functions get and set the environment of Lua functions: -<PRE> - void lua_getfenv (lua_State *L, int index); - int lua_setfenv (lua_State *L, int index); -</PRE> - -<code>lua_getfenv</code> pushes on the stack the environment table of -the function at index <code>index</code> in the stack. -If the function is a C function, -<code>lua_getfenv</code> pushes the global environment. -<code>lua_setfenv</code> pops a table from the stack and sets it as -the new environment for the function at index <code>index</code> in the stack. -If the object at the given index is not a Lua function, -<code>lua_setfenv</code> returns 0. - -<p><a name="3.13"><h2>3.13 - Using Tables as Arrays</h2></a> -The API has functions that help to use Lua tables as arrays, -that is, -tables indexed by numbers only: -<PRE> - void lua_rawgeti (lua_State *L, int index, int n); - void lua_rawseti (lua_State *L, int index, int n); -</PRE> - - - -<p><code>lua_rawgeti</code> pushes the value of the <em>n</em>-th element of the table -at stack position <code>index</code>. -<code>lua_rawseti</code> sets the value of the <em>n</em>-th element of the table -at stack position <code>index</code> to the value at the top of the stack, -removing this value from the stack. - -<p><a name="3.14"><h2>3.14 - Calling Functions</h2></a> - -<p>Functions defined in Lua -and C functions registered in Lua -can be called from the host program. -This is done using the following protocol: -First, the function to be called is pushed onto the stack; -then, the arguments to the function are pushed -in <em>direct order</em>, that is, the first argument is pushed first. -Finally, the function is called using -<PRE> - void lua_call (lua_State *L, int nargs, int nresults); -</PRE> - -<code>nargs</code> is the number of arguments that you pushed onto the stack. -All arguments and the function value are popped from the stack, -and the function results are pushed. -The number of results are adjusted to <code>nresults</code>, -unless <code>nresults</code> is <code>LUA_MULTRET</code>. -In that case, <em>all</em> 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. - -<p>The following example shows how the host program may do the -equivalent to this Lua code: -<PRE> - a = f("how", t.x, 14) -</PRE> -Here it is in C: -<PRE> - lua_pushstring(L, "t"); - lua_gettable(L, LUA_GLOBALSINDEX); /* global `t' (for later use) */ - lua_pushstring(L, "a"); /* var name */ - lua_pushstring(L, "f"); /* function name */ - lua_gettable(L, LUA_GLOBALSINDEX); /* function to be called */ - lua_pushstring(L, "how"); /* 1st argument */ - lua_pushstring(L, "x"); /* push the string "x" */ - lua_gettable(L, -5); /* push result of t.x (2nd arg) */ - lua_pushnumber(L, 14); /* 3rd argument */ - lua_call(L, 3, 1); /* call function with 3 arguments and 1 result */ - lua_settable(L, LUA_GLOBALSINDEX); /* set global variable `a' */ - lua_pop(L, 1); /* remove `t' from the stack */ -</PRE> -Note that the code above is "balanced": -at its end, the stack is back to its original configuration. -This is considered good programming practice. - -<p>(We did this example using only the raw functions provided by Lua's API, -to show all the details. -Usually programmers define and use several macros and auxiliary functions -that provide higher level access to Lua. -See the source code of the standard libraries for examples.) - -<p><a name="lua_pcall"><a name="3.15"><h2>3.15 - Protected Calls</h2></a></a> - -<p>When you call a function with <code>lua_call</code>, -any error inside the called function is propagated upwards -(with a <code>longjmp</code>). -If you need to handle errors, -then you should use <code>lua_pcall</code>: -<PRE> - int lua_pcall (lua_State *L, int nargs, int nresults, int errfunc); -</PRE> -Both <code>nargs</code> and <code>nresults</code> have the same meaning as -in <code>lua_call</code>. -If there are no errors during the call, -<code>lua_pcall</code> behaves exactly like <code>lua_call</code>. -However, if there is any error, -<code>lua_pcall</code> catches it, -pushes a single value at the stack (the error message), -and returns an error code. -Like <code>lua_call</code>, -<code>lua_pcall</code> always removes the function -and its arguments from the stack. - -<p>If <code>errfunc</code> is 0, -then the error message returned is exactly the original error message. -Otherwise, <code>errfunc</code> gives the stack index for an -<em>error handler function</em>. -(In the current implementation, that index cannot be a pseudo-index.) -In case of runtime errors, -that function will be called with the error message -and its return value will be the message returned by <code>lua_pcall</code>. - -<p>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 <code>lua_pcall</code>, -since by then the stack has unwound. - -<p>The <code>lua_pcall</code> function returns 0 in case of success -or one of the following error codes -(defined in <code>lua.h</code>): -<ul> -<li> <code>LUA_ERRRUN</code> --- a runtime error. -<li> <code>LUA_ERRMEM</code> --- memory allocation error. -For such errors, Lua does not call the error handler function. -<li> <code>LUA_ERRERR</code> --- -error while running the error handler function. -</ul> - -<p><a name="LuacallC"><a name="3.16"><h2>3.16 - Defining C Functions</h2></a></a> - -<p>Lua can be extended with functions written in C. -These functions must be of type <code>lua_CFunction</code>, -which is defined as -<PRE> - typedef int (*lua_CFunction) (lua_State *L); -</PRE> - -A C function receives a Lua state and returns an integer, -the number of values it wants to return to Lua. - -<p>In order to communicate properly with Lua, -a C function must follow 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, -its first argument (if any) is at index 1. -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 -discharged by Lua. -Like a Lua function, a C function called by Lua can also return -many results. - -<p>As an example, the following function receives a variable number -of numerical arguments and returns their average and sum: -<PRE> - 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 to function `average'"); - 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 */ - } -</PRE> - -<p>To register a C function to Lua, -there is the following convenience macro: -<PRE> - #define lua_register(L,n,f) \ - (lua_pushstring(L, n), \ - lua_pushcfunction(L, f), \ - lua_settable(L, LUA_GLOBALSINDEX)) - /* lua_State *L; */ - /* const char *n; */ - /* lua_CFunction f; */ -</PRE> - -which receives the name the function will have in Lua -and a pointer to the function. -Thus, -the C function <code>foo</code> above may be registered in Lua as -<code>average</code> by calling -<PRE> - lua_register(L, "average", foo); -</PRE> - -<p><a name="c-closure"><a name="3.17"><h2>3.17 - Defining C Closures</h2></a></a> - -<p>When a C function is created, -it is possible to associate some values with it, -thus creating a <em>C closure</em>; -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 the function -<PRE> - void lua_pushcclosure (lua_State *L, lua_CFunction fn, int n); -</PRE> - -is used to push the C function onto the stack, -with the argument <code>n</code> telling how many values should be -associated with the function -(<code>lua_pushcclosure</code> also pops these values from the stack); -in fact, the macro <code>lua_pushcfunction</code> is defined as -<code>lua_pushcclosure</code> with <code>n</code> set to 0. - -<p>Then, whenever the C function is called, -those values are located at specific pseudo-indices. -Those pseudo-indices are produced by a macro <code>lua_upvalueindex</code>. -The first value associated with a function is at position -<code>lua_upvalueindex(1)</code>, and so on. -Any access to <code>lua_upvalueindex(<em>n</em>)</code>, -where <em>n</em> is greater than the number of upvalues of the -current function, -produces an acceptable (but invalid) index. - -<p>For examples of C functions and closures, -see the standard libraries in the official Lua distribution -(<code>src/lib/*.c</code>). - -<p><a name="registry"><a name="3.18"><h2>3.18 - Registry</h2></a></a> - -<p>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, -specially if the C code needs to keep that Lua value -outside the life span of a C function. -This table is always located at pseudo-index -<code>LUA_REGISTRYINDEX</code>. -Any C library can store data into this table, -as long as it chooses keys different from other libraries. -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. - -<p>The integer keys in the registry are used by the reference mechanism, -implemented by the auxiliary library, -and therefore should not be used by other purposes. - -<p><a name="3.19"><h2>3.19 - Error Handling in C</h2></a> - -<p>Internally, Lua uses the C <code>longjmp</code> facility to handle errors. -When Lua faces any error -(such as memory allocation errors, type errors, syntax errors) -it <em>raises</em> an error, that is, it does a long jump. -A <em>protected environment</em> uses <code>setjmp</code> -to set a recover point; -any error jumps to the most recent active recover point. - -<p>If an error happens outside any protected environment, -Lua calls a <em>panic function</em> -and then calls <code>exit(EXIT_FAILURE)</code>. -You can change the panic function with -<PRE> - lua_CFunction lua_atpanic (lua_State *L, lua_CFunction panicf); -</PRE> -Your new panic function may avoid the application exit by -never returning (e.g., by doing a long jump). -Nevertheless, the corresponding Lua state will not be consistent; -the only safe operation with it is to close it. - -<p>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: -<code>lua_open</code>, <code>lua_close</code>, <code>lua_load</code>, -and <code>lua_pcall</code>. - -<p>There is yet another function that runs a given C function in protected mode: -<PRE> - int lua_cpcall (lua_State *L, lua_CFunction func, void *ud); -</PRE> - -<code>lua_cpcall</code> calls <code>func</code> in protected mode. -<code>func</code> starts with only one element in its stack, -a light userdata containing <code>ud</code>. -In case of errors, -<code>lua_cpcall</code> returns the same error codes as <code>lua_pcall</code> -(see <a href="#lua_pcall">3.15</a>), -plus the error object on the top of the stack; -otherwise, it returns zero, and does not change the stack. -Any value returned by <code>func</code> is discarded. - -<p>C code can generate a Lua error calling the function -<PRE> - void lua_error (lua_State *L); -</PRE> - -The error message (which actually can be any type of object) -must be on the stack top. -This function does a long jump, -and therefore never returns. - -<p><a name="3.20"><h2>3.20 - Threads</h2></a> - -<p>Lua offers partial support for multiple threads of execution. -If you have a C library that offers multi-threading, -then Lua can cooperate with it to implement the equivalent facility in Lua. -Also, Lua implements its own coroutine system on top of threads. -The following function creates a new thread in Lua: -<PRE> - lua_State *lua_newthread (lua_State *L); -</PRE> - -This function pushes the thread on the stack and returns a pointer to -a <code>lua_State</code> 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 run-time stack. - -<p>Each thread has an independent global environment table. -When you create a thread, this table is the same as that of the given state, -but you can change each one independently. - -<p>There is no explicit function to close or to destroy a thread. -Threads are subject to garbage collection, -like any Lua object. - -<p>To manipulate threads as coroutines, -Lua offers the following functions: -<PRE> - int lua_resume (lua_State *L, int narg); - int lua_yield (lua_State *L, int nresults); -</PRE> - -To start a coroutine, you first create a new thread; -then you push on its stack the body function plus any eventual arguments; -then you call <code>lua_resume</code>, -with <code>narg</code> 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 <code>lua_yield</code>, -or all values returned by the body function. -<code>lua_resume</code> returns 0 if there are no errors running the coroutine, -or an error code (see <a href="#lua_pcall">3.15</a>). -In case of errors, -the stack contains only the error message. -To restart a coroutine, you put on its stack only the values to -be passed as results from <code>yield</code>, -and then call <code>lua_resume</code>. - -<p>The <code>lua_yield</code> function can only be called as the -return expression of a C function, as follows: -<PRE> - return lua_yield (L, nresults); -</PRE> -When a C function calls <code>lua_yield</code> in that way, -the running coroutine suspends its execution, -and the call to <code>lua_resume</code> that started this coroutine returns. -The parameter <code>nresults</code> is the number of values from the stack -that are passed as results to <code>lua_resume</code>. - -<p>To exchange values between different threads, -you may use <code>lua_xmove</code>: -<PRE> - void lua_xmove (lua_State *from, lua_State *to, int n); -</PRE> -It pops <code>n</code> values from the stack <code>from</code>, -and puhses them into the stack <code>to</code>. - -<p> -<a name="debugI"><a name="4"><h1>4 - The Debug Interface</h1></a></a> - -<p>Lua has no built-in debugging facilities. -Instead, it offers a special interface -by means of functions and <em>hooks</em>. -This interface allows the construction of different -kinds of debuggers, profilers, and other tools -that need "inside information" from the interpreter. - -<p><a name="4.1"><h2>4.1 - Stack and Function Information</h2></a> - -<p>The main function to get information about the interpreter runtime stack is -<PRE> - int lua_getstack (lua_State *L, int level, lua_Debug *ar); -</PRE> - -This function fills parts of a <code>lua_Debug</code> structure with -an identification of the <em>activation record</em> -of the function executing at a given level. -Level 0 is the current running function, -whereas level <em>n+1</em> is the function that has called level <em>n</em>. -When there are no errors, <code>lua_getstack</code> returns 1; -when called with a level greater than the stack depth, -it returns 0. - -<p>The structure <code>lua_Debug</code> is used to carry different pieces of -information about an active function: -<PRE> - typedef struct lua_Debug { - int event; - const char *name; /* (n) */ - const char *namewhat; /* (n) `global', `local', `field', `method' */ - const char *what; /* (S) `Lua' function, `C' function, Lua `main' */ - const char *source; /* (S) */ - int currentline; /* (l) */ - int nups; /* (u) number of upvalues */ - int linedefined; /* (S) */ - char short_src[LUA_IDSIZE]; /* (S) */ - - /* private part */ - ... - } lua_Debug; -</PRE> - -<code>lua_getstack</code> fills only the private part -of this structure, for later use. -To fill the other fields of <code>lua_Debug</code> with useful information, -call -<PRE> - int lua_getinfo (lua_State *L, const char *what, lua_Debug *ar); -</PRE> - -This function returns 0 on error -(for instance, an invalid option in <code>what</code>). -Each character in the string <code>what</code> -selects some fields of the structure <code>ar</code> to be filled, -as indicated by the letter in parentheses in the definition of <code>lua_Debug</code> -above: -`<code>S</code>´ fills in the fields <code>source</code>, <code>linedefined</code>, -and <code>what</code>; -`<code>l</code>´ fills in the field <code>currentline</code>, etc. -Moreover, `<code>f</code>´ pushes onto the stack the function that is -running at the given level. - -<p>To get information about a function that is not active -(that is, not in the stack), -you push it onto the stack -and start the <code>what</code> string with the character `<code>></code>´. -For instance, to know in which line a function <code>f</code> was defined, -you can write -<PRE> - lua_Debug ar; - lua_pushstring(L, "f"); - lua_gettable(L, LUA_GLOBALSINDEX); /* get global `f' */ - lua_getinfo(L, ">S", &ar); - printf("%d\n", ar.linedefined); -</PRE> -The fields of <code>lua_Debug</code> have the following meaning: -<ul> - -<p><li><b><code>source</code></b> -If the function was defined in a string, -then <code>source</code> is that string. -If the function was defined in a file, -then <code>source</code> starts with a `<code>@</code>´ followed by the file name. - -<p><li><b><code>short_src</code></b> -A "printable" version of <code>source</code>, to be used in error messages. - -<p><li><b><code>linedefined</code></b> -the line number where the definition of the function starts. - -<p><li><b><code>what</code></b> the string <code>"Lua"</code> if this is a Lua function, -<code>"C"</code> if this is a C function, -<code>"main"</code> if this is the main part of a chunk, -and <code>"tail"</code> if this was a function that did a tail call. -In the latter case, -Lua has no other information about this function. - -<p><li><b><code>currentline</code></b> -the current line where the given function is executing. -When no line information is available, -<code>currentline</code> is set to <em>-1</em>. - -<p><li><b><code>name</code></b> -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 <code>lua_getinfo</code> function checks how the function was -called or whether it is the value of a global variable to -find a suitable name. -If it cannot find a name, -then <code>name</code> is set to <code>NULL</code>. - -<p><li><b><code>namewhat</code></b> -Explains the <code>name</code> field. -The value of <code>namewhat</code> can be -<code>"global"</code>, <code>"local"</code>, <code>"method"</code>, -<code>"field"</code>, or <code>""</code> (the empty string), -according to how the function was called. -(Lua uses the empty string when no other option seems to apply.) - -<p><li><b><code>nups</code></b> -The number of upvalues of the function. - -<p></ul> - -<p><a name="4.2"><h2>4.2 - Manipulating Local Variables and Upvalues</h2></a> - -<p>For the manipulation of local variables and upvalues, -the debug interface uses indices: -The first parameter or local variable has index 1, and so on, -until the last active local variable. -Upvalues have no particular order, -as they are active through the whole function. - -<p>The following functions allow the manipulation of the -local variables of a given activation record: -<PRE> - const char *lua_getlocal (lua_State *L, const lua_Debug *ar, int n); - const char *lua_setlocal (lua_State *L, const lua_Debug *ar, int n); -</PRE> - -The parameter <code>ar</code> must be a valid activation record that was -filled by a previous call to <code>lua_getstack</code> or -given as argument to a hook (see <a href="#sub-hooks">4.3</a>). -<code>lua_getlocal</code> gets the index <code>n</code> of a local variable, -pushes the variable's value onto the stack, -and returns its name. -<code>lua_setlocal</code> assigns the value at the top of the stack -to the variable and returns its name. -Both functions return <code>NULL</code> -when the index is greater than -the number of active local variables. - -<p>The following functions allow the manipulation of the -upvalues of a given function -(unlike local variables, -the upvalues of a function are accessible even when the -function is not active): -<PRE> - const char *lua_getupvalue (lua_State *L, int funcindex, int n); - const char *lua_setupvalue (lua_State *L, int funcindex, int n); -</PRE> - -These functions operate both on Lua functions and on C functions. -(For Lua functions, -upvalues are the external local variables that the function uses, -and that consequently are included in its closure.) -<code>funcindex</code> points to a function in the stack. -<code>lua_getpuvalue</code> gets the index <code>n</code> of an upvalue, -pushes the upvalue's value onto the stack, -and returns its name. -<code>lua_setupvalue</code> assigns the value at the top of the stack -to the upvalue and returns its name. -Both functions return <code>NULL</code> -when the index is greater than the number of upvalues. -For C functions, these functions use the empty string <code>""</code> -as a name for all upvalues. - -<p>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: -<PRE> - 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_getpuvalue(L, -1, i++)) != NULL) { - printf("upvalue %d %s\n", i-1, name); - lua_pop(L, 1); /* remove upvalue value */ - } - return 1; - } -</PRE> - -<p><a name="sub-hooks"><a name="4.3"><h2>4.3 - Hooks</h2></a></a> - -<p>Lua offers a mechanism of hooks, which are -user-defined C functions that are called during the program execution. -A hook may be called in four different events: -a <em>call</em> event, when Lua calls a function; -a <em>return</em> event, when Lua returns from a function; -a <em>line</em> event, when Lua starts executing a new line of code; -and a <em>count</em> event, which happens every "count" instructions. -Lua identifies these events with the following constants: -<code>LUA_HOOKCALL</code>, -<code>LUA_HOOKRET</code> (or <code>LUA_HOOKTAILRET</code>, see below), -<code>LUA_HOOKLINE</code>, -and <code>LUA_HOOKCOUNT</code>. - -<p>A hook has type <code>lua_Hook</code>, defined as follows: -<PRE> - typedef void (*lua_Hook) (lua_State *L, lua_Debug *ar); -</PRE> - -You can set the hook with the following function: -<PRE> - int lua_sethook (lua_State *L, lua_Hook func, int mask, int count); -</PRE> - -<code>func</code> is the hook. -<code>mask</code> specifies on which events the hook will be called: -It is formed by a disjunction of the constants -<code>LUA_MASKCALL</code>, -<code>LUA_MASKRET</code>, -<code>LUA_MASKLINE</code>, -and <code>LUA_MASKCOUNT</code>. -The <code>count</code> argument is only meaningful when the mask -includes <code>LUA_MASKCOUNT</code>. -For each event, the hook is called as explained below: -<ul> -<li><b>The call hook</b> is called when the interpreter calls a function. -The hook is called just after Lua enters the new function. -<li><b>The return hook</b> is called when the interpreter returns from a function. -The hook is called just before Lua leaves the function. -<li><b>The line hook</b> 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.) -<li><b>The count hook</b> is called after the interpreter executes every -<code>count</code> instructions. -(This event only happens while Lua is executing a Lua function.) -</ul> - -<p>A hook is disabled by setting <code>mask</code> to zero. - -<p>You can get the current hook, the current mask, -and the current count with the next functions: -<PRE> - lua_Hook lua_gethook (lua_State *L); - int lua_gethookmask (lua_State *L); - int lua_gethookcount (lua_State *L); -</PRE> - - -<p>Whenever a hook is called, its <code>ar</code> argument has its field -<code>event</code> set to the specific event that triggered the hook. -Moreover, for line events, the field <code>currentline</code> is also set. -To get the value of any other field in <code>ar</code>, -the hook must call <code>lua_getinfo</code>. -For return events, <code>event</code> may be <code>LUA_HOOKRET</code>, -the normal value, or <code>LUA_HOOKTAILRET</code>. -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 <code>lua_getinfo</code>. - -<p>While Lua is running a hook, it disables other calls to hooks. -Therefore, if a hook calls back Lua to execute a function or a chunk, -that execution occurs without any calls to hooks. - -<p> -<a name="libraries"><a name="5"><h1>5 - Standard Libraries</h1></a></a> - -<p>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., <code>type</code> and <code>getmetatable</code>); -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 to -deserve an implementation in C (e.g., <code>sort</code>). - -<p>All libraries are implemented through the official C API -and are provided as separate C modules. -Currently, Lua has the following standard libraries: -<ul> -<li> basic library; -<li> string manipulation; -<li> table manipulation; -<li> mathematical functions (sin, log, etc.); -<li> input and output; -<li> operating system facilities; -<li> debug facilities. -</ul> -Except for the basic library, -each library provides all its functions as fields of a global table -or as methods of its objects. - -<p>To have access to these libraries, -the C host program must first call the functions -<code>luaopen_base</code> (for the basic library), -<code>luaopen_string</code> (for the string library), -<code>luaopen_table</code> (for the table library), -<code>luaopen_math</code> (for the mathematical library), -<code>luaopen_io</code> (for the I/O and the Operating System libraries), -and <code>luaopen_debug</code> (for the debug library). -These functions are declared in <code>lualib.h</code>. - - - - - - - -<p><a name="predefined"><a name="5.1"><h2>5.1 - Basic Functions</h2></a></a> - -<p>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 some alternative -implementation for some of its facilities. - -<p><h3><code>assert (v [, message])</code></h3> -Issues an error when -the value of its argument <code>v</code> is <B>nil</B> or <B>false</B>; -otherwise, returns this value. -<code>message</code> is an error message; -when absent, it defaults to "assertion failed!" - -<p><h3><code>collectgarbage ([limit])</code></h3> - -<p>Sets the garbage-collection threshold to the given limit -(in Kbytes) and checks it against the byte counter. -If the new threshold is smaller than the byte counter, -then Lua immediately runs the garbage collector (see <a href="#GC">2.9</a>). -If <code>limit</code> is absent, it defaults to zero -(thus forcing a garbage-collection cycle). - -<p><h3><code>dofile (filename)</code></h3> -Opens the named file and executes its contents as a Lua chunk. -When called without arguments, -<code>dofile</code> executes the contents of the standard input (<code>stdin</code>). -Returns any value returned by the chunk. -In case of errors, <code>dofile</code> propagates the error -to its caller (that is, it does not run in protected mode). - -<p><a name="pdf-error"><h3><code>error (message [, level])</code></h3></a> - -Terminates the last protected function called -and returns <code>message</code> as the error message. -Function <code>error</code> never returns. - -<p>The <code>level</code> argument specifies where the error -message points the error. -With level 1 (the default), the error position is where the -<code>error</code> function was called. -Level 2 points the error to where the function -that called <code>error</code> was called; and so on. - -<p><h3><code>_G</code></h3> -A global variable (not a function) that -holds the global environment (that is, <code>_G._G = _G</code>). -Lua itself does not use this variable; -changing its value does not affect any environment. -(Use <code>setfenv</code> to change environments.) - -<p><h3><code>getfenv (f)</code></h3> -Returns the current environment in use by the function. -<code>f</code> can be a Lua function or a number, -which specifies the function at that stack level: -Level 1 is the function calling <code>getfenv</code>. -If the given function is not a Lua function, -or if <code>f</code> is 0, -<code>getfenv</code> returns the global environment. -The default for <code>f</code> is 1. - -<p>If the environment has a <code>"__fenv"</code> field, -returns the associated value, instead of the environment. - -<p><a name="pdf-getmetatable"><h3><code>getmetatable (object)</code></h3></a> - - -<p>If the object does not have a metatable, returns <B>nil</B>. -Otherwise, -if the object's metatable has a <code>"__metatable"</code> field, -returns the associated value. -Otherwise, returns the metatable of the given object. - -<p><h3><code>gcinfo ()</code></h3> - -<p>Returns two results: -the number of Kbytes of dynamic memory that Lua is using -and the current garbage collector threshold (also in Kbytes). - -<p><h3><code>ipairs (t)</code></h3> - -<p>Returns an iterator function, the table <code>t</code>, and 0, -so that the construction -<PRE> - for i,v in ipairs(t) do ... end -</PRE> -will iterate over the pairs (<code>1,t[1]</code>), (<code>2,t[2]</code>), ..., -up to the first integer key with a nil value in the table. - -<p><h3><code>loadfile (filename)</code></h3> - -<p>Loads a file as a Lua chunk (without running it). -If there are no errors, -returns the compiled chunk as a function; -otherwise, returns <B>nil</B> plus the error message. -The environment of the returned function is the global environment. - -<p><h3><code>loadlib (libname, funcname)</code></h3> - -<p>Links the program with the dynamic C library <code>libname</code>. -Inside this library, looks for a function <code>funcname</code> -and returns this function as a C function. - -<p><code>libname</code> must be the complete file name of the C library, -including any eventual path and extension. - -<p>This function is not supported by ANSI C. -As such, it is only available on some platforms -(Windows, Linux, Solaris, BSD, plus other Unix systems that -support the <code>dlfcn</code> standard). - -<p><h3><code>loadstring (string [, chunkname])</code></h3> -Loads a string as a Lua chunk (without running it). -If there are no errors, -returns the compiled chunk as a function; -otherwise, returns <B>nil</B> plus the error message. -The environment of the returned function is the global environment. - -<p>The optional parameter <code>chunkname</code> -is the name to be used in error messages and debug information. - -<p>To load and run a given string, use the idiom -<PRE> - assert(loadstring(s))() -</PRE> - -<p><h3><code>next (table [, index])</code></h3> -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. -<code>next</code> returns the next index of the table and the -value associated with the index. -When called with <B>nil</B> as its second argument, -<code>next</code> returns the first index -of the table and its associated value. -When called with the last index, -or with <B>nil</B> in an empty table, -<code>next</code> returns <B>nil</B>. -If the second argument is absent, then it is interpreted as <B>nil</B>. - -<p>Lua has no declaration of fields; -There is no difference between a -field not present in a table or a field with value <B>nil</B>. -Therefore, <code>next</code> only considers fields with non-<B>nil</B> values. -The order in which the indices are enumerated is not specified, -<em>even for numeric indices</em>. -(To traverse a table in numeric order, -use a numerical <b>for</b> or the <code>ipairs</code> function.) - -<p>The behavior of <code>next</code> is <em>undefined</em> if, -during the traversal, -you assign any value to a non-existent field in the table. - -<p><h3><code>pairs (t)</code></h3> - -<p>Returns the <code>next</code> function and the table <code>t</code> (plus a <B>nil</B>), -so that the construction -<PRE> - for k,v in pairs(t) do ... end -</PRE> -will iterate over all key-value pairs of table <code>t</code>. - -<p><a name="pdf-pcall"><h3><code>pcall (f, arg1, arg2, ...)</code></h3></a> - -<p>Calls function <code>f</code> with -the given arguments in protected mode. -That means that any error inside <code>f</code> is not propagated; -instead, <code>pcall</code> catches the error -and returns a status code. -Its first result is the status code (a boolean), -which is <B>true</B> if the call succeeds without errors. -In such case, <code>pcall</code> also returns all results from the call, -after this first result. -In case of any error, <code>pcall</code> returns <B>false</B> plus the error message. - -<p><h3><code>print (e1, e2, ...)</code></h3> -Receives any number of arguments, -and prints their values in <code>stdout</code>, -using the <code>tostring</code> function to convert them to strings. -This function is not intended for formatted output, -but only as a quick way to show a value, -typically for debugging. -For formatted output, use <code>format</code> (see <a href="#format">5.3</a>). - -<p><h3><code>rawequal (v1, v2)</code></h3> -Checks whether <code>v1</code> is equal to <code>v2</code>, -without invoking any metamethod. -Returns a boolean. - -<p><h3><code>rawget (table, index)</code></h3> -Gets the real value of <code>table[index]</code>, -without invoking any metamethod. -<code>table</code> must be a table; -<code>index</code> is any value different from <B>nil</B>. - -<p><h3><code>rawset (table, index, value)</code></h3> -Sets the real value of <code>table[index]</code> to <code>value</code>, -without invoking any metamethod. -<code>table</code> must be a table, -<code>index</code> is any value different from <B>nil</B>, -and <code>value</code> is any Lua value. - -<p><h3><code>require (packagename)</code></h3> - -<p>Loads the given package. -The function starts by looking into the table <code>_LOADED</code> -to determine whether <code>packagename</code> is already loaded. -If it is, then <code>require</code> returns the value that the package -returned when it was first loaded. -Otherwise, it searches a path looking for a file to load. - -<p>If the global variable <code>LUA_PATH</code> is a string, -this string is the path. -Otherwise, <code>require</code> tries the environment variable <code>LUA_PATH</code>. -As a last resort, it uses the predefined path <code>"?;?.lua"</code>. - -<p>The path is a sequence of <em>templates</em> separated by semicolons. -For each template, <code>require</code> will change each interrogation -mark in the template to <code>packagename</code>, -and then will try to load the resulting file name. -So, for instance, if the path is -<PRE> - "./?.lua;./?.lc;/usr/local/?/?.lua;/lasttry" -</PRE> -a <code>require "mod"</code> will try to load the files -<code>./mod.lua</code>, -<code>./mod.lc</code>, -<code>/usr/local/mod/mod.lua</code>, -and <code>/lasttry</code>, in that order. - -<p>The function stops the search as soon as it can load a file, -and then it runs the file. -After that, it associates, in table <code>_LOADED</code>, -the package name with the value that the package returned, -and returns that value. -If the package returns <B>nil</B> (or no value), -<code>require</code> converts this value to <B>true</B>. -If the package returns <B>false</B>, -<code>require</code> also returns <B>false</B>. -However, as the mark in table <code>_LOADED</code> is <B>false</B>, -any new attempt to reload the file -will happen as if the package was not loaded -(that is, the package will be loaded again). - -<p>If there is any error loading or running the file, -or if it cannot find any file in the path, -then <code>require</code> signals an error. - -<p>While running a file, -<code>require</code> defines the global variable <code>_REQUIREDNAME</code> -with the package name. -The package being loaded always runs within the global environment. - -<p><a name="setfenv"><h3><code>setfenv (f, table)</code></h3></a> - -<p>Sets the current environment to be used by the given function. -<code>f</code> can be a Lua function or a number, -which specifies the function at that stack level: -Level 1 is the function calling <code>setfenv</code>. - -<p>As a special case, when <code>f</code> is 0 <code>setfenv</code> changes -the global environment of the running thread. - -<p>If the original environment has a <code>"__fenv"</code> field, -<code>setfenv</code> raises an error. - -<p><h3><code>setmetatable (table, metatable)</code></h3> - -<p>Sets the metatable for the given table. -(You cannot change the metatable of a userdata from Lua.) -If <code>metatable</code> is <B>nil</B>, removes the metatable of the given table. -If the original metatable has a <code>"__metatable"</code> field, -raises an error. - -<p><h3><code>tonumber (e [, base])</code></h3> -Tries to convert its argument to a number. -If the argument is already a number or a string convertible -to a number, then <code>tonumber</code> returns that number; -otherwise, it returns <B>nil</B>. - -<p>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 `<code>A</code>´ (in either upper or lower case) -represents 10, `<code>B</code>´ represents 11, and so forth, -with `<code>Z</code>´ representing 35. -In base 10 (the default), the number may have a decimal part, -as well as an optional exponent part (see <a href="#coercion">2.2.1</a>). -In other bases, only unsigned integers are accepted. - -<p><h3><code>tostring (e)</code></h3> -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 <code>format</code> (see <a href="#format">5.3</a>). - -<p>If the metatable of <code>e</code> has a <code>"__tostring"</code> field, -<code>tostring</code> calls the corresponding value -with <code>e</code> as argument, -and uses the result of the call as its result. - -<p><a name="pdf-type"><h3><code>type (v)</code></h3></a> -Returns the type of its only argument, coded as a string. -The possible results of this function are -<code>"nil"</code> (a string, not the value <B>nil</B>), -<code>"number"</code>, -<code>"string"</code>, -<code>"boolean</code>, -<code>"table"</code>, -<code>"function"</code>, -<code>"thread"</code>, -and <code>"userdata"</code>. - -<p><h3><code>unpack (list)</code></h3> -Returns all elements from the given list. -This function is equivalent to -<PRE> - return list[1], list[2], ..., list[n] -</PRE> -except that the above code can be written only for a fixed <em>n</em>. -The number <em>n</em> is the size of the list, -as defined for the <code>table.getn</code> function. - -<p><h3><code>_VERSION</code></h3> -A global variable (not a function) that -holds a string containing the current interpreter version. -The current content of this string is <code>"Lua 5.0"</code>. - -<p><h3><code>xpcall (f, err)</code></h3> - -<p>This function is similar to <code>pcall</code>, -except that you can set a new error handler. - -<p><code>xpcall</code> calls function <code>f</code> in protected mode, -using <code>err</code> as the error handler. -Any error inside <code>f</code> is not propagated; -instead, <code>xpcall</code> catches the error, -calls the <code>err</code> 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 such case, <code>xpcall</code> also returns all results from the call, -after this first result. -In case of any error, -<code>xpcall</code> returns false plus the result from <code>err</code>. - -<p><a name="5.2"><h2>5.2 - Coroutine Manipulation</h2></a> - -<p>The operations related to coroutines comprise a sub-library of -the basic library and come inside the table <code>coroutine</code>. -See <a href="#coroutine">2.10</a> for a general description of coroutines. - -<p><h3><code>coroutine.create (f)</code></h3> - -<p>Creates a new coroutine, with body <code>f</code>. -<code>f</code> must be a Lua function. -Returns this new coroutine, -an object with type <code>"thread"</code>. - -<p><h3><code>coroutine.resume (co, val1, ...)</code></h3> - -<p>Starts or continues the execution of coroutine <code>co</code>. -The first time you resume a coroutine, -it starts running its body. -The arguments <code>val1</code>, ... go as the arguments to the body function. -If the coroutine has yielded, -<code>resume</code> restarts it; -the arguments <code>val1</code>, ... go as the results from the yield. - -<p>If the coroutine runs without any errors, -<code>resume</code> returns <B>true</B> plus any values passed to <code>yield</code> -(if the coroutine yields) or any values returned by the body function -(if the coroutine terminates). -If there is any error, -<code>resume</code> returns <B>false</B> plus the error message. - -<p><h3><code>coroutine.status (co)</code></h3> - -<p>Returns the status of coroutine <code>co</code>, as a string: -<code>"running"</code>, -if the coroutine is running (that is, it called <code>status</code>); -<code>"suspended"</code>, if the coroutine is suspended in a call to <code>yield</code>, -or if it has not started running yet; -and <code>"dead"</code> if the coroutine has finished its body function, -or if it has stopped with an error. - -<p><h3><code>coroutine.wrap (f)</code></h3> - -<p>Creates a new coroutine, with body <code>f</code>. -<code>f</code> 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 <code>resume</code>. -Returns the same values returned by <code>resume</code>, -except the first boolean. -In case of error, propagates the error. - -<p><h3><code>coroutine.yield (val1, ...)</code></h3> - -<p>Suspends the execution of the calling coroutine. -The coroutine cannot be running neither a C function, -nor a metamethod, nor an iterator. -Any arguments to <code>yield</code> go as extra results to <code>resume</code>. - -<p><a name="5.3"><h2>5.3 - String Manipulation</h2></a> -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 <em>-1</em>, and so on. - -<p>The string library provides all its functions inside the table -<code>string</code>. - -<p><h3><code>string.byte (s [, i])</code></h3> -Returns the internal numerical code of the <code>i</code>-th character of <code>s</code>, -or <B>nil</B> if the index is out of range. -If <code>i</code> is absent, then it is assumed to be 1. -<code>i</code> may be negative. - -<p>Note that numerical codes are not necessarily portable across platforms. - -<p><h3><code>string.char (i1, i2, ...)</code></h3> -Receives 0 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. - -<p>Note that numerical codes are not necessarily portable across platforms. - -<p><h3><code>string.dump (function)</code></h3> - -<p>Returns a binary representation of the given function, -so that a later <code>loadstring</code> on that string returns -a copy of the function. -<code>function</code> must be a Lua function without upvalues. - -<p><h3><code>string.find (s, pattern [, init [, plain]])</code></h3> -Looks for the first <em>match</em> of -<code>pattern</code> in the string <code>s</code>. -If it finds one, then <code>find</code> returns the indices of <code>s</code> -where this occurrence starts and ends; -otherwise, it returns <B>nil</B>. -If the pattern specifies captures (see <code>string.gsub</code> below), -the captured strings are returned as extra results. -A third, optional numerical argument <code>init</code> specifies -where to start the search; -its default value is 1 and may be negative. -A value of <B>true</B> as a fourth, optional argument <code>plain</code> -turns off the pattern matching facilities, -so the function does a plain "find substring" operation, -with no characters in <code>pattern</code> being considered "magic". -Note that if <code>plain</code> is given, then <code>init</code> must be given too. - -<p><h3><code>string.len (s)</code></h3> -Receives a string and returns its length. -The empty string <code>""</code> has length 0. -Embedded zeros are counted, -so <code>"a\000b\000c"</code> has length 5. - -<p><h3><code>string.lower (s)</code></h3> -Receives a string and returns a copy of that string with all -uppercase letters changed to lowercase. -All other characters are left unchanged. -The definition of what is an uppercase letter depends on the current locale. - -<p><h3><code>string.rep (s, n)</code></h3> -Returns a string that is the concatenation of <code>n</code> copies of -the string <code>s</code>. - -<p><h3><code>string.sub (s, i [, j])</code></h3> -Returns the substring of <code>s</code> that -starts at <code>i</code> and continues until <code>j</code>; -<code>i</code> and <code>j</code> may be negative. -If <code>j</code> is absent, then it is assumed to be equal to <em>-1</em> -(which is the same as the string length). -In particular, -the call <code>string.sub(s,1,j)</code> returns a prefix of <code>s</code> -with length <code>j</code>, -and <code>string.sub(s, -i)</code> returns a suffix of <code>s</code> -with length <code>i</code>. - -<p><h3><code>string.upper (s)</code></h3> -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 is a lowercase letter depends on the current locale. - -<p><a name="format"><h3><code>string.format (formatstring, e1, e2, ...)</code></h3></a> - -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 <code>printf</code> family of -standard C functions. -The only differences are that the options/modifiers -<code>*</code>, <code>l</code>, <code>L</code>, <code>n</code>, <code>p</code>, -and <code>h</code> are not supported, -and there is an extra option, <code>q</code>. -The <code>q</code> 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, and backslashes in the string -are correctly escaped when written. -For instance, the call -<PRE> - string.format('%q', 'a string with "quotes" and \n new line') -</PRE> -will produce the string: -<PRE> -"a string with \"quotes\" and \ - new line" -</PRE> - -<p>The options <code>c</code>, <code>d</code>, <code>E</code>, <code>e</code>, <code>f</code>, -<code>g</code>, <code>G</code>, <code>i</code>, <code>o</code>, <code>u</code>, <code>X</code>, and <code>x</code> all -expect a number as argument, -whereas <code>q</code> and <code>s</code> expect a string. -The <code>*</code> modifier can be simulated by building -the appropriate format string. -For example, <code>"%*g"</code> can be simulated with -<code>"%"..width.."g"</code>. - -<p>String values to be formatted with -<code>%s</code> cannot contain embedded zeros. - -<p><h3><code>string.gfind (s, pat)</code></h3> - -<p>Returns an iterator function that, -each time it is called, -returns the next captures from pattern <code>pat</code> over string <code>s</code>. - -<p>If <code>pat</code> specifies no captures, -then the whole match is produced in each call. - -<p>As an example, the following loop -<PRE> - s = "hello world from Lua" - for w in string.gfind(s, "%a+") do - print(w) - end -</PRE> -will iterate over all the words from string <code>s</code>, -printing one per line. -The next example collects all pairs <code>key=value</code> from the -given string into a table: -<PRE> - t = {} - s = "from=world, to=Lua" - for k, v in string.gfind(s, "(%w+)=(%w+)") do - t[k] = v - end -</PRE> - -<p><h3><code>string.gsub (s, pat, repl [, n])</code></h3> - -Returns a copy of <code>s</code> -in which all occurrences of the pattern <code>pat</code> have been -replaced by a replacement string specified by <code>repl</code>. -<code>gsub</code> also returns, as a second value, -the total number of substitutions made. - -<p>If <code>repl</code> is a string, then its value is used for replacement. -Any sequence in <code>repl</code> of the form <code>%</code><em>n</em>, -with <em>n</em> between 1 and 9, -stands for the value of the <em>n</em>-th captured substring (see below). - -<p>If <code>repl</code> 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 this function is a string, -then it is used as the replacement string; -otherwise, the replacement string is the empty string. - -<p>The optional last parameter <code>n</code> limits -the maximum number of substitutions to occur. -For instance, when <code>n</code> is 1 only the first occurrence of -<code>pat</code> is replaced. - -<p>Here are some examples: -<PRE> - x = string.gsub("hello world", "(%w+)", "%1 %1") - --> x="hello hello world world" - - x = string.gsub("hello world", "(%w+)", "%1 %1", 1) - --> x="hello hello world" - - x = string.gsub("hello world from Lua", "(%w+)%s*(%w+)", "%2 %1") - --> x="world hello Lua from" - - x = string.gsub("home = $HOME, user = $USER", "%$(%w+)", os.getenv) - --> x="home = /home/roberto, user = roberto" - - x = string.gsub("4+5 = $return 4+5$", "%$(.-)%$", function (s) - return loadstring(s)() - end) - --> x="4+5 = 9" - - local t = {name="lua", version="5.0"} - x = string.gsub("$name_$version.tar.gz", "%$(%w+)", function (v) - return t[v] - end) - --> x="lua_5.0.tar.gz" -</PRE> - -<p><a name="pm"><h3>Patterns</h3></a> - -<p><p> -A <em>character class</em> is used to represent a set of characters. -The following combinations are allowed in describing a character class: -<ul> -<li><b><em>x</em></b> (where <em>x</em> is not one of the magic characters -<code>^$()%.[]*+-?</code>) ---- represents the character <em>x</em> itself. -<li><b><code>.</code></b> --- (a dot) represents all characters. -<li><b><code>%a</code></b> --- represents all letters. -<li><b><code>%c</code></b> --- represents all control characters. -<li><b><code>%d</code></b> --- represents all digits. -<li><b><code>%l</code></b> --- represents all lowercase letters. -<li><b><code>%p</code></b> --- represents all punctuation characters. -<li><b><code>%s</code></b> --- represents all space characters. -<li><b><code>%u</code></b> --- represents all uppercase letters. -<li><b><code>%w</code></b> --- represents all alphanumeric characters. -<li><b><code>%x</code></b> --- represents all hexadecimal digits. -<li><b><code>%z</code></b> --- represents the character with representation 0. -<li><b><code>%<em>x</em></code></b> (where <em>x</em> is any non-alphanumeric character) --- -represents the character <em>x</em>. -This is the standard way to escape the magic characters. -Any punctuation character (even the non magic) -can be preceded by a `<code>%</code>´ -when used to represent itself in a pattern. - -<p><li><b><code>[<em>set</em>]</code></b> --- -represents the class which is the union of all -characters in <em>set</em>. -A range of characters may be specified by -separating the end characters of the range with a `<code>-</code>´. -All classes <code>%</code><em>x</em> described above may also be used as -components in <em>set</em>. -All other characters in <em>set</em> represent themselves. -For example, <code>[%w_]</code> (or <code>[_%w]</code>) -represents all alphanumeric characters plus the underscore, -<code>[0-7]</code> represents the octal digits, -and <code>[0-7%l%-]</code> represents the octal digits plus -the lowercase letters plus the `<code>-</code>´ character. - -<p>The interaction between ranges and classes is not defined. -Therefore, patterns like <code>[%a-z]</code> or <code>[a-%%]</code> -have no meaning. - -<p><li><b><code>[^<em>set</em>]</code></b> --- -represents the complement of <em>set</em>, -where <em>set</em> is interpreted as above. -</ul> -For all classes represented by single letters (<code>%a</code>, <code>%c</code>, etc.), -the corresponding uppercase letter represents the complement of the class. -For instance, <code>%S</code> represents all non-space characters. - -<p>The definitions of letter, space, and other character groups -depend on the current locale. -In particular, the class <code>[a-z]</code> may not be equivalent to <code>%l</code>. -The second form should be preferred for portability. - -<p><p> -A <em>pattern item</em> may be -<ul> -<li> -a single character class, -which matches any single character in the class; -<li> -a single character class followed by `<code>*</code>´, -which matches 0 or more repetitions of characters in the class. -These repetition items will always match the longest possible sequence; -<li> -a single character class followed by `<code>+</code>´, -which matches 1 or more repetitions of characters in the class. -These repetition items will always match the longest possible sequence; -<li> -a single character class followed by `<code>-</code>´, -which also matches 0 or more repetitions of characters in the class. -Unlike `<code>*</code>´, -these repetition items will always match the <em>shortest</em> possible sequence; -<li> -a single character class followed by `<code>?</code>´, -which matches 0 or 1 occurrence of a character in the class; -<li> -<code>%<em>n</em></code>, for <em>n</em> between 1 and 9; -such item matches a substring equal to the <em>n</em>-th captured string -(see below); -<li> -<code>%b<em>xy</em></code>, where <em>x</em> and <em>y</em> are two distinct characters; -such item matches strings that start with <em>x</em>, end with <em>y</em>, -and where the <em>x</em> and <em>y</em> are <em>balanced</em>. -This means that, if one reads the string from left to right, -counting <em>+1</em> for an <em>x</em> and <em>-1</em> for a <em>y</em>, -the ending <em>y</em> is the first <em>y</em> where the count reaches 0. -For instance, the item <code>%b()</code> matches expressions with -balanced parentheses. -</ul> - -<p><p> -A <em>pattern</em> is a sequence of pattern items. -A `<code>^</code>´ at the beginning of a pattern anchors the match at the -beginning of the subject string. -A `<code>$</code>´ at the end of a pattern anchors the match at the -end of the subject string. -At other positions, -`<code>^</code>´ and `<code>$</code>´ have no special meaning and represent themselves. - -<p><p> -A pattern may contain sub-patterns enclosed in parentheses; -they describe <em>captures</em>. -When a match succeeds, the substrings of the subject string -that match captures are stored (<em>captured</em>) for future use. -Captures are numbered according to their left parentheses. -For instance, in the pattern <code>"(a*(.)%w(%s*))"</code>, -the part of the string matching <code>"a*(.)%w(%s*)"</code> is -stored as the first capture (and therefore has number 1); -the character matching <code>.</code> is captured with number 2, -and the part matching <code>%s*</code> has number 3. - -<p>As a special case, the empty capture <code>()</code> captures -the current string position (a number). -For instance, if we apply the pattern <code>"()aa()"</code> on the -string <code>"flaaap"</code>, there will be two captures: 3 and 5. - -<p>A pattern cannot contain embedded zeros. Use <code>%z</code> instead. - -<p><a name="5.4"><h2>5.4 - Table Manipulation</h2></a> -This library provides generic functions for table manipulation. -It provides all its functions inside the table <code>table</code>. - -<p>Most functions in the table library assume that the table -represents an array or a list. -For those functions, an important concept is the <em>size</em> of the array. -There are three ways to specify that size: -<ul> -<li> the field <code>"n"</code> --- -When the table has a field <code>"n"</code> with a numerical value, -that value is assumed as its size. -<li> <code>setn</code> --- -You can call the <code>table.setn</code> function to explicitly set -the size of a table. -<li> implicit size --- -Otherwise, the size of the object is one less the first integer index -with a <B>nil</B> value. -</ul> -For more details, see the descriptions of the <code>table.getn</code> and -<code>table.setn</code> functions. - -<p><h3><code>table.concat (table [, sep [, i [, j]]])</code></h3> - -Returns <code>table[i]..sep..table[i+1] ... sep..table[j]</code>. -The default value for <code>sep</code> is the empty string, -the default for <code>i</code> is 1, -and the default for <code>j</code> is the size of the table. -If <code>i</code> is greater than <code>j</code>, returns the empty string. - -<p><h3><code>table.foreach (table, f)</code></h3> -Executes the given <code>f</code> over all elements of <code>table</code>. -For each element, <code>f</code> is called with the index and -respective value as arguments. -If <code>f</code> returns a non-<B>nil</B> value, -then the loop is broken, and this value is returned -as the final value of <code>foreach</code>. - -<p>See the <code>next</code> function for extra information about table traversals. - -<p><h3><code>table.foreachi (table, f)</code></h3> -Executes the given <code>f</code> over the -numerical indices of <code>table</code>. -For each index, <code>f</code> is called with the index and -respective value as arguments. -Indices are visited in sequential order, -from 1 to <code>n</code>, -where <code>n</code> is the size of the table (see <a href="#getn">5.4</a>). -If <code>f</code> returns a non-<B>nil</B> value, -then the loop is broken and this value is returned -as the result of <code>foreachi</code>. - -<p><a name="getn"><h3><code>table.getn (table)</code></h3></a> -Returns the size of a table, when seen as a list. -If the table has an <code>n</code> field with a numeric value, -this value is the size of the table. -Otherwise, if there was a previous call -to <code>table.setn</code> over this table, -the respective value is returned. -Otherwise, the size is one less the first integer index with -a <B>nil</B> value. - -<p><h3><code>table.sort (table [, comp])</code></h3> -Sorts table elements in a given order, <em>in-place</em>, -from <code>table[1]</code> to <code>table[n]</code>, -where <code>n</code> is the size of the table (see <a href="#getn">5.4</a>). -If <code>comp</code> 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 <code>not comp(a[i+1],a[i])</code> will be true after the sort). -If <code>comp</code> is not given, -then the standard Lua operator <code><</code> is used instead. - -<p>The sort algorithm is <em>not</em> stable, -that is, elements considered equal by the given order -may have their relative positions changed by the sort. - -<p><h3><code>table.insert (table, [pos,] value)</code></h3> - -<p>Inserts element <code>value</code> at position <code>pos</code> in <code>table</code>, -shifting up other elements to open space, if necessary. -The default value for <code>pos</code> is <code>n+1</code>, -where <code>n</code> is the size of the table (see <a href="#getn">5.4</a>), -so that a call <code>table.insert(t,x)</code> inserts <code>x</code> at the end -of table <code>t</code>. -This function also updates the size of the table by -calling <code>table.setn(table, n+1)</code>. - -<p><h3><code>table.remove (table [, pos])</code></h3> - -<p>Removes from <code>table</code> the element at position <code>pos</code>, -shifting down other elements to close the space, if necessary. -Returns the value of the removed element. -The default value for <code>pos</code> is <code>n</code>, -where <code>n</code> is the size of the table (see <a href="#getn">5.4</a>), -so that a call <code>table.remove(t)</code> removes the last element -of table <code>t</code>. -This function also updates the size of the table by -calling <code>table.setn(table, n-1)</code>. - -<p><h3><code>table.setn (table, n)</code></h3> - -<p>Updates the size of a table. -If the table has a field <code>"n"</code> with a numerical value, -that value is changed to the given <code>n</code>. -Otherwise, it updates an internal state -so that subsequent calls to <code>table.getn(table)</code> return <code>n</code>. - -<p><a name="mathlib"><a name="5.5"><h2>5.5 - Mathematical Functions</h2></a></a> - -<p>This library is an interface to most of the functions of the -standard C math library. -(Some have slightly different names.) -It provides all its functions inside the table <code>math</code>. -In addition, -it registers the global <code>__pow</code> -for the binary exponentiation operator <code>^</code>, -so that <code>x^y</code> returns <em>x<sup>y</sup></em>. -The library provides the following functions: - - - - - - - - - -<PRE> - math.abs math.acos math.asin math.atan math.atan2 - math.ceil math.cos math.deg math.exp math.floor - math.log math.log10 math.max math.min math.mod - math.pow math.rad math.sin math.sqrt math.tan - math.frexp math.ldexp math.random math.randomseed -</PRE> -plus a variable <code>math.pi</code>. -Most of them -are only interfaces to the corresponding functions in the C library. -All trigonometric functions work in radians -(previous versions of Lua used degrees). -The functions <code>math.deg</code> and <code>math.rad</code> convert -between radians and degrees. - -<p>The function <code>math.max</code> returns the maximum -value of its numeric arguments. -Similarly, <code>math.min</code> computes the minimum. -Both can be used with 1, 2, or more arguments. - -<p>The functions <code>math.random</code> and <code>math.randomseed</code> -are interfaces to the simple random generator functions -<code>rand</code> and <code>srand</code> that are provided by ANSI C. -(No guarantees can be given for their statistical properties.) -When called without arguments, -<code>math.random</code> returns a pseudo-random real number -in the range <em>[0,1)</em>. -When called with a number <em>n</em>, -<code>math.random</code> returns a pseudo-random integer in the range <em>[1,n]</em>. -When called with two arguments, <em>l</em> and <em>u</em>, -<code>math.random</code> returns a pseudo-random integer in the range <em>[l,u]</em>. -The <code>math.randomseed</code> function sets a "seed" -for the pseudo-random generator: -Equal seeds produce equal sequences of numbers. - -<p><a name="libio"><a name="5.6"><h2>5.6 - Input and Output Facilities</h2></a></a> - -<p>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 those default files. -The second style uses explicit file descriptors. - -<p>When using implicit file descriptors, -all operations are supplied by table <code>io</code>. -When using explicit file descriptors, -the operation <code>io.open</code> returns a file descriptor -and then all operations are supplied as methods by the file descriptor. - -<p>The table <code>io</code> also provides -three predefined file descriptors with their usual meanings from C: -<code>io.stdin</code>, <code>io.stdout</code>, and <code>io.stderr</code>. - -<p>A file handle is a userdata containing the file stream (<code>FILE*</code>), -with a distinctive metatable created by the I/O library. - -<p>Unless otherwise stated, -all I/O functions return <B>nil</B> on failure -(plus an error message as a second result) -and some value different from <B>nil</B> on success. - -<p><h3><code>io.close ([file])</code></h3> - -<p>Equivalent to <code>file:close()</code>. -Without a <code>file</code>, closes the default output file. - -<p><h3><code>io.flush ()</code></h3> - -<p>Equivalent to <code>file:flush</code> over the default output file. - -<p><h3><code>io.input ([file])</code></h3> - -<p>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 that file handle as the default input file. -When called without parameters, -it returns the current default input file. - -<p>In case of errors this function raises the error, -instead of returning an error code. - -<p><h3><code>io.lines ([filename])</code></h3> - -<p>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 -<PRE> - for line in io.lines(filename) do ... end -</PRE> -will iterate over all lines of the file. -When the iterator function detects the end of file, -it returns <B>nil</B> (to finish the loop) and automatically closes the file. - -<p>The call <code>io.lines()</code> (without a file name) is equivalent -to <code>io.input():lines()</code>, that is, it iterates over the -lines of the default input file. - -<p><h3><code>io.open (filename [, mode])</code></h3> - -<p>This function opens a file, -in the mode specified in the string <code>mode</code>. -It returns a new file handle, -or, in case of errors, <B>nil</B> plus an error message. - -<p>The <code>mode</code> string can be any of the following: -<ul> -<li><b>"r"</b> read mode (the default); -<li><b>"w"</b> write mode; -<li><b>"a"</b> append mode; -<li><b>"r+"</b> update mode, all previous data is preserved; -<li><b>"w+"</b> update mode, all previous data is erased; -<li><b>"a+"</b> append update mode, previous data is preserved, - writing is only allowed at the end of file. -</ul> -The <code>mode</code> string may also have a <code>b</code> 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 <code>fopen</code>. - -<p><h3><code>io.output ([file])</code></h3> - -<p>Similar to <code>io.input</code>, but operates over the default output file. - -<p><h3><code>io.read (format1, ...)</code></h3> - -<p>Equivalent to <code>io.input():read</code>. - -<p><h3><code>io.tmpfile ()</code></h3> - -<p>Returns a handle for a temporary file. -This file is open in update mode -and it is automatically removed when the program ends. - -<p><h3><code>io.type (obj)</code></h3> - -<p>Checks whether <code>obj</code> is a valid file handle. -Returns the string <code>"file"</code> if <code>obj</code> is an open file handle, -<code>"closed file"</code> if <code>obj</code> is a closed file handle, -and <B>nil</B> if <code>obj</code> is not a file handle. - -<p><h3><code>io.write (value1, ...)</code></h3> - -<p>Equivalent to <code>io.output():write</code>. - -<p><h3><code>file:close ()</code></h3> - -<p>Closes <code>file</code>. - -<p><h3><code>file:flush ()</code></h3> - -<p>Saves any written data to <code>file</code>. - -<p><h3><code>file:lines ()</code></h3> - -<p>Returns an iterator function that, -each time it is called, -returns a new line from the file. -Therefore, the construction -<PRE> - for line in file:lines() do ... end -</PRE> -will iterate over all lines of the file. -(Unlike <code>io.lines</code>, this function does not close the file -when the loop ends.) - -<p><h3><code>file:read (format1, ...)</code></h3> - -<p>Reads the file <code>file</code>, -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 <B>nil</B> 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). - -<p>The available formats are -<ul> -<li><b>"*n"</b> reads a number; -this is the only format that returns a number instead of a string. -<li><b>"*a"</b> reads the whole file, starting at the current position. -On end of file, it returns the empty string. -<li><b>"*l"</b> reads the next line (skipping the end of line), -returning <B>nil</B> on end of file. -This is the default format. -<li><b><em>number</em></b> reads a string with up to that number of characters, -returning <B>nil</B> on end of file. -If number is zero, -it reads nothing and returns an empty string, -or <B>nil</B> on end of file. -</ul> - -<p><h3><code>file:seek ([whence] [, offset])</code></h3> - -<p>Sets and gets the file position, -measured from the beginning of the file, -to the position given by <code>offset</code> plus a base -specified by the string <code>whence</code>, as follows: -<ul> -<li><b>"set"</b> base is position 0 (beginning of the file); -<li><b>"cur"</b> base is current position; -<li><b>"end"</b> base is end of file; -</ul> -In case of success, function <code>seek</code> returns the final file position, -measured in bytes from the beginning of the file. -If this function fails, it returns <B>nil</B>, -plus a string describing the error. - -<p>The default value for <code>whence</code> is <code>"cur"</code>, -and for <code>offset</code> is 0. -Therefore, the call <code>file:seek()</code> returns the current -file position, without changing it; -the call <code>file:seek("set")</code> sets the position to the -beginning of the file (and returns 0); -and the call <code>file:seek("end")</code> sets the position to the -end of the file, and returns its size. - -<p><h3><code>file:write (value1, ...)</code></h3> - -<p>Writes the value of each of its arguments to -the filehandle <code>file</code>. -The arguments must be strings or numbers. -To write other values, -use <code>tostring</code> or <code>string.format</code> before <code>write</code>. - -<p><a name="libiosys"><a name="5.7"><h2>5.7 - Operating System Facilities</h2></a></a> - -<p>This library is implemented through table <code>os</code>. - -<p><h3><code>os.clock ()</code></h3> - -<p>Returns an approximation of the amount of CPU time -used by the program, in seconds. - -<p><h3><code>os.date ([format [, time]])</code></h3> - -<p>Returns a string or a table containing date and time, -formatted according to the given string <code>format</code>. - -<p>If the <code>time</code> argument is present, -this is the time to be formatted -(see the <code>os.time</code> function for a description of this value). -Otherwise, <code>date</code> formats the current time. - -<p>If <code>format</code> starts with `<code>!</code>´, -then the date is formatted in Coordinated Universal Time. -After that optional character, -if <code>format</code> is <code>*t</code>, -then <code>date</code> returns a table with the following fields: -<code>year</code> (four digits), <code>month</code> (1--12), <code>day</code> (1--31), -<code>hour</code> (0--23), <code>min</code> (0--59), <code>sec</code> (0--61), -<code>wday</code> (weekday, Sunday is 1), -<code>yday</code> (day of the year), -and <code>isdst</code> (daylight saving flag, a boolean). - -<p>If <code>format</code> is not <code>*t</code>, -then <code>date</code> returns the date as a string, -formatted according with the same rules as the C function <code>strftime</code>. - -<p>When called without arguments, -<code>date</code> returns a reasonable date and time representation that depends on -the host system and on the current locale -(that is, <code>os.date()</code> is equivalent to <code>os.date("%c")</code>). - -<p><h3><code>os.difftime (t2, t1)</code></h3> - -<p>Returns the number of seconds from time <code>t1</code> to time <code>t2</code>. -In Posix, Windows, and some other systems, -this value is exactly <code>t2</code><em>-</em><code>t1</code>. - -<p><h3><code>os.execute (command)</code></h3> - -<p>This function is equivalent to the C function <code>system</code>. -It passes <code>command</code> to be executed by an operating system shell. -It returns a status code, which is system-dependent. - -<p><h3><code>os.exit ([code])</code></h3> - -<p>Calls the C function <code>exit</code>, -with an optional <code>code</code>, -to terminate the host program. -The default value for <code>code</code> is the success code. - -<p><h3><code>os.getenv (varname)</code></h3> - -<p>Returns the value of the process environment variable <code>varname</code>, -or <B>nil</B> if the variable is not defined. - -<p><h3><code>os.remove (filename)</code></h3> - -<p>Deletes the file with the given name. -If this function fails, it returns <B>nil</B>, -plus a string describing the error. - -<p><h3><code>os.rename (oldname, newname)</code></h3> - -<p>Renames file named <code>oldname</code> to <code>newname</code>. -If this function fails, it returns <B>nil</B>, -plus a string describing the error. - -<p><h3><code>os.setlocale (locale [, category])</code></h3> - -<p>Sets the current locale of the program. -<code>locale</code> is a string specifying a locale; -<code>category</code> is an optional string describing which category to change: -<code>"all"</code>, <code>"collate"</code>, <code>"ctype"</code>, -<code>"monetary"</code>, <code>"numeric"</code>, or <code>"time"</code>; -the default category is <code>"all"</code>. -The function returns the name of the new locale, -or <B>nil</B> if the request cannot be honored. - -<p><h3><code>os.time ([table])</code></h3> - -<p>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 <code>year</code>, <code>month</code>, and <code>day</code>, -and may have fields <code>hour</code>, <code>min</code>, <code>sec</code>, and <code>isdst</code> -(for a description of these fields, see the <code>os.date</code> function). - -<p>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 <code>time</code> can be used only as an argument to -<code>date</code> and <code>difftime</code>. - -<p><h3><code>os.tmpname ()</code></h3> - -<p>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 removed when no longer needed. - -<p>This function is equivalent to the <code>tmpnam</code> C function, -and many people (and even some compilers!) advise against its use, -because between the time you call this function -and the time you open the file, -it is possible for another process -to create a file with the same name. - -<p><a name="5.8"><h2>5.8 - The Reflexive Debug Interface</h2></a> - -<p>The <code>debug</code> 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, <code>setlocal</code> and <code>getlocal</code> -violate the privacy of local variables -and therefore can compromise some otherwise secure code. - -<p>All functions in this library are provided -inside a <code>debug</code> table. - -<p><h3><code>debug.debug ()</code></h3> - -<p>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 <code>cont</code> finishes this function, -so that the caller continues its execution. - -<p>Note that commands for <code>debug.debug</code> are not lexically nested -with any function, so they have no direct access to local variables. - -<p><h3><code>debug.gethook ()</code></h3> - -<p>Returns the current hook settings, as three values: -the current hook function, the current hook mask, -and the current hook count (as set by the <code>debug.sethook</code> function). - -<p><h3><code>debug.getinfo (function [, what])</code></h3> - -<p>This function returns a table with information about a function. -You can give the function directly, -or you can give a number as the value of <code>function</code>, -which means the function running at level <code>function</code> of the call stack: -Level 0 is the current function (<code>getinfo</code> itself); -level 1 is the function that called <code>getinfo</code>; -and so on. -If <code>function</code> is a number larger than the number of active functions, -then <code>getinfo</code> returns <B>nil</B>. - -<p>The returned table contains all the fields returned by <code>lua_getinfo</code>, -with the string <code>what</code> describing which fields to fill in. -The default for <code>what</code> is to get all information available. -If present, -the option `<code>f</code>´ -adds a field named <code>func</code> with the function itself. - -<p>For instance, the expression <code>debug.getinfo(1,"n").name</code> returns -the name of the current function, if a reasonable name can be found, -and <code>debug.getinfo(print)</code> returns a table with all available information -about the <code>print</code> function. - -<p><h3><code>debug.getlocal (level, local)</code></h3> - -<p>This function returns the name and the value of the local variable -with index <code>local</code> of the function at level <code>level</code> of the stack. -(The first parameter or local variable has index 1, and so on, -until the last active local variable.) -The function returns <B>nil</B> if there is no local -variable with the given index, -and raises an error when called with a <code>level</code> out of range. -(You can call <code>debug.getinfo</code> to check whether the level is valid.) - -<p><h3><code>debug.getupvalue (func, up)</code></h3> - -<p>This function returns the name and the value of the upvalue -with index <code>up</code> of the function <code>func</code>. -The function returns <B>nil</B> if there is no upvalue with the given index. - -<p><h3><code>debug.setlocal (level, local, value)</code></h3> - -<p>This function assigns the value <code>value</code> to the local variable -with index <code>local</code> of the function at level <code>level</code> of the stack. -The function returns <B>nil</B> if there is no local -variable with the given index, -and raises an error when called with a <code>level</code> out of range. -(You can call <code>getinfo</code> to check whether the level is valid.) - -<p><h3><code>debug.setupvalue (func, up, value)</code></h3> - -<p>This function assigns the value <code>value</code> to the upvalue -with index <code>up</code> of the function <code>func</code>. -The function returns <B>nil</B> if there is no upvalue -with the given index. - -<p><h3><code>debug.sethook (hook, mask [, count])</code></h3> - - -<p>Sets the given function as a hook. -The string <code>mask</code> and the number <code>count</code> describe -when the hook will be called. -The string mask may have the following characters, -with the given meaning: -<ul> -<li><b><code>"c"</code></b> The hook is called every time Lua calls a function; -<li><b><code>"r"</code></b> The hook is called every time Lua returns from a function; -<li><b><code>"l"</code></b> The hook is called every time Lua enters a new line of code. -</ul> -With a <code>count</code> different from zero, -the hook is called after every <code>count</code> instructions. - -<p>When called without arguments, -the <code>debug.sethook</code> function turns off the hook. - -<p>When the hook is called, its first parameter is always a string -describing the event that triggered its call: -<code>"call"</code>, <code>"return"</code> (or <code>"tail return"</code>), -<code>"line"</code>, and <code>"count"</code>. -Moreover, for line events, -it also gets as its second parameter the new line number. -Inside a hook, -you can call <code>getinfo</code> with level 2 to get more information about -the running function -(level 0 is the <code>getinfo</code> function, -and level 1 is the hook function), -unless the event is <code>"tail return"</code>. -In this case, Lua is only simulating the return, -and a call to <code>getinfo</code> will return invalid data. - -<p><h3><code>debug.traceback ([message])</code></h3> - -<p>Returns a string with a traceback of the call stack. -An optional <code>message</code> string is appended -at the beginning of the traceback. -This function is typically used with <code>xpcall</code> to produce -better error messages. - -<p> -<a name="lua-sa"><a name="6"><h1>6 - Lua Stand-alone</h1></a></a> - -<p>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 <code>lua</code>, -is provided with the standard distribution. -The stand-alone interpreter includes -all standard libraries plus the reflexive debug interface. -Its usage is: -<PRE> - lua [options] [script [args]] -</PRE> -The options are: -<ul> -<li><b><code>-</code> </b> executes <code>stdin</code> as a file; -<li><b><code>-e</code> <em>stat</em></b> executes string <em>stat</em>; -<li><b><code>-l</code> <em>file</em></b> "requires" <em>file</em>; -<li><b><code>-i</code></b> enters interactive mode after running <em>script</em>; -<li><b><code>-v</code></b> prints version information; -<li><b><code>--</code></b> stop handling options. -</ul> -After handling its options, <code>lua</code> runs the given <em>script</em>, -passing to it the given <em>args</em>. -When called without arguments, -<code>lua</code> behaves as <code>lua -v -i</code> when <code>stdin</code> is a terminal, -and as <code>lua -</code> otherwise. - -<p>Before running any argument, -the interpreter checks for an environment variable <code>LUA_INIT</code>. -If its format is @<em>filename</em>, -then lua executes the file. -Otherwise, lua executes the string itself. - -<p>All options are handled in order, except <code>-i</code>. -For instance, an invocation like -<PRE> - $ lua -e'a=1' -e 'print(a)' script.lua -</PRE> -will first set <code>a</code> to 1, then print <code>a</code>, -and finally run the file <code>script.lua</code>. -(Here, <code>$</code> is the shell prompt. Your prompt may be different.) - -<p>Before starting to run the script, -<code>lua</code> collects all arguments in the command line -in a global table called <code>arg</code>. -The script name is stored in index 0, -the first argument after the script name goes to index 1, -and so on. -The field <code>n</code> gets the number of arguments after the script name. -Any arguments before the script name -(that is, the interpreter name plus the options) -go to negative indices. -For instance, in the call -<PRE> - $ lua -la.lua b.lua t1 t2 -</PRE> -the interpreter first runs the file <code>a.lua</code>, -then creates a table -<PRE> - arg = { [-2] = "lua", [-1] = "-la.lua", [0] = "b.lua", - [1] = "t1", [2] = "t2"; n = 2 } -</PRE> -and finally runs the file <code>b.lua</code>. - -<p>In interactive mode, -if you write an incomplete statement, -the interpreter waits for its completion. - -<p>If the global variable <code>_PROMPT</code> is defined as a string, -then its value is used as the prompt. -Therefore, the prompt can be changed directly on the command line: -<PRE> - $ lua -e"_PROMPT='myprompt> '" -i -</PRE> -(the outer pair of quotes is for the shell, -the inner is for Lua), -or in any Lua programs by assigning to <code>_PROMPT</code>. -Note the use of <code>-i</code> to enter interactive mode; otherwise, -the program would end just after the assignment to <code>_PROMPT</code>. - -<p>In Unix systems, Lua scripts can be made into executable programs -by using <code>chmod +x</code> and the <code>#!</code> form, -as in -<PRE> -#!/usr/local/bin/lua -</PRE> -(Of course, -the location of the Lua interpreter may be different in your machine. -If <code>lua</code> is in your <code>PATH</code>, -then -<PRE> -#!/usr/bin/env lua -</PRE> -is a more portable solution.) - -<p> -<h1>Acknowledgments</h1> - -<p>The Lua team is grateful to <a href="http://www.tecgraf.puc-rio.br">Tecgraf</a> for its continued support to Lua. -We thank everyone at <a href="http://www.tecgraf.puc-rio.br">Tecgraf</a>, -specially the head of the group, Marcelo Gattass. -At the risk of omitting several names, -we also thank the following individuals for supporting, -contributing to, and spreading the word about Lua: -Alan Watson. -André Clinio, -André Costa, -Antonio Scuri, -Asko Kauppi, -Bret Mogilefsky, -Cameron Laird, -Carlos Cassino, -Carlos Henrique Levy, -Claudio Terra, -David Jeske, -Ed Ferguson, -Edgar Toernig, -Erik Hougaard, -Jim Mathies, -John Belmonte, -John Passaniti, -John Roll, -Jon Erickson, -Jon Kleiser, -Mark Ian Barlow, -Nick Trout, -Noemi Rodriguez, -Norman Ramsey, -Philippe Lhoste, -Renata Ratton, -Renato Borges, -Renato Cerqueira, -Reuben Thomas, -Stephan Herrmann, -Steve Dekorte, -Thatcher Ulrich, -Tomás Gorham, -Vincent Penquerc'h. -Thank you! - -<p><hr> - -<p><h1>Incompatibilities with Previous Versions</h1> - - -<p>Lua 5.0 is a major release. -There are several incompatibilities with its previous version, Lua 4.0. - -<p><h2>Incompatibilities with version 4.0</h2> - -<p><h3>Changes in the Language</h3> -<ul> - -<p><li> -The whole tag-method scheme was replaced by metatables. - -<p><li> -Function calls written between parentheses result in exactly one value. - -<p><li> -A function call as the last expression in a list constructor -(like <code>{a,b,f()}</code>) has all its return values inserted in the list. - -<p><li> -The precedence of <b>or</b> is smaller than the precedence of <b>and</b>. - -<p><li> -<b>in</b>, <b>false</b>, and <b>true</b> are reserved words. - -<p><li> -The old construction <code>for k,v in t</code>, where <code>t</code> is a table, -is deprecated (although it is still supported). -Use <code>for k,v in pairs(t)</code> instead. - -<p><li> -When a literal string of the form <code>[[...]]</code> starts with a newline, -this newline is ignored. - -<p> - -<p><li> Upvalues in the form <code>%var</code> are obsolete; -use external local variables instead. - -<p></ul> - -<p><h3>Changes in the Libraries</h3> -<ul> - -<p><li> -Most library functions now are defined inside tables. -There is a compatibility script (<code>compat.lua</code>) that -redefine most of them as global names. - -<p><li> -In the math library, angles are expressed in radians. -With the compatibility script (<code>compat.lua</code>), -functions still work in degrees. - -<p><li> -The <code>call</code> function is deprecated. -Use <code>f(unpack(tab))</code> instead of <code>call(f, tab)</code> -for unprotected calls, -or the new <code>pcall</code> function for protected calls. - -<p><li> -<code>dofile</code> do not handle errors, but simply propagates them. - -<p><li> -<code>dostring</code> is deprecated. Use <code>loadstring</code> instead. - -<p><li> -The <code>read</code> option <code>*w</code> is obsolete. - -<p><li> -The <code>format</code> option <code>%n$</code> is obsolete. - -<p></ul> - -<p><h3>Changes in the API</h3> -<ul> - -<p><li> -<code>lua_open</code> does not have a stack size as its argument -(stacks are dynamic). - -<p><li> -<code>lua_pushuserdata</code> is deprecated. -Use <code>lua_newuserdata</code> or <code>lua_pushlightuserdata</code> instead. - -<p></ul> - -<p> - -<a name="BNF"><h1>The Complete Syntax of Lua</h1></a> - - -<p> - -<p><pre> - -<p> chunk ::= {stat [`<b>;</b>´]} - -<p> block ::= chunk - -<p> stat ::= varlist1 `<b>=</b>´ explist1 | functioncall | <b>do</b> block <b>end</b> | <b>while</b> exp <b>do</b> block <b>end</b> | <b>repeat</b> block <b>until</b> exp | <b>if</b> exp <b>then</b> block {<b>elseif</b> exp <b>then</b> block} [<b>else</b> block] <b>end</b> | <b>return</b> [explist1] | <b>break</b> | <b>for</b> Name `<b>=</b>´ exp `<b>,</b>´ exp [`<b>,</b>´ exp] <b>do</b> block <b>end</b> | <b>for</b> Name {`<b>,</b>´ Name} <b>in</b> explist1 <b>do</b> block <b>end</b> | <b>function</b> funcname funcbody | <b>local</b> <b>function</b> Name funcbody | <b>local</b> namelist [init] - -<p> funcname ::= Name {`<b>.</b>´ Name} [`<b>:</b>´ Name] - -<p> varlist1 ::= var {`<b>,</b>´ var} - -<p> var ::= Name | prefixexp `<b>[</b>´ exp `<b>]</b>´ | prefixexp `<b>.</b>´ Name - -<p> namelist ::= Name {`<b>,</b>´ Name} - -<p> init ::= `<b>=</b>´ explist1 - -<p> explist1 ::= {exp `<b>,</b>´} exp - -<p> exp ::= <b>nil</b> | <b>false</b> | <b>true</b> | Number | Literal | function | prefixexp | tableconstructor | exp binop exp | unop exp - -<p> prefixexp ::= var | functioncall | `<b>(</b>´ exp `<b>)</b>´ - -<p> functioncall ::= prefixexp args | prefixexp `<b>:</b>´ Name args - -<p> args ::= `<b>(</b>´ [explist1] `<b>)</b>´ | tableconstructor | Literal - -<p> function ::= <b>function</b> funcbody - -<p> funcbody ::= `<b>(</b>´ [parlist1] `<b>)</b>´ block <b>end</b> - -<p> parlist1 ::= Name {`<b>,</b>´ Name} [`<b>,</b>´ `<b>...</b>´] | `<b>...</b>´ - -<p> tableconstructor ::= `<b>{</b>´ [fieldlist] `<b>}</b>´ - fieldlist ::= field {fieldsep field} [fieldsep] - field ::= `<b>[</b>´ exp `<b>]</b>´ `<b>=</b>´ exp | name `<b>=</b>´ exp | exp - fieldsep ::= `<b>,</b>´ | `<b>;</b>´ - -<p> binop ::= `<b>+</b>´ | `<b>-</b>´ | `<b>*</b>´ | `<b>/</b>´ | `<b>^</b>´ | `<b>..</b>´ | `<b><</b>´ | `<b><=</b>´ | `<b>></b>´ | `<b>>=</b>´ | `<b>==</b>´ | `<b>~=</b>´ | <b>and</b> | <b>or</b> - -<p> unop ::= `<b>-</b>´ | <b>not</b> - -<p></pre> - -<p> - -<p> - -<HR> -<SMALL> -Last update: -Tue Nov 25 16:08:37 BRST 2003 -</SMALL> - -</BODY> -</HTML> |