]> git.saurik.com Git - redis.git/blame - deps/lua/doc/manual.html
Sentinel: SENTINEL FAILOVER command implemented.
[redis.git] / deps / lua / doc / manual.html
CommitLineData
21d3294c 1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
2<html>
3
4<head>
5<title>Lua 5.1 Reference Manual</title>
6<link rel="stylesheet" type="text/css" href="lua.css">
7<link rel="stylesheet" type="text/css" href="manual.css">
8<META HTTP-EQUIV="content-type" CONTENT="text/html; charset=iso-8859-1">
9</head>
10
11<body>
12
13<hr>
14<h1>
15<a href="http://www.lua.org/"><img src="logo.gif" alt="" border="0"></a>
16Lua 5.1 Reference Manual
17</h1>
18
19by Roberto Ierusalimschy, Luiz Henrique de Figueiredo, Waldemar Celes
20<p>
21<small>
22Copyright &copy; 2006-2008 Lua.org, PUC-Rio.
23Freely available under the terms of the
24<a href="http://www.lua.org/license.html#5">Lua license</a>.
25</small>
26<hr>
27<p>
28
29<a href="contents.html#contents">contents</A>
30&middot;
31<a href="contents.html#index">index</A>
32
33<!-- ====================================================================== -->
34<p>
35
36<!-- $Id: manual.of,v 1.48 2008/08/18 15:24:20 roberto Exp $ -->
37
38
39
40
41<h1>1 - <a name="1">Introduction</a></h1>
42
43<p>
44Lua is an extension programming language designed to support
45general procedural programming with data description
46facilities.
47It also offers good support for object-oriented programming,
48functional programming, and data-driven programming.
49Lua is intended to be used as a powerful, light-weight
50scripting language for any program that needs one.
51Lua is implemented as a library, written in <em>clean</em> C
52(that is, in the common subset of ANSI&nbsp;C and C++).
53
54
55<p>
56Being an extension language, Lua has no notion of a "main" program:
57it only works <em>embedded</em> in a host client,
58called the <em>embedding program</em> or simply the <em>host</em>.
59This host program can invoke functions to execute a piece of Lua code,
60can write and read Lua variables,
61and can register C&nbsp;functions to be called by Lua code.
62Through the use of C&nbsp;functions, Lua can be augmented to cope with
63a wide range of different domains,
64thus creating customized programming languages sharing a syntactical framework.
65The Lua distribution includes a sample host program called <code>lua</code>,
66which uses the Lua library to offer a complete, stand-alone Lua interpreter.
67
68
69<p>
70Lua is free software,
71and is provided as usual with no guarantees,
72as stated in its license.
73The implementation described in this manual is available
74at Lua's official web site, <code>www.lua.org</code>.
75
76
77<p>
78Like any other reference manual,
79this document is dry in places.
80For a discussion of the decisions behind the design of Lua,
81see the technical papers available at Lua's web site.
82For a detailed introduction to programming in Lua,
83see Roberto's book, <em>Programming in Lua (Second Edition)</em>.
84
85
86
87<h1>2 - <a name="2">The Language</a></h1>
88
89<p>
90This section describes the lexis, the syntax, and the semantics of Lua.
91In other words,
92this section describes
93which tokens are valid,
94how they can be combined,
95and what their combinations mean.
96
97
98<p>
99The language constructs will be explained using the usual extended BNF notation,
100in which
101{<em>a</em>}&nbsp;means&nbsp;0 or more <em>a</em>'s, and
102[<em>a</em>]&nbsp;means an optional <em>a</em>.
103Non-terminals are shown like non-terminal,
104keywords are shown like <b>kword</b>,
105and other terminal symbols are shown like `<b>=</b>&acute;.
106The complete syntax of Lua can be found in <a href="#8">&sect;8</a>
107at the end of this manual.
108
109
110
111<h2>2.1 - <a name="2.1">Lexical Conventions</a></h2>
112
113<p>
114<em>Names</em>
115(also called <em>identifiers</em>)
116in Lua can be any string of letters,
117digits, and underscores,
118not beginning with a digit.
119This coincides with the definition of names in most languages.
120(The definition of letter depends on the current locale:
121any character considered alphabetic by the current locale
122can be used in an identifier.)
123Identifiers are used to name variables and table fields.
124
125
126<p>
127The following <em>keywords</em> are reserved
128and cannot be used as names:
129
130
131<pre>
132 and break do else elseif
133 end false for function if
134 in local nil not or
135 repeat return then true until while
136</pre>
137
138<p>
139Lua is a case-sensitive language:
140<code>and</code> is a reserved word, but <code>And</code> and <code>AND</code>
141are two different, valid names.
142As a convention, names starting with an underscore followed by
143uppercase letters (such as <a href="#pdf-_VERSION"><code>_VERSION</code></a>)
144are reserved for internal global variables used by Lua.
145
146
147<p>
148The following strings denote other tokens:
149
150<pre>
151 + - * / % ^ #
152 == ~= &lt;= &gt;= &lt; &gt; =
153 ( ) { } [ ]
154 ; : , . .. ...
155</pre>
156
157<p>
158<em>Literal strings</em>
159can be delimited by matching single or double quotes,
160and can contain the following C-like escape sequences:
161'<code>\a</code>' (bell),
162'<code>\b</code>' (backspace),
163'<code>\f</code>' (form feed),
164'<code>\n</code>' (newline),
165'<code>\r</code>' (carriage return),
166'<code>\t</code>' (horizontal tab),
167'<code>\v</code>' (vertical tab),
168'<code>\\</code>' (backslash),
169'<code>\"</code>' (quotation mark [double quote]),
170and '<code>\'</code>' (apostrophe [single quote]).
171Moreover, a backslash followed by a real newline
172results in a newline in the string.
173A character in a string can also be specified by its numerical value
174using the escape sequence <code>\<em>ddd</em></code>,
175where <em>ddd</em> is a sequence of up to three decimal digits.
176(Note that if a numerical escape is to be followed by a digit,
177it must be expressed using exactly three digits.)
178Strings in Lua can contain any 8-bit value, including embedded zeros,
179which can be specified as '<code>\0</code>'.
180
181
182<p>
183Literal strings can also be defined using a long format
184enclosed by <em>long brackets</em>.
185We define an <em>opening long bracket of level <em>n</em></em> as an opening
186square bracket followed by <em>n</em> equal signs followed by another
187opening square bracket.
188So, an opening long bracket of level&nbsp;0 is written as <code>[[</code>,
189an opening long bracket of level&nbsp;1 is written as <code>[=[</code>,
190and so on.
191A <em>closing long bracket</em> is defined similarly;
192for instance, a closing long bracket of level&nbsp;4 is written as <code>]====]</code>.
193A long string starts with an opening long bracket of any level and
194ends at the first closing long bracket of the same level.
195Literals in this bracketed form can run for several lines,
196do not interpret any escape sequences,
197and ignore long brackets of any other level.
198They can contain anything except a closing bracket of the proper level.
199
200
201<p>
202For convenience,
203when the opening long bracket is immediately followed by a newline,
204the newline is not included in the string.
205As an example, in a system using ASCII
206(in which '<code>a</code>' is coded as&nbsp;97,
207newline is coded as&nbsp;10, and '<code>1</code>' is coded as&nbsp;49),
208the five literal strings below denote the same string:
209
210<pre>
211 a = 'alo\n123"'
212 a = "alo\n123\""
213 a = '\97lo\10\04923"'
214 a = [[alo
215 123"]]
216 a = [==[
217 alo
218 123"]==]
219</pre>
220
221<p>
222A <em>numerical constant</em> can be written with an optional decimal part
223and an optional decimal exponent.
224Lua also accepts integer hexadecimal constants,
225by prefixing them with <code>0x</code>.
226Examples of valid numerical constants are
227
228<pre>
229 3 3.0 3.1416 314.16e-2 0.31416E1 0xff 0x56
230</pre>
231
232<p>
233A <em>comment</em> starts with a double hyphen (<code>--</code>)
234anywhere outside a string.
235If the text immediately after <code>--</code> is not an opening long bracket,
236the comment is a <em>short comment</em>,
237which runs until the end of the line.
238Otherwise, it is a <em>long comment</em>,
239which runs until the corresponding closing long bracket.
240Long comments are frequently used to disable code temporarily.
241
242
243
244
245
246<h2>2.2 - <a name="2.2">Values and Types</a></h2>
247
248<p>
249Lua is a <em>dynamically typed language</em>.
250This means that
251variables do not have types; only values do.
252There are no type definitions in the language.
253All values carry their own type.
254
255
256<p>
257All values in Lua are <em>first-class values</em>.
258This means that all values can be stored in variables,
259passed as arguments to other functions, and returned as results.
260
261
262<p>
263There are eight basic types in Lua:
264<em>nil</em>, <em>boolean</em>, <em>number</em>,
265<em>string</em>, <em>function</em>, <em>userdata</em>,
266<em>thread</em>, and <em>table</em>.
267<em>Nil</em> is the type of the value <b>nil</b>,
268whose main property is to be different from any other value;
269it usually represents the absence of a useful value.
270<em>Boolean</em> is the type of the values <b>false</b> and <b>true</b>.
271Both <b>nil</b> and <b>false</b> make a condition false;
272any other value makes it true.
273<em>Number</em> represents real (double-precision floating-point) numbers.
274(It is easy to build Lua interpreters that use other
275internal representations for numbers,
276such as single-precision float or long integers;
277see file <code>luaconf.h</code>.)
278<em>String</em> represents arrays of characters.
279
280Lua is 8-bit clean:
281strings can contain any 8-bit character,
282including embedded zeros ('<code>\0</code>') (see <a href="#2.1">&sect;2.1</a>).
283
284
285<p>
286Lua can call (and manipulate) functions written in Lua and
287functions written in C
288(see <a href="#2.5.8">&sect;2.5.8</a>).
289
290
291<p>
292The type <em>userdata</em> is provided to allow arbitrary C&nbsp;data to
293be stored in Lua variables.
294This type corresponds to a block of raw memory
295and has no pre-defined operations in Lua,
296except assignment and identity test.
297However, by using <em>metatables</em>,
298the programmer can define operations for userdata values
299(see <a href="#2.8">&sect;2.8</a>).
300Userdata values cannot be created or modified in Lua,
301only through the C&nbsp;API.
302This guarantees the integrity of data owned by the host program.
303
304
305<p>
306The type <em>thread</em> represents independent threads of execution
307and it is used to implement coroutines (see <a href="#2.11">&sect;2.11</a>).
308Do not confuse Lua threads with operating-system threads.
309Lua supports coroutines on all systems,
310even those that do not support threads.
311
312
313<p>
314The type <em>table</em> implements associative arrays,
315that is, arrays that can be indexed not only with numbers,
316but with any value (except <b>nil</b>).
317Tables can be <em>heterogeneous</em>;
318that is, they can contain values of all types (except <b>nil</b>).
319Tables are the sole data structuring mechanism in Lua;
320they can be used to represent ordinary arrays,
321symbol tables, sets, records, graphs, trees, etc.
322To represent records, Lua uses the field name as an index.
323The language supports this representation by
324providing <code>a.name</code> as syntactic sugar for <code>a["name"]</code>.
325There are several convenient ways to create tables in Lua
326(see <a href="#2.5.7">&sect;2.5.7</a>).
327
328
329<p>
330Like indices,
331the value of a table field can be of any type (except <b>nil</b>).
332In particular,
333because functions are first-class values,
334table fields can contain functions.
335Thus tables can also carry <em>methods</em> (see <a href="#2.5.9">&sect;2.5.9</a>).
336
337
338<p>
339Tables, functions, threads, and (full) userdata values are <em>objects</em>:
340variables do not actually <em>contain</em> these values,
341only <em>references</em> to them.
342Assignment, parameter passing, and function returns
343always manipulate references to such values;
344these operations do not imply any kind of copy.
345
346
347<p>
348The library function <a href="#pdf-type"><code>type</code></a> returns a string describing the type
349of a given value.
350
351
352
353<h3>2.2.1 - <a name="2.2.1">Coercion</a></h3>
354
355<p>
356Lua provides automatic conversion between
357string and number values at run time.
358Any arithmetic operation applied to a string tries to convert
359this string to a number, following the usual conversion rules.
360Conversely, whenever a number is used where a string is expected,
361the number is converted to a string, in a reasonable format.
362For complete control over how numbers are converted to strings,
363use the <code>format</code> function from the string library
364(see <a href="#pdf-string.format"><code>string.format</code></a>).
365
366
367
368
369
370
371
372<h2>2.3 - <a name="2.3">Variables</a></h2>
373
374<p>
375Variables are places that store values.
376
377There are three kinds of variables in Lua:
378global variables, local variables, and table fields.
379
380
381<p>
382A single name can denote a global variable or a local variable
383(or a function's formal parameter,
384which is a particular kind of local variable):
385
386<pre>
387 var ::= Name
388</pre><p>
389Name denotes identifiers, as defined in <a href="#2.1">&sect;2.1</a>.
390
391
392<p>
393Any variable is assumed to be global unless explicitly declared
394as a local (see <a href="#2.4.7">&sect;2.4.7</a>).
395Local variables are <em>lexically scoped</em>:
396local variables can be freely accessed by functions
397defined inside their scope (see <a href="#2.6">&sect;2.6</a>).
398
399
400<p>
401Before the first assignment to a variable, its value is <b>nil</b>.
402
403
404<p>
405Square brackets are used to index a table:
406
407<pre>
408 var ::= prefixexp `<b>[</b>&acute; exp `<b>]</b>&acute;
409</pre><p>
410The meaning of accesses to global variables
411and table fields can be changed via metatables.
412An access to an indexed variable <code>t[i]</code> is equivalent to
413a call <code>gettable_event(t,i)</code>.
414(See <a href="#2.8">&sect;2.8</a> for a complete description of the
415<code>gettable_event</code> function.
416This function is not defined or callable in Lua.
417We use it here only for explanatory purposes.)
418
419
420<p>
421The syntax <code>var.Name</code> is just syntactic sugar for
422<code>var["Name"]</code>:
423
424<pre>
425 var ::= prefixexp `<b>.</b>&acute; Name
426</pre>
427
428<p>
429All global variables live as fields in ordinary Lua tables,
430called <em>environment tables</em> or simply
431<em>environments</em> (see <a href="#2.9">&sect;2.9</a>).
432Each function has its own reference to an environment,
433so that all global variables in this function
434will refer to this environment table.
435When a function is created,
436it inherits the environment from the function that created it.
437To get the environment table of a Lua function,
438you call <a href="#pdf-getfenv"><code>getfenv</code></a>.
439To replace it,
440you call <a href="#pdf-setfenv"><code>setfenv</code></a>.
441(You can only manipulate the environment of C&nbsp;functions
442through the debug library; (see <a href="#5.9">&sect;5.9</a>).)
443
444
445<p>
446An access to a global variable <code>x</code>
447is equivalent to <code>_env.x</code>,
448which in turn is equivalent to
449
450<pre>
451 gettable_event(_env, "x")
452</pre><p>
453where <code>_env</code> is the environment of the running function.
454(See <a href="#2.8">&sect;2.8</a> for a complete description of the
455<code>gettable_event</code> function.
456This function is not defined or callable in Lua.
457Similarly, the <code>_env</code> variable is not defined in Lua.
458We use them here only for explanatory purposes.)
459
460
461
462
463
464<h2>2.4 - <a name="2.4">Statements</a></h2>
465
466<p>
467Lua supports an almost conventional set of statements,
468similar to those in Pascal or C.
469This set includes
470assignments, control structures, function calls,
471and variable declarations.
472
473
474
475<h3>2.4.1 - <a name="2.4.1">Chunks</a></h3>
476
477<p>
478The unit of execution of Lua is called a <em>chunk</em>.
479A chunk is simply a sequence of statements,
480which are executed sequentially.
481Each statement can be optionally followed by a semicolon:
482
483<pre>
484 chunk ::= {stat [`<b>;</b>&acute;]}
485</pre><p>
486There are no empty statements and thus '<code>;;</code>' is not legal.
487
488
489<p>
490Lua handles a chunk as the body of an anonymous function
491with a variable number of arguments
492(see <a href="#2.5.9">&sect;2.5.9</a>).
493As such, chunks can define local variables,
494receive arguments, and return values.
495
496
497<p>
498A chunk can be stored in a file or in a string inside the host program.
499To execute a chunk,
500Lua first pre-compiles the chunk into instructions for a virtual machine,
501and then it executes the compiled code
502with an interpreter for the virtual machine.
503
504
505<p>
506Chunks can also be pre-compiled into binary form;
507see program <code>luac</code> for details.
508Programs in source and compiled forms are interchangeable;
509Lua automatically detects the file type and acts accordingly.
510
511
512
513
514
515
516<h3>2.4.2 - <a name="2.4.2">Blocks</a></h3><p>
517A block is a list of statements;
518syntactically, a block is the same as a chunk:
519
520<pre>
521 block ::= chunk
522</pre>
523
524<p>
525A block can be explicitly delimited to produce a single statement:
526
527<pre>
528 stat ::= <b>do</b> block <b>end</b>
529</pre><p>
530Explicit blocks are useful
531to control the scope of variable declarations.
532Explicit blocks are also sometimes used to
533add a <b>return</b> or <b>break</b> statement in the middle
534of another block (see <a href="#2.4.4">&sect;2.4.4</a>).
535
536
537
538
539
540<h3>2.4.3 - <a name="2.4.3">Assignment</a></h3>
541
542<p>
543Lua allows multiple assignments.
544Therefore, the syntax for assignment
545defines a list of variables on the left side
546and a list of expressions on the right side.
547The elements in both lists are separated by commas:
548
549<pre>
550 stat ::= varlist `<b>=</b>&acute; explist
551 varlist ::= var {`<b>,</b>&acute; var}
552 explist ::= exp {`<b>,</b>&acute; exp}
553</pre><p>
554Expressions are discussed in <a href="#2.5">&sect;2.5</a>.
555
556
557<p>
558Before the assignment,
559the list of values is <em>adjusted</em> to the length of
560the list of variables.
561If there are more values than needed,
562the excess values are thrown away.
563If there are fewer values than needed,
564the list is extended with as many <b>nil</b>'s as needed.
565If the list of expressions ends with a function call,
566then all values returned by that call enter the list of values,
567before the adjustment
568(except when the call is enclosed in parentheses; see <a href="#2.5">&sect;2.5</a>).
569
570
571<p>
572The assignment statement first evaluates all its expressions
573and only then are the assignments performed.
574Thus the code
575
576<pre>
577 i = 3
578 i, a[i] = i+1, 20
579</pre><p>
580sets <code>a[3]</code> to 20, without affecting <code>a[4]</code>
581because the <code>i</code> in <code>a[i]</code> is evaluated (to 3)
582before it is assigned&nbsp;4.
583Similarly, the line
584
585<pre>
586 x, y = y, x
587</pre><p>
588exchanges the values of <code>x</code> and <code>y</code>,
589and
590
591<pre>
592 x, y, z = y, z, x
593</pre><p>
594cyclically permutes the values of <code>x</code>, <code>y</code>, and <code>z</code>.
595
596
597<p>
598The meaning of assignments to global variables
599and table fields can be changed via metatables.
600An assignment to an indexed variable <code>t[i] = val</code> is equivalent to
601<code>settable_event(t,i,val)</code>.
602(See <a href="#2.8">&sect;2.8</a> for a complete description of the
603<code>settable_event</code> function.
604This function is not defined or callable in Lua.
605We use it here only for explanatory purposes.)
606
607
608<p>
609An assignment to a global variable <code>x = val</code>
610is equivalent to the assignment
611<code>_env.x = val</code>,
612which in turn is equivalent to
613
614<pre>
615 settable_event(_env, "x", val)
616</pre><p>
617where <code>_env</code> is the environment of the running function.
618(The <code>_env</code> variable is not defined in Lua.
619We use it here only for explanatory purposes.)
620
621
622
623
624
625<h3>2.4.4 - <a name="2.4.4">Control Structures</a></h3><p>
626The control structures
627<b>if</b>, <b>while</b>, and <b>repeat</b> have the usual meaning and
628familiar syntax:
629
630
631
632
633<pre>
634 stat ::= <b>while</b> exp <b>do</b> block <b>end</b>
635 stat ::= <b>repeat</b> block <b>until</b> exp
636 stat ::= <b>if</b> exp <b>then</b> block {<b>elseif</b> exp <b>then</b> block} [<b>else</b> block] <b>end</b>
637</pre><p>
638Lua also has a <b>for</b> statement, in two flavors (see <a href="#2.4.5">&sect;2.4.5</a>).
639
640
641<p>
642The condition expression of a
643control structure can return any value.
644Both <b>false</b> and <b>nil</b> are considered false.
645All values different from <b>nil</b> and <b>false</b> are considered true
646(in particular, the number 0 and the empty string are also true).
647
648
649<p>
650In the <b>repeat</b>&ndash;<b>until</b> loop,
651the inner block does not end at the <b>until</b> keyword,
652but only after the condition.
653So, the condition can refer to local variables
654declared inside the loop block.
655
656
657<p>
658The <b>return</b> statement is used to return values
659from a function or a chunk (which is just a function).
660
661Functions and chunks can return more than one value,
662and so the syntax for the <b>return</b> statement is
663
664<pre>
665 stat ::= <b>return</b> [explist]
666</pre>
667
668<p>
669The <b>break</b> statement is used to terminate the execution of a
670<b>while</b>, <b>repeat</b>, or <b>for</b> loop,
671skipping to the next statement after the loop:
672
673
674<pre>
675 stat ::= <b>break</b>
676</pre><p>
677A <b>break</b> ends the innermost enclosing loop.
678
679
680<p>
681The <b>return</b> and <b>break</b>
682statements can only be written as the <em>last</em> statement of a block.
683If it is really necessary to <b>return</b> or <b>break</b> in the
684middle of a block,
685then an explicit inner block can be used,
686as in the idioms
687<code>do return end</code> and <code>do break end</code>,
688because now <b>return</b> and <b>break</b> are the last statements in
689their (inner) blocks.
690
691
692
693
694
695<h3>2.4.5 - <a name="2.4.5">For Statement</a></h3>
696
697<p>
698
699The <b>for</b> statement has two forms:
700one numeric and one generic.
701
702
703<p>
704The numeric <b>for</b> loop repeats a block of code while a
705control variable runs through an arithmetic progression.
706It has the following syntax:
707
708<pre>
709 stat ::= <b>for</b> Name `<b>=</b>&acute; exp `<b>,</b>&acute; exp [`<b>,</b>&acute; exp] <b>do</b> block <b>end</b>
710</pre><p>
711The <em>block</em> is repeated for <em>name</em> starting at the value of
712the first <em>exp</em>, until it passes the second <em>exp</em> by steps of the
713third <em>exp</em>.
714More precisely, a <b>for</b> statement like
715
716<pre>
717 for v = <em>e1</em>, <em>e2</em>, <em>e3</em> do <em>block</em> end
718</pre><p>
719is equivalent to the code:
720
721<pre>
722 do
723 local <em>var</em>, <em>limit</em>, <em>step</em> = tonumber(<em>e1</em>), tonumber(<em>e2</em>), tonumber(<em>e3</em>)
724 if not (<em>var</em> and <em>limit</em> and <em>step</em>) then error() end
725 while (<em>step</em> &gt; 0 and <em>var</em> &lt;= <em>limit</em>) or (<em>step</em> &lt;= 0 and <em>var</em> &gt;= <em>limit</em>) do
726 local v = <em>var</em>
727 <em>block</em>
728 <em>var</em> = <em>var</em> + <em>step</em>
729 end
730 end
731</pre><p>
732Note the following:
733
734<ul>
735
736<li>
737All three control expressions are evaluated only once,
738before the loop starts.
739They must all result in numbers.
740</li>
741
742<li>
743<code><em>var</em></code>, <code><em>limit</em></code>, and <code><em>step</em></code> are invisible variables.
744The names shown here are for explanatory purposes only.
745</li>
746
747<li>
748If the third expression (the step) is absent,
749then a step of&nbsp;1 is used.
750</li>
751
752<li>
753You can use <b>break</b> to exit a <b>for</b> loop.
754</li>
755
756<li>
757The loop variable <code>v</code> is local to the loop;
758you cannot use its value after the <b>for</b> ends or is broken.
759If you need this value,
760assign it to another variable before breaking or exiting the loop.
761</li>
762
763</ul>
764
765<p>
766The generic <b>for</b> statement works over functions,
767called <em>iterators</em>.
768On each iteration, the iterator function is called to produce a new value,
769stopping when this new value is <b>nil</b>.
770The generic <b>for</b> loop has the following syntax:
771
772<pre>
773 stat ::= <b>for</b> namelist <b>in</b> explist <b>do</b> block <b>end</b>
774 namelist ::= Name {`<b>,</b>&acute; Name}
775</pre><p>
776A <b>for</b> statement like
777
778<pre>
779 for <em>var_1</em>, &middot;&middot;&middot;, <em>var_n</em> in <em>explist</em> do <em>block</em> end
780</pre><p>
781is equivalent to the code:
782
783<pre>
784 do
785 local <em>f</em>, <em>s</em>, <em>var</em> = <em>explist</em>
786 while true do
787 local <em>var_1</em>, &middot;&middot;&middot;, <em>var_n</em> = <em>f</em>(<em>s</em>, <em>var</em>)
788 <em>var</em> = <em>var_1</em>
789 if <em>var</em> == nil then break end
790 <em>block</em>
791 end
792 end
793</pre><p>
794Note the following:
795
796<ul>
797
798<li>
799<code><em>explist</em></code> is evaluated only once.
800Its results are an <em>iterator</em> function,
801a <em>state</em>,
802and an initial value for the first <em>iterator variable</em>.
803</li>
804
805<li>
806<code><em>f</em></code>, <code><em>s</em></code>, and <code><em>var</em></code> are invisible variables.
807The names are here for explanatory purposes only.
808</li>
809
810<li>
811You can use <b>break</b> to exit a <b>for</b> loop.
812</li>
813
814<li>
815The loop variables <code><em>var_i</em></code> are local to the loop;
816you cannot use their values after the <b>for</b> ends.
817If you need these values,
818then assign them to other variables before breaking or exiting the loop.
819</li>
820
821</ul>
822
823
824
825
826<h3>2.4.6 - <a name="2.4.6">Function Calls as Statements</a></h3><p>
827To allow possible side-effects,
828function calls can be executed as statements:
829
830<pre>
831 stat ::= functioncall
832</pre><p>
833In this case, all returned values are thrown away.
834Function calls are explained in <a href="#2.5.8">&sect;2.5.8</a>.
835
836
837
838
839
840<h3>2.4.7 - <a name="2.4.7">Local Declarations</a></h3><p>
841Local variables can be declared anywhere inside a block.
842The declaration can include an initial assignment:
843
844<pre>
845 stat ::= <b>local</b> namelist [`<b>=</b>&acute; explist]
846</pre><p>
847If present, an initial assignment has the same semantics
848of a multiple assignment (see <a href="#2.4.3">&sect;2.4.3</a>).
849Otherwise, all variables are initialized with <b>nil</b>.
850
851
852<p>
853A chunk is also a block (see <a href="#2.4.1">&sect;2.4.1</a>),
854and so local variables can be declared in a chunk outside any explicit block.
855The scope of such local variables extends until the end of the chunk.
856
857
858<p>
859The visibility rules for local variables are explained in <a href="#2.6">&sect;2.6</a>.
860
861
862
863
864
865
866
867<h2>2.5 - <a name="2.5">Expressions</a></h2>
868
869<p>
870The basic expressions in Lua are the following:
871
872<pre>
873 exp ::= prefixexp
874 exp ::= <b>nil</b> | <b>false</b> | <b>true</b>
875 exp ::= Number
876 exp ::= String
877 exp ::= function
878 exp ::= tableconstructor
879 exp ::= `<b>...</b>&acute;
880 exp ::= exp binop exp
881 exp ::= unop exp
882 prefixexp ::= var | functioncall | `<b>(</b>&acute; exp `<b>)</b>&acute;
883</pre>
884
885<p>
886Numbers and literal strings are explained in <a href="#2.1">&sect;2.1</a>;
887variables are explained in <a href="#2.3">&sect;2.3</a>;
888function definitions are explained in <a href="#2.5.9">&sect;2.5.9</a>;
889function calls are explained in <a href="#2.5.8">&sect;2.5.8</a>;
890table constructors are explained in <a href="#2.5.7">&sect;2.5.7</a>.
891Vararg expressions,
892denoted by three dots ('<code>...</code>'), can only be used when
893directly inside a vararg function;
894they are explained in <a href="#2.5.9">&sect;2.5.9</a>.
895
896
897<p>
898Binary operators comprise arithmetic operators (see <a href="#2.5.1">&sect;2.5.1</a>),
899relational operators (see <a href="#2.5.2">&sect;2.5.2</a>), logical operators (see <a href="#2.5.3">&sect;2.5.3</a>),
900and the concatenation operator (see <a href="#2.5.4">&sect;2.5.4</a>).
901Unary operators comprise the unary minus (see <a href="#2.5.1">&sect;2.5.1</a>),
902the unary <b>not</b> (see <a href="#2.5.3">&sect;2.5.3</a>),
903and the unary <em>length operator</em> (see <a href="#2.5.5">&sect;2.5.5</a>).
904
905
906<p>
907Both function calls and vararg expressions can result in multiple values.
908If an expression is used as a statement
909(only possible for function calls (see <a href="#2.4.6">&sect;2.4.6</a>)),
910then its return list is adjusted to zero elements,
911thus discarding all returned values.
912If an expression is used as the last (or the only) element
913of a list of expressions,
914then no adjustment is made
915(unless the call is enclosed in parentheses).
916In all other contexts,
917Lua adjusts the result list to one element,
918discarding all values except the first one.
919
920
921<p>
922Here are some examples:
923
924<pre>
925 f() -- adjusted to 0 results
926 g(f(), x) -- f() is adjusted to 1 result
927 g(x, f()) -- g gets x plus all results from f()
928 a,b,c = f(), x -- f() is adjusted to 1 result (c gets nil)
929 a,b = ... -- a gets the first vararg parameter, b gets
930 -- the second (both a and b can get nil if there
931 -- is no corresponding vararg parameter)
932
933 a,b,c = x, f() -- f() is adjusted to 2 results
934 a,b,c = f() -- f() is adjusted to 3 results
935 return f() -- returns all results from f()
936 return ... -- returns all received vararg parameters
937 return x,y,f() -- returns x, y, and all results from f()
938 {f()} -- creates a list with all results from f()
939 {...} -- creates a list with all vararg parameters
940 {f(), nil} -- f() is adjusted to 1 result
941</pre>
942
943<p>
944Any expression enclosed in parentheses always results in only one value.
945Thus,
946<code>(f(x,y,z))</code> is always a single value,
947even if <code>f</code> returns several values.
948(The value of <code>(f(x,y,z))</code> is the first value returned by <code>f</code>
949or <b>nil</b> if <code>f</code> does not return any values.)
950
951
952
953<h3>2.5.1 - <a name="2.5.1">Arithmetic Operators</a></h3><p>
954Lua supports the usual arithmetic operators:
955the binary <code>+</code> (addition),
956<code>-</code> (subtraction), <code>*</code> (multiplication),
957<code>/</code> (division), <code>%</code> (modulo), and <code>^</code> (exponentiation);
958and unary <code>-</code> (negation).
959If the operands are numbers, or strings that can be converted to
960numbers (see <a href="#2.2.1">&sect;2.2.1</a>),
961then all operations have the usual meaning.
962Exponentiation works for any exponent.
963For instance, <code>x^(-0.5)</code> computes the inverse of the square root of <code>x</code>.
964Modulo is defined as
965
966<pre>
967 a % b == a - math.floor(a/b)*b
968</pre><p>
969That is, it is the remainder of a division that rounds
970the quotient towards minus infinity.
971
972
973
974
975
976<h3>2.5.2 - <a name="2.5.2">Relational Operators</a></h3><p>
977The relational operators in Lua are
978
979<pre>
980 == ~= &lt; &gt; &lt;= &gt;=
981</pre><p>
982These operators always result in <b>false</b> or <b>true</b>.
983
984
985<p>
986Equality (<code>==</code>) first compares the type of its operands.
987If the types are different, then the result is <b>false</b>.
988Otherwise, the values of the operands are compared.
989Numbers and strings are compared in the usual way.
990Objects (tables, userdata, threads, and functions)
991are compared by <em>reference</em>:
992two objects are considered equal only if they are the <em>same</em> object.
993Every time you create a new object
994(a table, userdata, thread, or function),
995this new object is different from any previously existing object.
996
997
998<p>
999You can change the way that Lua compares tables and userdata
1000by using the "eq" metamethod (see <a href="#2.8">&sect;2.8</a>).
1001
1002
1003<p>
1004The conversion rules of <a href="#2.2.1">&sect;2.2.1</a>
1005<em>do not</em> apply to equality comparisons.
1006Thus, <code>"0"==0</code> evaluates to <b>false</b>,
1007and <code>t[0]</code> and <code>t["0"]</code> denote different
1008entries in a table.
1009
1010
1011<p>
1012The operator <code>~=</code> is exactly the negation of equality (<code>==</code>).
1013
1014
1015<p>
1016The order operators work as follows.
1017If both arguments are numbers, then they are compared as such.
1018Otherwise, if both arguments are strings,
1019then their values are compared according to the current locale.
1020Otherwise, Lua tries to call the "lt" or the "le"
1021metamethod (see <a href="#2.8">&sect;2.8</a>).
1022A comparison <code>a &gt; b</code> is translated to <code>b &lt; a</code>
1023and <code>a &gt;= b</code> is translated to <code>b &lt;= a</code>.
1024
1025
1026
1027
1028
1029<h3>2.5.3 - <a name="2.5.3">Logical Operators</a></h3><p>
1030The logical operators in Lua are
1031<b>and</b>, <b>or</b>, and <b>not</b>.
1032Like the control structures (see <a href="#2.4.4">&sect;2.4.4</a>),
1033all logical operators consider both <b>false</b> and <b>nil</b> as false
1034and anything else as true.
1035
1036
1037<p>
1038The negation operator <b>not</b> always returns <b>false</b> or <b>true</b>.
1039The conjunction operator <b>and</b> returns its first argument
1040if this value is <b>false</b> or <b>nil</b>;
1041otherwise, <b>and</b> returns its second argument.
1042The disjunction operator <b>or</b> returns its first argument
1043if this value is different from <b>nil</b> and <b>false</b>;
1044otherwise, <b>or</b> returns its second argument.
1045Both <b>and</b> and <b>or</b> use short-cut evaluation;
1046that is,
1047the second operand is evaluated only if necessary.
1048Here are some examples:
1049
1050<pre>
1051 10 or 20 --&gt; 10
1052 10 or error() --&gt; 10
1053 nil or "a" --&gt; "a"
1054 nil and 10 --&gt; nil
1055 false and error() --&gt; false
1056 false and nil --&gt; false
1057 false or nil --&gt; nil
1058 10 and 20 --&gt; 20
1059</pre><p>
1060(In this manual,
1061<code>--&gt;</code> indicates the result of the preceding expression.)
1062
1063
1064
1065
1066
1067<h3>2.5.4 - <a name="2.5.4">Concatenation</a></h3><p>
1068The string concatenation operator in Lua is
1069denoted by two dots ('<code>..</code>').
1070If both operands are strings or numbers, then they are converted to
1071strings according to the rules mentioned in <a href="#2.2.1">&sect;2.2.1</a>.
1072Otherwise, the "concat" metamethod is called (see <a href="#2.8">&sect;2.8</a>).
1073
1074
1075
1076
1077
1078<h3>2.5.5 - <a name="2.5.5">The Length Operator</a></h3>
1079
1080<p>
1081The length operator is denoted by the unary operator <code>#</code>.
1082The length of a string is its number of bytes
1083(that is, the usual meaning of string length when each
1084character is one byte).
1085
1086
1087<p>
1088The length of a table <code>t</code> is defined to be any
1089integer index <code>n</code>
1090such that <code>t[n]</code> is not <b>nil</b> and <code>t[n+1]</code> is <b>nil</b>;
1091moreover, if <code>t[1]</code> is <b>nil</b>, <code>n</code> can be zero.
1092For a regular array, with non-nil values from 1 to a given <code>n</code>,
1093its length is exactly that <code>n</code>,
1094the index of its last value.
1095If the array has "holes"
1096(that is, <b>nil</b> values between other non-nil values),
1097then <code>#t</code> can be any of the indices that
1098directly precedes a <b>nil</b> value
1099(that is, it may consider any such <b>nil</b> value as the end of
1100the array).
1101
1102
1103
1104
1105
1106<h3>2.5.6 - <a name="2.5.6">Precedence</a></h3><p>
1107Operator precedence in Lua follows the table below,
1108from lower to higher priority:
1109
1110<pre>
1111 or
1112 and
1113 &lt; &gt; &lt;= &gt;= ~= ==
1114 ..
1115 + -
1116 * / %
1117 not # - (unary)
1118 ^
1119</pre><p>
1120As usual,
1121you can use parentheses to change the precedences of an expression.
1122The concatenation ('<code>..</code>') and exponentiation ('<code>^</code>')
1123operators are right associative.
1124All other binary operators are left associative.
1125
1126
1127
1128
1129
1130<h3>2.5.7 - <a name="2.5.7">Table Constructors</a></h3><p>
1131Table constructors are expressions that create tables.
1132Every time a constructor is evaluated, a new table is created.
1133A constructor can be used to create an empty table
1134or to create a table and initialize some of its fields.
1135The general syntax for constructors is
1136
1137<pre>
1138 tableconstructor ::= `<b>{</b>&acute; [fieldlist] `<b>}</b>&acute;
1139 fieldlist ::= field {fieldsep field} [fieldsep]
1140 field ::= `<b>[</b>&acute; exp `<b>]</b>&acute; `<b>=</b>&acute; exp | Name `<b>=</b>&acute; exp | exp
1141 fieldsep ::= `<b>,</b>&acute; | `<b>;</b>&acute;
1142</pre>
1143
1144<p>
1145Each field of the form <code>[exp1] = exp2</code> adds to the new table an entry
1146with key <code>exp1</code> and value <code>exp2</code>.
1147A field of the form <code>name = exp</code> is equivalent to
1148<code>["name"] = exp</code>.
1149Finally, fields of the form <code>exp</code> are equivalent to
1150<code>[i] = exp</code>, where <code>i</code> are consecutive numerical integers,
1151starting with 1.
1152Fields in the other formats do not affect this counting.
1153For example,
1154
1155<pre>
1156 a = { [f(1)] = g; "x", "y"; x = 1, f(x), [30] = 23; 45 }
1157</pre><p>
1158is equivalent to
1159
1160<pre>
1161 do
1162 local t = {}
1163 t[f(1)] = g
1164 t[1] = "x" -- 1st exp
1165 t[2] = "y" -- 2nd exp
1166 t.x = 1 -- t["x"] = 1
1167 t[3] = f(x) -- 3rd exp
1168 t[30] = 23
1169 t[4] = 45 -- 4th exp
1170 a = t
1171 end
1172</pre>
1173
1174<p>
1175If the last field in the list has the form <code>exp</code>
1176and the expression is a function call or a vararg expression,
1177then all values returned by this expression enter the list consecutively
1178(see <a href="#2.5.8">&sect;2.5.8</a>).
1179To avoid this,
1180enclose the function call or the vararg expression
1181in parentheses (see <a href="#2.5">&sect;2.5</a>).
1182
1183
1184<p>
1185The field list can have an optional trailing separator,
1186as a convenience for machine-generated code.
1187
1188
1189
1190
1191
1192<h3>2.5.8 - <a name="2.5.8">Function Calls</a></h3><p>
1193A function call in Lua has the following syntax:
1194
1195<pre>
1196 functioncall ::= prefixexp args
1197</pre><p>
1198In a function call,
1199first prefixexp and args are evaluated.
1200If the value of prefixexp has type <em>function</em>,
1201then this function is called
1202with the given arguments.
1203Otherwise, the prefixexp "call" metamethod is called,
1204having as first parameter the value of prefixexp,
1205followed by the original call arguments
1206(see <a href="#2.8">&sect;2.8</a>).
1207
1208
1209<p>
1210The form
1211
1212<pre>
1213 functioncall ::= prefixexp `<b>:</b>&acute; Name args
1214</pre><p>
1215can be used to call "methods".
1216A call <code>v:name(<em>args</em>)</code>
1217is syntactic sugar for <code>v.name(v,<em>args</em>)</code>,
1218except that <code>v</code> is evaluated only once.
1219
1220
1221<p>
1222Arguments have the following syntax:
1223
1224<pre>
1225 args ::= `<b>(</b>&acute; [explist] `<b>)</b>&acute;
1226 args ::= tableconstructor
1227 args ::= String
1228</pre><p>
1229All argument expressions are evaluated before the call.
1230A call of the form <code>f{<em>fields</em>}</code> is
1231syntactic sugar for <code>f({<em>fields</em>})</code>;
1232that is, the argument list is a single new table.
1233A call of the form <code>f'<em>string</em>'</code>
1234(or <code>f"<em>string</em>"</code> or <code>f[[<em>string</em>]]</code>)
1235is syntactic sugar for <code>f('<em>string</em>')</code>;
1236that is, the argument list is a single literal string.
1237
1238
1239<p>
1240As an exception to the free-format syntax of Lua,
1241you cannot put a line break before the '<code>(</code>' in a function call.
1242This restriction avoids some ambiguities in the language.
1243If you write
1244
1245<pre>
1246 a = f
1247 (g).x(a)
1248</pre><p>
1249Lua would see that as a single statement, <code>a = f(g).x(a)</code>.
1250So, if you want two statements, you must add a semi-colon between them.
1251If you actually want to call <code>f</code>,
1252you must remove the line break before <code>(g)</code>.
1253
1254
1255<p>
1256A call of the form <code>return</code> <em>functioncall</em> is called
1257a <em>tail call</em>.
1258Lua implements <em>proper tail calls</em>
1259(or <em>proper tail recursion</em>):
1260in a tail call,
1261the called function reuses the stack entry of the calling function.
1262Therefore, there is no limit on the number of nested tail calls that
1263a program can execute.
1264However, a tail call erases any debug information about the
1265calling function.
1266Note that a tail call only happens with a particular syntax,
1267where the <b>return</b> has one single function call as argument;
1268this syntax makes the calling function return exactly
1269the returns of the called function.
1270So, none of the following examples are tail calls:
1271
1272<pre>
1273 return (f(x)) -- results adjusted to 1
1274 return 2 * f(x)
1275 return x, f(x) -- additional results
1276 f(x); return -- results discarded
1277 return x or f(x) -- results adjusted to 1
1278</pre>
1279
1280
1281
1282
1283<h3>2.5.9 - <a name="2.5.9">Function Definitions</a></h3>
1284
1285<p>
1286The syntax for function definition is
1287
1288<pre>
1289 function ::= <b>function</b> funcbody
1290 funcbody ::= `<b>(</b>&acute; [parlist] `<b>)</b>&acute; block <b>end</b>
1291</pre>
1292
1293<p>
1294The following syntactic sugar simplifies function definitions:
1295
1296<pre>
1297 stat ::= <b>function</b> funcname funcbody
1298 stat ::= <b>local</b> <b>function</b> Name funcbody
1299 funcname ::= Name {`<b>.</b>&acute; Name} [`<b>:</b>&acute; Name]
1300</pre><p>
1301The statement
1302
1303<pre>
1304 function f () <em>body</em> end
1305</pre><p>
1306translates to
1307
1308<pre>
1309 f = function () <em>body</em> end
1310</pre><p>
1311The statement
1312
1313<pre>
1314 function t.a.b.c.f () <em>body</em> end
1315</pre><p>
1316translates to
1317
1318<pre>
1319 t.a.b.c.f = function () <em>body</em> end
1320</pre><p>
1321The statement
1322
1323<pre>
1324 local function f () <em>body</em> end
1325</pre><p>
1326translates to
1327
1328<pre>
1329 local f; f = function () <em>body</em> end
1330</pre><p>
1331<em>not</em> to
1332
1333<pre>
1334 local f = function () <em>body</em> end
1335</pre><p>
1336(This only makes a difference when the body of the function
1337contains references to <code>f</code>.)
1338
1339
1340<p>
1341A function definition is an executable expression,
1342whose value has type <em>function</em>.
1343When Lua pre-compiles a chunk,
1344all its function bodies are pre-compiled too.
1345Then, whenever Lua executes the function definition,
1346the function is <em>instantiated</em> (or <em>closed</em>).
1347This function instance (or <em>closure</em>)
1348is the final value of the expression.
1349Different instances of the same function
1350can refer to different external local variables
1351and can have different environment tables.
1352
1353
1354<p>
1355Parameters act as local variables that are
1356initialized with the argument values:
1357
1358<pre>
1359 parlist ::= namelist [`<b>,</b>&acute; `<b>...</b>&acute;] | `<b>...</b>&acute;
1360</pre><p>
1361When a function is called,
1362the list of arguments is adjusted to
1363the length of the list of parameters,
1364unless the function is a variadic or <em>vararg function</em>,
1365which is
1366indicated by three dots ('<code>...</code>') at the end of its parameter list.
1367A vararg function does not adjust its argument list;
1368instead, it collects all extra arguments and supplies them
1369to the function through a <em>vararg expression</em>,
1370which is also written as three dots.
1371The value of this expression is a list of all actual extra arguments,
1372similar to a function with multiple results.
1373If a vararg expression is used inside another expression
1374or in the middle of a list of expressions,
1375then its return list is adjusted to one element.
1376If the expression is used as the last element of a list of expressions,
1377then no adjustment is made
1378(unless that last expression is enclosed in parentheses).
1379
1380
1381<p>
1382As an example, consider the following definitions:
1383
1384<pre>
1385 function f(a, b) end
1386 function g(a, b, ...) end
1387 function r() return 1,2,3 end
1388</pre><p>
1389Then, we have the following mapping from arguments to parameters and
1390to the vararg expression:
1391
1392<pre>
1393 CALL PARAMETERS
1394
1395 f(3) a=3, b=nil
1396 f(3, 4) a=3, b=4
1397 f(3, 4, 5) a=3, b=4
1398 f(r(), 10) a=1, b=10
1399 f(r()) a=1, b=2
1400
1401 g(3) a=3, b=nil, ... --&gt; (nothing)
1402 g(3, 4) a=3, b=4, ... --&gt; (nothing)
1403 g(3, 4, 5, 8) a=3, b=4, ... --&gt; 5 8
1404 g(5, r()) a=5, b=1, ... --&gt; 2 3
1405</pre>
1406
1407<p>
1408Results are returned using the <b>return</b> statement (see <a href="#2.4.4">&sect;2.4.4</a>).
1409If control reaches the end of a function
1410without encountering a <b>return</b> statement,
1411then the function returns with no results.
1412
1413
1414<p>
1415The <em>colon</em> syntax
1416is used for defining <em>methods</em>,
1417that is, functions that have an implicit extra parameter <code>self</code>.
1418Thus, the statement
1419
1420<pre>
1421 function t.a.b.c:f (<em>params</em>) <em>body</em> end
1422</pre><p>
1423is syntactic sugar for
1424
1425<pre>
1426 t.a.b.c.f = function (self, <em>params</em>) <em>body</em> end
1427</pre>
1428
1429
1430
1431
1432
1433
1434<h2>2.6 - <a name="2.6">Visibility Rules</a></h2>
1435
1436<p>
1437
1438Lua is a lexically scoped language.
1439The scope of variables begins at the first statement <em>after</em>
1440their declaration and lasts until the end of the innermost block that
1441includes the declaration.
1442Consider the following example:
1443
1444<pre>
1445 x = 10 -- global variable
1446 do -- new block
1447 local x = x -- new 'x', with value 10
1448 print(x) --&gt; 10
1449 x = x+1
1450 do -- another block
1451 local x = x+1 -- another 'x'
1452 print(x) --&gt; 12
1453 end
1454 print(x) --&gt; 11
1455 end
1456 print(x) --&gt; 10 (the global one)
1457</pre>
1458
1459<p>
1460Notice that, in a declaration like <code>local x = x</code>,
1461the new <code>x</code> being declared is not in scope yet,
1462and so the second <code>x</code> refers to the outside variable.
1463
1464
1465<p>
1466Because of the lexical scoping rules,
1467local variables can be freely accessed by functions
1468defined inside their scope.
1469A local variable used by an inner function is called
1470an <em>upvalue</em>, or <em>external local variable</em>,
1471inside the inner function.
1472
1473
1474<p>
1475Notice that each execution of a <b>local</b> statement
1476defines new local variables.
1477Consider the following example:
1478
1479<pre>
1480 a = {}
1481 local x = 20
1482 for i=1,10 do
1483 local y = 0
1484 a[i] = function () y=y+1; return x+y end
1485 end
1486</pre><p>
1487The loop creates ten closures
1488(that is, ten instances of the anonymous function).
1489Each of these closures uses a different <code>y</code> variable,
1490while all of them share the same <code>x</code>.
1491
1492
1493
1494
1495
1496<h2>2.7 - <a name="2.7">Error Handling</a></h2>
1497
1498<p>
1499Because Lua is an embedded extension language,
1500all Lua actions start from C&nbsp;code in the host program
1501calling a function from the Lua library (see <a href="#lua_pcall"><code>lua_pcall</code></a>).
1502Whenever an error occurs during Lua compilation or execution,
1503control returns to C,
1504which can take appropriate measures
1505(such as printing an error message).
1506
1507
1508<p>
1509Lua code can explicitly generate an error by calling the
1510<a href="#pdf-error"><code>error</code></a> function.
1511If you need to catch errors in Lua,
1512you can use the <a href="#pdf-pcall"><code>pcall</code></a> function.
1513
1514
1515
1516
1517
1518<h2>2.8 - <a name="2.8">Metatables</a></h2>
1519
1520<p>
1521Every value in Lua can have a <em>metatable</em>.
1522This <em>metatable</em> is an ordinary Lua table
1523that defines the behavior of the original value
1524under certain special operations.
1525You can change several aspects of the behavior
1526of operations over a value by setting specific fields in its metatable.
1527For instance, when a non-numeric value is the operand of an addition,
1528Lua checks for a function in the field <code>"__add"</code> in its metatable.
1529If it finds one,
1530Lua calls this function to perform the addition.
1531
1532
1533<p>
1534We call the keys in a metatable <em>events</em>
1535and the values <em>metamethods</em>.
1536In the previous example, the event is <code>"add"</code>
1537and the metamethod is the function that performs the addition.
1538
1539
1540<p>
1541You can query the metatable of any value
1542through the <a href="#pdf-getmetatable"><code>getmetatable</code></a> function.
1543
1544
1545<p>
1546You can replace the metatable of tables
1547through the <a href="#pdf-setmetatable"><code>setmetatable</code></a>
1548function.
1549You cannot change the metatable of other types from Lua
1550(except by using the debug library);
1551you must use the C&nbsp;API for that.
1552
1553
1554<p>
1555Tables and full userdata have individual metatables
1556(although multiple tables and userdata can share their metatables).
1557Values of all other types share one single metatable per type;
1558that is, there is one single metatable for all numbers,
1559one for all strings, etc.
1560
1561
1562<p>
1563A metatable controls how an object behaves in arithmetic operations,
1564order comparisons, concatenation, length operation, and indexing.
1565A metatable also can define a function to be called when a userdata
1566is garbage collected.
1567For each of these operations Lua associates a specific key
1568called an <em>event</em>.
1569When Lua performs one of these operations over a value,
1570it checks whether this value has a metatable with the corresponding event.
1571If so, the value associated with that key (the metamethod)
1572controls how Lua will perform the operation.
1573
1574
1575<p>
1576Metatables control the operations listed next.
1577Each operation is identified by its corresponding name.
1578The key for each operation is a string with its name prefixed by
1579two underscores, '<code>__</code>';
1580for instance, the key for operation "add" is the
1581string <code>"__add"</code>.
1582The semantics of these operations is better explained by a Lua function
1583describing how the interpreter executes the operation.
1584
1585
1586<p>
1587The code shown here in Lua is only illustrative;
1588the real behavior is hard coded in the interpreter
1589and it is much more efficient than this simulation.
1590All functions used in these descriptions
1591(<a href="#pdf-rawget"><code>rawget</code></a>, <a href="#pdf-tonumber"><code>tonumber</code></a>, etc.)
1592are described in <a href="#5.1">&sect;5.1</a>.
1593In particular, to retrieve the metamethod of a given object,
1594we use the expression
1595
1596<pre>
1597 metatable(obj)[event]
1598</pre><p>
1599This should be read as
1600
1601<pre>
1602 rawget(getmetatable(obj) or {}, event)
1603</pre><p>
1604
1605That is, the access to a metamethod does not invoke other metamethods,
1606and the access to objects with no metatables does not fail
1607(it simply results in <b>nil</b>).
1608
1609
1610
1611<ul>
1612
1613<li><b>"add":</b>
1614the <code>+</code> operation.
1615
1616
1617
1618<p>
1619The function <code>getbinhandler</code> below defines how Lua chooses a handler
1620for a binary operation.
1621First, Lua tries the first operand.
1622If its type does not define a handler for the operation,
1623then Lua tries the second operand.
1624
1625<pre>
1626 function getbinhandler (op1, op2, event)
1627 return metatable(op1)[event] or metatable(op2)[event]
1628 end
1629</pre><p>
1630By using this function,
1631the behavior of the <code>op1 + op2</code> is
1632
1633<pre>
1634 function add_event (op1, op2)
1635 local o1, o2 = tonumber(op1), tonumber(op2)
1636 if o1 and o2 then -- both operands are numeric?
1637 return o1 + o2 -- '+' here is the primitive 'add'
1638 else -- at least one of the operands is not numeric
1639 local h = getbinhandler(op1, op2, "__add")
1640 if h then
1641 -- call the handler with both operands
1642 return (h(op1, op2))
1643 else -- no handler available: default behavior
1644 error(&middot;&middot;&middot;)
1645 end
1646 end
1647 end
1648</pre><p>
1649</li>
1650
1651<li><b>"sub":</b>
1652the <code>-</code> operation.
1653
1654Behavior similar to the "add" operation.
1655</li>
1656
1657<li><b>"mul":</b>
1658the <code>*</code> operation.
1659
1660Behavior similar to the "add" operation.
1661</li>
1662
1663<li><b>"div":</b>
1664the <code>/</code> operation.
1665
1666Behavior similar to the "add" operation.
1667</li>
1668
1669<li><b>"mod":</b>
1670the <code>%</code> operation.
1671
1672Behavior similar to the "add" operation,
1673with the operation
1674<code>o1 - floor(o1/o2)*o2</code> as the primitive operation.
1675</li>
1676
1677<li><b>"pow":</b>
1678the <code>^</code> (exponentiation) operation.
1679
1680Behavior similar to the "add" operation,
1681with the function <code>pow</code> (from the C&nbsp;math library)
1682as the primitive operation.
1683</li>
1684
1685<li><b>"unm":</b>
1686the unary <code>-</code> operation.
1687
1688
1689<pre>
1690 function unm_event (op)
1691 local o = tonumber(op)
1692 if o then -- operand is numeric?
1693 return -o -- '-' here is the primitive 'unm'
1694 else -- the operand is not numeric.
1695 -- Try to get a handler from the operand
1696 local h = metatable(op).__unm
1697 if h then
1698 -- call the handler with the operand
1699 return (h(op))
1700 else -- no handler available: default behavior
1701 error(&middot;&middot;&middot;)
1702 end
1703 end
1704 end
1705</pre><p>
1706</li>
1707
1708<li><b>"concat":</b>
1709the <code>..</code> (concatenation) operation.
1710
1711
1712<pre>
1713 function concat_event (op1, op2)
1714 if (type(op1) == "string" or type(op1) == "number") and
1715 (type(op2) == "string" or type(op2) == "number") then
1716 return op1 .. op2 -- primitive string concatenation
1717 else
1718 local h = getbinhandler(op1, op2, "__concat")
1719 if h then
1720 return (h(op1, op2))
1721 else
1722 error(&middot;&middot;&middot;)
1723 end
1724 end
1725 end
1726</pre><p>
1727</li>
1728
1729<li><b>"len":</b>
1730the <code>#</code> operation.
1731
1732
1733<pre>
1734 function len_event (op)
1735 if type(op) == "string" then
1736 return strlen(op) -- primitive string length
1737 elseif type(op) == "table" then
1738 return #op -- primitive table length
1739 else
1740 local h = metatable(op).__len
1741 if h then
1742 -- call the handler with the operand
1743 return (h(op))
1744 else -- no handler available: default behavior
1745 error(&middot;&middot;&middot;)
1746 end
1747 end
1748 end
1749</pre><p>
1750See <a href="#2.5.5">&sect;2.5.5</a> for a description of the length of a table.
1751</li>
1752
1753<li><b>"eq":</b>
1754the <code>==</code> operation.
1755
1756The function <code>getcomphandler</code> defines how Lua chooses a metamethod
1757for comparison operators.
1758A metamethod only is selected when both objects
1759being compared have the same type
1760and the same metamethod for the selected operation.
1761
1762<pre>
1763 function getcomphandler (op1, op2, event)
1764 if type(op1) ~= type(op2) then return nil end
1765 local mm1 = metatable(op1)[event]
1766 local mm2 = metatable(op2)[event]
1767 if mm1 == mm2 then return mm1 else return nil end
1768 end
1769</pre><p>
1770The "eq" event is defined as follows:
1771
1772<pre>
1773 function eq_event (op1, op2)
1774 if type(op1) ~= type(op2) then -- different types?
1775 return false -- different objects
1776 end
1777 if op1 == op2 then -- primitive equal?
1778 return true -- objects are equal
1779 end
1780 -- try metamethod
1781 local h = getcomphandler(op1, op2, "__eq")
1782 if h then
1783 return (h(op1, op2))
1784 else
1785 return false
1786 end
1787 end
1788</pre><p>
1789<code>a ~= b</code> is equivalent to <code>not (a == b)</code>.
1790</li>
1791
1792<li><b>"lt":</b>
1793the <code>&lt;</code> operation.
1794
1795
1796<pre>
1797 function lt_event (op1, op2)
1798 if type(op1) == "number" and type(op2) == "number" then
1799 return op1 &lt; op2 -- numeric comparison
1800 elseif type(op1) == "string" and type(op2) == "string" then
1801 return op1 &lt; op2 -- lexicographic comparison
1802 else
1803 local h = getcomphandler(op1, op2, "__lt")
1804 if h then
1805 return (h(op1, op2))
1806 else
1807 error(&middot;&middot;&middot;)
1808 end
1809 end
1810 end
1811</pre><p>
1812<code>a &gt; b</code> is equivalent to <code>b &lt; a</code>.
1813</li>
1814
1815<li><b>"le":</b>
1816the <code>&lt;=</code> operation.
1817
1818
1819<pre>
1820 function le_event (op1, op2)
1821 if type(op1) == "number" and type(op2) == "number" then
1822 return op1 &lt;= op2 -- numeric comparison
1823 elseif type(op1) == "string" and type(op2) == "string" then
1824 return op1 &lt;= op2 -- lexicographic comparison
1825 else
1826 local h = getcomphandler(op1, op2, "__le")
1827 if h then
1828 return (h(op1, op2))
1829 else
1830 h = getcomphandler(op1, op2, "__lt")
1831 if h then
1832 return not h(op2, op1)
1833 else
1834 error(&middot;&middot;&middot;)
1835 end
1836 end
1837 end
1838 end
1839</pre><p>
1840<code>a &gt;= b</code> is equivalent to <code>b &lt;= a</code>.
1841Note that, in the absence of a "le" metamethod,
1842Lua tries the "lt", assuming that <code>a &lt;= b</code> is
1843equivalent to <code>not (b &lt; a)</code>.
1844</li>
1845
1846<li><b>"index":</b>
1847The indexing access <code>table[key]</code>.
1848
1849
1850<pre>
1851 function gettable_event (table, key)
1852 local h
1853 if type(table) == "table" then
1854 local v = rawget(table, key)
1855 if v ~= nil then return v end
1856 h = metatable(table).__index
1857 if h == nil then return nil end
1858 else
1859 h = metatable(table).__index
1860 if h == nil then
1861 error(&middot;&middot;&middot;)
1862 end
1863 end
1864 if type(h) == "function" then
1865 return (h(table, key)) -- call the handler
1866 else return h[key] -- or repeat operation on it
1867 end
1868 end
1869</pre><p>
1870</li>
1871
1872<li><b>"newindex":</b>
1873The indexing assignment <code>table[key] = value</code>.
1874
1875
1876<pre>
1877 function settable_event (table, key, value)
1878 local h
1879 if type(table) == "table" then
1880 local v = rawget(table, key)
1881 if v ~= nil then rawset(table, key, value); return end
1882 h = metatable(table).__newindex
1883 if h == nil then rawset(table, key, value); return end
1884 else
1885 h = metatable(table).__newindex
1886 if h == nil then
1887 error(&middot;&middot;&middot;)
1888 end
1889 end
1890 if type(h) == "function" then
1891 h(table, key,value) -- call the handler
1892 else h[key] = value -- or repeat operation on it
1893 end
1894 end
1895</pre><p>
1896</li>
1897
1898<li><b>"call":</b>
1899called when Lua calls a value.
1900
1901
1902<pre>
1903 function function_event (func, ...)
1904 if type(func) == "function" then
1905 return func(...) -- primitive call
1906 else
1907 local h = metatable(func).__call
1908 if h then
1909 return h(func, ...)
1910 else
1911 error(&middot;&middot;&middot;)
1912 end
1913 end
1914 end
1915</pre><p>
1916</li>
1917
1918</ul>
1919
1920
1921
1922
1923<h2>2.9 - <a name="2.9">Environments</a></h2>
1924
1925<p>
1926Besides metatables,
1927objects of types thread, function, and userdata
1928have another table associated with them,
1929called their <em>environment</em>.
1930Like metatables, environments are regular tables and
1931multiple objects can share the same environment.
1932
1933
1934<p>
1935Threads are created sharing the environment of the creating thread.
1936Userdata and C&nbsp;functions are created sharing the environment
1937of the creating C&nbsp;function.
1938Non-nested Lua functions
1939(created by <a href="#pdf-loadfile"><code>loadfile</code></a>, <a href="#pdf-loadstring"><code>loadstring</code></a> or <a href="#pdf-load"><code>load</code></a>)
1940are created sharing the environment of the creating thread.
1941Nested Lua functions are created sharing the environment of
1942the creating Lua function.
1943
1944
1945<p>
1946Environments associated with userdata have no meaning for Lua.
1947It is only a convenience feature for programmers to associate a table to
1948a userdata.
1949
1950
1951<p>
1952Environments associated with threads are called
1953<em>global environments</em>.
1954They are used as the default environment for threads and
1955non-nested Lua functions created by the thread
1956and can be directly accessed by C&nbsp;code (see <a href="#3.3">&sect;3.3</a>).
1957
1958
1959<p>
1960The environment associated with a C&nbsp;function can be directly
1961accessed by C&nbsp;code (see <a href="#3.3">&sect;3.3</a>).
1962It is used as the default environment for other C&nbsp;functions
1963and userdata created by the function.
1964
1965
1966<p>
1967Environments associated with Lua functions are used to resolve
1968all accesses to global variables within the function (see <a href="#2.3">&sect;2.3</a>).
1969They are used as the default environment for nested Lua functions
1970created by the function.
1971
1972
1973<p>
1974You can change the environment of a Lua function or the
1975running thread by calling <a href="#pdf-setfenv"><code>setfenv</code></a>.
1976You can get the environment of a Lua function or the running thread
1977by calling <a href="#pdf-getfenv"><code>getfenv</code></a>.
1978To manipulate the environment of other objects
1979(userdata, C&nbsp;functions, other threads) you must
1980use the C&nbsp;API.
1981
1982
1983
1984
1985
1986<h2>2.10 - <a name="2.10">Garbage Collection</a></h2>
1987
1988<p>
1989Lua performs automatic memory management.
1990This means that
1991you have to worry neither about allocating memory for new objects
1992nor about freeing it when the objects are no longer needed.
1993Lua manages memory automatically by running
1994a <em>garbage collector</em> from time to time
1995to collect all <em>dead objects</em>
1996(that is, objects that are no longer accessible from Lua).
1997All memory used by Lua is subject to automatic management:
1998tables, userdata, functions, threads, strings, etc.
1999
2000
2001<p>
2002Lua implements an incremental mark-and-sweep collector.
2003It uses two numbers to control its garbage-collection cycles:
2004the <em>garbage-collector pause</em> and
2005the <em>garbage-collector step multiplier</em>.
2006Both use percentage points as units
2007(so that a value of 100 means an internal value of 1).
2008
2009
2010<p>
2011The garbage-collector pause
2012controls how long the collector waits before starting a new cycle.
2013Larger values make the collector less aggressive.
2014Values smaller than 100 mean the collector will not wait to
2015start a new cycle.
2016A value of 200 means that the collector waits for the total memory in use
2017to double before starting a new cycle.
2018
2019
2020<p>
2021The step multiplier
2022controls the relative speed of the collector relative to
2023memory allocation.
2024Larger values make the collector more aggressive but also increase
2025the size of each incremental step.
2026Values smaller than 100 make the collector too slow and
2027can result in the collector never finishing a cycle.
2028The default, 200, means that the collector runs at "twice"
2029the speed of memory allocation.
2030
2031
2032<p>
2033You can change these numbers by calling <a href="#lua_gc"><code>lua_gc</code></a> in C
2034or <a href="#pdf-collectgarbage"><code>collectgarbage</code></a> in Lua.
2035With these functions you can also control
2036the collector directly (e.g., stop and restart it).
2037
2038
2039
2040<h3>2.10.1 - <a name="2.10.1">Garbage-Collection Metamethods</a></h3>
2041
2042<p>
2043Using the C&nbsp;API,
2044you can set garbage-collector metamethods for userdata (see <a href="#2.8">&sect;2.8</a>).
2045These metamethods are also called <em>finalizers</em>.
2046Finalizers allow you to coordinate Lua's garbage collection
2047with external resource management
2048(such as closing files, network or database connections,
2049or freeing your own memory).
2050
2051
2052<p>
2053Garbage userdata with a field <code>__gc</code> in their metatables are not
2054collected immediately by the garbage collector.
2055Instead, Lua puts them in a list.
2056After the collection,
2057Lua does the equivalent of the following function
2058for each userdata in that list:
2059
2060<pre>
2061 function gc_event (udata)
2062 local h = metatable(udata).__gc
2063 if h then
2064 h(udata)
2065 end
2066 end
2067</pre>
2068
2069<p>
2070At the end of each garbage-collection cycle,
2071the finalizers for userdata are called in <em>reverse</em>
2072order of their creation,
2073among those collected in that cycle.
2074That is, the first finalizer to be called is the one associated
2075with the userdata created last in the program.
2076The userdata itself is freed only in the next garbage-collection cycle.
2077
2078
2079
2080
2081
2082<h3>2.10.2 - <a name="2.10.2">Weak Tables</a></h3>
2083
2084<p>
2085A <em>weak table</em> is a table whose elements are
2086<em>weak references</em>.
2087A weak reference is ignored by the garbage collector.
2088In other words,
2089if the only references to an object are weak references,
2090then the garbage collector will collect this object.
2091
2092
2093<p>
2094A weak table can have weak keys, weak values, or both.
2095A table with weak keys allows the collection of its keys,
2096but prevents the collection of its values.
2097A table with both weak keys and weak values allows the collection of
2098both keys and values.
2099In any case, if either the key or the value is collected,
2100the whole pair is removed from the table.
2101The weakness of a table is controlled by the
2102<code>__mode</code> field of its metatable.
2103If the <code>__mode</code> field is a string containing the character&nbsp;'<code>k</code>',
2104the keys in the table are weak.
2105If <code>__mode</code> contains '<code>v</code>',
2106the values in the table are weak.
2107
2108
2109<p>
2110After you use a table as a metatable,
2111you should not change the value of its <code>__mode</code> field.
2112Otherwise, the weak behavior of the tables controlled by this
2113metatable is undefined.
2114
2115
2116
2117
2118
2119
2120
2121<h2>2.11 - <a name="2.11">Coroutines</a></h2>
2122
2123<p>
2124Lua supports coroutines,
2125also called <em>collaborative multithreading</em>.
2126A coroutine in Lua represents an independent thread of execution.
2127Unlike threads in multithread systems, however,
2128a coroutine only suspends its execution by explicitly calling
2129a yield function.
2130
2131
2132<p>
2133You create a coroutine with a call to <a href="#pdf-coroutine.create"><code>coroutine.create</code></a>.
2134Its sole argument is a function
2135that is the main function of the coroutine.
2136The <code>create</code> function only creates a new coroutine and
2137returns a handle to it (an object of type <em>thread</em>);
2138it does not start the coroutine execution.
2139
2140
2141<p>
2142When you first call <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a>,
2143passing as its first argument
2144a thread returned by <a href="#pdf-coroutine.create"><code>coroutine.create</code></a>,
2145the coroutine starts its execution,
2146at the first line of its main function.
2147Extra arguments passed to <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a> are passed on
2148to the coroutine main function.
2149After the coroutine starts running,
2150it runs until it terminates or <em>yields</em>.
2151
2152
2153<p>
2154A coroutine can terminate its execution in two ways:
2155normally, when its main function returns
2156(explicitly or implicitly, after the last instruction);
2157and abnormally, if there is an unprotected error.
2158In the first case, <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a> returns <b>true</b>,
2159plus any values returned by the coroutine main function.
2160In case of errors, <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a> returns <b>false</b>
2161plus an error message.
2162
2163
2164<p>
2165A coroutine yields by calling <a href="#pdf-coroutine.yield"><code>coroutine.yield</code></a>.
2166When a coroutine yields,
2167the corresponding <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a> returns immediately,
2168even if the yield happens inside nested function calls
2169(that is, not in the main function,
2170but in a function directly or indirectly called by the main function).
2171In the case of a yield, <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a> also returns <b>true</b>,
2172plus any values passed to <a href="#pdf-coroutine.yield"><code>coroutine.yield</code></a>.
2173The next time you resume the same coroutine,
2174it continues its execution from the point where it yielded,
2175with the call to <a href="#pdf-coroutine.yield"><code>coroutine.yield</code></a> returning any extra
2176arguments passed to <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a>.
2177
2178
2179<p>
2180Like <a href="#pdf-coroutine.create"><code>coroutine.create</code></a>,
2181the <a href="#pdf-coroutine.wrap"><code>coroutine.wrap</code></a> function also creates a coroutine,
2182but instead of returning the coroutine itself,
2183it returns a function that, when called, resumes the coroutine.
2184Any arguments passed to this function
2185go as extra arguments to <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a>.
2186<a href="#pdf-coroutine.wrap"><code>coroutine.wrap</code></a> returns all the values returned by <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a>,
2187except the first one (the boolean error code).
2188Unlike <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a>,
2189<a href="#pdf-coroutine.wrap"><code>coroutine.wrap</code></a> does not catch errors;
2190any error is propagated to the caller.
2191
2192
2193<p>
2194As an example,
2195consider the following code:
2196
2197<pre>
2198 function foo (a)
2199 print("foo", a)
2200 return coroutine.yield(2*a)
2201 end
2202
2203 co = coroutine.create(function (a,b)
2204 print("co-body", a, b)
2205 local r = foo(a+1)
2206 print("co-body", r)
2207 local r, s = coroutine.yield(a+b, a-b)
2208 print("co-body", r, s)
2209 return b, "end"
2210 end)
2211
2212 print("main", coroutine.resume(co, 1, 10))
2213 print("main", coroutine.resume(co, "r"))
2214 print("main", coroutine.resume(co, "x", "y"))
2215 print("main", coroutine.resume(co, "x", "y"))
2216</pre><p>
2217When you run it, it produces the following output:
2218
2219<pre>
2220 co-body 1 10
2221 foo 2
2222
2223 main true 4
2224 co-body r
2225 main true 11 -9
2226 co-body x y
2227 main true 10 end
2228 main false cannot resume dead coroutine
2229</pre>
2230
2231
2232
2233
2234<h1>3 - <a name="3">The Application Program Interface</a></h1>
2235
2236<p>
2237
2238This section describes the C&nbsp;API for Lua, that is,
2239the set of C&nbsp;functions available to the host program to communicate
2240with Lua.
2241All API functions and related types and constants
2242are declared in the header file <a name="pdf-lua.h"><code>lua.h</code></a>.
2243
2244
2245<p>
2246Even when we use the term "function",
2247any facility in the API may be provided as a macro instead.
2248All such macros use each of their arguments exactly once
2249(except for the first argument, which is always a Lua state),
2250and so do not generate any hidden side-effects.
2251
2252
2253<p>
2254As in most C&nbsp;libraries,
2255the Lua API functions do not check their arguments for validity or consistency.
2256However, you can change this behavior by compiling Lua
2257with a proper definition for the macro <a name="pdf-luai_apicheck"><code>luai_apicheck</code></a>,
2258in file <code>luaconf.h</code>.
2259
2260
2261
2262<h2>3.1 - <a name="3.1">The Stack</a></h2>
2263
2264<p>
2265Lua uses a <em>virtual stack</em> to pass values to and from C.
2266Each element in this stack represents a Lua value
2267(<b>nil</b>, number, string, etc.).
2268
2269
2270<p>
2271Whenever Lua calls C, the called function gets a new stack,
2272which is independent of previous stacks and of stacks of
2273C&nbsp;functions that are still active.
2274This stack initially contains any arguments to the C&nbsp;function
2275and it is where the C&nbsp;function pushes its results
2276to be returned to the caller (see <a href="#lua_CFunction"><code>lua_CFunction</code></a>).
2277
2278
2279<p>
2280For convenience,
2281most query operations in the API do not follow a strict stack discipline.
2282Instead, they can refer to any element in the stack
2283by using an <em>index</em>:
2284A positive index represents an <em>absolute</em> stack position
2285(starting at&nbsp;1);
2286a negative index represents an <em>offset</em> relative to the top of the stack.
2287More specifically, if the stack has <em>n</em> elements,
2288then index&nbsp;1 represents the first element
2289(that is, the element that was pushed onto the stack first)
2290and
2291index&nbsp;<em>n</em> represents the last element;
2292index&nbsp;-1 also represents the last element
2293(that is, the element at the&nbsp;top)
2294and index <em>-n</em> represents the first element.
2295We say that an index is <em>valid</em>
2296if it lies between&nbsp;1 and the stack top
2297(that is, if <code>1 &le; abs(index) &le; top</code>).
2298
2299
2300
2301
2302
2303
2304<h2>3.2 - <a name="3.2">Stack Size</a></h2>
2305
2306<p>
2307When you interact with Lua API,
2308you are responsible for ensuring consistency.
2309In particular,
2310<em>you are responsible for controlling stack overflow</em>.
2311You can use the function <a href="#lua_checkstack"><code>lua_checkstack</code></a>
2312to grow the stack size.
2313
2314
2315<p>
2316Whenever Lua calls C,
2317it ensures that at least <a name="pdf-LUA_MINSTACK"><code>LUA_MINSTACK</code></a> stack positions are available.
2318<code>LUA_MINSTACK</code> is defined as 20,
2319so that usually you do not have to worry about stack space
2320unless your code has loops pushing elements onto the stack.
2321
2322
2323<p>
2324Most query functions accept as indices any value inside the
2325available stack space, that is, indices up to the maximum stack size
2326you have set through <a href="#lua_checkstack"><code>lua_checkstack</code></a>.
2327Such indices are called <em>acceptable indices</em>.
2328More formally, we define an <em>acceptable index</em>
2329as follows:
2330
2331<pre>
2332 (index &lt; 0 &amp;&amp; abs(index) &lt;= top) ||
2333 (index &gt; 0 &amp;&amp; index &lt;= stackspace)
2334</pre><p>
2335Note that 0 is never an acceptable index.
2336
2337
2338
2339
2340
2341<h2>3.3 - <a name="3.3">Pseudo-Indices</a></h2>
2342
2343<p>
2344Unless otherwise noted,
2345any function that accepts valid indices can also be called with
2346<em>pseudo-indices</em>,
2347which represent some Lua values that are accessible to C&nbsp;code
2348but which are not in the stack.
2349Pseudo-indices are used to access the thread environment,
2350the function environment,
2351the registry,
2352and the upvalues of a C&nbsp;function (see <a href="#3.4">&sect;3.4</a>).
2353
2354
2355<p>
2356The thread environment (where global variables live) is
2357always at pseudo-index <a name="pdf-LUA_GLOBALSINDEX"><code>LUA_GLOBALSINDEX</code></a>.
2358The environment of the running C&nbsp;function is always
2359at pseudo-index <a name="pdf-LUA_ENVIRONINDEX"><code>LUA_ENVIRONINDEX</code></a>.
2360
2361
2362<p>
2363To access and change the value of global variables,
2364you can use regular table operations over an environment table.
2365For instance, to access the value of a global variable, do
2366
2367<pre>
2368 lua_getfield(L, LUA_GLOBALSINDEX, varname);
2369</pre>
2370
2371
2372
2373
2374<h2>3.4 - <a name="3.4">C Closures</a></h2>
2375
2376<p>
2377When a C&nbsp;function is created,
2378it is possible to associate some values with it,
2379thus creating a <em>C&nbsp;closure</em>;
2380these values are called <em>upvalues</em> and are
2381accessible to the function whenever it is called
2382(see <a href="#lua_pushcclosure"><code>lua_pushcclosure</code></a>).
2383
2384
2385<p>
2386Whenever a C&nbsp;function is called,
2387its upvalues are located at specific pseudo-indices.
2388These pseudo-indices are produced by the macro
2389<a name="lua_upvalueindex"><code>lua_upvalueindex</code></a>.
2390The first value associated with a function is at position
2391<code>lua_upvalueindex(1)</code>, and so on.
2392Any access to <code>lua_upvalueindex(<em>n</em>)</code>,
2393where <em>n</em> is greater than the number of upvalues of the
2394current function (but not greater than 256),
2395produces an acceptable (but invalid) index.
2396
2397
2398
2399
2400
2401<h2>3.5 - <a name="3.5">Registry</a></h2>
2402
2403<p>
2404Lua provides a <em>registry</em>,
2405a pre-defined table that can be used by any C&nbsp;code to
2406store whatever Lua value it needs to store.
2407This table is always located at pseudo-index
2408<a name="pdf-LUA_REGISTRYINDEX"><code>LUA_REGISTRYINDEX</code></a>.
2409Any C&nbsp;library can store data into this table,
2410but it should take care to choose keys different from those used
2411by other libraries, to avoid collisions.
2412Typically, you should use as key a string containing your library name
2413or a light userdata with the address of a C&nbsp;object in your code.
2414
2415
2416<p>
2417The integer keys in the registry are used by the reference mechanism,
2418implemented by the auxiliary library,
2419and therefore should not be used for other purposes.
2420
2421
2422
2423
2424
2425<h2>3.6 - <a name="3.6">Error Handling in C</a></h2>
2426
2427<p>
2428Internally, Lua uses the C <code>longjmp</code> facility to handle errors.
2429(You can also choose to use exceptions if you use C++;
2430see file <code>luaconf.h</code>.)
2431When Lua faces any error
2432(such as memory allocation errors, type errors, syntax errors,
2433and runtime errors)
2434it <em>raises</em> an error;
2435that is, it does a long jump.
2436A <em>protected environment</em> uses <code>setjmp</code>
2437to set a recover point;
2438any error jumps to the most recent active recover point.
2439
2440
2441<p>
2442Most functions in the API can throw an error,
2443for instance due to a memory allocation error.
2444The documentation for each function indicates whether
2445it can throw errors.
2446
2447
2448<p>
2449Inside a C&nbsp;function you can throw an error by calling <a href="#lua_error"><code>lua_error</code></a>.
2450
2451
2452
2453
2454
2455<h2>3.7 - <a name="3.7">Functions and Types</a></h2>
2456
2457<p>
2458Here we list all functions and types from the C&nbsp;API in
2459alphabetical order.
2460Each function has an indicator like this:
2461<span class="apii">[-o, +p, <em>x</em>]</span>
2462
2463
2464<p>
2465The first field, <code>o</code>,
2466is how many elements the function pops from the stack.
2467The second field, <code>p</code>,
2468is how many elements the function pushes onto the stack.
2469(Any function always pushes its results after popping its arguments.)
2470A field in the form <code>x|y</code> means the function can push (or pop)
2471<code>x</code> or <code>y</code> elements,
2472depending on the situation;
2473an interrogation mark '<code>?</code>' means that
2474we cannot know how many elements the function pops/pushes
2475by looking only at its arguments
2476(e.g., they may depend on what is on the stack).
2477The third field, <code>x</code>,
2478tells whether the function may throw errors:
2479'<code>-</code>' means the function never throws any error;
2480'<code>m</code>' means the function may throw an error
2481only due to not enough memory;
2482'<code>e</code>' means the function may throw other kinds of errors;
2483'<code>v</code>' means the function may throw an error on purpose.
2484
2485
2486
2487<hr><h3><a name="lua_Alloc"><code>lua_Alloc</code></a></h3>
2488<pre>typedef void * (*lua_Alloc) (void *ud,
2489 void *ptr,
2490 size_t osize,
2491 size_t nsize);</pre>
2492
2493<p>
2494The type of the memory-allocation function used by Lua states.
2495The allocator function must provide a
2496functionality similar to <code>realloc</code>,
2497but not exactly the same.
2498Its arguments are
2499<code>ud</code>, an opaque pointer passed to <a href="#lua_newstate"><code>lua_newstate</code></a>;
2500<code>ptr</code>, a pointer to the block being allocated/reallocated/freed;
2501<code>osize</code>, the original size of the block;
2502<code>nsize</code>, the new size of the block.
2503<code>ptr</code> is <code>NULL</code> if and only if <code>osize</code> is zero.
2504When <code>nsize</code> is zero, the allocator must return <code>NULL</code>;
2505if <code>osize</code> is not zero,
2506it should free the block pointed to by <code>ptr</code>.
2507When <code>nsize</code> is not zero, the allocator returns <code>NULL</code>
2508if and only if it cannot fill the request.
2509When <code>nsize</code> is not zero and <code>osize</code> is zero,
2510the allocator should behave like <code>malloc</code>.
2511When <code>nsize</code> and <code>osize</code> are not zero,
2512the allocator behaves like <code>realloc</code>.
2513Lua assumes that the allocator never fails when
2514<code>osize &gt;= nsize</code>.
2515
2516
2517<p>
2518Here is a simple implementation for the allocator function.
2519It is used in the auxiliary library by <a href="#luaL_newstate"><code>luaL_newstate</code></a>.
2520
2521<pre>
2522 static void *l_alloc (void *ud, void *ptr, size_t osize,
2523 size_t nsize) {
2524 (void)ud; (void)osize; /* not used */
2525 if (nsize == 0) {
2526 free(ptr);
2527 return NULL;
2528 }
2529 else
2530 return realloc(ptr, nsize);
2531 }
2532</pre><p>
2533This code assumes
2534that <code>free(NULL)</code> has no effect and that
2535<code>realloc(NULL, size)</code> is equivalent to <code>malloc(size)</code>.
2536ANSI&nbsp;C ensures both behaviors.
2537
2538
2539
2540
2541
2542<hr><h3><a name="lua_atpanic"><code>lua_atpanic</code></a></h3><p>
2543<span class="apii">[-0, +0, <em>-</em>]</span>
2544<pre>lua_CFunction lua_atpanic (lua_State *L, lua_CFunction panicf);</pre>
2545
2546<p>
2547Sets a new panic function and returns the old one.
2548
2549
2550<p>
2551If an error happens outside any protected environment,
2552Lua calls a <em>panic function</em>
2553and then calls <code>exit(EXIT_FAILURE)</code>,
2554thus exiting the host application.
2555Your panic function can avoid this exit by
2556never returning (e.g., doing a long jump).
2557
2558
2559<p>
2560The panic function can access the error message at the top of the stack.
2561
2562
2563
2564
2565
2566<hr><h3><a name="lua_call"><code>lua_call</code></a></h3><p>
2567<span class="apii">[-(nargs + 1), +nresults, <em>e</em>]</span>
2568<pre>void lua_call (lua_State *L, int nargs, int nresults);</pre>
2569
2570<p>
2571Calls a function.
2572
2573
2574<p>
2575To call a function you must use the following protocol:
2576first, the function to be called is pushed onto the stack;
2577then, the arguments to the function are pushed
2578in direct order;
2579that is, the first argument is pushed first.
2580Finally you call <a href="#lua_call"><code>lua_call</code></a>;
2581<code>nargs</code> is the number of arguments that you pushed onto the stack.
2582All arguments and the function value are popped from the stack
2583when the function is called.
2584The function results are pushed onto the stack when the function returns.
2585The number of results is adjusted to <code>nresults</code>,
2586unless <code>nresults</code> is <a name="pdf-LUA_MULTRET"><code>LUA_MULTRET</code></a>.
2587In this case, <em>all</em> results from the function are pushed.
2588Lua takes care that the returned values fit into the stack space.
2589The function results are pushed onto the stack in direct order
2590(the first result is pushed first),
2591so that after the call the last result is on the top of the stack.
2592
2593
2594<p>
2595Any error inside the called function is propagated upwards
2596(with a <code>longjmp</code>).
2597
2598
2599<p>
2600The following example shows how the host program can do the
2601equivalent to this Lua code:
2602
2603<pre>
2604 a = f("how", t.x, 14)
2605</pre><p>
2606Here it is in&nbsp;C:
2607
2608<pre>
2609 lua_getfield(L, LUA_GLOBALSINDEX, "f"); /* function to be called */
2610 lua_pushstring(L, "how"); /* 1st argument */
2611 lua_getfield(L, LUA_GLOBALSINDEX, "t"); /* table to be indexed */
2612 lua_getfield(L, -1, "x"); /* push result of t.x (2nd arg) */
2613 lua_remove(L, -2); /* remove 't' from the stack */
2614 lua_pushinteger(L, 14); /* 3rd argument */
2615 lua_call(L, 3, 1); /* call 'f' with 3 arguments and 1 result */
2616 lua_setfield(L, LUA_GLOBALSINDEX, "a"); /* set global 'a' */
2617</pre><p>
2618Note that the code above is "balanced":
2619at its end, the stack is back to its original configuration.
2620This is considered good programming practice.
2621
2622
2623
2624
2625
2626<hr><h3><a name="lua_CFunction"><code>lua_CFunction</code></a></h3>
2627<pre>typedef int (*lua_CFunction) (lua_State *L);</pre>
2628
2629<p>
2630Type for C&nbsp;functions.
2631
2632
2633<p>
2634In order to communicate properly with Lua,
2635a C&nbsp;function must use the following protocol,
2636which defines the way parameters and results are passed:
2637a C&nbsp;function receives its arguments from Lua in its stack
2638in direct order (the first argument is pushed first).
2639So, when the function starts,
2640<code>lua_gettop(L)</code> returns the number of arguments received by the function.
2641The first argument (if any) is at index 1
2642and its last argument is at index <code>lua_gettop(L)</code>.
2643To return values to Lua, a C&nbsp;function just pushes them onto the stack,
2644in direct order (the first result is pushed first),
2645and returns the number of results.
2646Any other value in the stack below the results will be properly
2647discarded by Lua.
2648Like a Lua function, a C&nbsp;function called by Lua can also return
2649many results.
2650
2651
2652<p>
2653As an example, the following function receives a variable number
2654of numerical arguments and returns their average and sum:
2655
2656<pre>
2657 static int foo (lua_State *L) {
2658 int n = lua_gettop(L); /* number of arguments */
2659 lua_Number sum = 0;
2660 int i;
2661 for (i = 1; i &lt;= n; i++) {
2662 if (!lua_isnumber(L, i)) {
2663 lua_pushstring(L, "incorrect argument");
2664 lua_error(L);
2665 }
2666 sum += lua_tonumber(L, i);
2667 }
2668 lua_pushnumber(L, sum/n); /* first result */
2669 lua_pushnumber(L, sum); /* second result */
2670 return 2; /* number of results */
2671 }
2672</pre>
2673
2674
2675
2676
2677<hr><h3><a name="lua_checkstack"><code>lua_checkstack</code></a></h3><p>
2678<span class="apii">[-0, +0, <em>m</em>]</span>
2679<pre>int lua_checkstack (lua_State *L, int extra);</pre>
2680
2681<p>
2682Ensures that there are at least <code>extra</code> free stack slots in the stack.
2683It returns false if it cannot grow the stack to that size.
2684This function never shrinks the stack;
2685if the stack is already larger than the new size,
2686it is left unchanged.
2687
2688
2689
2690
2691
2692<hr><h3><a name="lua_close"><code>lua_close</code></a></h3><p>
2693<span class="apii">[-0, +0, <em>-</em>]</span>
2694<pre>void lua_close (lua_State *L);</pre>
2695
2696<p>
2697Destroys all objects in the given Lua state
2698(calling the corresponding garbage-collection metamethods, if any)
2699and frees all dynamic memory used by this state.
2700On several platforms, you may not need to call this function,
2701because all resources are naturally released when the host program ends.
2702On the other hand, long-running programs,
2703such as a daemon or a web server,
2704might need to release states as soon as they are not needed,
2705to avoid growing too large.
2706
2707
2708
2709
2710
2711<hr><h3><a name="lua_concat"><code>lua_concat</code></a></h3><p>
2712<span class="apii">[-n, +1, <em>e</em>]</span>
2713<pre>void lua_concat (lua_State *L, int n);</pre>
2714
2715<p>
2716Concatenates the <code>n</code> values at the top of the stack,
2717pops them, and leaves the result at the top.
2718If <code>n</code>&nbsp;is&nbsp;1, the result is the single value on the stack
2719(that is, the function does nothing);
2720if <code>n</code> is 0, the result is the empty string.
2721Concatenation is performed following the usual semantics of Lua
2722(see <a href="#2.5.4">&sect;2.5.4</a>).
2723
2724
2725
2726
2727
2728<hr><h3><a name="lua_cpcall"><code>lua_cpcall</code></a></h3><p>
2729<span class="apii">[-0, +(0|1), <em>-</em>]</span>
2730<pre>int lua_cpcall (lua_State *L, lua_CFunction func, void *ud);</pre>
2731
2732<p>
2733Calls the C&nbsp;function <code>func</code> in protected mode.
2734<code>func</code> starts with only one element in its stack,
2735a light userdata containing <code>ud</code>.
2736In case of errors,
2737<a href="#lua_cpcall"><code>lua_cpcall</code></a> returns the same error codes as <a href="#lua_pcall"><code>lua_pcall</code></a>,
2738plus the error object on the top of the stack;
2739otherwise, it returns zero, and does not change the stack.
2740All values returned by <code>func</code> are discarded.
2741
2742
2743
2744
2745
2746<hr><h3><a name="lua_createtable"><code>lua_createtable</code></a></h3><p>
2747<span class="apii">[-0, +1, <em>m</em>]</span>
2748<pre>void lua_createtable (lua_State *L, int narr, int nrec);</pre>
2749
2750<p>
2751Creates a new empty table and pushes it onto the stack.
2752The new table has space pre-allocated
2753for <code>narr</code> array elements and <code>nrec</code> non-array elements.
2754This pre-allocation is useful when you know exactly how many elements
2755the table will have.
2756Otherwise you can use the function <a href="#lua_newtable"><code>lua_newtable</code></a>.
2757
2758
2759
2760
2761
2762<hr><h3><a name="lua_dump"><code>lua_dump</code></a></h3><p>
2763<span class="apii">[-0, +0, <em>m</em>]</span>
2764<pre>int lua_dump (lua_State *L, lua_Writer writer, void *data);</pre>
2765
2766<p>
2767Dumps a function as a binary chunk.
2768Receives a Lua function on the top of the stack
2769and produces a binary chunk that,
2770if loaded again,
2771results in a function equivalent to the one dumped.
2772As it produces parts of the chunk,
2773<a href="#lua_dump"><code>lua_dump</code></a> calls function <code>writer</code> (see <a href="#lua_Writer"><code>lua_Writer</code></a>)
2774with the given <code>data</code>
2775to write them.
2776
2777
2778<p>
2779The value returned is the error code returned by the last
2780call to the writer;
27810&nbsp;means no errors.
2782
2783
2784<p>
2785This function does not pop the Lua function from the stack.
2786
2787
2788
2789
2790
2791<hr><h3><a name="lua_equal"><code>lua_equal</code></a></h3><p>
2792<span class="apii">[-0, +0, <em>e</em>]</span>
2793<pre>int lua_equal (lua_State *L, int index1, int index2);</pre>
2794
2795<p>
2796Returns 1 if the two values in acceptable indices <code>index1</code> and
2797<code>index2</code> are equal,
2798following the semantics of the Lua <code>==</code> operator
2799(that is, may call metamethods).
2800Otherwise returns&nbsp;0.
2801Also returns&nbsp;0 if any of the indices is non valid.
2802
2803
2804
2805
2806
2807<hr><h3><a name="lua_error"><code>lua_error</code></a></h3><p>
2808<span class="apii">[-1, +0, <em>v</em>]</span>
2809<pre>int lua_error (lua_State *L);</pre>
2810
2811<p>
2812Generates a Lua error.
2813The error message (which can actually be a Lua value of any type)
2814must be on the stack top.
2815This function does a long jump,
2816and therefore never returns.
2817(see <a href="#luaL_error"><code>luaL_error</code></a>).
2818
2819
2820
2821
2822
2823<hr><h3><a name="lua_gc"><code>lua_gc</code></a></h3><p>
2824<span class="apii">[-0, +0, <em>e</em>]</span>
2825<pre>int lua_gc (lua_State *L, int what, int data);</pre>
2826
2827<p>
2828Controls the garbage collector.
2829
2830
2831<p>
2832This function performs several tasks,
2833according to the value of the parameter <code>what</code>:
2834
2835<ul>
2836
2837<li><b><code>LUA_GCSTOP</code>:</b>
2838stops the garbage collector.
2839</li>
2840
2841<li><b><code>LUA_GCRESTART</code>:</b>
2842restarts the garbage collector.
2843</li>
2844
2845<li><b><code>LUA_GCCOLLECT</code>:</b>
2846performs a full garbage-collection cycle.
2847</li>
2848
2849<li><b><code>LUA_GCCOUNT</code>:</b>
2850returns the current amount of memory (in Kbytes) in use by Lua.
2851</li>
2852
2853<li><b><code>LUA_GCCOUNTB</code>:</b>
2854returns the remainder of dividing the current amount of bytes of
2855memory in use by Lua by 1024.
2856</li>
2857
2858<li><b><code>LUA_GCSTEP</code>:</b>
2859performs an incremental step of garbage collection.
2860The step "size" is controlled by <code>data</code>
2861(larger values mean more steps) in a non-specified way.
2862If you want to control the step size
2863you must experimentally tune the value of <code>data</code>.
2864The function returns 1 if the step finished a
2865garbage-collection cycle.
2866</li>
2867
2868<li><b><code>LUA_GCSETPAUSE</code>:</b>
2869sets <code>data</code> as the new value
2870for the <em>pause</em> of the collector (see <a href="#2.10">&sect;2.10</a>).
2871The function returns the previous value of the pause.
2872</li>
2873
2874<li><b><code>LUA_GCSETSTEPMUL</code>:</b>
2875sets <code>data</code> as the new value for the <em>step multiplier</em> of
2876the collector (see <a href="#2.10">&sect;2.10</a>).
2877The function returns the previous value of the step multiplier.
2878</li>
2879
2880</ul>
2881
2882
2883
2884
2885<hr><h3><a name="lua_getallocf"><code>lua_getallocf</code></a></h3><p>
2886<span class="apii">[-0, +0, <em>-</em>]</span>
2887<pre>lua_Alloc lua_getallocf (lua_State *L, void **ud);</pre>
2888
2889<p>
2890Returns the memory-allocation function of a given state.
2891If <code>ud</code> is not <code>NULL</code>, Lua stores in <code>*ud</code> the
2892opaque pointer passed to <a href="#lua_newstate"><code>lua_newstate</code></a>.
2893
2894
2895
2896
2897
2898<hr><h3><a name="lua_getfenv"><code>lua_getfenv</code></a></h3><p>
2899<span class="apii">[-0, +1, <em>-</em>]</span>
2900<pre>void lua_getfenv (lua_State *L, int index);</pre>
2901
2902<p>
2903Pushes onto the stack the environment table of
2904the value at the given index.
2905
2906
2907
2908
2909
2910<hr><h3><a name="lua_getfield"><code>lua_getfield</code></a></h3><p>
2911<span class="apii">[-0, +1, <em>e</em>]</span>
2912<pre>void lua_getfield (lua_State *L, int index, const char *k);</pre>
2913
2914<p>
2915Pushes onto the stack the value <code>t[k]</code>,
2916where <code>t</code> is the value at the given valid index.
2917As in Lua, this function may trigger a metamethod
2918for the "index" event (see <a href="#2.8">&sect;2.8</a>).
2919
2920
2921
2922
2923
2924<hr><h3><a name="lua_getglobal"><code>lua_getglobal</code></a></h3><p>
2925<span class="apii">[-0, +1, <em>e</em>]</span>
2926<pre>void lua_getglobal (lua_State *L, const char *name);</pre>
2927
2928<p>
2929Pushes onto the stack the value of the global <code>name</code>.
2930It is defined as a macro:
2931
2932<pre>
2933 #define lua_getglobal(L,s) lua_getfield(L, LUA_GLOBALSINDEX, s)
2934</pre>
2935
2936
2937
2938
2939<hr><h3><a name="lua_getmetatable"><code>lua_getmetatable</code></a></h3><p>
2940<span class="apii">[-0, +(0|1), <em>-</em>]</span>
2941<pre>int lua_getmetatable (lua_State *L, int index);</pre>
2942
2943<p>
2944Pushes onto the stack the metatable of the value at the given
2945acceptable index.
2946If the index is not valid,
2947or if the value does not have a metatable,
2948the function returns&nbsp;0 and pushes nothing on the stack.
2949
2950
2951
2952
2953
2954<hr><h3><a name="lua_gettable"><code>lua_gettable</code></a></h3><p>
2955<span class="apii">[-1, +1, <em>e</em>]</span>
2956<pre>void lua_gettable (lua_State *L, int index);</pre>
2957
2958<p>
2959Pushes onto the stack the value <code>t[k]</code>,
2960where <code>t</code> is the value at the given valid index
2961and <code>k</code> is the value at the top of the stack.
2962
2963
2964<p>
2965This function pops the key from the stack
2966(putting the resulting value in its place).
2967As in Lua, this function may trigger a metamethod
2968for the "index" event (see <a href="#2.8">&sect;2.8</a>).
2969
2970
2971
2972
2973
2974<hr><h3><a name="lua_gettop"><code>lua_gettop</code></a></h3><p>
2975<span class="apii">[-0, +0, <em>-</em>]</span>
2976<pre>int lua_gettop (lua_State *L);</pre>
2977
2978<p>
2979Returns the index of the top element in the stack.
2980Because indices start at&nbsp;1,
2981this result is equal to the number of elements in the stack
2982(and so 0&nbsp;means an empty stack).
2983
2984
2985
2986
2987
2988<hr><h3><a name="lua_insert"><code>lua_insert</code></a></h3><p>
2989<span class="apii">[-1, +1, <em>-</em>]</span>
2990<pre>void lua_insert (lua_State *L, int index);</pre>
2991
2992<p>
2993Moves the top element into the given valid index,
2994shifting up the elements above this index to open space.
2995Cannot be called with a pseudo-index,
2996because a pseudo-index is not an actual stack position.
2997
2998
2999
3000
3001
3002<hr><h3><a name="lua_Integer"><code>lua_Integer</code></a></h3>
3003<pre>typedef ptrdiff_t lua_Integer;</pre>
3004
3005<p>
3006The type used by the Lua API to represent integral values.
3007
3008
3009<p>
3010By default it is a <code>ptrdiff_t</code>,
3011which is usually the largest signed integral type the machine handles
3012"comfortably".
3013
3014
3015
3016
3017
3018<hr><h3><a name="lua_isboolean"><code>lua_isboolean</code></a></h3><p>
3019<span class="apii">[-0, +0, <em>-</em>]</span>
3020<pre>int lua_isboolean (lua_State *L, int index);</pre>
3021
3022<p>
3023Returns 1 if the value at the given acceptable index has type boolean,
3024and 0&nbsp;otherwise.
3025
3026
3027
3028
3029
3030<hr><h3><a name="lua_iscfunction"><code>lua_iscfunction</code></a></h3><p>
3031<span class="apii">[-0, +0, <em>-</em>]</span>
3032<pre>int lua_iscfunction (lua_State *L, int index);</pre>
3033
3034<p>
3035Returns 1 if the value at the given acceptable index is a C&nbsp;function,
3036and 0&nbsp;otherwise.
3037
3038
3039
3040
3041
3042<hr><h3><a name="lua_isfunction"><code>lua_isfunction</code></a></h3><p>
3043<span class="apii">[-0, +0, <em>-</em>]</span>
3044<pre>int lua_isfunction (lua_State *L, int index);</pre>
3045
3046<p>
3047Returns 1 if the value at the given acceptable index is a function
3048(either C or Lua), and 0&nbsp;otherwise.
3049
3050
3051
3052
3053
3054<hr><h3><a name="lua_islightuserdata"><code>lua_islightuserdata</code></a></h3><p>
3055<span class="apii">[-0, +0, <em>-</em>]</span>
3056<pre>int lua_islightuserdata (lua_State *L, int index);</pre>
3057
3058<p>
3059Returns 1 if the value at the given acceptable index is a light userdata,
3060and 0&nbsp;otherwise.
3061
3062
3063
3064
3065
3066<hr><h3><a name="lua_isnil"><code>lua_isnil</code></a></h3><p>
3067<span class="apii">[-0, +0, <em>-</em>]</span>
3068<pre>int lua_isnil (lua_State *L, int index);</pre>
3069
3070<p>
3071Returns 1 if the value at the given acceptable index is <b>nil</b>,
3072and 0&nbsp;otherwise.
3073
3074
3075
3076
3077
3078<hr><h3><a name="lua_isnone"><code>lua_isnone</code></a></h3><p>
3079<span class="apii">[-0, +0, <em>-</em>]</span>
3080<pre>int lua_isnone (lua_State *L, int index);</pre>
3081
3082<p>
3083Returns 1 if the given acceptable index is not valid
3084(that is, it refers to an element outside the current stack),
3085and 0&nbsp;otherwise.
3086
3087
3088
3089
3090
3091<hr><h3><a name="lua_isnoneornil"><code>lua_isnoneornil</code></a></h3><p>
3092<span class="apii">[-0, +0, <em>-</em>]</span>
3093<pre>int lua_isnoneornil (lua_State *L, int index);</pre>
3094
3095<p>
3096Returns 1 if the given acceptable index is not valid
3097(that is, it refers to an element outside the current stack)
3098or if the value at this index is <b>nil</b>,
3099and 0&nbsp;otherwise.
3100
3101
3102
3103
3104
3105<hr><h3><a name="lua_isnumber"><code>lua_isnumber</code></a></h3><p>
3106<span class="apii">[-0, +0, <em>-</em>]</span>
3107<pre>int lua_isnumber (lua_State *L, int index);</pre>
3108
3109<p>
3110Returns 1 if the value at the given acceptable index is a number
3111or a string convertible to a number,
3112and 0&nbsp;otherwise.
3113
3114
3115
3116
3117
3118<hr><h3><a name="lua_isstring"><code>lua_isstring</code></a></h3><p>
3119<span class="apii">[-0, +0, <em>-</em>]</span>
3120<pre>int lua_isstring (lua_State *L, int index);</pre>
3121
3122<p>
3123Returns 1 if the value at the given acceptable index is a string
3124or a number (which is always convertible to a string),
3125and 0&nbsp;otherwise.
3126
3127
3128
3129
3130
3131<hr><h3><a name="lua_istable"><code>lua_istable</code></a></h3><p>
3132<span class="apii">[-0, +0, <em>-</em>]</span>
3133<pre>int lua_istable (lua_State *L, int index);</pre>
3134
3135<p>
3136Returns 1 if the value at the given acceptable index is a table,
3137and 0&nbsp;otherwise.
3138
3139
3140
3141
3142
3143<hr><h3><a name="lua_isthread"><code>lua_isthread</code></a></h3><p>
3144<span class="apii">[-0, +0, <em>-</em>]</span>
3145<pre>int lua_isthread (lua_State *L, int index);</pre>
3146
3147<p>
3148Returns 1 if the value at the given acceptable index is a thread,
3149and 0&nbsp;otherwise.
3150
3151
3152
3153
3154
3155<hr><h3><a name="lua_isuserdata"><code>lua_isuserdata</code></a></h3><p>
3156<span class="apii">[-0, +0, <em>-</em>]</span>
3157<pre>int lua_isuserdata (lua_State *L, int index);</pre>
3158
3159<p>
3160Returns 1 if the value at the given acceptable index is a userdata
3161(either full or light), and 0&nbsp;otherwise.
3162
3163
3164
3165
3166
3167<hr><h3><a name="lua_lessthan"><code>lua_lessthan</code></a></h3><p>
3168<span class="apii">[-0, +0, <em>e</em>]</span>
3169<pre>int lua_lessthan (lua_State *L, int index1, int index2);</pre>
3170
3171<p>
3172Returns 1 if the value at acceptable index <code>index1</code> is smaller
3173than the value at acceptable index <code>index2</code>,
3174following the semantics of the Lua <code>&lt;</code> operator
3175(that is, may call metamethods).
3176Otherwise returns&nbsp;0.
3177Also returns&nbsp;0 if any of the indices is non valid.
3178
3179
3180
3181
3182
3183<hr><h3><a name="lua_load"><code>lua_load</code></a></h3><p>
3184<span class="apii">[-0, +1, <em>-</em>]</span>
3185<pre>int lua_load (lua_State *L,
3186 lua_Reader reader,
3187 void *data,
3188 const char *chunkname);</pre>
3189
3190<p>
3191Loads a Lua chunk.
3192If there are no errors,
3193<a href="#lua_load"><code>lua_load</code></a> pushes the compiled chunk as a Lua
3194function on top of the stack.
3195Otherwise, it pushes an error message.
3196The return values of <a href="#lua_load"><code>lua_load</code></a> are:
3197
3198<ul>
3199
3200<li><b>0:</b> no errors;</li>
3201
3202<li><b><a name="pdf-LUA_ERRSYNTAX"><code>LUA_ERRSYNTAX</code></a>:</b>
3203syntax error during pre-compilation;</li>
3204
3205<li><b><a href="#pdf-LUA_ERRMEM"><code>LUA_ERRMEM</code></a>:</b>
3206memory allocation error.</li>
3207
3208</ul>
3209
3210<p>
3211This function only loads a chunk;
3212it does not run it.
3213
3214
3215<p>
3216<a href="#lua_load"><code>lua_load</code></a> automatically detects whether the chunk is text or binary,
3217and loads it accordingly (see program <code>luac</code>).
3218
3219
3220<p>
3221The <a href="#lua_load"><code>lua_load</code></a> function uses a user-supplied <code>reader</code> function
3222to read the chunk (see <a href="#lua_Reader"><code>lua_Reader</code></a>).
3223The <code>data</code> argument is an opaque value passed to the reader function.
3224
3225
3226<p>
3227The <code>chunkname</code> argument gives a name to the chunk,
3228which is used for error messages and in debug information (see <a href="#3.8">&sect;3.8</a>).
3229
3230
3231
3232
3233
3234<hr><h3><a name="lua_newstate"><code>lua_newstate</code></a></h3><p>
3235<span class="apii">[-0, +0, <em>-</em>]</span>
3236<pre>lua_State *lua_newstate (lua_Alloc f, void *ud);</pre>
3237
3238<p>
3239Creates a new, independent state.
3240Returns <code>NULL</code> if cannot create the state
3241(due to lack of memory).
3242The argument <code>f</code> is the allocator function;
3243Lua does all memory allocation for this state through this function.
3244The second argument, <code>ud</code>, is an opaque pointer that Lua
3245simply passes to the allocator in every call.
3246
3247
3248
3249
3250
3251<hr><h3><a name="lua_newtable"><code>lua_newtable</code></a></h3><p>
3252<span class="apii">[-0, +1, <em>m</em>]</span>
3253<pre>void lua_newtable (lua_State *L);</pre>
3254
3255<p>
3256Creates a new empty table and pushes it onto the stack.
3257It is equivalent to <code>lua_createtable(L, 0, 0)</code>.
3258
3259
3260
3261
3262
3263<hr><h3><a name="lua_newthread"><code>lua_newthread</code></a></h3><p>
3264<span class="apii">[-0, +1, <em>m</em>]</span>
3265<pre>lua_State *lua_newthread (lua_State *L);</pre>
3266
3267<p>
3268Creates a new thread, pushes it on the stack,
3269and returns a pointer to a <a href="#lua_State"><code>lua_State</code></a> that represents this new thread.
3270The new state returned by this function shares with the original state
3271all global objects (such as tables),
3272but has an independent execution stack.
3273
3274
3275<p>
3276There is no explicit function to close or to destroy a thread.
3277Threads are subject to garbage collection,
3278like any Lua object.
3279
3280
3281
3282
3283
3284<hr><h3><a name="lua_newuserdata"><code>lua_newuserdata</code></a></h3><p>
3285<span class="apii">[-0, +1, <em>m</em>]</span>
3286<pre>void *lua_newuserdata (lua_State *L, size_t size);</pre>
3287
3288<p>
3289This function allocates a new block of memory with the given size,
3290pushes onto the stack a new full userdata with the block address,
3291and returns this address.
3292
3293
3294<p>
3295Userdata represent C&nbsp;values in Lua.
3296A <em>full userdata</em> represents a block of memory.
3297It is an object (like a table):
3298you must create it, it can have its own metatable,
3299and you can detect when it is being collected.
3300A full userdata is only equal to itself (under raw equality).
3301
3302
3303<p>
3304When Lua collects a full userdata with a <code>gc</code> metamethod,
3305Lua calls the metamethod and marks the userdata as finalized.
3306When this userdata is collected again then
3307Lua frees its corresponding memory.
3308
3309
3310
3311
3312
3313<hr><h3><a name="lua_next"><code>lua_next</code></a></h3><p>
3314<span class="apii">[-1, +(2|0), <em>e</em>]</span>
3315<pre>int lua_next (lua_State *L, int index);</pre>
3316
3317<p>
3318Pops a key from the stack,
3319and pushes a key-value pair from the table at the given index
3320(the "next" pair after the given key).
3321If there are no more elements in the table,
3322then <a href="#lua_next"><code>lua_next</code></a> returns 0 (and pushes nothing).
3323
3324
3325<p>
3326A typical traversal looks like this:
3327
3328<pre>
3329 /* table is in the stack at index 't' */
3330 lua_pushnil(L); /* first key */
3331 while (lua_next(L, t) != 0) {
3332 /* uses 'key' (at index -2) and 'value' (at index -1) */
3333 printf("%s - %s\n",
3334 lua_typename(L, lua_type(L, -2)),
3335 lua_typename(L, lua_type(L, -1)));
3336 /* removes 'value'; keeps 'key' for next iteration */
3337 lua_pop(L, 1);
3338 }
3339</pre>
3340
3341<p>
3342While traversing a table,
3343do not call <a href="#lua_tolstring"><code>lua_tolstring</code></a> directly on a key,
3344unless you know that the key is actually a string.
3345Recall that <a href="#lua_tolstring"><code>lua_tolstring</code></a> <em>changes</em>
3346the value at the given index;
3347this confuses the next call to <a href="#lua_next"><code>lua_next</code></a>.
3348
3349
3350
3351
3352
3353<hr><h3><a name="lua_Number"><code>lua_Number</code></a></h3>
3354<pre>typedef double lua_Number;</pre>
3355
3356<p>
3357The type of numbers in Lua.
3358By default, it is double, but that can be changed in <code>luaconf.h</code>.
3359
3360
3361<p>
3362Through the configuration file you can change
3363Lua to operate with another type for numbers (e.g., float or long).
3364
3365
3366
3367
3368
3369<hr><h3><a name="lua_objlen"><code>lua_objlen</code></a></h3><p>
3370<span class="apii">[-0, +0, <em>-</em>]</span>
3371<pre>size_t lua_objlen (lua_State *L, int index);</pre>
3372
3373<p>
3374Returns the "length" of the value at the given acceptable index:
3375for strings, this is the string length;
3376for tables, this is the result of the length operator ('<code>#</code>');
3377for userdata, this is the size of the block of memory allocated
3378for the userdata;
3379for other values, it is&nbsp;0.
3380
3381
3382
3383
3384
3385<hr><h3><a name="lua_pcall"><code>lua_pcall</code></a></h3><p>
3386<span class="apii">[-(nargs + 1), +(nresults|1), <em>-</em>]</span>
3387<pre>int lua_pcall (lua_State *L, int nargs, int nresults, int errfunc);</pre>
3388
3389<p>
3390Calls a function in protected mode.
3391
3392
3393<p>
3394Both <code>nargs</code> and <code>nresults</code> have the same meaning as
3395in <a href="#lua_call"><code>lua_call</code></a>.
3396If there are no errors during the call,
3397<a href="#lua_pcall"><code>lua_pcall</code></a> behaves exactly like <a href="#lua_call"><code>lua_call</code></a>.
3398However, if there is any error,
3399<a href="#lua_pcall"><code>lua_pcall</code></a> catches it,
3400pushes a single value on the stack (the error message),
3401and returns an error code.
3402Like <a href="#lua_call"><code>lua_call</code></a>,
3403<a href="#lua_pcall"><code>lua_pcall</code></a> always removes the function
3404and its arguments from the stack.
3405
3406
3407<p>
3408If <code>errfunc</code> is 0,
3409then the error message returned on the stack
3410is exactly the original error message.
3411Otherwise, <code>errfunc</code> is the stack index of an
3412<em>error handler function</em>.
3413(In the current implementation, this index cannot be a pseudo-index.)
3414In case of runtime errors,
3415this function will be called with the error message
3416and its return value will be the message returned on the stack by <a href="#lua_pcall"><code>lua_pcall</code></a>.
3417
3418
3419<p>
3420Typically, the error handler function is used to add more debug
3421information to the error message, such as a stack traceback.
3422Such information cannot be gathered after the return of <a href="#lua_pcall"><code>lua_pcall</code></a>,
3423since by then the stack has unwound.
3424
3425
3426<p>
3427The <a href="#lua_pcall"><code>lua_pcall</code></a> function returns 0 in case of success
3428or one of the following error codes
3429(defined in <code>lua.h</code>):
3430
3431<ul>
3432
3433<li><b><a name="pdf-LUA_ERRRUN"><code>LUA_ERRRUN</code></a>:</b>
3434a runtime error.
3435</li>
3436
3437<li><b><a name="pdf-LUA_ERRMEM"><code>LUA_ERRMEM</code></a>:</b>
3438memory allocation error.
3439For such errors, Lua does not call the error handler function.
3440</li>
3441
3442<li><b><a name="pdf-LUA_ERRERR"><code>LUA_ERRERR</code></a>:</b>
3443error while running the error handler function.
3444</li>
3445
3446</ul>
3447
3448
3449
3450
3451<hr><h3><a name="lua_pop"><code>lua_pop</code></a></h3><p>
3452<span class="apii">[-n, +0, <em>-</em>]</span>
3453<pre>void lua_pop (lua_State *L, int n);</pre>
3454
3455<p>
3456Pops <code>n</code> elements from the stack.
3457
3458
3459
3460
3461
3462<hr><h3><a name="lua_pushboolean"><code>lua_pushboolean</code></a></h3><p>
3463<span class="apii">[-0, +1, <em>-</em>]</span>
3464<pre>void lua_pushboolean (lua_State *L, int b);</pre>
3465
3466<p>
3467Pushes a boolean value with value <code>b</code> onto the stack.
3468
3469
3470
3471
3472
3473<hr><h3><a name="lua_pushcclosure"><code>lua_pushcclosure</code></a></h3><p>
3474<span class="apii">[-n, +1, <em>m</em>]</span>
3475<pre>void lua_pushcclosure (lua_State *L, lua_CFunction fn, int n);</pre>
3476
3477<p>
3478Pushes a new C&nbsp;closure onto the stack.
3479
3480
3481<p>
3482When a C&nbsp;function is created,
3483it is possible to associate some values with it,
3484thus creating a C&nbsp;closure (see <a href="#3.4">&sect;3.4</a>);
3485these values are then accessible to the function whenever it is called.
3486To associate values with a C&nbsp;function,
3487first these values should be pushed onto the stack
3488(when there are multiple values, the first value is pushed first).
3489Then <a href="#lua_pushcclosure"><code>lua_pushcclosure</code></a>
3490is called to create and push the C&nbsp;function onto the stack,
3491with the argument <code>n</code> telling how many values should be
3492associated with the function.
3493<a href="#lua_pushcclosure"><code>lua_pushcclosure</code></a> also pops these values from the stack.
3494
3495
3496<p>
3497The maximum value for <code>n</code> is 255.
3498
3499
3500
3501
3502
3503<hr><h3><a name="lua_pushcfunction"><code>lua_pushcfunction</code></a></h3><p>
3504<span class="apii">[-0, +1, <em>m</em>]</span>
3505<pre>void lua_pushcfunction (lua_State *L, lua_CFunction f);</pre>
3506
3507<p>
3508Pushes a C&nbsp;function onto the stack.
3509This function receives a pointer to a C function
3510and pushes onto the stack a Lua value of type <code>function</code> that,
3511when called, invokes the corresponding C&nbsp;function.
3512
3513
3514<p>
3515Any function to be registered in Lua must
3516follow the correct protocol to receive its parameters
3517and return its results (see <a href="#lua_CFunction"><code>lua_CFunction</code></a>).
3518
3519
3520<p>
3521<code>lua_pushcfunction</code> is defined as a macro:
3522
3523<pre>
3524 #define lua_pushcfunction(L,f) lua_pushcclosure(L,f,0)
3525</pre>
3526
3527
3528
3529
3530<hr><h3><a name="lua_pushfstring"><code>lua_pushfstring</code></a></h3><p>
3531<span class="apii">[-0, +1, <em>m</em>]</span>
3532<pre>const char *lua_pushfstring (lua_State *L, const char *fmt, ...);</pre>
3533
3534<p>
3535Pushes onto the stack a formatted string
3536and returns a pointer to this string.
3537It is similar to the C&nbsp;function <code>sprintf</code>,
3538but has some important differences:
3539
3540<ul>
3541
3542<li>
3543You do not have to allocate space for the result:
3544the result is a Lua string and Lua takes care of memory allocation
3545(and deallocation, through garbage collection).
3546</li>
3547
3548<li>
3549The conversion specifiers are quite restricted.
3550There are no flags, widths, or precisions.
3551The conversion specifiers can only be
3552'<code>%%</code>' (inserts a '<code>%</code>' in the string),
3553'<code>%s</code>' (inserts a zero-terminated string, with no size restrictions),
3554'<code>%f</code>' (inserts a <a href="#lua_Number"><code>lua_Number</code></a>),
3555'<code>%p</code>' (inserts a pointer as a hexadecimal numeral),
3556'<code>%d</code>' (inserts an <code>int</code>), and
3557'<code>%c</code>' (inserts an <code>int</code> as a character).
3558</li>
3559
3560</ul>
3561
3562
3563
3564
3565<hr><h3><a name="lua_pushinteger"><code>lua_pushinteger</code></a></h3><p>
3566<span class="apii">[-0, +1, <em>-</em>]</span>
3567<pre>void lua_pushinteger (lua_State *L, lua_Integer n);</pre>
3568
3569<p>
3570Pushes a number with value <code>n</code> onto the stack.
3571
3572
3573
3574
3575
3576<hr><h3><a name="lua_pushlightuserdata"><code>lua_pushlightuserdata</code></a></h3><p>
3577<span class="apii">[-0, +1, <em>-</em>]</span>
3578<pre>void lua_pushlightuserdata (lua_State *L, void *p);</pre>
3579
3580<p>
3581Pushes a light userdata onto the stack.
3582
3583
3584<p>
3585Userdata represent C&nbsp;values in Lua.
3586A <em>light userdata</em> represents a pointer.
3587It is a value (like a number):
3588you do not create it, it has no individual metatable,
3589and it is not collected (as it was never created).
3590A light userdata is equal to "any"
3591light userdata with the same C&nbsp;address.
3592
3593
3594
3595
3596
3597<hr><h3><a name="lua_pushliteral"><code>lua_pushliteral</code></a></h3><p>
3598<span class="apii">[-0, +1, <em>m</em>]</span>
3599<pre>void lua_pushliteral (lua_State *L, const char *s);</pre>
3600
3601<p>
3602This macro is equivalent to <a href="#lua_pushlstring"><code>lua_pushlstring</code></a>,
3603but can be used only when <code>s</code> is a literal string.
3604In these cases, it automatically provides the string length.
3605
3606
3607
3608
3609
3610<hr><h3><a name="lua_pushlstring"><code>lua_pushlstring</code></a></h3><p>
3611<span class="apii">[-0, +1, <em>m</em>]</span>
3612<pre>void lua_pushlstring (lua_State *L, const char *s, size_t len);</pre>
3613
3614<p>
3615Pushes the string pointed to by <code>s</code> with size <code>len</code>
3616onto the stack.
3617Lua makes (or reuses) an internal copy of the given string,
3618so the memory at <code>s</code> can be freed or reused immediately after
3619the function returns.
3620The string can contain embedded zeros.
3621
3622
3623
3624
3625
3626<hr><h3><a name="lua_pushnil"><code>lua_pushnil</code></a></h3><p>
3627<span class="apii">[-0, +1, <em>-</em>]</span>
3628<pre>void lua_pushnil (lua_State *L);</pre>
3629
3630<p>
3631Pushes a nil value onto the stack.
3632
3633
3634
3635
3636
3637<hr><h3><a name="lua_pushnumber"><code>lua_pushnumber</code></a></h3><p>
3638<span class="apii">[-0, +1, <em>-</em>]</span>
3639<pre>void lua_pushnumber (lua_State *L, lua_Number n);</pre>
3640
3641<p>
3642Pushes a number with value <code>n</code> onto the stack.
3643
3644
3645
3646
3647
3648<hr><h3><a name="lua_pushstring"><code>lua_pushstring</code></a></h3><p>
3649<span class="apii">[-0, +1, <em>m</em>]</span>
3650<pre>void lua_pushstring (lua_State *L, const char *s);</pre>
3651
3652<p>
3653Pushes the zero-terminated string pointed to by <code>s</code>
3654onto the stack.
3655Lua makes (or reuses) an internal copy of the given string,
3656so the memory at <code>s</code> can be freed or reused immediately after
3657the function returns.
3658The string cannot contain embedded zeros;
3659it is assumed to end at the first zero.
3660
3661
3662
3663
3664
3665<hr><h3><a name="lua_pushthread"><code>lua_pushthread</code></a></h3><p>
3666<span class="apii">[-0, +1, <em>-</em>]</span>
3667<pre>int lua_pushthread (lua_State *L);</pre>
3668
3669<p>
3670Pushes the thread represented by <code>L</code> onto the stack.
3671Returns 1 if this thread is the main thread of its state.
3672
3673
3674
3675
3676
3677<hr><h3><a name="lua_pushvalue"><code>lua_pushvalue</code></a></h3><p>
3678<span class="apii">[-0, +1, <em>-</em>]</span>
3679<pre>void lua_pushvalue (lua_State *L, int index);</pre>
3680
3681<p>
3682Pushes a copy of the element at the given valid index
3683onto the stack.
3684
3685
3686
3687
3688
3689<hr><h3><a name="lua_pushvfstring"><code>lua_pushvfstring</code></a></h3><p>
3690<span class="apii">[-0, +1, <em>m</em>]</span>
3691<pre>const char *lua_pushvfstring (lua_State *L,
3692 const char *fmt,
3693 va_list argp);</pre>
3694
3695<p>
3696Equivalent to <a href="#lua_pushfstring"><code>lua_pushfstring</code></a>, except that it receives a <code>va_list</code>
3697instead of a variable number of arguments.
3698
3699
3700
3701
3702
3703<hr><h3><a name="lua_rawequal"><code>lua_rawequal</code></a></h3><p>
3704<span class="apii">[-0, +0, <em>-</em>]</span>
3705<pre>int lua_rawequal (lua_State *L, int index1, int index2);</pre>
3706
3707<p>
3708Returns 1 if the two values in acceptable indices <code>index1</code> and
3709<code>index2</code> are primitively equal
3710(that is, without calling metamethods).
3711Otherwise returns&nbsp;0.
3712Also returns&nbsp;0 if any of the indices are non valid.
3713
3714
3715
3716
3717
3718<hr><h3><a name="lua_rawget"><code>lua_rawget</code></a></h3><p>
3719<span class="apii">[-1, +1, <em>-</em>]</span>
3720<pre>void lua_rawget (lua_State *L, int index);</pre>
3721
3722<p>
3723Similar to <a href="#lua_gettable"><code>lua_gettable</code></a>, but does a raw access
3724(i.e., without metamethods).
3725
3726
3727
3728
3729
3730<hr><h3><a name="lua_rawgeti"><code>lua_rawgeti</code></a></h3><p>
3731<span class="apii">[-0, +1, <em>-</em>]</span>
3732<pre>void lua_rawgeti (lua_State *L, int index, int n);</pre>
3733
3734<p>
3735Pushes onto the stack the value <code>t[n]</code>,
3736where <code>t</code> is the value at the given valid index.
3737The access is raw;
3738that is, it does not invoke metamethods.
3739
3740
3741
3742
3743
3744<hr><h3><a name="lua_rawset"><code>lua_rawset</code></a></h3><p>
3745<span class="apii">[-2, +0, <em>m</em>]</span>
3746<pre>void lua_rawset (lua_State *L, int index);</pre>
3747
3748<p>
3749Similar to <a href="#lua_settable"><code>lua_settable</code></a>, but does a raw assignment
3750(i.e., without metamethods).
3751
3752
3753
3754
3755
3756<hr><h3><a name="lua_rawseti"><code>lua_rawseti</code></a></h3><p>
3757<span class="apii">[-1, +0, <em>m</em>]</span>
3758<pre>void lua_rawseti (lua_State *L, int index, int n);</pre>
3759
3760<p>
3761Does the equivalent of <code>t[n] = v</code>,
3762where <code>t</code> is the value at the given valid index
3763and <code>v</code> is the value at the top of the stack.
3764
3765
3766<p>
3767This function pops the value from the stack.
3768The assignment is raw;
3769that is, it does not invoke metamethods.
3770
3771
3772
3773
3774
3775<hr><h3><a name="lua_Reader"><code>lua_Reader</code></a></h3>
3776<pre>typedef const char * (*lua_Reader) (lua_State *L,
3777 void *data,
3778 size_t *size);</pre>
3779
3780<p>
3781The reader function used by <a href="#lua_load"><code>lua_load</code></a>.
3782Every time it needs another piece of the chunk,
3783<a href="#lua_load"><code>lua_load</code></a> calls the reader,
3784passing along its <code>data</code> parameter.
3785The reader must return a pointer to a block of memory
3786with a new piece of the chunk
3787and set <code>size</code> to the block size.
3788The block must exist until the reader function is called again.
3789To signal the end of the chunk,
3790the reader must return <code>NULL</code> or set <code>size</code> to zero.
3791The reader function may return pieces of any size greater than zero.
3792
3793
3794
3795
3796
3797<hr><h3><a name="lua_register"><code>lua_register</code></a></h3><p>
3798<span class="apii">[-0, +0, <em>e</em>]</span>
3799<pre>void lua_register (lua_State *L,
3800 const char *name,
3801 lua_CFunction f);</pre>
3802
3803<p>
3804Sets the C function <code>f</code> as the new value of global <code>name</code>.
3805It is defined as a macro:
3806
3807<pre>
3808 #define lua_register(L,n,f) \
3809 (lua_pushcfunction(L, f), lua_setglobal(L, n))
3810</pre>
3811
3812
3813
3814
3815<hr><h3><a name="lua_remove"><code>lua_remove</code></a></h3><p>
3816<span class="apii">[-1, +0, <em>-</em>]</span>
3817<pre>void lua_remove (lua_State *L, int index);</pre>
3818
3819<p>
3820Removes the element at the given valid index,
3821shifting down the elements above this index to fill the gap.
3822Cannot be called with a pseudo-index,
3823because a pseudo-index is not an actual stack position.
3824
3825
3826
3827
3828
3829<hr><h3><a name="lua_replace"><code>lua_replace</code></a></h3><p>
3830<span class="apii">[-1, +0, <em>-</em>]</span>
3831<pre>void lua_replace (lua_State *L, int index);</pre>
3832
3833<p>
3834Moves the top element into the given position (and pops it),
3835without shifting any element
3836(therefore replacing the value at the given position).
3837
3838
3839
3840
3841
3842<hr><h3><a name="lua_resume"><code>lua_resume</code></a></h3><p>
3843<span class="apii">[-?, +?, <em>-</em>]</span>
3844<pre>int lua_resume (lua_State *L, int narg);</pre>
3845
3846<p>
3847Starts and resumes a coroutine in a given thread.
3848
3849
3850<p>
3851To start a coroutine, you first create a new thread
3852(see <a href="#lua_newthread"><code>lua_newthread</code></a>);
3853then you push onto its stack the main function plus any arguments;
3854then you call <a href="#lua_resume"><code>lua_resume</code></a>,
3855with <code>narg</code> being the number of arguments.
3856This call returns when the coroutine suspends or finishes its execution.
3857When it returns, the stack contains all values passed to <a href="#lua_yield"><code>lua_yield</code></a>,
3858or all values returned by the body function.
3859<a href="#lua_resume"><code>lua_resume</code></a> returns
3860<a href="#pdf-LUA_YIELD"><code>LUA_YIELD</code></a> if the coroutine yields,
38610 if the coroutine finishes its execution
3862without errors,
3863or an error code in case of errors (see <a href="#lua_pcall"><code>lua_pcall</code></a>).
3864In case of errors,
3865the stack is not unwound,
3866so you can use the debug API over it.
3867The error message is on the top of the stack.
3868To restart a coroutine, you put on its stack only the values to
3869be passed as results from <code>yield</code>,
3870and then call <a href="#lua_resume"><code>lua_resume</code></a>.
3871
3872
3873
3874
3875
3876<hr><h3><a name="lua_setallocf"><code>lua_setallocf</code></a></h3><p>
3877<span class="apii">[-0, +0, <em>-</em>]</span>
3878<pre>void lua_setallocf (lua_State *L, lua_Alloc f, void *ud);</pre>
3879
3880<p>
3881Changes the allocator function of a given state to <code>f</code>
3882with user data <code>ud</code>.
3883
3884
3885
3886
3887
3888<hr><h3><a name="lua_setfenv"><code>lua_setfenv</code></a></h3><p>
3889<span class="apii">[-1, +0, <em>-</em>]</span>
3890<pre>int lua_setfenv (lua_State *L, int index);</pre>
3891
3892<p>
3893Pops a table from the stack and sets it as
3894the new environment for the value at the given index.
3895If the value at the given index is
3896neither a function nor a thread nor a userdata,
3897<a href="#lua_setfenv"><code>lua_setfenv</code></a> returns 0.
3898Otherwise it returns 1.
3899
3900
3901
3902
3903
3904<hr><h3><a name="lua_setfield"><code>lua_setfield</code></a></h3><p>
3905<span class="apii">[-1, +0, <em>e</em>]</span>
3906<pre>void lua_setfield (lua_State *L, int index, const char *k);</pre>
3907
3908<p>
3909Does the equivalent to <code>t[k] = v</code>,
3910where <code>t</code> is the value at the given valid index
3911and <code>v</code> is the value at the top of the stack.
3912
3913
3914<p>
3915This function pops the value from the stack.
3916As in Lua, this function may trigger a metamethod
3917for the "newindex" event (see <a href="#2.8">&sect;2.8</a>).
3918
3919
3920
3921
3922
3923<hr><h3><a name="lua_setglobal"><code>lua_setglobal</code></a></h3><p>
3924<span class="apii">[-1, +0, <em>e</em>]</span>
3925<pre>void lua_setglobal (lua_State *L, const char *name);</pre>
3926
3927<p>
3928Pops a value from the stack and
3929sets it as the new value of global <code>name</code>.
3930It is defined as a macro:
3931
3932<pre>
3933 #define lua_setglobal(L,s) lua_setfield(L, LUA_GLOBALSINDEX, s)
3934</pre>
3935
3936
3937
3938
3939<hr><h3><a name="lua_setmetatable"><code>lua_setmetatable</code></a></h3><p>
3940<span class="apii">[-1, +0, <em>-</em>]</span>
3941<pre>int lua_setmetatable (lua_State *L, int index);</pre>
3942
3943<p>
3944Pops a table from the stack and
3945sets it as the new metatable for the value at the given
3946acceptable index.
3947
3948
3949
3950
3951
3952<hr><h3><a name="lua_settable"><code>lua_settable</code></a></h3><p>
3953<span class="apii">[-2, +0, <em>e</em>]</span>
3954<pre>void lua_settable (lua_State *L, int index);</pre>
3955
3956<p>
3957Does the equivalent to <code>t[k] = v</code>,
3958where <code>t</code> is the value at the given valid index,
3959<code>v</code> is the value at the top of the stack,
3960and <code>k</code> is the value just below the top.
3961
3962
3963<p>
3964This function pops both the key and the value from the stack.
3965As in Lua, this function may trigger a metamethod
3966for the "newindex" event (see <a href="#2.8">&sect;2.8</a>).
3967
3968
3969
3970
3971
3972<hr><h3><a name="lua_settop"><code>lua_settop</code></a></h3><p>
3973<span class="apii">[-?, +?, <em>-</em>]</span>
3974<pre>void lua_settop (lua_State *L, int index);</pre>
3975
3976<p>
3977Accepts any acceptable index, or&nbsp;0,
3978and sets the stack top to this index.
3979If the new top is larger than the old one,
3980then the new elements are filled with <b>nil</b>.
3981If <code>index</code> is&nbsp;0, then all stack elements are removed.
3982
3983
3984
3985
3986
3987<hr><h3><a name="lua_State"><code>lua_State</code></a></h3>
3988<pre>typedef struct lua_State lua_State;</pre>
3989
3990<p>
3991Opaque structure that keeps the whole state of a Lua interpreter.
3992The Lua library is fully reentrant:
3993it has no global variables.
3994All information about a state is kept in this structure.
3995
3996
3997<p>
3998A pointer to this state must be passed as the first argument to
3999every function in the library, except to <a href="#lua_newstate"><code>lua_newstate</code></a>,
4000which creates a Lua state from scratch.
4001
4002
4003
4004
4005
4006<hr><h3><a name="lua_status"><code>lua_status</code></a></h3><p>
4007<span class="apii">[-0, +0, <em>-</em>]</span>
4008<pre>int lua_status (lua_State *L);</pre>
4009
4010<p>
4011Returns the status of the thread <code>L</code>.
4012
4013
4014<p>
4015The status can be 0 for a normal thread,
4016an error code if the thread finished its execution with an error,
4017or <a name="pdf-LUA_YIELD"><code>LUA_YIELD</code></a> if the thread is suspended.
4018
4019
4020
4021
4022
4023<hr><h3><a name="lua_toboolean"><code>lua_toboolean</code></a></h3><p>
4024<span class="apii">[-0, +0, <em>-</em>]</span>
4025<pre>int lua_toboolean (lua_State *L, int index);</pre>
4026
4027<p>
4028Converts the Lua value at the given acceptable index to a C&nbsp;boolean
4029value (0&nbsp;or&nbsp;1).
4030Like all tests in Lua,
4031<a href="#lua_toboolean"><code>lua_toboolean</code></a> returns 1 for any Lua value
4032different from <b>false</b> and <b>nil</b>;
4033otherwise it returns 0.
4034It also returns 0 when called with a non-valid index.
4035(If you want to accept only actual boolean values,
4036use <a href="#lua_isboolean"><code>lua_isboolean</code></a> to test the value's type.)
4037
4038
4039
4040
4041
4042<hr><h3><a name="lua_tocfunction"><code>lua_tocfunction</code></a></h3><p>
4043<span class="apii">[-0, +0, <em>-</em>]</span>
4044<pre>lua_CFunction lua_tocfunction (lua_State *L, int index);</pre>
4045
4046<p>
4047Converts a value at the given acceptable index to a C&nbsp;function.
4048That value must be a C&nbsp;function;
4049otherwise, returns <code>NULL</code>.
4050
4051
4052
4053
4054
4055<hr><h3><a name="lua_tointeger"><code>lua_tointeger</code></a></h3><p>
4056<span class="apii">[-0, +0, <em>-</em>]</span>
4057<pre>lua_Integer lua_tointeger (lua_State *L, int index);</pre>
4058
4059<p>
4060Converts the Lua value at the given acceptable index
4061to the signed integral type <a href="#lua_Integer"><code>lua_Integer</code></a>.
4062The Lua value must be a number or a string convertible to a number
4063(see <a href="#2.2.1">&sect;2.2.1</a>);
4064otherwise, <a href="#lua_tointeger"><code>lua_tointeger</code></a> returns&nbsp;0.
4065
4066
4067<p>
4068If the number is not an integer,
4069it is truncated in some non-specified way.
4070
4071
4072
4073
4074
4075<hr><h3><a name="lua_tolstring"><code>lua_tolstring</code></a></h3><p>
4076<span class="apii">[-0, +0, <em>m</em>]</span>
4077<pre>const char *lua_tolstring (lua_State *L, int index, size_t *len);</pre>
4078
4079<p>
4080Converts the Lua value at the given acceptable index to a C&nbsp;string.
4081If <code>len</code> is not <code>NULL</code>,
4082it also sets <code>*len</code> with the string length.
4083The Lua value must be a string or a number;
4084otherwise, the function returns <code>NULL</code>.
4085If the value is a number,
4086then <a href="#lua_tolstring"><code>lua_tolstring</code></a> also
4087<em>changes the actual value in the stack to a string</em>.
4088(This change confuses <a href="#lua_next"><code>lua_next</code></a>
4089when <a href="#lua_tolstring"><code>lua_tolstring</code></a> is applied to keys during a table traversal.)
4090
4091
4092<p>
4093<a href="#lua_tolstring"><code>lua_tolstring</code></a> returns a fully aligned pointer
4094to a string inside the Lua state.
4095This string always has a zero ('<code>\0</code>')
4096after its last character (as in&nbsp;C),
4097but can contain other zeros in its body.
4098Because Lua has garbage collection,
4099there is no guarantee that the pointer returned by <a href="#lua_tolstring"><code>lua_tolstring</code></a>
4100will be valid after the corresponding value is removed from the stack.
4101
4102
4103
4104
4105
4106<hr><h3><a name="lua_tonumber"><code>lua_tonumber</code></a></h3><p>
4107<span class="apii">[-0, +0, <em>-</em>]</span>
4108<pre>lua_Number lua_tonumber (lua_State *L, int index);</pre>
4109
4110<p>
4111Converts the Lua value at the given acceptable index
4112to the C&nbsp;type <a href="#lua_Number"><code>lua_Number</code></a> (see <a href="#lua_Number"><code>lua_Number</code></a>).
4113The Lua value must be a number or a string convertible to a number
4114(see <a href="#2.2.1">&sect;2.2.1</a>);
4115otherwise, <a href="#lua_tonumber"><code>lua_tonumber</code></a> returns&nbsp;0.
4116
4117
4118
4119
4120
4121<hr><h3><a name="lua_topointer"><code>lua_topointer</code></a></h3><p>
4122<span class="apii">[-0, +0, <em>-</em>]</span>
4123<pre>const void *lua_topointer (lua_State *L, int index);</pre>
4124
4125<p>
4126Converts the value at the given acceptable index to a generic
4127C&nbsp;pointer (<code>void*</code>).
4128The value can be a userdata, a table, a thread, or a function;
4129otherwise, <a href="#lua_topointer"><code>lua_topointer</code></a> returns <code>NULL</code>.
4130Different objects will give different pointers.
4131There is no way to convert the pointer back to its original value.
4132
4133
4134<p>
4135Typically this function is used only for debug information.
4136
4137
4138
4139
4140
4141<hr><h3><a name="lua_tostring"><code>lua_tostring</code></a></h3><p>
4142<span class="apii">[-0, +0, <em>m</em>]</span>
4143<pre>const char *lua_tostring (lua_State *L, int index);</pre>
4144
4145<p>
4146Equivalent to <a href="#lua_tolstring"><code>lua_tolstring</code></a> with <code>len</code> equal to <code>NULL</code>.
4147
4148
4149
4150
4151
4152<hr><h3><a name="lua_tothread"><code>lua_tothread</code></a></h3><p>
4153<span class="apii">[-0, +0, <em>-</em>]</span>
4154<pre>lua_State *lua_tothread (lua_State *L, int index);</pre>
4155
4156<p>
4157Converts the value at the given acceptable index to a Lua thread
4158(represented as <code>lua_State*</code>).
4159This value must be a thread;
4160otherwise, the function returns <code>NULL</code>.
4161
4162
4163
4164
4165
4166<hr><h3><a name="lua_touserdata"><code>lua_touserdata</code></a></h3><p>
4167<span class="apii">[-0, +0, <em>-</em>]</span>
4168<pre>void *lua_touserdata (lua_State *L, int index);</pre>
4169
4170<p>
4171If the value at the given acceptable index is a full userdata,
4172returns its block address.
4173If the value is a light userdata,
4174returns its pointer.
4175Otherwise, returns <code>NULL</code>.
4176
4177
4178
4179
4180
4181<hr><h3><a name="lua_type"><code>lua_type</code></a></h3><p>
4182<span class="apii">[-0, +0, <em>-</em>]</span>
4183<pre>int lua_type (lua_State *L, int index);</pre>
4184
4185<p>
4186Returns the type of the value in the given acceptable index,
4187or <code>LUA_TNONE</code> for a non-valid index
4188(that is, an index to an "empty" stack position).
4189The types returned by <a href="#lua_type"><code>lua_type</code></a> are coded by the following constants
4190defined in <code>lua.h</code>:
4191<code>LUA_TNIL</code>,
4192<code>LUA_TNUMBER</code>,
4193<code>LUA_TBOOLEAN</code>,
4194<code>LUA_TSTRING</code>,
4195<code>LUA_TTABLE</code>,
4196<code>LUA_TFUNCTION</code>,
4197<code>LUA_TUSERDATA</code>,
4198<code>LUA_TTHREAD</code>,
4199and
4200<code>LUA_TLIGHTUSERDATA</code>.
4201
4202
4203
4204
4205
4206<hr><h3><a name="lua_typename"><code>lua_typename</code></a></h3><p>
4207<span class="apii">[-0, +0, <em>-</em>]</span>
4208<pre>const char *lua_typename (lua_State *L, int tp);</pre>
4209
4210<p>
4211Returns the name of the type encoded by the value <code>tp</code>,
4212which must be one the values returned by <a href="#lua_type"><code>lua_type</code></a>.
4213
4214
4215
4216
4217
4218<hr><h3><a name="lua_Writer"><code>lua_Writer</code></a></h3>
4219<pre>typedef int (*lua_Writer) (lua_State *L,
4220 const void* p,
4221 size_t sz,
4222 void* ud);</pre>
4223
4224<p>
4225The type of the writer function used by <a href="#lua_dump"><code>lua_dump</code></a>.
4226Every time it produces another piece of chunk,
4227<a href="#lua_dump"><code>lua_dump</code></a> calls the writer,
4228passing along the buffer to be written (<code>p</code>),
4229its size (<code>sz</code>),
4230and the <code>data</code> parameter supplied to <a href="#lua_dump"><code>lua_dump</code></a>.
4231
4232
4233<p>
4234The writer returns an error code:
42350&nbsp;means no errors;
4236any other value means an error and stops <a href="#lua_dump"><code>lua_dump</code></a> from
4237calling the writer again.
4238
4239
4240
4241
4242
4243<hr><h3><a name="lua_xmove"><code>lua_xmove</code></a></h3><p>
4244<span class="apii">[-?, +?, <em>-</em>]</span>
4245<pre>void lua_xmove (lua_State *from, lua_State *to, int n);</pre>
4246
4247<p>
4248Exchange values between different threads of the <em>same</em> global state.
4249
4250
4251<p>
4252This function pops <code>n</code> values from the stack <code>from</code>,
4253and pushes them onto the stack <code>to</code>.
4254
4255
4256
4257
4258
4259<hr><h3><a name="lua_yield"><code>lua_yield</code></a></h3><p>
4260<span class="apii">[-?, +?, <em>-</em>]</span>
4261<pre>int lua_yield (lua_State *L, int nresults);</pre>
4262
4263<p>
4264Yields a coroutine.
4265
4266
4267<p>
4268This function should only be called as the
4269return expression of a C&nbsp;function, as follows:
4270
4271<pre>
4272 return lua_yield (L, nresults);
4273</pre><p>
4274When a C&nbsp;function calls <a href="#lua_yield"><code>lua_yield</code></a> in that way,
4275the running coroutine suspends its execution,
4276and the call to <a href="#lua_resume"><code>lua_resume</code></a> that started this coroutine returns.
4277The parameter <code>nresults</code> is the number of values from the stack
4278that are passed as results to <a href="#lua_resume"><code>lua_resume</code></a>.
4279
4280
4281
4282
4283
4284
4285
4286<h2>3.8 - <a name="3.8">The Debug Interface</a></h2>
4287
4288<p>
4289Lua has no built-in debugging facilities.
4290Instead, it offers a special interface
4291by means of functions and <em>hooks</em>.
4292This interface allows the construction of different
4293kinds of debuggers, profilers, and other tools
4294that need "inside information" from the interpreter.
4295
4296
4297
4298<hr><h3><a name="lua_Debug"><code>lua_Debug</code></a></h3>
4299<pre>typedef struct lua_Debug {
4300 int event;
4301 const char *name; /* (n) */
4302 const char *namewhat; /* (n) */
4303 const char *what; /* (S) */
4304 const char *source; /* (S) */
4305 int currentline; /* (l) */
4306 int nups; /* (u) number of upvalues */
4307 int linedefined; /* (S) */
4308 int lastlinedefined; /* (S) */
4309 char short_src[LUA_IDSIZE]; /* (S) */
4310 /* private part */
4311 <em>other fields</em>
4312} lua_Debug;</pre>
4313
4314<p>
4315A structure used to carry different pieces of
4316information about an active function.
4317<a href="#lua_getstack"><code>lua_getstack</code></a> fills only the private part
4318of this structure, for later use.
4319To fill the other fields of <a href="#lua_Debug"><code>lua_Debug</code></a> with useful information,
4320call <a href="#lua_getinfo"><code>lua_getinfo</code></a>.
4321
4322
4323<p>
4324The fields of <a href="#lua_Debug"><code>lua_Debug</code></a> have the following meaning:
4325
4326<ul>
4327
4328<li><b><code>source</code>:</b>
4329If the function was defined in a string,
4330then <code>source</code> is that string.
4331If the function was defined in a file,
4332then <code>source</code> starts with a '<code>@</code>' followed by the file name.
4333</li>
4334
4335<li><b><code>short_src</code>:</b>
4336a "printable" version of <code>source</code>, to be used in error messages.
4337</li>
4338
4339<li><b><code>linedefined</code>:</b>
4340the line number where the definition of the function starts.
4341</li>
4342
4343<li><b><code>lastlinedefined</code>:</b>
4344the line number where the definition of the function ends.
4345</li>
4346
4347<li><b><code>what</code>:</b>
4348the string <code>"Lua"</code> if the function is a Lua function,
4349<code>"C"</code> if it is a C&nbsp;function,
4350<code>"main"</code> if it is the main part of a chunk,
4351and <code>"tail"</code> if it was a function that did a tail call.
4352In the latter case,
4353Lua has no other information about the function.
4354</li>
4355
4356<li><b><code>currentline</code>:</b>
4357the current line where the given function is executing.
4358When no line information is available,
4359<code>currentline</code> is set to -1.
4360</li>
4361
4362<li><b><code>name</code>:</b>
4363a reasonable name for the given function.
4364Because functions in Lua are first-class values,
4365they do not have a fixed name:
4366some functions can be the value of multiple global variables,
4367while others can be stored only in a table field.
4368The <code>lua_getinfo</code> function checks how the function was
4369called to find a suitable name.
4370If it cannot find a name,
4371then <code>name</code> is set to <code>NULL</code>.
4372</li>
4373
4374<li><b><code>namewhat</code>:</b>
4375explains the <code>name</code> field.
4376The value of <code>namewhat</code> can be
4377<code>"global"</code>, <code>"local"</code>, <code>"method"</code>,
4378<code>"field"</code>, <code>"upvalue"</code>, or <code>""</code> (the empty string),
4379according to how the function was called.
4380(Lua uses the empty string when no other option seems to apply.)
4381</li>
4382
4383<li><b><code>nups</code>:</b>
4384the number of upvalues of the function.
4385</li>
4386
4387</ul>
4388
4389
4390
4391
4392<hr><h3><a name="lua_gethook"><code>lua_gethook</code></a></h3><p>
4393<span class="apii">[-0, +0, <em>-</em>]</span>
4394<pre>lua_Hook lua_gethook (lua_State *L);</pre>
4395
4396<p>
4397Returns the current hook function.
4398
4399
4400
4401
4402
4403<hr><h3><a name="lua_gethookcount"><code>lua_gethookcount</code></a></h3><p>
4404<span class="apii">[-0, +0, <em>-</em>]</span>
4405<pre>int lua_gethookcount (lua_State *L);</pre>
4406
4407<p>
4408Returns the current hook count.
4409
4410
4411
4412
4413
4414<hr><h3><a name="lua_gethookmask"><code>lua_gethookmask</code></a></h3><p>
4415<span class="apii">[-0, +0, <em>-</em>]</span>
4416<pre>int lua_gethookmask (lua_State *L);</pre>
4417
4418<p>
4419Returns the current hook mask.
4420
4421
4422
4423
4424
4425<hr><h3><a name="lua_getinfo"><code>lua_getinfo</code></a></h3><p>
4426<span class="apii">[-(0|1), +(0|1|2), <em>m</em>]</span>
4427<pre>int lua_getinfo (lua_State *L, const char *what, lua_Debug *ar);</pre>
4428
4429<p>
4430Returns information about a specific function or function invocation.
4431
4432
4433<p>
4434To get information about a function invocation,
4435the parameter <code>ar</code> must be a valid activation record that was
4436filled by a previous call to <a href="#lua_getstack"><code>lua_getstack</code></a> or
4437given as argument to a hook (see <a href="#lua_Hook"><code>lua_Hook</code></a>).
4438
4439
4440<p>
4441To get information about a function you push it onto the stack
4442and start the <code>what</code> string with the character '<code>&gt;</code>'.
4443(In that case,
4444<code>lua_getinfo</code> pops the function in the top of the stack.)
4445For instance, to know in which line a function <code>f</code> was defined,
4446you can write the following code:
4447
4448<pre>
4449 lua_Debug ar;
4450 lua_getfield(L, LUA_GLOBALSINDEX, "f"); /* get global 'f' */
4451 lua_getinfo(L, "&gt;S", &amp;ar);
4452 printf("%d\n", ar.linedefined);
4453</pre>
4454
4455<p>
4456Each character in the string <code>what</code>
4457selects some fields of the structure <code>ar</code> to be filled or
4458a value to be pushed on the stack:
4459
4460<ul>
4461
4462<li><b>'<code>n</code>':</b> fills in the field <code>name</code> and <code>namewhat</code>;
4463</li>
4464
4465<li><b>'<code>S</code>':</b>
4466fills in the fields <code>source</code>, <code>short_src</code>,
4467<code>linedefined</code>, <code>lastlinedefined</code>, and <code>what</code>;
4468</li>
4469
4470<li><b>'<code>l</code>':</b> fills in the field <code>currentline</code>;
4471</li>
4472
4473<li><b>'<code>u</code>':</b> fills in the field <code>nups</code>;
4474</li>
4475
4476<li><b>'<code>f</code>':</b>
4477pushes onto the stack the function that is
4478running at the given level;
4479</li>
4480
4481<li><b>'<code>L</code>':</b>
4482pushes onto the stack a table whose indices are the
4483numbers of the lines that are valid on the function.
4484(A <em>valid line</em> is a line with some associated code,
4485that is, a line where you can put a break point.
4486Non-valid lines include empty lines and comments.)
4487</li>
4488
4489</ul>
4490
4491<p>
4492This function returns 0 on error
4493(for instance, an invalid option in <code>what</code>).
4494
4495
4496
4497
4498
4499<hr><h3><a name="lua_getlocal"><code>lua_getlocal</code></a></h3><p>
4500<span class="apii">[-0, +(0|1), <em>-</em>]</span>
4501<pre>const char *lua_getlocal (lua_State *L, lua_Debug *ar, int n);</pre>
4502
4503<p>
4504Gets information about a local variable of a given activation record.
4505The parameter <code>ar</code> must be a valid activation record that was
4506filled by a previous call to <a href="#lua_getstack"><code>lua_getstack</code></a> or
4507given as argument to a hook (see <a href="#lua_Hook"><code>lua_Hook</code></a>).
4508The index <code>n</code> selects which local variable to inspect
4509(1 is the first parameter or active local variable, and so on,
4510until the last active local variable).
4511<a href="#lua_getlocal"><code>lua_getlocal</code></a> pushes the variable's value onto the stack
4512and returns its name.
4513
4514
4515<p>
4516Variable names starting with '<code>(</code>' (open parentheses)
4517represent internal variables
4518(loop control variables, temporaries, and C&nbsp;function locals).
4519
4520
4521<p>
4522Returns <code>NULL</code> (and pushes nothing)
4523when the index is greater than
4524the number of active local variables.
4525
4526
4527
4528
4529
4530<hr><h3><a name="lua_getstack"><code>lua_getstack</code></a></h3><p>
4531<span class="apii">[-0, +0, <em>-</em>]</span>
4532<pre>int lua_getstack (lua_State *L, int level, lua_Debug *ar);</pre>
4533
4534<p>
4535Get information about the interpreter runtime stack.
4536
4537
4538<p>
4539This function fills parts of a <a href="#lua_Debug"><code>lua_Debug</code></a> structure with
4540an identification of the <em>activation record</em>
4541of the function executing at a given level.
4542Level&nbsp;0 is the current running function,
4543whereas level <em>n+1</em> is the function that has called level <em>n</em>.
4544When there are no errors, <a href="#lua_getstack"><code>lua_getstack</code></a> returns 1;
4545when called with a level greater than the stack depth,
4546it returns 0.
4547
4548
4549
4550
4551
4552<hr><h3><a name="lua_getupvalue"><code>lua_getupvalue</code></a></h3><p>
4553<span class="apii">[-0, +(0|1), <em>-</em>]</span>
4554<pre>const char *lua_getupvalue (lua_State *L, int funcindex, int n);</pre>
4555
4556<p>
4557Gets information about a closure's upvalue.
4558(For Lua functions,
4559upvalues are the external local variables that the function uses,
4560and that are consequently included in its closure.)
4561<a href="#lua_getupvalue"><code>lua_getupvalue</code></a> gets the index <code>n</code> of an upvalue,
4562pushes the upvalue's value onto the stack,
4563and returns its name.
4564<code>funcindex</code> points to the closure in the stack.
4565(Upvalues have no particular order,
4566as they are active through the whole function.
4567So, they are numbered in an arbitrary order.)
4568
4569
4570<p>
4571Returns <code>NULL</code> (and pushes nothing)
4572when the index is greater than the number of upvalues.
4573For C&nbsp;functions, this function uses the empty string <code>""</code>
4574as a name for all upvalues.
4575
4576
4577
4578
4579
4580<hr><h3><a name="lua_Hook"><code>lua_Hook</code></a></h3>
4581<pre>typedef void (*lua_Hook) (lua_State *L, lua_Debug *ar);</pre>
4582
4583<p>
4584Type for debugging hook functions.
4585
4586
4587<p>
4588Whenever a hook is called, its <code>ar</code> argument has its field
4589<code>event</code> set to the specific event that triggered the hook.
4590Lua identifies these events with the following constants:
4591<a name="pdf-LUA_HOOKCALL"><code>LUA_HOOKCALL</code></a>, <a name="pdf-LUA_HOOKRET"><code>LUA_HOOKRET</code></a>,
4592<a name="pdf-LUA_HOOKTAILRET"><code>LUA_HOOKTAILRET</code></a>, <a name="pdf-LUA_HOOKLINE"><code>LUA_HOOKLINE</code></a>,
4593and <a name="pdf-LUA_HOOKCOUNT"><code>LUA_HOOKCOUNT</code></a>.
4594Moreover, for line events, the field <code>currentline</code> is also set.
4595To get the value of any other field in <code>ar</code>,
4596the hook must call <a href="#lua_getinfo"><code>lua_getinfo</code></a>.
4597For return events, <code>event</code> can be <code>LUA_HOOKRET</code>,
4598the normal value, or <code>LUA_HOOKTAILRET</code>.
4599In the latter case, Lua is simulating a return from
4600a function that did a tail call;
4601in this case, it is useless to call <a href="#lua_getinfo"><code>lua_getinfo</code></a>.
4602
4603
4604<p>
4605While Lua is running a hook, it disables other calls to hooks.
4606Therefore, if a hook calls back Lua to execute a function or a chunk,
4607this execution occurs without any calls to hooks.
4608
4609
4610
4611
4612
4613<hr><h3><a name="lua_sethook"><code>lua_sethook</code></a></h3><p>
4614<span class="apii">[-0, +0, <em>-</em>]</span>
4615<pre>int lua_sethook (lua_State *L, lua_Hook f, int mask, int count);</pre>
4616
4617<p>
4618Sets the debugging hook function.
4619
4620
4621<p>
4622Argument <code>f</code> is the hook function.
4623<code>mask</code> specifies on which events the hook will be called:
4624it is formed by a bitwise or of the constants
4625<a name="pdf-LUA_MASKCALL"><code>LUA_MASKCALL</code></a>,
4626<a name="pdf-LUA_MASKRET"><code>LUA_MASKRET</code></a>,
4627<a name="pdf-LUA_MASKLINE"><code>LUA_MASKLINE</code></a>,
4628and <a name="pdf-LUA_MASKCOUNT"><code>LUA_MASKCOUNT</code></a>.
4629The <code>count</code> argument is only meaningful when the mask
4630includes <code>LUA_MASKCOUNT</code>.
4631For each event, the hook is called as explained below:
4632
4633<ul>
4634
4635<li><b>The call hook:</b> is called when the interpreter calls a function.
4636The hook is called just after Lua enters the new function,
4637before the function gets its arguments.
4638</li>
4639
4640<li><b>The return hook:</b> is called when the interpreter returns from a function.
4641The hook is called just before Lua leaves the function.
4642You have no access to the values to be returned by the function.
4643</li>
4644
4645<li><b>The line hook:</b> is called when the interpreter is about to
4646start the execution of a new line of code,
4647or when it jumps back in the code (even to the same line).
4648(This event only happens while Lua is executing a Lua function.)
4649</li>
4650
4651<li><b>The count hook:</b> is called after the interpreter executes every
4652<code>count</code> instructions.
4653(This event only happens while Lua is executing a Lua function.)
4654</li>
4655
4656</ul>
4657
4658<p>
4659A hook is disabled by setting <code>mask</code> to zero.
4660
4661
4662
4663
4664
4665<hr><h3><a name="lua_setlocal"><code>lua_setlocal</code></a></h3><p>
4666<span class="apii">[-(0|1), +0, <em>-</em>]</span>
4667<pre>const char *lua_setlocal (lua_State *L, lua_Debug *ar, int n);</pre>
4668
4669<p>
4670Sets the value of a local variable of a given activation record.
4671Parameters <code>ar</code> and <code>n</code> are as in <a href="#lua_getlocal"><code>lua_getlocal</code></a>
4672(see <a href="#lua_getlocal"><code>lua_getlocal</code></a>).
4673<a href="#lua_setlocal"><code>lua_setlocal</code></a> assigns the value at the top of the stack
4674to the variable and returns its name.
4675It also pops the value from the stack.
4676
4677
4678<p>
4679Returns <code>NULL</code> (and pops nothing)
4680when the index is greater than
4681the number of active local variables.
4682
4683
4684
4685
4686
4687<hr><h3><a name="lua_setupvalue"><code>lua_setupvalue</code></a></h3><p>
4688<span class="apii">[-(0|1), +0, <em>-</em>]</span>
4689<pre>const char *lua_setupvalue (lua_State *L, int funcindex, int n);</pre>
4690
4691<p>
4692Sets the value of a closure's upvalue.
4693It assigns the value at the top of the stack
4694to the upvalue and returns its name.
4695It also pops the value from the stack.
4696Parameters <code>funcindex</code> and <code>n</code> are as in the <a href="#lua_getupvalue"><code>lua_getupvalue</code></a>
4697(see <a href="#lua_getupvalue"><code>lua_getupvalue</code></a>).
4698
4699
4700<p>
4701Returns <code>NULL</code> (and pops nothing)
4702when the index is greater than the number of upvalues.
4703
4704
4705
4706
4707
4708
4709
4710<h1>4 - <a name="4">The Auxiliary Library</a></h1>
4711
4712<p>
4713
4714The <em>auxiliary library</em> provides several convenient functions
4715to interface C with Lua.
4716While the basic API provides the primitive functions for all
4717interactions between C and Lua,
4718the auxiliary library provides higher-level functions for some
4719common tasks.
4720
4721
4722<p>
4723All functions from the auxiliary library
4724are defined in header file <code>lauxlib.h</code> and
4725have a prefix <code>luaL_</code>.
4726
4727
4728<p>
4729All functions in the auxiliary library are built on
4730top of the basic API,
4731and so they provide nothing that cannot be done with this API.
4732
4733
4734<p>
4735Several functions in the auxiliary library are used to
4736check C&nbsp;function arguments.
4737Their names are always <code>luaL_check*</code> or <code>luaL_opt*</code>.
4738All of these functions throw an error if the check is not satisfied.
4739Because the error message is formatted for arguments
4740(e.g., "<code>bad argument #1</code>"),
4741you should not use these functions for other stack values.
4742
4743
4744
4745<h2>4.1 - <a name="4.1">Functions and Types</a></h2>
4746
4747<p>
4748Here we list all functions and types from the auxiliary library
4749in alphabetical order.
4750
4751
4752
4753<hr><h3><a name="luaL_addchar"><code>luaL_addchar</code></a></h3><p>
4754<span class="apii">[-0, +0, <em>m</em>]</span>
4755<pre>void luaL_addchar (luaL_Buffer *B, char c);</pre>
4756
4757<p>
4758Adds the character <code>c</code> to the buffer <code>B</code>
4759(see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>).
4760
4761
4762
4763
4764
4765<hr><h3><a name="luaL_addlstring"><code>luaL_addlstring</code></a></h3><p>
4766<span class="apii">[-0, +0, <em>m</em>]</span>
4767<pre>void luaL_addlstring (luaL_Buffer *B, const char *s, size_t l);</pre>
4768
4769<p>
4770Adds the string pointed to by <code>s</code> with length <code>l</code> to
4771the buffer <code>B</code>
4772(see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>).
4773The string may contain embedded zeros.
4774
4775
4776
4777
4778
4779<hr><h3><a name="luaL_addsize"><code>luaL_addsize</code></a></h3><p>
4780<span class="apii">[-0, +0, <em>m</em>]</span>
4781<pre>void luaL_addsize (luaL_Buffer *B, size_t n);</pre>
4782
4783<p>
4784Adds to the buffer <code>B</code> (see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>)
4785a string of length <code>n</code> previously copied to the
4786buffer area (see <a href="#luaL_prepbuffer"><code>luaL_prepbuffer</code></a>).
4787
4788
4789
4790
4791
4792<hr><h3><a name="luaL_addstring"><code>luaL_addstring</code></a></h3><p>
4793<span class="apii">[-0, +0, <em>m</em>]</span>
4794<pre>void luaL_addstring (luaL_Buffer *B, const char *s);</pre>
4795
4796<p>
4797Adds the zero-terminated string pointed to by <code>s</code>
4798to the buffer <code>B</code>
4799(see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>).
4800The string may not contain embedded zeros.
4801
4802
4803
4804
4805
4806<hr><h3><a name="luaL_addvalue"><code>luaL_addvalue</code></a></h3><p>
4807<span class="apii">[-1, +0, <em>m</em>]</span>
4808<pre>void luaL_addvalue (luaL_Buffer *B);</pre>
4809
4810<p>
4811Adds the value at the top of the stack
4812to the buffer <code>B</code>
4813(see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>).
4814Pops the value.
4815
4816
4817<p>
4818This is the only function on string buffers that can (and must)
4819be called with an extra element on the stack,
4820which is the value to be added to the buffer.
4821
4822
4823
4824
4825
4826<hr><h3><a name="luaL_argcheck"><code>luaL_argcheck</code></a></h3><p>
4827<span class="apii">[-0, +0, <em>v</em>]</span>
4828<pre>void luaL_argcheck (lua_State *L,
4829 int cond,
4830 int narg,
4831 const char *extramsg);</pre>
4832
4833<p>
4834Checks whether <code>cond</code> is true.
4835If not, raises an error with the following message,
4836where <code>func</code> is retrieved from the call stack:
4837
4838<pre>
4839 bad argument #&lt;narg&gt; to &lt;func&gt; (&lt;extramsg&gt;)
4840</pre>
4841
4842
4843
4844
4845<hr><h3><a name="luaL_argerror"><code>luaL_argerror</code></a></h3><p>
4846<span class="apii">[-0, +0, <em>v</em>]</span>
4847<pre>int luaL_argerror (lua_State *L, int narg, const char *extramsg);</pre>
4848
4849<p>
4850Raises an error with the following message,
4851where <code>func</code> is retrieved from the call stack:
4852
4853<pre>
4854 bad argument #&lt;narg&gt; to &lt;func&gt; (&lt;extramsg&gt;)
4855</pre>
4856
4857<p>
4858This function never returns,
4859but it is an idiom to use it in C&nbsp;functions
4860as <code>return luaL_argerror(<em>args</em>)</code>.
4861
4862
4863
4864
4865
4866<hr><h3><a name="luaL_Buffer"><code>luaL_Buffer</code></a></h3>
4867<pre>typedef struct luaL_Buffer luaL_Buffer;</pre>
4868
4869<p>
4870Type for a <em>string buffer</em>.
4871
4872
4873<p>
4874A string buffer allows C&nbsp;code to build Lua strings piecemeal.
4875Its pattern of use is as follows:
4876
4877<ul>
4878
4879<li>First you declare a variable <code>b</code> of type <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>.</li>
4880
4881<li>Then you initialize it with a call <code>luaL_buffinit(L, &amp;b)</code>.</li>
4882
4883<li>
4884Then you add string pieces to the buffer calling any of
4885the <code>luaL_add*</code> functions.
4886</li>
4887
4888<li>
4889You finish by calling <code>luaL_pushresult(&amp;b)</code>.
4890This call leaves the final string on the top of the stack.
4891</li>
4892
4893</ul>
4894
4895<p>
4896During its normal operation,
4897a string buffer uses a variable number of stack slots.
4898So, while using a buffer, you cannot assume that you know where
4899the top of the stack is.
4900You can use the stack between successive calls to buffer operations
4901as long as that use is balanced;
4902that is,
4903when you call a buffer operation,
4904the stack is at the same level
4905it was immediately after the previous buffer operation.
4906(The only exception to this rule is <a href="#luaL_addvalue"><code>luaL_addvalue</code></a>.)
4907After calling <a href="#luaL_pushresult"><code>luaL_pushresult</code></a> the stack is back to its
4908level when the buffer was initialized,
4909plus the final string on its top.
4910
4911
4912
4913
4914
4915<hr><h3><a name="luaL_buffinit"><code>luaL_buffinit</code></a></h3><p>
4916<span class="apii">[-0, +0, <em>-</em>]</span>
4917<pre>void luaL_buffinit (lua_State *L, luaL_Buffer *B);</pre>
4918
4919<p>
4920Initializes a buffer <code>B</code>.
4921This function does not allocate any space;
4922the buffer must be declared as a variable
4923(see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>).
4924
4925
4926
4927
4928
4929<hr><h3><a name="luaL_callmeta"><code>luaL_callmeta</code></a></h3><p>
4930<span class="apii">[-0, +(0|1), <em>e</em>]</span>
4931<pre>int luaL_callmeta (lua_State *L, int obj, const char *e);</pre>
4932
4933<p>
4934Calls a metamethod.
4935
4936
4937<p>
4938If the object at index <code>obj</code> has a metatable and this
4939metatable has a field <code>e</code>,
4940this function calls this field and passes the object as its only argument.
4941In this case this function returns 1 and pushes onto the
4942stack the value returned by the call.
4943If there is no metatable or no metamethod,
4944this function returns 0 (without pushing any value on the stack).
4945
4946
4947
4948
4949
4950<hr><h3><a name="luaL_checkany"><code>luaL_checkany</code></a></h3><p>
4951<span class="apii">[-0, +0, <em>v</em>]</span>
4952<pre>void luaL_checkany (lua_State *L, int narg);</pre>
4953
4954<p>
4955Checks whether the function has an argument
4956of any type (including <b>nil</b>) at position <code>narg</code>.
4957
4958
4959
4960
4961
4962<hr><h3><a name="luaL_checkint"><code>luaL_checkint</code></a></h3><p>
4963<span class="apii">[-0, +0, <em>v</em>]</span>
4964<pre>int luaL_checkint (lua_State *L, int narg);</pre>
4965
4966<p>
4967Checks whether the function argument <code>narg</code> is a number
4968and returns this number cast to an <code>int</code>.
4969
4970
4971
4972
4973
4974<hr><h3><a name="luaL_checkinteger"><code>luaL_checkinteger</code></a></h3><p>
4975<span class="apii">[-0, +0, <em>v</em>]</span>
4976<pre>lua_Integer luaL_checkinteger (lua_State *L, int narg);</pre>
4977
4978<p>
4979Checks whether the function argument <code>narg</code> is a number
4980and returns this number cast to a <a href="#lua_Integer"><code>lua_Integer</code></a>.
4981
4982
4983
4984
4985
4986<hr><h3><a name="luaL_checklong"><code>luaL_checklong</code></a></h3><p>
4987<span class="apii">[-0, +0, <em>v</em>]</span>
4988<pre>long luaL_checklong (lua_State *L, int narg);</pre>
4989
4990<p>
4991Checks whether the function argument <code>narg</code> is a number
4992and returns this number cast to a <code>long</code>.
4993
4994
4995
4996
4997
4998<hr><h3><a name="luaL_checklstring"><code>luaL_checklstring</code></a></h3><p>
4999<span class="apii">[-0, +0, <em>v</em>]</span>
5000<pre>const char *luaL_checklstring (lua_State *L, int narg, size_t *l);</pre>
5001
5002<p>
5003Checks whether the function argument <code>narg</code> is a string
5004and returns this string;
5005if <code>l</code> is not <code>NULL</code> fills <code>*l</code>
5006with the string's length.
5007
5008
5009<p>
5010This function uses <a href="#lua_tolstring"><code>lua_tolstring</code></a> to get its result,
5011so all conversions and caveats of that function apply here.
5012
5013
5014
5015
5016
5017<hr><h3><a name="luaL_checknumber"><code>luaL_checknumber</code></a></h3><p>
5018<span class="apii">[-0, +0, <em>v</em>]</span>
5019<pre>lua_Number luaL_checknumber (lua_State *L, int narg);</pre>
5020
5021<p>
5022Checks whether the function argument <code>narg</code> is a number
5023and returns this number.
5024
5025
5026
5027
5028
5029<hr><h3><a name="luaL_checkoption"><code>luaL_checkoption</code></a></h3><p>
5030<span class="apii">[-0, +0, <em>v</em>]</span>
5031<pre>int luaL_checkoption (lua_State *L,
5032 int narg,
5033 const char *def,
5034 const char *const lst[]);</pre>
5035
5036<p>
5037Checks whether the function argument <code>narg</code> is a string and
5038searches for this string in the array <code>lst</code>
5039(which must be NULL-terminated).
5040Returns the index in the array where the string was found.
5041Raises an error if the argument is not a string or
5042if the string cannot be found.
5043
5044
5045<p>
5046If <code>def</code> is not <code>NULL</code>,
5047the function uses <code>def</code> as a default value when
5048there is no argument <code>narg</code> or if this argument is <b>nil</b>.
5049
5050
5051<p>
5052This is a useful function for mapping strings to C&nbsp;enums.
5053(The usual convention in Lua libraries is
5054to use strings instead of numbers to select options.)
5055
5056
5057
5058
5059
5060<hr><h3><a name="luaL_checkstack"><code>luaL_checkstack</code></a></h3><p>
5061<span class="apii">[-0, +0, <em>v</em>]</span>
5062<pre>void luaL_checkstack (lua_State *L, int sz, const char *msg);</pre>
5063
5064<p>
5065Grows the stack size to <code>top + sz</code> elements,
5066raising an error if the stack cannot grow to that size.
5067<code>msg</code> is an additional text to go into the error message.
5068
5069
5070
5071
5072
5073<hr><h3><a name="luaL_checkstring"><code>luaL_checkstring</code></a></h3><p>
5074<span class="apii">[-0, +0, <em>v</em>]</span>
5075<pre>const char *luaL_checkstring (lua_State *L, int narg);</pre>
5076
5077<p>
5078Checks whether the function argument <code>narg</code> is a string
5079and returns this string.
5080
5081
5082<p>
5083This function uses <a href="#lua_tolstring"><code>lua_tolstring</code></a> to get its result,
5084so all conversions and caveats of that function apply here.
5085
5086
5087
5088
5089
5090<hr><h3><a name="luaL_checktype"><code>luaL_checktype</code></a></h3><p>
5091<span class="apii">[-0, +0, <em>v</em>]</span>
5092<pre>void luaL_checktype (lua_State *L, int narg, int t);</pre>
5093
5094<p>
5095Checks whether the function argument <code>narg</code> has type <code>t</code>.
5096See <a href="#lua_type"><code>lua_type</code></a> for the encoding of types for <code>t</code>.
5097
5098
5099
5100
5101
5102<hr><h3><a name="luaL_checkudata"><code>luaL_checkudata</code></a></h3><p>
5103<span class="apii">[-0, +0, <em>v</em>]</span>
5104<pre>void *luaL_checkudata (lua_State *L, int narg, const char *tname);</pre>
5105
5106<p>
5107Checks whether the function argument <code>narg</code> is a userdata
5108of the type <code>tname</code> (see <a href="#luaL_newmetatable"><code>luaL_newmetatable</code></a>).
5109
5110
5111
5112
5113
5114<hr><h3><a name="luaL_dofile"><code>luaL_dofile</code></a></h3><p>
5115<span class="apii">[-0, +?, <em>m</em>]</span>
5116<pre>int luaL_dofile (lua_State *L, const char *filename);</pre>
5117
5118<p>
5119Loads and runs the given file.
5120It is defined as the following macro:
5121
5122<pre>
5123 (luaL_loadfile(L, filename) || lua_pcall(L, 0, LUA_MULTRET, 0))
5124</pre><p>
5125It returns 0 if there are no errors
5126or 1 in case of errors.
5127
5128
5129
5130
5131
5132<hr><h3><a name="luaL_dostring"><code>luaL_dostring</code></a></h3><p>
5133<span class="apii">[-0, +?, <em>m</em>]</span>
5134<pre>int luaL_dostring (lua_State *L, const char *str);</pre>
5135
5136<p>
5137Loads and runs the given string.
5138It is defined as the following macro:
5139
5140<pre>
5141 (luaL_loadstring(L, str) || lua_pcall(L, 0, LUA_MULTRET, 0))
5142</pre><p>
5143It returns 0 if there are no errors
5144or 1 in case of errors.
5145
5146
5147
5148
5149
5150<hr><h3><a name="luaL_error"><code>luaL_error</code></a></h3><p>
5151<span class="apii">[-0, +0, <em>v</em>]</span>
5152<pre>int luaL_error (lua_State *L, const char *fmt, ...);</pre>
5153
5154<p>
5155Raises an error.
5156The error message format is given by <code>fmt</code>
5157plus any extra arguments,
5158following the same rules of <a href="#lua_pushfstring"><code>lua_pushfstring</code></a>.
5159It also adds at the beginning of the message the file name and
5160the line number where the error occurred,
5161if this information is available.
5162
5163
5164<p>
5165This function never returns,
5166but it is an idiom to use it in C&nbsp;functions
5167as <code>return luaL_error(<em>args</em>)</code>.
5168
5169
5170
5171
5172
5173<hr><h3><a name="luaL_getmetafield"><code>luaL_getmetafield</code></a></h3><p>
5174<span class="apii">[-0, +(0|1), <em>m</em>]</span>
5175<pre>int luaL_getmetafield (lua_State *L, int obj, const char *e);</pre>
5176
5177<p>
5178Pushes onto the stack the field <code>e</code> from the metatable
5179of the object at index <code>obj</code>.
5180If the object does not have a metatable,
5181or if the metatable does not have this field,
5182returns 0 and pushes nothing.
5183
5184
5185
5186
5187
5188<hr><h3><a name="luaL_getmetatable"><code>luaL_getmetatable</code></a></h3><p>
5189<span class="apii">[-0, +1, <em>-</em>]</span>
5190<pre>void luaL_getmetatable (lua_State *L, const char *tname);</pre>
5191
5192<p>
5193Pushes onto the stack the metatable associated with name <code>tname</code>
5194in the registry (see <a href="#luaL_newmetatable"><code>luaL_newmetatable</code></a>).
5195
5196
5197
5198
5199
5200<hr><h3><a name="luaL_gsub"><code>luaL_gsub</code></a></h3><p>
5201<span class="apii">[-0, +1, <em>m</em>]</span>
5202<pre>const char *luaL_gsub (lua_State *L,
5203 const char *s,
5204 const char *p,
5205 const char *r);</pre>
5206
5207<p>
5208Creates a copy of string <code>s</code> by replacing
5209any occurrence of the string <code>p</code>
5210with the string <code>r</code>.
5211Pushes the resulting string on the stack and returns it.
5212
5213
5214
5215
5216
5217<hr><h3><a name="luaL_loadbuffer"><code>luaL_loadbuffer</code></a></h3><p>
5218<span class="apii">[-0, +1, <em>m</em>]</span>
5219<pre>int luaL_loadbuffer (lua_State *L,
5220 const char *buff,
5221 size_t sz,
5222 const char *name);</pre>
5223
5224<p>
5225Loads a buffer as a Lua chunk.
5226This function uses <a href="#lua_load"><code>lua_load</code></a> to load the chunk in the
5227buffer pointed to by <code>buff</code> with size <code>sz</code>.
5228
5229
5230<p>
5231This function returns the same results as <a href="#lua_load"><code>lua_load</code></a>.
5232<code>name</code> is the chunk name,
5233used for debug information and error messages.
5234
5235
5236
5237
5238
5239<hr><h3><a name="luaL_loadfile"><code>luaL_loadfile</code></a></h3><p>
5240<span class="apii">[-0, +1, <em>m</em>]</span>
5241<pre>int luaL_loadfile (lua_State *L, const char *filename);</pre>
5242
5243<p>
5244Loads a file as a Lua chunk.
5245This function uses <a href="#lua_load"><code>lua_load</code></a> to load the chunk in the file
5246named <code>filename</code>.
5247If <code>filename</code> is <code>NULL</code>,
5248then it loads from the standard input.
5249The first line in the file is ignored if it starts with a <code>#</code>.
5250
5251
5252<p>
5253This function returns the same results as <a href="#lua_load"><code>lua_load</code></a>,
5254but it has an extra error code <a name="pdf-LUA_ERRFILE"><code>LUA_ERRFILE</code></a>
5255if it cannot open/read the file.
5256
5257
5258<p>
5259As <a href="#lua_load"><code>lua_load</code></a>, this function only loads the chunk;
5260it does not run it.
5261
5262
5263
5264
5265
5266<hr><h3><a name="luaL_loadstring"><code>luaL_loadstring</code></a></h3><p>
5267<span class="apii">[-0, +1, <em>m</em>]</span>
5268<pre>int luaL_loadstring (lua_State *L, const char *s);</pre>
5269
5270<p>
5271Loads a string as a Lua chunk.
5272This function uses <a href="#lua_load"><code>lua_load</code></a> to load the chunk in
5273the zero-terminated string <code>s</code>.
5274
5275
5276<p>
5277This function returns the same results as <a href="#lua_load"><code>lua_load</code></a>.
5278
5279
5280<p>
5281Also as <a href="#lua_load"><code>lua_load</code></a>, this function only loads the chunk;
5282it does not run it.
5283
5284
5285
5286
5287
5288<hr><h3><a name="luaL_newmetatable"><code>luaL_newmetatable</code></a></h3><p>
5289<span class="apii">[-0, +1, <em>m</em>]</span>
5290<pre>int luaL_newmetatable (lua_State *L, const char *tname);</pre>
5291
5292<p>
5293If the registry already has the key <code>tname</code>,
5294returns 0.
5295Otherwise,
5296creates a new table to be used as a metatable for userdata,
5297adds it to the registry with key <code>tname</code>,
5298and returns 1.
5299
5300
5301<p>
5302In both cases pushes onto the stack the final value associated
5303with <code>tname</code> in the registry.
5304
5305
5306
5307
5308
5309<hr><h3><a name="luaL_newstate"><code>luaL_newstate</code></a></h3><p>
5310<span class="apii">[-0, +0, <em>-</em>]</span>
5311<pre>lua_State *luaL_newstate (void);</pre>
5312
5313<p>
5314Creates a new Lua state.
5315It calls <a href="#lua_newstate"><code>lua_newstate</code></a> with an
5316allocator based on the standard&nbsp;C <code>realloc</code> function
5317and then sets a panic function (see <a href="#lua_atpanic"><code>lua_atpanic</code></a>) that prints
5318an error message to the standard error output in case of fatal
5319errors.
5320
5321
5322<p>
5323Returns the new state,
5324or <code>NULL</code> if there is a memory allocation error.
5325
5326
5327
5328
5329
5330<hr><h3><a name="luaL_openlibs"><code>luaL_openlibs</code></a></h3><p>
5331<span class="apii">[-0, +0, <em>m</em>]</span>
5332<pre>void luaL_openlibs (lua_State *L);</pre>
5333
5334<p>
5335Opens all standard Lua libraries into the given state.
5336
5337
5338
5339
5340
5341<hr><h3><a name="luaL_optint"><code>luaL_optint</code></a></h3><p>
5342<span class="apii">[-0, +0, <em>v</em>]</span>
5343<pre>int luaL_optint (lua_State *L, int narg, int d);</pre>
5344
5345<p>
5346If the function argument <code>narg</code> is a number,
5347returns this number cast to an <code>int</code>.
5348If this argument is absent or is <b>nil</b>,
5349returns <code>d</code>.
5350Otherwise, raises an error.
5351
5352
5353
5354
5355
5356<hr><h3><a name="luaL_optinteger"><code>luaL_optinteger</code></a></h3><p>
5357<span class="apii">[-0, +0, <em>v</em>]</span>
5358<pre>lua_Integer luaL_optinteger (lua_State *L,
5359 int narg,
5360 lua_Integer d);</pre>
5361
5362<p>
5363If the function argument <code>narg</code> is a number,
5364returns this number cast to a <a href="#lua_Integer"><code>lua_Integer</code></a>.
5365If this argument is absent or is <b>nil</b>,
5366returns <code>d</code>.
5367Otherwise, raises an error.
5368
5369
5370
5371
5372
5373<hr><h3><a name="luaL_optlong"><code>luaL_optlong</code></a></h3><p>
5374<span class="apii">[-0, +0, <em>v</em>]</span>
5375<pre>long luaL_optlong (lua_State *L, int narg, long d);</pre>
5376
5377<p>
5378If the function argument <code>narg</code> is a number,
5379returns this number cast to a <code>long</code>.
5380If this argument is absent or is <b>nil</b>,
5381returns <code>d</code>.
5382Otherwise, raises an error.
5383
5384
5385
5386
5387
5388<hr><h3><a name="luaL_optlstring"><code>luaL_optlstring</code></a></h3><p>
5389<span class="apii">[-0, +0, <em>v</em>]</span>
5390<pre>const char *luaL_optlstring (lua_State *L,
5391 int narg,
5392 const char *d,
5393 size_t *l);</pre>
5394
5395<p>
5396If the function argument <code>narg</code> is a string,
5397returns this string.
5398If this argument is absent or is <b>nil</b>,
5399returns <code>d</code>.
5400Otherwise, raises an error.
5401
5402
5403<p>
5404If <code>l</code> is not <code>NULL</code>,
5405fills the position <code>*l</code> with the results's length.
5406
5407
5408
5409
5410
5411<hr><h3><a name="luaL_optnumber"><code>luaL_optnumber</code></a></h3><p>
5412<span class="apii">[-0, +0, <em>v</em>]</span>
5413<pre>lua_Number luaL_optnumber (lua_State *L, int narg, lua_Number d);</pre>
5414
5415<p>
5416If the function argument <code>narg</code> is a number,
5417returns this number.
5418If this argument is absent or is <b>nil</b>,
5419returns <code>d</code>.
5420Otherwise, raises an error.
5421
5422
5423
5424
5425
5426<hr><h3><a name="luaL_optstring"><code>luaL_optstring</code></a></h3><p>
5427<span class="apii">[-0, +0, <em>v</em>]</span>
5428<pre>const char *luaL_optstring (lua_State *L,
5429 int narg,
5430 const char *d);</pre>
5431
5432<p>
5433If the function argument <code>narg</code> is a string,
5434returns this string.
5435If this argument is absent or is <b>nil</b>,
5436returns <code>d</code>.
5437Otherwise, raises an error.
5438
5439
5440
5441
5442
5443<hr><h3><a name="luaL_prepbuffer"><code>luaL_prepbuffer</code></a></h3><p>
5444<span class="apii">[-0, +0, <em>-</em>]</span>
5445<pre>char *luaL_prepbuffer (luaL_Buffer *B);</pre>
5446
5447<p>
5448Returns an address to a space of size <a name="pdf-LUAL_BUFFERSIZE"><code>LUAL_BUFFERSIZE</code></a>
5449where you can copy a string to be added to buffer <code>B</code>
5450(see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>).
5451After copying the string into this space you must call
5452<a href="#luaL_addsize"><code>luaL_addsize</code></a> with the size of the string to actually add
5453it to the buffer.
5454
5455
5456
5457
5458
5459<hr><h3><a name="luaL_pushresult"><code>luaL_pushresult</code></a></h3><p>
5460<span class="apii">[-?, +1, <em>m</em>]</span>
5461<pre>void luaL_pushresult (luaL_Buffer *B);</pre>
5462
5463<p>
5464Finishes the use of buffer <code>B</code> leaving the final string on
5465the top of the stack.
5466
5467
5468
5469
5470
5471<hr><h3><a name="luaL_ref"><code>luaL_ref</code></a></h3><p>
5472<span class="apii">[-1, +0, <em>m</em>]</span>
5473<pre>int luaL_ref (lua_State *L, int t);</pre>
5474
5475<p>
5476Creates and returns a <em>reference</em>,
5477in the table at index <code>t</code>,
5478for the object at the top of the stack (and pops the object).
5479
5480
5481<p>
5482A reference is a unique integer key.
5483As long as you do not manually add integer keys into table <code>t</code>,
5484<a href="#luaL_ref"><code>luaL_ref</code></a> ensures the uniqueness of the key it returns.
5485You can retrieve an object referred by reference <code>r</code>
5486by calling <code>lua_rawgeti(L, t, r)</code>.
5487Function <a href="#luaL_unref"><code>luaL_unref</code></a> frees a reference and its associated object.
5488
5489
5490<p>
5491If the object at the top of the stack is <b>nil</b>,
5492<a href="#luaL_ref"><code>luaL_ref</code></a> returns the constant <a name="pdf-LUA_REFNIL"><code>LUA_REFNIL</code></a>.
5493The constant <a name="pdf-LUA_NOREF"><code>LUA_NOREF</code></a> is guaranteed to be different
5494from any reference returned by <a href="#luaL_ref"><code>luaL_ref</code></a>.
5495
5496
5497
5498
5499
5500<hr><h3><a name="luaL_Reg"><code>luaL_Reg</code></a></h3>
5501<pre>typedef struct luaL_Reg {
5502 const char *name;
5503 lua_CFunction func;
5504} luaL_Reg;</pre>
5505
5506<p>
5507Type for arrays of functions to be registered by
5508<a href="#luaL_register"><code>luaL_register</code></a>.
5509<code>name</code> is the function name and <code>func</code> is a pointer to
5510the function.
5511Any array of <a href="#luaL_Reg"><code>luaL_Reg</code></a> must end with an sentinel entry
5512in which both <code>name</code> and <code>func</code> are <code>NULL</code>.
5513
5514
5515
5516
5517
5518<hr><h3><a name="luaL_register"><code>luaL_register</code></a></h3><p>
5519<span class="apii">[-(0|1), +1, <em>m</em>]</span>
5520<pre>void luaL_register (lua_State *L,
5521 const char *libname,
5522 const luaL_Reg *l);</pre>
5523
5524<p>
5525Opens a library.
5526
5527
5528<p>
5529When called with <code>libname</code> equal to <code>NULL</code>,
5530it simply registers all functions in the list <code>l</code>
5531(see <a href="#luaL_Reg"><code>luaL_Reg</code></a>) into the table on the top of the stack.
5532
5533
5534<p>
5535When called with a non-null <code>libname</code>,
5536<code>luaL_register</code> creates a new table <code>t</code>,
5537sets it as the value of the global variable <code>libname</code>,
5538sets it as the value of <code>package.loaded[libname]</code>,
5539and registers on it all functions in the list <code>l</code>.
5540If there is a table in <code>package.loaded[libname]</code> or in
5541variable <code>libname</code>,
5542reuses this table instead of creating a new one.
5543
5544
5545<p>
5546In any case the function leaves the table
5547on the top of the stack.
5548
5549
5550
5551
5552
5553<hr><h3><a name="luaL_typename"><code>luaL_typename</code></a></h3><p>
5554<span class="apii">[-0, +0, <em>-</em>]</span>
5555<pre>const char *luaL_typename (lua_State *L, int index);</pre>
5556
5557<p>
5558Returns the name of the type of the value at the given index.
5559
5560
5561
5562
5563
5564<hr><h3><a name="luaL_typerror"><code>luaL_typerror</code></a></h3><p>
5565<span class="apii">[-0, +0, <em>v</em>]</span>
5566<pre>int luaL_typerror (lua_State *L, int narg, const char *tname);</pre>
5567
5568<p>
5569Generates an error with a message like the following:
5570
5571<pre>
5572 <em>location</em>: bad argument <em>narg</em> to '<em>func</em>' (<em>tname</em> expected, got <em>rt</em>)
5573</pre><p>
5574where <code><em>location</em></code> is produced by <a href="#luaL_where"><code>luaL_where</code></a>,
5575<code><em>func</em></code> is the name of the current function,
5576and <code><em>rt</em></code> is the type name of the actual argument.
5577
5578
5579
5580
5581
5582<hr><h3><a name="luaL_unref"><code>luaL_unref</code></a></h3><p>
5583<span class="apii">[-0, +0, <em>-</em>]</span>
5584<pre>void luaL_unref (lua_State *L, int t, int ref);</pre>
5585
5586<p>
5587Releases reference <code>ref</code> from the table at index <code>t</code>
5588(see <a href="#luaL_ref"><code>luaL_ref</code></a>).
5589The entry is removed from the table,
5590so that the referred object can be collected.
5591The reference <code>ref</code> is also freed to be used again.
5592
5593
5594<p>
5595If <code>ref</code> is <a href="#pdf-LUA_NOREF"><code>LUA_NOREF</code></a> or <a href="#pdf-LUA_REFNIL"><code>LUA_REFNIL</code></a>,
5596<a href="#luaL_unref"><code>luaL_unref</code></a> does nothing.
5597
5598
5599
5600
5601
5602<hr><h3><a name="luaL_where"><code>luaL_where</code></a></h3><p>
5603<span class="apii">[-0, +1, <em>m</em>]</span>
5604<pre>void luaL_where (lua_State *L, int lvl);</pre>
5605
5606<p>
5607Pushes onto the stack a string identifying the current position
5608of the control at level <code>lvl</code> in the call stack.
5609Typically this string has the following format:
5610
5611<pre>
5612 <em>chunkname</em>:<em>currentline</em>:
5613</pre><p>
5614Level&nbsp;0 is the running function,
5615level&nbsp;1 is the function that called the running function,
5616etc.
5617
5618
5619<p>
5620This function is used to build a prefix for error messages.
5621
5622
5623
5624
5625
5626
5627
5628<h1>5 - <a name="5">Standard Libraries</a></h1>
5629
5630<p>
5631The standard Lua libraries provide useful functions
5632that are implemented directly through the C&nbsp;API.
5633Some of these functions provide essential services to the language
5634(e.g., <a href="#pdf-type"><code>type</code></a> and <a href="#pdf-getmetatable"><code>getmetatable</code></a>);
5635others provide access to "outside" services (e.g., I/O);
5636and others could be implemented in Lua itself,
5637but are quite useful or have critical performance requirements that
5638deserve an implementation in C (e.g., <a href="#pdf-table.sort"><code>table.sort</code></a>).
5639
5640
5641<p>
5642All libraries are implemented through the official C&nbsp;API
5643and are provided as separate C&nbsp;modules.
5644Currently, Lua has the following standard libraries:
5645
5646<ul>
5647
5648<li>basic library,</li> which includes the coroutine sub-library;
5649
5650<li>package library;</li>
5651
5652<li>string manipulation;</li>
5653
5654<li>table manipulation;</li>
5655
5656<li>mathematical functions (sin, log, etc.);</li>
5657
5658<li>input and output;</li>
5659
5660<li>operating system facilities;</li>
5661
5662<li>debug facilities.</li>
5663
5664</ul><p>
5665Except for the basic and package libraries,
5666each library provides all its functions as fields of a global table
5667or as methods of its objects.
5668
5669
5670<p>
5671To have access to these libraries,
5672the C&nbsp;host program should call the <a href="#luaL_openlibs"><code>luaL_openlibs</code></a> function,
5673which opens all standard libraries.
5674Alternatively,
5675it can open them individually by calling
5676<a name="pdf-luaopen_base"><code>luaopen_base</code></a> (for the basic library),
5677<a name="pdf-luaopen_package"><code>luaopen_package</code></a> (for the package library),
5678<a name="pdf-luaopen_string"><code>luaopen_string</code></a> (for the string library),
5679<a name="pdf-luaopen_table"><code>luaopen_table</code></a> (for the table library),
5680<a name="pdf-luaopen_math"><code>luaopen_math</code></a> (for the mathematical library),
5681<a name="pdf-luaopen_io"><code>luaopen_io</code></a> (for the I/O library),
5682<a name="pdf-luaopen_os"><code>luaopen_os</code></a> (for the Operating System library),
5683and <a name="pdf-luaopen_debug"><code>luaopen_debug</code></a> (for the debug library).
5684These functions are declared in <a name="pdf-lualib.h"><code>lualib.h</code></a>
5685and should not be called directly:
5686you must call them like any other Lua C&nbsp;function,
5687e.g., by using <a href="#lua_call"><code>lua_call</code></a>.
5688
5689
5690
5691<h2>5.1 - <a name="5.1">Basic Functions</a></h2>
5692
5693<p>
5694The basic library provides some core functions to Lua.
5695If you do not include this library in your application,
5696you should check carefully whether you need to provide
5697implementations for some of its facilities.
5698
5699
5700<p>
5701<hr><h3><a name="pdf-assert"><code>assert (v [, message])</code></a></h3>
5702Issues an error when
5703the value of its argument <code>v</code> is false (i.e., <b>nil</b> or <b>false</b>);
5704otherwise, returns all its arguments.
5705<code>message</code> is an error message;
5706when absent, it defaults to "assertion failed!"
5707
5708
5709
5710
5711<p>
5712<hr><h3><a name="pdf-collectgarbage"><code>collectgarbage (opt [, arg])</code></a></h3>
5713
5714
5715<p>
5716This function is a generic interface to the garbage collector.
5717It performs different functions according to its first argument, <code>opt</code>:
5718
5719<ul>
5720
5721<li><b>"stop":</b>
5722stops the garbage collector.
5723</li>
5724
5725<li><b>"restart":</b>
5726restarts the garbage collector.
5727</li>
5728
5729<li><b>"collect":</b>
5730performs a full garbage-collection cycle.
5731</li>
5732
5733<li><b>"count":</b>
5734returns the total memory in use by Lua (in Kbytes).
5735</li>
5736
5737<li><b>"step":</b>
5738performs a garbage-collection step.
5739The step "size" is controlled by <code>arg</code>
5740(larger values mean more steps) in a non-specified way.
5741If you want to control the step size
5742you must experimentally tune the value of <code>arg</code>.
5743Returns <b>true</b> if the step finished a collection cycle.
5744</li>
5745
5746<li><b>"setpause":</b>
5747sets <code>arg</code> as the new value for the <em>pause</em> of
5748the collector (see <a href="#2.10">&sect;2.10</a>).
5749Returns the previous value for <em>pause</em>.
5750</li>
5751
5752<li><b>"setstepmul":</b>
5753sets <code>arg</code> as the new value for the <em>step multiplier</em> of
5754the collector (see <a href="#2.10">&sect;2.10</a>).
5755Returns the previous value for <em>step</em>.
5756</li>
5757
5758</ul>
5759
5760
5761
5762<p>
5763<hr><h3><a name="pdf-dofile"><code>dofile (filename)</code></a></h3>
5764Opens the named file and executes its contents as a Lua chunk.
5765When called without arguments,
5766<code>dofile</code> executes the contents of the standard input (<code>stdin</code>).
5767Returns all values returned by the chunk.
5768In case of errors, <code>dofile</code> propagates the error
5769to its caller (that is, <code>dofile</code> does not run in protected mode).
5770
5771
5772
5773
5774<p>
5775<hr><h3><a name="pdf-error"><code>error (message [, level])</code></a></h3>
5776Terminates the last protected function called
5777and returns <code>message</code> as the error message.
5778Function <code>error</code> never returns.
5779
5780
5781<p>
5782Usually, <code>error</code> adds some information about the error position
5783at the beginning of the message.
5784The <code>level</code> argument specifies how to get the error position.
5785With level&nbsp;1 (the default), the error position is where the
5786<code>error</code> function was called.
5787Level&nbsp;2 points the error to where the function
5788that called <code>error</code> was called; and so on.
5789Passing a level&nbsp;0 avoids the addition of error position information
5790to the message.
5791
5792
5793
5794
5795<p>
5796<hr><h3><a name="pdf-_G"><code>_G</code></a></h3>
5797A global variable (not a function) that
5798holds the global environment (that is, <code>_G._G = _G</code>).
5799Lua itself does not use this variable;
5800changing its value does not affect any environment,
5801nor vice-versa.
5802(Use <a href="#pdf-setfenv"><code>setfenv</code></a> to change environments.)
5803
5804
5805
5806
5807<p>
5808<hr><h3><a name="pdf-getfenv"><code>getfenv ([f])</code></a></h3>
5809Returns the current environment in use by the function.
5810<code>f</code> can be a Lua function or a number
5811that specifies the function at that stack level:
5812Level&nbsp;1 is the function calling <code>getfenv</code>.
5813If the given function is not a Lua function,
5814or if <code>f</code> is 0,
5815<code>getfenv</code> returns the global environment.
5816The default for <code>f</code> is 1.
5817
5818
5819
5820
5821<p>
5822<hr><h3><a name="pdf-getmetatable"><code>getmetatable (object)</code></a></h3>
5823
5824
5825<p>
5826If <code>object</code> does not have a metatable, returns <b>nil</b>.
5827Otherwise,
5828if the object's metatable has a <code>"__metatable"</code> field,
5829returns the associated value.
5830Otherwise, returns the metatable of the given object.
5831
5832
5833
5834
5835<p>
5836<hr><h3><a name="pdf-ipairs"><code>ipairs (t)</code></a></h3>
5837
5838
5839<p>
5840Returns three values: an iterator function, the table <code>t</code>, and 0,
5841so that the construction
5842
5843<pre>
5844 for i,v in ipairs(t) do <em>body</em> end
5845</pre><p>
5846will iterate over the pairs (<code>1,t[1]</code>), (<code>2,t[2]</code>), &middot;&middot;&middot;,
5847up to the first integer key absent from the table.
5848
5849
5850
5851
5852<p>
5853<hr><h3><a name="pdf-load"><code>load (func [, chunkname])</code></a></h3>
5854
5855
5856<p>
5857Loads a chunk using function <code>func</code> to get its pieces.
5858Each call to <code>func</code> must return a string that concatenates
5859with previous results.
5860A return of an empty string, <b>nil</b>, or no value signals the end of the chunk.
5861
5862
5863<p>
5864If there are no errors,
5865returns the compiled chunk as a function;
5866otherwise, returns <b>nil</b> plus the error message.
5867The environment of the returned function is the global environment.
5868
5869
5870<p>
5871<code>chunkname</code> is used as the chunk name for error messages
5872and debug information.
5873When absent,
5874it defaults to "<code>=(load)</code>".
5875
5876
5877
5878
5879<p>
5880<hr><h3><a name="pdf-loadfile"><code>loadfile ([filename])</code></a></h3>
5881
5882
5883<p>
5884Similar to <a href="#pdf-load"><code>load</code></a>,
5885but gets the chunk from file <code>filename</code>
5886or from the standard input,
5887if no file name is given.
5888
5889
5890
5891
5892<p>
5893<hr><h3><a name="pdf-loadstring"><code>loadstring (string [, chunkname])</code></a></h3>
5894
5895
5896<p>
5897Similar to <a href="#pdf-load"><code>load</code></a>,
5898but gets the chunk from the given string.
5899
5900
5901<p>
5902To load and run a given string, use the idiom
5903
5904<pre>
5905 assert(loadstring(s))()
5906</pre>
5907
5908<p>
5909When absent,
5910<code>chunkname</code> defaults to the given string.
5911
5912
5913
5914
5915<p>
5916<hr><h3><a name="pdf-next"><code>next (table [, index])</code></a></h3>
5917
5918
5919<p>
5920Allows a program to traverse all fields of a table.
5921Its first argument is a table and its second argument
5922is an index in this table.
5923<code>next</code> returns the next index of the table
5924and its associated value.
5925When called with <b>nil</b> as its second argument,
5926<code>next</code> returns an initial index
5927and its associated value.
5928When called with the last index,
5929or with <b>nil</b> in an empty table,
5930<code>next</code> returns <b>nil</b>.
5931If the second argument is absent, then it is interpreted as <b>nil</b>.
5932In particular,
5933you can use <code>next(t)</code> to check whether a table is empty.
5934
5935
5936<p>
5937The order in which the indices are enumerated is not specified,
5938<em>even for numeric indices</em>.
5939(To traverse a table in numeric order,
5940use a numerical <b>for</b> or the <a href="#pdf-ipairs"><code>ipairs</code></a> function.)
5941
5942
5943<p>
5944The behavior of <code>next</code> is <em>undefined</em> if,
5945during the traversal,
5946you assign any value to a non-existent field in the table.
5947You may however modify existing fields.
5948In particular, you may clear existing fields.
5949
5950
5951
5952
5953<p>
5954<hr><h3><a name="pdf-pairs"><code>pairs (t)</code></a></h3>
5955
5956
5957<p>
5958Returns three values: the <a href="#pdf-next"><code>next</code></a> function, the table <code>t</code>, and <b>nil</b>,
5959so that the construction
5960
5961<pre>
5962 for k,v in pairs(t) do <em>body</em> end
5963</pre><p>
5964will iterate over all key&ndash;value pairs of table <code>t</code>.
5965
5966
5967<p>
5968See function <a href="#pdf-next"><code>next</code></a> for the caveats of modifying
5969the table during its traversal.
5970
5971
5972
5973
5974<p>
5975<hr><h3><a name="pdf-pcall"><code>pcall (f, arg1, &middot;&middot;&middot;)</code></a></h3>
5976
5977
5978<p>
5979Calls function <code>f</code> with
5980the given arguments in <em>protected mode</em>.
5981This means that any error inside&nbsp;<code>f</code> is not propagated;
5982instead, <code>pcall</code> catches the error
5983and returns a status code.
5984Its first result is the status code (a boolean),
5985which is true if the call succeeds without errors.
5986In such case, <code>pcall</code> also returns all results from the call,
5987after this first result.
5988In case of any error, <code>pcall</code> returns <b>false</b> plus the error message.
5989
5990
5991
5992
5993<p>
5994<hr><h3><a name="pdf-print"><code>print (&middot;&middot;&middot;)</code></a></h3>
5995Receives any number of arguments,
5996and prints their values to <code>stdout</code>,
5997using the <a href="#pdf-tostring"><code>tostring</code></a> function to convert them to strings.
5998<code>print</code> is not intended for formatted output,
5999but only as a quick way to show a value,
6000typically for debugging.
6001For formatted output, use <a href="#pdf-string.format"><code>string.format</code></a>.
6002
6003
6004
6005
6006<p>
6007<hr><h3><a name="pdf-rawequal"><code>rawequal (v1, v2)</code></a></h3>
6008Checks whether <code>v1</code> is equal to <code>v2</code>,
6009without invoking any metamethod.
6010Returns a boolean.
6011
6012
6013
6014
6015<p>
6016<hr><h3><a name="pdf-rawget"><code>rawget (table, index)</code></a></h3>
6017Gets the real value of <code>table[index]</code>,
6018without invoking any metamethod.
6019<code>table</code> must be a table;
6020<code>index</code> may be any value.
6021
6022
6023
6024
6025<p>
6026<hr><h3><a name="pdf-rawset"><code>rawset (table, index, value)</code></a></h3>
6027Sets the real value of <code>table[index]</code> to <code>value</code>,
6028without invoking any metamethod.
6029<code>table</code> must be a table,
6030<code>index</code> any value different from <b>nil</b>,
6031and <code>value</code> any Lua value.
6032
6033
6034<p>
6035This function returns <code>table</code>.
6036
6037
6038
6039
6040<p>
6041<hr><h3><a name="pdf-select"><code>select (index, &middot;&middot;&middot;)</code></a></h3>
6042
6043
6044<p>
6045If <code>index</code> is a number,
6046returns all arguments after argument number <code>index</code>.
6047Otherwise, <code>index</code> must be the string <code>"#"</code>,
6048and <code>select</code> returns the total number of extra arguments it received.
6049
6050
6051
6052
6053<p>
6054<hr><h3><a name="pdf-setfenv"><code>setfenv (f, table)</code></a></h3>
6055
6056
6057<p>
6058Sets the environment to be used by the given function.
6059<code>f</code> can be a Lua function or a number
6060that specifies the function at that stack level:
6061Level&nbsp;1 is the function calling <code>setfenv</code>.
6062<code>setfenv</code> returns the given function.
6063
6064
6065<p>
6066As a special case, when <code>f</code> is 0 <code>setfenv</code> changes
6067the environment of the running thread.
6068In this case, <code>setfenv</code> returns no values.
6069
6070
6071
6072
6073<p>
6074<hr><h3><a name="pdf-setmetatable"><code>setmetatable (table, metatable)</code></a></h3>
6075
6076
6077<p>
6078Sets the metatable for the given table.
6079(You cannot change the metatable of other types from Lua, only from&nbsp;C.)
6080If <code>metatable</code> is <b>nil</b>,
6081removes the metatable of the given table.
6082If the original metatable has a <code>"__metatable"</code> field,
6083raises an error.
6084
6085
6086<p>
6087This function returns <code>table</code>.
6088
6089
6090
6091
6092<p>
6093<hr><h3><a name="pdf-tonumber"><code>tonumber (e [, base])</code></a></h3>
6094Tries to convert its argument to a number.
6095If the argument is already a number or a string convertible
6096to a number, then <code>tonumber</code> returns this number;
6097otherwise, it returns <b>nil</b>.
6098
6099
6100<p>
6101An optional argument specifies the base to interpret the numeral.
6102The base may be any integer between 2 and 36, inclusive.
6103In bases above&nbsp;10, the letter '<code>A</code>' (in either upper or lower case)
6104represents&nbsp;10, '<code>B</code>' represents&nbsp;11, and so forth,
6105with '<code>Z</code>' representing 35.
6106In base 10 (the default), the number can have a decimal part,
6107as well as an optional exponent part (see <a href="#2.1">&sect;2.1</a>).
6108In other bases, only unsigned integers are accepted.
6109
6110
6111
6112
6113<p>
6114<hr><h3><a name="pdf-tostring"><code>tostring (e)</code></a></h3>
6115Receives an argument of any type and
6116converts it to a string in a reasonable format.
6117For complete control of how numbers are converted,
6118use <a href="#pdf-string.format"><code>string.format</code></a>.
6119
6120
6121<p>
6122If the metatable of <code>e</code> has a <code>"__tostring"</code> field,
6123then <code>tostring</code> calls the corresponding value
6124with <code>e</code> as argument,
6125and uses the result of the call as its result.
6126
6127
6128
6129
6130<p>
6131<hr><h3><a name="pdf-type"><code>type (v)</code></a></h3>
6132Returns the type of its only argument, coded as a string.
6133The possible results of this function are
6134"<code>nil</code>" (a string, not the value <b>nil</b>),
6135"<code>number</code>",
6136"<code>string</code>",
6137"<code>boolean</code>",
6138"<code>table</code>",
6139"<code>function</code>",
6140"<code>thread</code>",
6141and "<code>userdata</code>".
6142
6143
6144
6145
6146<p>
6147<hr><h3><a name="pdf-unpack"><code>unpack (list [, i [, j]])</code></a></h3>
6148Returns the elements from the given table.
6149This function is equivalent to
6150
6151<pre>
6152 return list[i], list[i+1], &middot;&middot;&middot;, list[j]
6153</pre><p>
6154except that the above code can be written only for a fixed number
6155of elements.
6156By default, <code>i</code> is&nbsp;1 and <code>j</code> is the length of the list,
6157as defined by the length operator (see <a href="#2.5.5">&sect;2.5.5</a>).
6158
6159
6160
6161
6162<p>
6163<hr><h3><a name="pdf-_VERSION"><code>_VERSION</code></a></h3>
6164A global variable (not a function) that
6165holds a string containing the current interpreter version.
6166The current contents of this variable is "<code>Lua 5.1</code>".
6167
6168
6169
6170
6171<p>
6172<hr><h3><a name="pdf-xpcall"><code>xpcall (f, err)</code></a></h3>
6173
6174
6175<p>
6176This function is similar to <a href="#pdf-pcall"><code>pcall</code></a>,
6177except that you can set a new error handler.
6178
6179
6180<p>
6181<code>xpcall</code> calls function <code>f</code> in protected mode,
6182using <code>err</code> as the error handler.
6183Any error inside <code>f</code> is not propagated;
6184instead, <code>xpcall</code> catches the error,
6185calls the <code>err</code> function with the original error object,
6186and returns a status code.
6187Its first result is the status code (a boolean),
6188which is true if the call succeeds without errors.
6189In this case, <code>xpcall</code> also returns all results from the call,
6190after this first result.
6191In case of any error,
6192<code>xpcall</code> returns <b>false</b> plus the result from <code>err</code>.
6193
6194
6195
6196
6197
6198
6199
6200<h2>5.2 - <a name="5.2">Coroutine Manipulation</a></h2>
6201
6202<p>
6203The operations related to coroutines comprise a sub-library of
6204the basic library and come inside the table <a name="pdf-coroutine"><code>coroutine</code></a>.
6205See <a href="#2.11">&sect;2.11</a> for a general description of coroutines.
6206
6207
6208<p>
6209<hr><h3><a name="pdf-coroutine.create"><code>coroutine.create (f)</code></a></h3>
6210
6211
6212<p>
6213Creates a new coroutine, with body <code>f</code>.
6214<code>f</code> must be a Lua function.
6215Returns this new coroutine,
6216an object with type <code>"thread"</code>.
6217
6218
6219
6220
6221<p>
6222<hr><h3><a name="pdf-coroutine.resume"><code>coroutine.resume (co [, val1, &middot;&middot;&middot;])</code></a></h3>
6223
6224
6225<p>
6226Starts or continues the execution of coroutine <code>co</code>.
6227The first time you resume a coroutine,
6228it starts running its body.
6229The values <code>val1</code>, &middot;&middot;&middot; are passed
6230as the arguments to the body function.
6231If the coroutine has yielded,
6232<code>resume</code> restarts it;
6233the values <code>val1</code>, &middot;&middot;&middot; are passed
6234as the results from the yield.
6235
6236
6237<p>
6238If the coroutine runs without any errors,
6239<code>resume</code> returns <b>true</b> plus any values passed to <code>yield</code>
6240(if the coroutine yields) or any values returned by the body function
6241(if the coroutine terminates).
6242If there is any error,
6243<code>resume</code> returns <b>false</b> plus the error message.
6244
6245
6246
6247
6248<p>
6249<hr><h3><a name="pdf-coroutine.running"><code>coroutine.running ()</code></a></h3>
6250
6251
6252<p>
6253Returns the running coroutine,
6254or <b>nil</b> when called by the main thread.
6255
6256
6257
6258
6259<p>
6260<hr><h3><a name="pdf-coroutine.status"><code>coroutine.status (co)</code></a></h3>
6261
6262
6263<p>
6264Returns the status of coroutine <code>co</code>, as a string:
6265<code>"running"</code>,
6266if the coroutine is running (that is, it called <code>status</code>);
6267<code>"suspended"</code>, if the coroutine is suspended in a call to <code>yield</code>,
6268or if it has not started running yet;
6269<code>"normal"</code> if the coroutine is active but not running
6270(that is, it has resumed another coroutine);
6271and <code>"dead"</code> if the coroutine has finished its body function,
6272or if it has stopped with an error.
6273
6274
6275
6276
6277<p>
6278<hr><h3><a name="pdf-coroutine.wrap"><code>coroutine.wrap (f)</code></a></h3>
6279
6280
6281<p>
6282Creates a new coroutine, with body <code>f</code>.
6283<code>f</code> must be a Lua function.
6284Returns a function that resumes the coroutine each time it is called.
6285Any arguments passed to the function behave as the
6286extra arguments to <code>resume</code>.
6287Returns the same values returned by <code>resume</code>,
6288except the first boolean.
6289In case of error, propagates the error.
6290
6291
6292
6293
6294<p>
6295<hr><h3><a name="pdf-coroutine.yield"><code>coroutine.yield (&middot;&middot;&middot;)</code></a></h3>
6296
6297
6298<p>
6299Suspends the execution of the calling coroutine.
6300The coroutine cannot be running a C&nbsp;function,
6301a metamethod, or an iterator.
6302Any arguments to <code>yield</code> are passed as extra results to <code>resume</code>.
6303
6304
6305
6306
6307
6308
6309
6310<h2>5.3 - <a name="5.3">Modules</a></h2>
6311
6312<p>
6313The package library provides basic
6314facilities for loading and building modules in Lua.
6315It exports two of its functions directly in the global environment:
6316<a href="#pdf-require"><code>require</code></a> and <a href="#pdf-module"><code>module</code></a>.
6317Everything else is exported in a table <a name="pdf-package"><code>package</code></a>.
6318
6319
6320<p>
6321<hr><h3><a name="pdf-module"><code>module (name [, &middot;&middot;&middot;])</code></a></h3>
6322
6323
6324<p>
6325Creates a module.
6326If there is a table in <code>package.loaded[name]</code>,
6327this table is the module.
6328Otherwise, if there is a global table <code>t</code> with the given name,
6329this table is the module.
6330Otherwise creates a new table <code>t</code> and
6331sets it as the value of the global <code>name</code> and
6332the value of <code>package.loaded[name]</code>.
6333This function also initializes <code>t._NAME</code> with the given name,
6334<code>t._M</code> with the module (<code>t</code> itself),
6335and <code>t._PACKAGE</code> with the package name
6336(the full module name minus last component; see below).
6337Finally, <code>module</code> sets <code>t</code> as the new environment
6338of the current function and the new value of <code>package.loaded[name]</code>,
6339so that <a href="#pdf-require"><code>require</code></a> returns <code>t</code>.
6340
6341
6342<p>
6343If <code>name</code> is a compound name
6344(that is, one with components separated by dots),
6345<code>module</code> creates (or reuses, if they already exist)
6346tables for each component.
6347For instance, if <code>name</code> is <code>a.b.c</code>,
6348then <code>module</code> stores the module table in field <code>c</code> of
6349field <code>b</code> of global <code>a</code>.
6350
6351
6352<p>
6353This function can receive optional <em>options</em> after
6354the module name,
6355where each option is a function to be applied over the module.
6356
6357
6358
6359
6360<p>
6361<hr><h3><a name="pdf-require"><code>require (modname)</code></a></h3>
6362
6363
6364<p>
6365Loads the given module.
6366The function starts by looking into the <a href="#pdf-package.loaded"><code>package.loaded</code></a> table
6367to determine whether <code>modname</code> is already loaded.
6368If it is, then <code>require</code> returns the value stored
6369at <code>package.loaded[modname]</code>.
6370Otherwise, it tries to find a <em>loader</em> for the module.
6371
6372
6373<p>
6374To find a loader,
6375<code>require</code> is guided by the <a href="#pdf-package.loaders"><code>package.loaders</code></a> array.
6376By changing this array,
6377we can change how <code>require</code> looks for a module.
6378The following explanation is based on the default configuration
6379for <a href="#pdf-package.loaders"><code>package.loaders</code></a>.
6380
6381
6382<p>
6383First <code>require</code> queries <code>package.preload[modname]</code>.
6384If it has a value,
6385this value (which should be a function) is the loader.
6386Otherwise <code>require</code> searches for a Lua loader using the
6387path stored in <a href="#pdf-package.path"><code>package.path</code></a>.
6388If that also fails, it searches for a C&nbsp;loader using the
6389path stored in <a href="#pdf-package.cpath"><code>package.cpath</code></a>.
6390If that also fails,
6391it tries an <em>all-in-one</em> loader (see <a href="#pdf-package.loaders"><code>package.loaders</code></a>).
6392
6393
6394<p>
6395Once a loader is found,
6396<code>require</code> calls the loader with a single argument, <code>modname</code>.
6397If the loader returns any value,
6398<code>require</code> assigns the returned value to <code>package.loaded[modname]</code>.
6399If the loader returns no value and
6400has not assigned any value to <code>package.loaded[modname]</code>,
6401then <code>require</code> assigns <b>true</b> to this entry.
6402In any case, <code>require</code> returns the
6403final value of <code>package.loaded[modname]</code>.
6404
6405
6406<p>
6407If there is any error loading or running the module,
6408or if it cannot find any loader for the module,
6409then <code>require</code> signals an error.
6410
6411
6412
6413
6414<p>
6415<hr><h3><a name="pdf-package.cpath"><code>package.cpath</code></a></h3>
6416
6417
6418<p>
6419The path used by <a href="#pdf-require"><code>require</code></a> to search for a C&nbsp;loader.
6420
6421
6422<p>
6423Lua initializes the C&nbsp;path <a href="#pdf-package.cpath"><code>package.cpath</code></a> in the same way
6424it initializes the Lua path <a href="#pdf-package.path"><code>package.path</code></a>,
6425using the environment variable <a name="pdf-LUA_CPATH"><code>LUA_CPATH</code></a>
6426or a default path defined in <code>luaconf.h</code>.
6427
6428
6429
6430
6431<p>
6432
6433<hr><h3><a name="pdf-package.loaded"><code>package.loaded</code></a></h3>
6434
6435
6436<p>
6437A table used by <a href="#pdf-require"><code>require</code></a> to control which
6438modules are already loaded.
6439When you require a module <code>modname</code> and
6440<code>package.loaded[modname]</code> is not false,
6441<a href="#pdf-require"><code>require</code></a> simply returns the value stored there.
6442
6443
6444
6445
6446<p>
6447<hr><h3><a name="pdf-package.loaders"><code>package.loaders</code></a></h3>
6448
6449
6450<p>
6451A table used by <a href="#pdf-require"><code>require</code></a> to control how to load modules.
6452
6453
6454<p>
6455Each entry in this table is a <em>searcher function</em>.
6456When looking for a module,
6457<a href="#pdf-require"><code>require</code></a> calls each of these searchers in ascending order,
6458with the module name (the argument given to <a href="#pdf-require"><code>require</code></a>) as its
6459sole parameter.
6460The function can return another function (the module <em>loader</em>)
6461or a string explaining why it did not find that module
6462(or <b>nil</b> if it has nothing to say).
6463Lua initializes this table with four functions.
6464
6465
6466<p>
6467The first searcher simply looks for a loader in the
6468<a href="#pdf-package.preload"><code>package.preload</code></a> table.
6469
6470
6471<p>
6472The second searcher looks for a loader as a Lua library,
6473using the path stored at <a href="#pdf-package.path"><code>package.path</code></a>.
6474A path is a sequence of <em>templates</em> separated by semicolons.
6475For each template,
6476the searcher will change each interrogation
6477mark in the template by <code>filename</code>,
6478which is the module name with each dot replaced by a
6479"directory separator" (such as "<code>/</code>" in Unix);
6480then it will try to open the resulting file name.
6481So, for instance, if the Lua path is the string
6482
6483<pre>
6484 "./?.lua;./?.lc;/usr/local/?/init.lua"
6485</pre><p>
6486the search for a Lua file for module <code>foo</code>
6487will try to open the files
6488<code>./foo.lua</code>, <code>./foo.lc</code>, and
6489<code>/usr/local/foo/init.lua</code>, in that order.
6490
6491
6492<p>
6493The third searcher looks for a loader as a C&nbsp;library,
6494using the path given by the variable <a href="#pdf-package.cpath"><code>package.cpath</code></a>.
6495For instance,
6496if the C&nbsp;path is the string
6497
6498<pre>
6499 "./?.so;./?.dll;/usr/local/?/init.so"
6500</pre><p>
6501the searcher for module <code>foo</code>
6502will try to open the files <code>./foo.so</code>, <code>./foo.dll</code>,
6503and <code>/usr/local/foo/init.so</code>, in that order.
6504Once it finds a C&nbsp;library,
6505this searcher first uses a dynamic link facility to link the
6506application with the library.
6507Then it tries to find a C&nbsp;function inside the library to
6508be used as the loader.
6509The name of this C&nbsp;function is the string "<code>luaopen_</code>"
6510concatenated with a copy of the module name where each dot
6511is replaced by an underscore.
6512Moreover, if the module name has a hyphen,
6513its prefix up to (and including) the first hyphen is removed.
6514For instance, if the module name is <code>a.v1-b.c</code>,
6515the function name will be <code>luaopen_b_c</code>.
6516
6517
6518<p>
6519The fourth searcher tries an <em>all-in-one loader</em>.
6520It searches the C&nbsp;path for a library for
6521the root name of the given module.
6522For instance, when requiring <code>a.b.c</code>,
6523it will search for a C&nbsp;library for <code>a</code>.
6524If found, it looks into it for an open function for
6525the submodule;
6526in our example, that would be <code>luaopen_a_b_c</code>.
6527With this facility, a package can pack several C&nbsp;submodules
6528into one single library,
6529with each submodule keeping its original open function.
6530
6531
6532
6533
6534<p>
6535<hr><h3><a name="pdf-package.loadlib"><code>package.loadlib (libname, funcname)</code></a></h3>
6536
6537
6538<p>
6539Dynamically links the host program with the C&nbsp;library <code>libname</code>.
6540Inside this library, looks for a function <code>funcname</code>
6541and returns this function as a C&nbsp;function.
6542(So, <code>funcname</code> must follow the protocol (see <a href="#lua_CFunction"><code>lua_CFunction</code></a>)).
6543
6544
6545<p>
6546This is a low-level function.
6547It completely bypasses the package and module system.
6548Unlike <a href="#pdf-require"><code>require</code></a>,
6549it does not perform any path searching and
6550does not automatically adds extensions.
6551<code>libname</code> must be the complete file name of the C&nbsp;library,
6552including if necessary a path and extension.
6553<code>funcname</code> must be the exact name exported by the C&nbsp;library
6554(which may depend on the C&nbsp;compiler and linker used).
6555
6556
6557<p>
6558This function is not supported by ANSI C.
6559As such, it is only available on some platforms
6560(Windows, Linux, Mac OS X, Solaris, BSD,
6561plus other Unix systems that support the <code>dlfcn</code> standard).
6562
6563
6564
6565
6566<p>
6567<hr><h3><a name="pdf-package.path"><code>package.path</code></a></h3>
6568
6569
6570<p>
6571The path used by <a href="#pdf-require"><code>require</code></a> to search for a Lua loader.
6572
6573
6574<p>
6575At start-up, Lua initializes this variable with
6576the value of the environment variable <a name="pdf-LUA_PATH"><code>LUA_PATH</code></a> or
6577with a default path defined in <code>luaconf.h</code>,
6578if the environment variable is not defined.
6579Any "<code>;;</code>" in the value of the environment variable
6580is replaced by the default path.
6581
6582
6583
6584
6585<p>
6586<hr><h3><a name="pdf-package.preload"><code>package.preload</code></a></h3>
6587
6588
6589<p>
6590A table to store loaders for specific modules
6591(see <a href="#pdf-require"><code>require</code></a>).
6592
6593
6594
6595
6596<p>
6597<hr><h3><a name="pdf-package.seeall"><code>package.seeall (module)</code></a></h3>
6598
6599
6600<p>
6601Sets a metatable for <code>module</code> with
6602its <code>__index</code> field referring to the global environment,
6603so that this module inherits values
6604from the global environment.
6605To be used as an option to function <a href="#pdf-module"><code>module</code></a>.
6606
6607
6608
6609
6610
6611
6612
6613<h2>5.4 - <a name="5.4">String Manipulation</a></h2>
6614
6615<p>
6616This library provides generic functions for string manipulation,
6617such as finding and extracting substrings, and pattern matching.
6618When indexing a string in Lua, the first character is at position&nbsp;1
6619(not at&nbsp;0, as in C).
6620Indices are allowed to be negative and are interpreted as indexing backwards,
6621from the end of the string.
6622Thus, the last character is at position -1, and so on.
6623
6624
6625<p>
6626The string library provides all its functions inside the table
6627<a name="pdf-string"><code>string</code></a>.
6628It also sets a metatable for strings
6629where the <code>__index</code> field points to the <code>string</code> table.
6630Therefore, you can use the string functions in object-oriented style.
6631For instance, <code>string.byte(s, i)</code>
6632can be written as <code>s:byte(i)</code>.
6633
6634
6635<p>
6636The string library assumes one-byte character encodings.
6637
6638
6639<p>
6640<hr><h3><a name="pdf-string.byte"><code>string.byte (s [, i [, j]])</code></a></h3>
6641Returns the internal numerical codes of the characters <code>s[i]</code>,
6642<code>s[i+1]</code>, &middot;&middot;&middot;, <code>s[j]</code>.
6643The default value for <code>i</code> is&nbsp;1;
6644the default value for <code>j</code> is&nbsp;<code>i</code>.
6645
6646
6647<p>
6648Note that numerical codes are not necessarily portable across platforms.
6649
6650
6651
6652
6653<p>
6654<hr><h3><a name="pdf-string.char"><code>string.char (&middot;&middot;&middot;)</code></a></h3>
6655Receives zero or more integers.
6656Returns a string with length equal to the number of arguments,
6657in which each character has the internal numerical code equal
6658to its corresponding argument.
6659
6660
6661<p>
6662Note that numerical codes are not necessarily portable across platforms.
6663
6664
6665
6666
6667<p>
6668<hr><h3><a name="pdf-string.dump"><code>string.dump (function)</code></a></h3>
6669
6670
6671<p>
6672Returns a string containing a binary representation of the given function,
6673so that a later <a href="#pdf-loadstring"><code>loadstring</code></a> on this string returns
6674a copy of the function.
6675<code>function</code> must be a Lua function without upvalues.
6676
6677
6678
6679
6680<p>
6681<hr><h3><a name="pdf-string.find"><code>string.find (s, pattern [, init [, plain]])</code></a></h3>
6682Looks for the first match of
6683<code>pattern</code> in the string <code>s</code>.
6684If it finds a match, then <code>find</code> returns the indices of&nbsp;<code>s</code>
6685where this occurrence starts and ends;
6686otherwise, it returns <b>nil</b>.
6687A third, optional numerical argument <code>init</code> specifies
6688where to start the search;
6689its default value is&nbsp;1 and can be negative.
6690A value of <b>true</b> as a fourth, optional argument <code>plain</code>
6691turns off the pattern matching facilities,
6692so the function does a plain "find substring" operation,
6693with no characters in <code>pattern</code> being considered "magic".
6694Note that if <code>plain</code> is given, then <code>init</code> must be given as well.
6695
6696
6697<p>
6698If the pattern has captures,
6699then in a successful match
6700the captured values are also returned,
6701after the two indices.
6702
6703
6704
6705
6706<p>
6707<hr><h3><a name="pdf-string.format"><code>string.format (formatstring, &middot;&middot;&middot;)</code></a></h3>
6708Returns a formatted version of its variable number of arguments
6709following the description given in its first argument (which must be a string).
6710The format string follows the same rules as the <code>printf</code> family of
6711standard C&nbsp;functions.
6712The only differences are that the options/modifiers
6713<code>*</code>, <code>l</code>, <code>L</code>, <code>n</code>, <code>p</code>,
6714and <code>h</code> are not supported
6715and that there is an extra option, <code>q</code>.
6716The <code>q</code> option formats a string in a form suitable to be safely read
6717back by the Lua interpreter:
6718the string is written between double quotes,
6719and all double quotes, newlines, embedded zeros,
6720and backslashes in the string
6721are correctly escaped when written.
6722For instance, the call
6723
6724<pre>
6725 string.format('%q', 'a string with "quotes" and \n new line')
6726</pre><p>
6727will produce the string:
6728
6729<pre>
6730 "a string with \"quotes\" and \
6731 new line"
6732</pre>
6733
6734<p>
6735The options <code>c</code>, <code>d</code>, <code>E</code>, <code>e</code>, <code>f</code>,
6736<code>g</code>, <code>G</code>, <code>i</code>, <code>o</code>, <code>u</code>, <code>X</code>, and <code>x</code> all
6737expect a number as argument,
6738whereas <code>q</code> and <code>s</code> expect a string.
6739
6740
6741<p>
6742This function does not accept string values
6743containing embedded zeros,
6744except as arguments to the <code>q</code> option.
6745
6746
6747
6748
6749<p>
6750<hr><h3><a name="pdf-string.gmatch"><code>string.gmatch (s, pattern)</code></a></h3>
6751Returns an iterator function that,
6752each time it is called,
6753returns the next captures from <code>pattern</code> over string <code>s</code>.
6754If <code>pattern</code> specifies no captures,
6755then the whole match is produced in each call.
6756
6757
6758<p>
6759As an example, the following loop
6760
6761<pre>
6762 s = "hello world from Lua"
6763 for w in string.gmatch(s, "%a+") do
6764 print(w)
6765 end
6766</pre><p>
6767will iterate over all the words from string <code>s</code>,
6768printing one per line.
6769The next example collects all pairs <code>key=value</code> from the
6770given string into a table:
6771
6772<pre>
6773 t = {}
6774 s = "from=world, to=Lua"
6775 for k, v in string.gmatch(s, "(%w+)=(%w+)") do
6776 t[k] = v
6777 end
6778</pre>
6779
6780<p>
6781For this function, a '<code>^</code>' at the start of a pattern does not
6782work as an anchor, as this would prevent the iteration.
6783
6784
6785
6786
6787<p>
6788<hr><h3><a name="pdf-string.gsub"><code>string.gsub (s, pattern, repl [, n])</code></a></h3>
6789Returns a copy of <code>s</code>
6790in which all (or the first <code>n</code>, if given)
6791occurrences of the <code>pattern</code> have been
6792replaced by a replacement string specified by <code>repl</code>,
6793which can be a string, a table, or a function.
6794<code>gsub</code> also returns, as its second value,
6795the total number of matches that occurred.
6796
6797
6798<p>
6799If <code>repl</code> is a string, then its value is used for replacement.
6800The character&nbsp;<code>%</code> works as an escape character:
6801any sequence in <code>repl</code> of the form <code>%<em>n</em></code>,
6802with <em>n</em> between 1 and 9,
6803stands for the value of the <em>n</em>-th captured substring (see below).
6804The sequence <code>%0</code> stands for the whole match.
6805The sequence <code>%%</code> stands for a single&nbsp;<code>%</code>.
6806
6807
6808<p>
6809If <code>repl</code> is a table, then the table is queried for every match,
6810using the first capture as the key;
6811if the pattern specifies no captures,
6812then the whole match is used as the key.
6813
6814
6815<p>
6816If <code>repl</code> is a function, then this function is called every time a
6817match occurs, with all captured substrings passed as arguments,
6818in order;
6819if the pattern specifies no captures,
6820then the whole match is passed as a sole argument.
6821
6822
6823<p>
6824If the value returned by the table query or by the function call
6825is a string or a number,
6826then it is used as the replacement string;
6827otherwise, if it is <b>false</b> or <b>nil</b>,
6828then there is no replacement
6829(that is, the original match is kept in the string).
6830
6831
6832<p>
6833Here are some examples:
6834
6835<pre>
6836 x = string.gsub("hello world", "(%w+)", "%1 %1")
6837 --&gt; x="hello hello world world"
6838
6839 x = string.gsub("hello world", "%w+", "%0 %0", 1)
6840 --&gt; x="hello hello world"
6841
6842 x = string.gsub("hello world from Lua", "(%w+)%s*(%w+)", "%2 %1")
6843 --&gt; x="world hello Lua from"
6844
6845 x = string.gsub("home = $HOME, user = $USER", "%$(%w+)", os.getenv)
6846 --&gt; x="home = /home/roberto, user = roberto"
6847
6848 x = string.gsub("4+5 = $return 4+5$", "%$(.-)%$", function (s)
6849 return loadstring(s)()
6850 end)
6851 --&gt; x="4+5 = 9"
6852
6853 local t = {name="lua", version="5.1"}
6854 x = string.gsub("$name-$version.tar.gz", "%$(%w+)", t)
6855 --&gt; x="lua-5.1.tar.gz"
6856</pre>
6857
6858
6859
6860<p>
6861<hr><h3><a name="pdf-string.len"><code>string.len (s)</code></a></h3>
6862Receives a string and returns its length.
6863The empty string <code>""</code> has length 0.
6864Embedded zeros are counted,
6865so <code>"a\000bc\000"</code> has length 5.
6866
6867
6868
6869
6870<p>
6871<hr><h3><a name="pdf-string.lower"><code>string.lower (s)</code></a></h3>
6872Receives a string and returns a copy of this string with all
6873uppercase letters changed to lowercase.
6874All other characters are left unchanged.
6875The definition of what an uppercase letter is depends on the current locale.
6876
6877
6878
6879
6880<p>
6881<hr><h3><a name="pdf-string.match"><code>string.match (s, pattern [, init])</code></a></h3>
6882Looks for the first <em>match</em> of
6883<code>pattern</code> in the string <code>s</code>.
6884If it finds one, then <code>match</code> returns
6885the captures from the pattern;
6886otherwise it returns <b>nil</b>.
6887If <code>pattern</code> specifies no captures,
6888then the whole match is returned.
6889A third, optional numerical argument <code>init</code> specifies
6890where to start the search;
6891its default value is&nbsp;1 and can be negative.
6892
6893
6894
6895
6896<p>
6897<hr><h3><a name="pdf-string.rep"><code>string.rep (s, n)</code></a></h3>
6898Returns a string that is the concatenation of <code>n</code> copies of
6899the string <code>s</code>.
6900
6901
6902
6903
6904<p>
6905<hr><h3><a name="pdf-string.reverse"><code>string.reverse (s)</code></a></h3>
6906Returns a string that is the string <code>s</code> reversed.
6907
6908
6909
6910
6911<p>
6912<hr><h3><a name="pdf-string.sub"><code>string.sub (s, i [, j])</code></a></h3>
6913Returns the substring of <code>s</code> that
6914starts at <code>i</code> and continues until <code>j</code>;
6915<code>i</code> and <code>j</code> can be negative.
6916If <code>j</code> is absent, then it is assumed to be equal to -1
6917(which is the same as the string length).
6918In particular,
6919the call <code>string.sub(s,1,j)</code> returns a prefix of <code>s</code>
6920with length <code>j</code>,
6921and <code>string.sub(s, -i)</code> returns a suffix of <code>s</code>
6922with length <code>i</code>.
6923
6924
6925
6926
6927<p>
6928<hr><h3><a name="pdf-string.upper"><code>string.upper (s)</code></a></h3>
6929Receives a string and returns a copy of this string with all
6930lowercase letters changed to uppercase.
6931All other characters are left unchanged.
6932The definition of what a lowercase letter is depends on the current locale.
6933
6934
6935
6936<h3>5.4.1 - <a name="5.4.1">Patterns</a></h3>
6937
6938
6939<h4>Character Class:</h4><p>
6940A <em>character class</em> is used to represent a set of characters.
6941The following combinations are allowed in describing a character class:
6942
6943<ul>
6944
6945<li><b><em>x</em>:</b>
6946(where <em>x</em> is not one of the <em>magic characters</em>
6947<code>^$()%.[]*+-?</code>)
6948represents the character <em>x</em> itself.
6949</li>
6950
6951<li><b><code>.</code>:</b> (a dot) represents all characters.</li>
6952
6953<li><b><code>%a</code>:</b> represents all letters.</li>
6954
6955<li><b><code>%c</code>:</b> represents all control characters.</li>
6956
6957<li><b><code>%d</code>:</b> represents all digits.</li>
6958
6959<li><b><code>%l</code>:</b> represents all lowercase letters.</li>
6960
6961<li><b><code>%p</code>:</b> represents all punctuation characters.</li>
6962
6963<li><b><code>%s</code>:</b> represents all space characters.</li>
6964
6965<li><b><code>%u</code>:</b> represents all uppercase letters.</li>
6966
6967<li><b><code>%w</code>:</b> represents all alphanumeric characters.</li>
6968
6969<li><b><code>%x</code>:</b> represents all hexadecimal digits.</li>
6970
6971<li><b><code>%z</code>:</b> represents the character with representation 0.</li>
6972
6973<li><b><code>%<em>x</em></code>:</b> (where <em>x</em> is any non-alphanumeric character)
6974represents the character <em>x</em>.
6975This is the standard way to escape the magic characters.
6976Any punctuation character (even the non magic)
6977can be preceded by a '<code>%</code>'
6978when used to represent itself in a pattern.
6979</li>
6980
6981<li><b><code>[<em>set</em>]</code>:</b>
6982represents the class which is the union of all
6983characters in <em>set</em>.
6984A range of characters can be specified by
6985separating the end characters of the range with a '<code>-</code>'.
6986All classes <code>%</code><em>x</em> described above can also be used as
6987components in <em>set</em>.
6988All other characters in <em>set</em> represent themselves.
6989For example, <code>[%w_]</code> (or <code>[_%w]</code>)
6990represents all alphanumeric characters plus the underscore,
6991<code>[0-7]</code> represents the octal digits,
6992and <code>[0-7%l%-]</code> represents the octal digits plus
6993the lowercase letters plus the '<code>-</code>' character.
6994
6995
6996<p>
6997The interaction between ranges and classes is not defined.
6998Therefore, patterns like <code>[%a-z]</code> or <code>[a-%%]</code>
6999have no meaning.
7000</li>
7001
7002<li><b><code>[^<em>set</em>]</code>:</b>
7003represents the complement of <em>set</em>,
7004where <em>set</em> is interpreted as above.
7005</li>
7006
7007</ul><p>
7008For all classes represented by single letters (<code>%a</code>, <code>%c</code>, etc.),
7009the corresponding uppercase letter represents the complement of the class.
7010For instance, <code>%S</code> represents all non-space characters.
7011
7012
7013<p>
7014The definitions of letter, space, and other character groups
7015depend on the current locale.
7016In particular, the class <code>[a-z]</code> may not be equivalent to <code>%l</code>.
7017
7018
7019
7020
7021
7022<h4>Pattern Item:</h4><p>
7023A <em>pattern item</em> can be
7024
7025<ul>
7026
7027<li>
7028a single character class,
7029which matches any single character in the class;
7030</li>
7031
7032<li>
7033a single character class followed by '<code>*</code>',
7034which matches 0 or more repetitions of characters in the class.
7035These repetition items will always match the longest possible sequence;
7036</li>
7037
7038<li>
7039a single character class followed by '<code>+</code>',
7040which matches 1 or more repetitions of characters in the class.
7041These repetition items will always match the longest possible sequence;
7042</li>
7043
7044<li>
7045a single character class followed by '<code>-</code>',
7046which also matches 0 or more repetitions of characters in the class.
7047Unlike '<code>*</code>',
7048these repetition items will always match the <em>shortest</em> possible sequence;
7049</li>
7050
7051<li>
7052a single character class followed by '<code>?</code>',
7053which matches 0 or 1 occurrence of a character in the class;
7054</li>
7055
7056<li>
7057<code>%<em>n</em></code>, for <em>n</em> between 1 and 9;
7058such item matches a substring equal to the <em>n</em>-th captured string
7059(see below);
7060</li>
7061
7062<li>
7063<code>%b<em>xy</em></code>, where <em>x</em> and <em>y</em> are two distinct characters;
7064such item matches strings that start with&nbsp;<em>x</em>, end with&nbsp;<em>y</em>,
7065and where the <em>x</em> and <em>y</em> are <em>balanced</em>.
7066This means that, if one reads the string from left to right,
7067counting <em>+1</em> for an <em>x</em> and <em>-1</em> for a <em>y</em>,
7068the ending <em>y</em> is the first <em>y</em> where the count reaches 0.
7069For instance, the item <code>%b()</code> matches expressions with
7070balanced parentheses.
7071</li>
7072
7073</ul>
7074
7075
7076
7077
7078<h4>Pattern:</h4><p>
7079A <em>pattern</em> is a sequence of pattern items.
7080A '<code>^</code>' at the beginning of a pattern anchors the match at the
7081beginning of the subject string.
7082A '<code>$</code>' at the end of a pattern anchors the match at the
7083end of the subject string.
7084At other positions,
7085'<code>^</code>' and '<code>$</code>' have no special meaning and represent themselves.
7086
7087
7088
7089
7090
7091<h4>Captures:</h4><p>
7092A pattern can contain sub-patterns enclosed in parentheses;
7093they describe <em>captures</em>.
7094When a match succeeds, the substrings of the subject string
7095that match captures are stored (<em>captured</em>) for future use.
7096Captures are numbered according to their left parentheses.
7097For instance, in the pattern <code>"(a*(.)%w(%s*))"</code>,
7098the part of the string matching <code>"a*(.)%w(%s*)"</code> is
7099stored as the first capture (and therefore has number&nbsp;1);
7100the character matching "<code>.</code>" is captured with number&nbsp;2,
7101and the part matching "<code>%s*</code>" has number&nbsp;3.
7102
7103
7104<p>
7105As a special case, the empty capture <code>()</code> captures
7106the current string position (a number).
7107For instance, if we apply the pattern <code>"()aa()"</code> on the
7108string <code>"flaaap"</code>, there will be two captures: 3&nbsp;and&nbsp;5.
7109
7110
7111<p>
7112A pattern cannot contain embedded zeros. Use <code>%z</code> instead.
7113
7114
7115
7116
7117
7118
7119
7120
7121
7122
7123
7124<h2>5.5 - <a name="5.5">Table Manipulation</a></h2><p>
7125This library provides generic functions for table manipulation.
7126It provides all its functions inside the table <a name="pdf-table"><code>table</code></a>.
7127
7128
7129<p>
7130Most functions in the table library assume that the table
7131represents an array or a list.
7132For these functions, when we talk about the "length" of a table
7133we mean the result of the length operator.
7134
7135
7136<p>
7137<hr><h3><a name="pdf-table.concat"><code>table.concat (table [, sep [, i [, j]]])</code></a></h3>
7138Given an array where all elements are strings or numbers,
7139returns <code>table[i]..sep..table[i+1] &middot;&middot;&middot; sep..table[j]</code>.
7140The default value for <code>sep</code> is the empty string,
7141the default for <code>i</code> is 1,
7142and the default for <code>j</code> is the length of the table.
7143If <code>i</code> is greater than <code>j</code>, returns the empty string.
7144
7145
7146
7147
7148<p>
7149<hr><h3><a name="pdf-table.insert"><code>table.insert (table, [pos,] value)</code></a></h3>
7150
7151
7152<p>
7153Inserts element <code>value</code> at position <code>pos</code> in <code>table</code>,
7154shifting up other elements to open space, if necessary.
7155The default value for <code>pos</code> is <code>n+1</code>,
7156where <code>n</code> is the length of the table (see <a href="#2.5.5">&sect;2.5.5</a>),
7157so that a call <code>table.insert(t,x)</code> inserts <code>x</code> at the end
7158of table <code>t</code>.
7159
7160
7161
7162
7163<p>
7164<hr><h3><a name="pdf-table.maxn"><code>table.maxn (table)</code></a></h3>
7165
7166
7167<p>
7168Returns the largest positive numerical index of the given table,
7169or zero if the table has no positive numerical indices.
7170(To do its job this function does a linear traversal of
7171the whole table.)
7172
7173
7174
7175
7176<p>
7177<hr><h3><a name="pdf-table.remove"><code>table.remove (table [, pos])</code></a></h3>
7178
7179
7180<p>
7181Removes from <code>table</code> the element at position <code>pos</code>,
7182shifting down other elements to close the space, if necessary.
7183Returns the value of the removed element.
7184The default value for <code>pos</code> is <code>n</code>,
7185where <code>n</code> is the length of the table,
7186so that a call <code>table.remove(t)</code> removes the last element
7187of table <code>t</code>.
7188
7189
7190
7191
7192<p>
7193<hr><h3><a name="pdf-table.sort"><code>table.sort (table [, comp])</code></a></h3>
7194Sorts table elements in a given order, <em>in-place</em>,
7195from <code>table[1]</code> to <code>table[n]</code>,
7196where <code>n</code> is the length of the table.
7197If <code>comp</code> is given,
7198then it must be a function that receives two table elements,
7199and returns true
7200when the first is less than the second
7201(so that <code>not comp(a[i+1],a[i])</code> will be true after the sort).
7202If <code>comp</code> is not given,
7203then the standard Lua operator <code>&lt;</code> is used instead.
7204
7205
7206<p>
7207The sort algorithm is not stable;
7208that is, elements considered equal by the given order
7209may have their relative positions changed by the sort.
7210
7211
7212
7213
7214
7215
7216
7217<h2>5.6 - <a name="5.6">Mathematical Functions</a></h2>
7218
7219<p>
7220This library is an interface to the standard C&nbsp;math library.
7221It provides all its functions inside the table <a name="pdf-math"><code>math</code></a>.
7222
7223
7224<p>
7225<hr><h3><a name="pdf-math.abs"><code>math.abs (x)</code></a></h3>
7226
7227
7228<p>
7229Returns the absolute value of <code>x</code>.
7230
7231
7232
7233
7234<p>
7235<hr><h3><a name="pdf-math.acos"><code>math.acos (x)</code></a></h3>
7236
7237
7238<p>
7239Returns the arc cosine of <code>x</code> (in radians).
7240
7241
7242
7243
7244<p>
7245<hr><h3><a name="pdf-math.asin"><code>math.asin (x)</code></a></h3>
7246
7247
7248<p>
7249Returns the arc sine of <code>x</code> (in radians).
7250
7251
7252
7253
7254<p>
7255<hr><h3><a name="pdf-math.atan"><code>math.atan (x)</code></a></h3>
7256
7257
7258<p>
7259Returns the arc tangent of <code>x</code> (in radians).
7260
7261
7262
7263
7264<p>
7265<hr><h3><a name="pdf-math.atan2"><code>math.atan2 (y, x)</code></a></h3>
7266
7267
7268<p>
7269Returns the arc tangent of <code>y/x</code> (in radians),
7270but uses the signs of both parameters to find the
7271quadrant of the result.
7272(It also handles correctly the case of <code>x</code> being zero.)
7273
7274
7275
7276
7277<p>
7278<hr><h3><a name="pdf-math.ceil"><code>math.ceil (x)</code></a></h3>
7279
7280
7281<p>
7282Returns the smallest integer larger than or equal to <code>x</code>.
7283
7284
7285
7286
7287<p>
7288<hr><h3><a name="pdf-math.cos"><code>math.cos (x)</code></a></h3>
7289
7290
7291<p>
7292Returns the cosine of <code>x</code> (assumed to be in radians).
7293
7294
7295
7296
7297<p>
7298<hr><h3><a name="pdf-math.cosh"><code>math.cosh (x)</code></a></h3>
7299
7300
7301<p>
7302Returns the hyperbolic cosine of <code>x</code>.
7303
7304
7305
7306
7307<p>
7308<hr><h3><a name="pdf-math.deg"><code>math.deg (x)</code></a></h3>
7309
7310
7311<p>
7312Returns the angle <code>x</code> (given in radians) in degrees.
7313
7314
7315
7316
7317<p>
7318<hr><h3><a name="pdf-math.exp"><code>math.exp (x)</code></a></h3>
7319
7320
7321<p>
7322Returns the value <em>e<sup>x</sup></em>.
7323
7324
7325
7326
7327<p>
7328<hr><h3><a name="pdf-math.floor"><code>math.floor (x)</code></a></h3>
7329
7330
7331<p>
7332Returns the largest integer smaller than or equal to <code>x</code>.
7333
7334
7335
7336
7337<p>
7338<hr><h3><a name="pdf-math.fmod"><code>math.fmod (x, y)</code></a></h3>
7339
7340
7341<p>
7342Returns the remainder of the division of <code>x</code> by <code>y</code>
7343that rounds the quotient towards zero.
7344
7345
7346
7347
7348<p>
7349<hr><h3><a name="pdf-math.frexp"><code>math.frexp (x)</code></a></h3>
7350
7351
7352<p>
7353Returns <code>m</code> and <code>e</code> such that <em>x = m2<sup>e</sup></em>,
7354<code>e</code> is an integer and the absolute value of <code>m</code> is
7355in the range <em>[0.5, 1)</em>
7356(or zero when <code>x</code> is zero).
7357
7358
7359
7360
7361<p>
7362<hr><h3><a name="pdf-math.huge"><code>math.huge</code></a></h3>
7363
7364
7365<p>
7366The value <code>HUGE_VAL</code>,
7367a value larger than or equal to any other numerical value.
7368
7369
7370
7371
7372<p>
7373<hr><h3><a name="pdf-math.ldexp"><code>math.ldexp (m, e)</code></a></h3>
7374
7375
7376<p>
7377Returns <em>m2<sup>e</sup></em> (<code>e</code> should be an integer).
7378
7379
7380
7381
7382<p>
7383<hr><h3><a name="pdf-math.log"><code>math.log (x)</code></a></h3>
7384
7385
7386<p>
7387Returns the natural logarithm of <code>x</code>.
7388
7389
7390
7391
7392<p>
7393<hr><h3><a name="pdf-math.log10"><code>math.log10 (x)</code></a></h3>
7394
7395
7396<p>
7397Returns the base-10 logarithm of <code>x</code>.
7398
7399
7400
7401
7402<p>
7403<hr><h3><a name="pdf-math.max"><code>math.max (x, &middot;&middot;&middot;)</code></a></h3>
7404
7405
7406<p>
7407Returns the maximum value among its arguments.
7408
7409
7410
7411
7412<p>
7413<hr><h3><a name="pdf-math.min"><code>math.min (x, &middot;&middot;&middot;)</code></a></h3>
7414
7415
7416<p>
7417Returns the minimum value among its arguments.
7418
7419
7420
7421
7422<p>
7423<hr><h3><a name="pdf-math.modf"><code>math.modf (x)</code></a></h3>
7424
7425
7426<p>
7427Returns two numbers,
7428the integral part of <code>x</code> and the fractional part of <code>x</code>.
7429
7430
7431
7432
7433<p>
7434<hr><h3><a name="pdf-math.pi"><code>math.pi</code></a></h3>
7435
7436
7437<p>
7438The value of <em>pi</em>.
7439
7440
7441
7442
7443<p>
7444<hr><h3><a name="pdf-math.pow"><code>math.pow (x, y)</code></a></h3>
7445
7446
7447<p>
7448Returns <em>x<sup>y</sup></em>.
7449(You can also use the expression <code>x^y</code> to compute this value.)
7450
7451
7452
7453
7454<p>
7455<hr><h3><a name="pdf-math.rad"><code>math.rad (x)</code></a></h3>
7456
7457
7458<p>
7459Returns the angle <code>x</code> (given in degrees) in radians.
7460
7461
7462
7463
7464<p>
7465<hr><h3><a name="pdf-math.random"><code>math.random ([m [, n]])</code></a></h3>
7466
7467
7468<p>
7469This function is an interface to the simple
7470pseudo-random generator function <code>rand</code> provided by ANSI&nbsp;C.
7471(No guarantees can be given for its statistical properties.)
7472
7473
7474<p>
7475When called without arguments,
7476returns a uniform pseudo-random real number
7477in the range <em>[0,1)</em>.
7478When called with an integer number <code>m</code>,
7479<code>math.random</code> returns
7480a uniform pseudo-random integer in the range <em>[1, m]</em>.
7481When called with two integer numbers <code>m</code> and <code>n</code>,
7482<code>math.random</code> returns a uniform pseudo-random
7483integer in the range <em>[m, n]</em>.
7484
7485
7486
7487
7488<p>
7489<hr><h3><a name="pdf-math.randomseed"><code>math.randomseed (x)</code></a></h3>
7490
7491
7492<p>
7493Sets <code>x</code> as the "seed"
7494for the pseudo-random generator:
7495equal seeds produce equal sequences of numbers.
7496
7497
7498
7499
7500<p>
7501<hr><h3><a name="pdf-math.sin"><code>math.sin (x)</code></a></h3>
7502
7503
7504<p>
7505Returns the sine of <code>x</code> (assumed to be in radians).
7506
7507
7508
7509
7510<p>
7511<hr><h3><a name="pdf-math.sinh"><code>math.sinh (x)</code></a></h3>
7512
7513
7514<p>
7515Returns the hyperbolic sine of <code>x</code>.
7516
7517
7518
7519
7520<p>
7521<hr><h3><a name="pdf-math.sqrt"><code>math.sqrt (x)</code></a></h3>
7522
7523
7524<p>
7525Returns the square root of <code>x</code>.
7526(You can also use the expression <code>x^0.5</code> to compute this value.)
7527
7528
7529
7530
7531<p>
7532<hr><h3><a name="pdf-math.tan"><code>math.tan (x)</code></a></h3>
7533
7534
7535<p>
7536Returns the tangent of <code>x</code> (assumed to be in radians).
7537
7538
7539
7540
7541<p>
7542<hr><h3><a name="pdf-math.tanh"><code>math.tanh (x)</code></a></h3>
7543
7544
7545<p>
7546Returns the hyperbolic tangent of <code>x</code>.
7547
7548
7549
7550
7551
7552
7553
7554<h2>5.7 - <a name="5.7">Input and Output Facilities</a></h2>
7555
7556<p>
7557The I/O library provides two different styles for file manipulation.
7558The first one uses implicit file descriptors;
7559that is, there are operations to set a default input file and a
7560default output file,
7561and all input/output operations are over these default files.
7562The second style uses explicit file descriptors.
7563
7564
7565<p>
7566When using implicit file descriptors,
7567all operations are supplied by table <a name="pdf-io"><code>io</code></a>.
7568When using explicit file descriptors,
7569the operation <a href="#pdf-io.open"><code>io.open</code></a> returns a file descriptor
7570and then all operations are supplied as methods of the file descriptor.
7571
7572
7573<p>
7574The table <code>io</code> also provides
7575three predefined file descriptors with their usual meanings from C:
7576<a name="pdf-io.stdin"><code>io.stdin</code></a>, <a name="pdf-io.stdout"><code>io.stdout</code></a>, and <a name="pdf-io.stderr"><code>io.stderr</code></a>.
7577The I/O library never closes these files.
7578
7579
7580<p>
7581Unless otherwise stated,
7582all I/O functions return <b>nil</b> on failure
7583(plus an error message as a second result and
7584a system-dependent error code as a third result)
7585and some value different from <b>nil</b> on success.
7586
7587
7588<p>
7589<hr><h3><a name="pdf-io.close"><code>io.close ([file])</code></a></h3>
7590
7591
7592<p>
7593Equivalent to <code>file:close()</code>.
7594Without a <code>file</code>, closes the default output file.
7595
7596
7597
7598
7599<p>
7600<hr><h3><a name="pdf-io.flush"><code>io.flush ()</code></a></h3>
7601
7602
7603<p>
7604Equivalent to <code>file:flush</code> over the default output file.
7605
7606
7607
7608
7609<p>
7610<hr><h3><a name="pdf-io.input"><code>io.input ([file])</code></a></h3>
7611
7612
7613<p>
7614When called with a file name, it opens the named file (in text mode),
7615and sets its handle as the default input file.
7616When called with a file handle,
7617it simply sets this file handle as the default input file.
7618When called without parameters,
7619it returns the current default input file.
7620
7621
7622<p>
7623In case of errors this function raises the error,
7624instead of returning an error code.
7625
7626
7627
7628
7629<p>
7630<hr><h3><a name="pdf-io.lines"><code>io.lines ([filename])</code></a></h3>
7631
7632
7633<p>
7634Opens the given file name in read mode
7635and returns an iterator function that,
7636each time it is called,
7637returns a new line from the file.
7638Therefore, the construction
7639
7640<pre>
7641 for line in io.lines(filename) do <em>body</em> end
7642</pre><p>
7643will iterate over all lines of the file.
7644When the iterator function detects the end of file,
7645it returns <b>nil</b> (to finish the loop) and automatically closes the file.
7646
7647
7648<p>
7649The call <code>io.lines()</code> (with no file name) is equivalent
7650to <code>io.input():lines()</code>;
7651that is, it iterates over the lines of the default input file.
7652In this case it does not close the file when the loop ends.
7653
7654
7655
7656
7657<p>
7658<hr><h3><a name="pdf-io.open"><code>io.open (filename [, mode])</code></a></h3>
7659
7660
7661<p>
7662This function opens a file,
7663in the mode specified in the string <code>mode</code>.
7664It returns a new file handle,
7665or, in case of errors, <b>nil</b> plus an error message.
7666
7667
7668<p>
7669The <code>mode</code> string can be any of the following:
7670
7671<ul>
7672<li><b>"r":</b> read mode (the default);</li>
7673<li><b>"w":</b> write mode;</li>
7674<li><b>"a":</b> append mode;</li>
7675<li><b>"r+":</b> update mode, all previous data is preserved;</li>
7676<li><b>"w+":</b> update mode, all previous data is erased;</li>
7677<li><b>"a+":</b> append update mode, previous data is preserved,
7678 writing is only allowed at the end of file.</li>
7679</ul><p>
7680The <code>mode</code> string can also have a '<code>b</code>' at the end,
7681which is needed in some systems to open the file in binary mode.
7682This string is exactly what is used in the
7683standard&nbsp;C function <code>fopen</code>.
7684
7685
7686
7687
7688<p>
7689<hr><h3><a name="pdf-io.output"><code>io.output ([file])</code></a></h3>
7690
7691
7692<p>
7693Similar to <a href="#pdf-io.input"><code>io.input</code></a>, but operates over the default output file.
7694
7695
7696
7697
7698<p>
7699<hr><h3><a name="pdf-io.popen"><code>io.popen (prog [, mode])</code></a></h3>
7700
7701
7702<p>
7703Starts program <code>prog</code> in a separated process and returns
7704a file handle that you can use to read data from this program
7705(if <code>mode</code> is <code>"r"</code>, the default)
7706or to write data to this program
7707(if <code>mode</code> is <code>"w"</code>).
7708
7709
7710<p>
7711This function is system dependent and is not available
7712on all platforms.
7713
7714
7715
7716
7717<p>
7718<hr><h3><a name="pdf-io.read"><code>io.read (&middot;&middot;&middot;)</code></a></h3>
7719
7720
7721<p>
7722Equivalent to <code>io.input():read</code>.
7723
7724
7725
7726
7727<p>
7728<hr><h3><a name="pdf-io.tmpfile"><code>io.tmpfile ()</code></a></h3>
7729
7730
7731<p>
7732Returns a handle for a temporary file.
7733This file is opened in update mode
7734and it is automatically removed when the program ends.
7735
7736
7737
7738
7739<p>
7740<hr><h3><a name="pdf-io.type"><code>io.type (obj)</code></a></h3>
7741
7742
7743<p>
7744Checks whether <code>obj</code> is a valid file handle.
7745Returns the string <code>"file"</code> if <code>obj</code> is an open file handle,
7746<code>"closed file"</code> if <code>obj</code> is a closed file handle,
7747or <b>nil</b> if <code>obj</code> is not a file handle.
7748
7749
7750
7751
7752<p>
7753<hr><h3><a name="pdf-io.write"><code>io.write (&middot;&middot;&middot;)</code></a></h3>
7754
7755
7756<p>
7757Equivalent to <code>io.output():write</code>.
7758
7759
7760
7761
7762<p>
7763<hr><h3><a name="pdf-file:close"><code>file:close ()</code></a></h3>
7764
7765
7766<p>
7767Closes <code>file</code>.
7768Note that files are automatically closed when
7769their handles are garbage collected,
7770but that takes an unpredictable amount of time to happen.
7771
7772
7773
7774
7775<p>
7776<hr><h3><a name="pdf-file:flush"><code>file:flush ()</code></a></h3>
7777
7778
7779<p>
7780Saves any written data to <code>file</code>.
7781
7782
7783
7784
7785<p>
7786<hr><h3><a name="pdf-file:lines"><code>file:lines ()</code></a></h3>
7787
7788
7789<p>
7790Returns an iterator function that,
7791each time it is called,
7792returns a new line from the file.
7793Therefore, the construction
7794
7795<pre>
7796 for line in file:lines() do <em>body</em> end
7797</pre><p>
7798will iterate over all lines of the file.
7799(Unlike <a href="#pdf-io.lines"><code>io.lines</code></a>, this function does not close the file
7800when the loop ends.)
7801
7802
7803
7804
7805<p>
7806<hr><h3><a name="pdf-file:read"><code>file:read (&middot;&middot;&middot;)</code></a></h3>
7807
7808
7809<p>
7810Reads the file <code>file</code>,
7811according to the given formats, which specify what to read.
7812For each format,
7813the function returns a string (or a number) with the characters read,
7814or <b>nil</b> if it cannot read data with the specified format.
7815When called without formats,
7816it uses a default format that reads the entire next line
7817(see below).
7818
7819
7820<p>
7821The available formats are
7822
7823<ul>
7824
7825<li><b>"*n":</b>
7826reads a number;
7827this is the only format that returns a number instead of a string.
7828</li>
7829
7830<li><b>"*a":</b>
7831reads the whole file, starting at the current position.
7832On end of file, it returns the empty string.
7833</li>
7834
7835<li><b>"*l":</b>
7836reads the next line (skipping the end of line),
7837returning <b>nil</b> on end of file.
7838This is the default format.
7839</li>
7840
7841<li><b><em>number</em>:</b>
7842reads a string with up to this number of characters,
7843returning <b>nil</b> on end of file.
7844If number is zero,
7845it reads nothing and returns an empty string,
7846or <b>nil</b> on end of file.
7847</li>
7848
7849</ul>
7850
7851
7852
7853<p>
7854<hr><h3><a name="pdf-file:seek"><code>file:seek ([whence] [, offset])</code></a></h3>
7855
7856
7857<p>
7858Sets and gets the file position,
7859measured from the beginning of the file,
7860to the position given by <code>offset</code> plus a base
7861specified by the string <code>whence</code>, as follows:
7862
7863<ul>
7864<li><b>"set":</b> base is position 0 (beginning of the file);</li>
7865<li><b>"cur":</b> base is current position;</li>
7866<li><b>"end":</b> base is end of file;</li>
7867</ul><p>
7868In case of success, function <code>seek</code> returns the final file position,
7869measured in bytes from the beginning of the file.
7870If this function fails, it returns <b>nil</b>,
7871plus a string describing the error.
7872
7873
7874<p>
7875The default value for <code>whence</code> is <code>"cur"</code>,
7876and for <code>offset</code> is 0.
7877Therefore, the call <code>file:seek()</code> returns the current
7878file position, without changing it;
7879the call <code>file:seek("set")</code> sets the position to the
7880beginning of the file (and returns 0);
7881and the call <code>file:seek("end")</code> sets the position to the
7882end of the file, and returns its size.
7883
7884
7885
7886
7887<p>
7888<hr><h3><a name="pdf-file:setvbuf"><code>file:setvbuf (mode [, size])</code></a></h3>
7889
7890
7891<p>
7892Sets the buffering mode for an output file.
7893There are three available modes:
7894
7895<ul>
7896
7897<li><b>"no":</b>
7898no buffering; the result of any output operation appears immediately.
7899</li>
7900
7901<li><b>"full":</b>
7902full buffering; output operation is performed only
7903when the buffer is full (or when you explicitly <code>flush</code> the file
7904(see <a href="#pdf-io.flush"><code>io.flush</code></a>)).
7905</li>
7906
7907<li><b>"line":</b>
7908line buffering; output is buffered until a newline is output
7909or there is any input from some special files
7910(such as a terminal device).
7911</li>
7912
7913</ul><p>
7914For the last two cases, <code>size</code>
7915specifies the size of the buffer, in bytes.
7916The default is an appropriate size.
7917
7918
7919
7920
7921<p>
7922<hr><h3><a name="pdf-file:write"><code>file:write (&middot;&middot;&middot;)</code></a></h3>
7923
7924
7925<p>
7926Writes the value of each of its arguments to
7927the <code>file</code>.
7928The arguments must be strings or numbers.
7929To write other values,
7930use <a href="#pdf-tostring"><code>tostring</code></a> or <a href="#pdf-string.format"><code>string.format</code></a> before <code>write</code>.
7931
7932
7933
7934
7935
7936
7937
7938<h2>5.8 - <a name="5.8">Operating System Facilities</a></h2>
7939
7940<p>
7941This library is implemented through table <a name="pdf-os"><code>os</code></a>.
7942
7943
7944<p>
7945<hr><h3><a name="pdf-os.clock"><code>os.clock ()</code></a></h3>
7946
7947
7948<p>
7949Returns an approximation of the amount in seconds of CPU time
7950used by the program.
7951
7952
7953
7954
7955<p>
7956<hr><h3><a name="pdf-os.date"><code>os.date ([format [, time]])</code></a></h3>
7957
7958
7959<p>
7960Returns a string or a table containing date and time,
7961formatted according to the given string <code>format</code>.
7962
7963
7964<p>
7965If the <code>time</code> argument is present,
7966this is the time to be formatted
7967(see the <a href="#pdf-os.time"><code>os.time</code></a> function for a description of this value).
7968Otherwise, <code>date</code> formats the current time.
7969
7970
7971<p>
7972If <code>format</code> starts with '<code>!</code>',
7973then the date is formatted in Coordinated Universal Time.
7974After this optional character,
7975if <code>format</code> is the string "<code>*t</code>",
7976then <code>date</code> returns a table with the following fields:
7977<code>year</code> (four digits), <code>month</code> (1--12), <code>day</code> (1--31),
7978<code>hour</code> (0--23), <code>min</code> (0--59), <code>sec</code> (0--61),
7979<code>wday</code> (weekday, Sunday is&nbsp;1),
7980<code>yday</code> (day of the year),
7981and <code>isdst</code> (daylight saving flag, a boolean).
7982
7983
7984<p>
7985If <code>format</code> is not "<code>*t</code>",
7986then <code>date</code> returns the date as a string,
7987formatted according to the same rules as the C&nbsp;function <code>strftime</code>.
7988
7989
7990<p>
7991When called without arguments,
7992<code>date</code> returns a reasonable date and time representation that depends on
7993the host system and on the current locale
7994(that is, <code>os.date()</code> is equivalent to <code>os.date("%c")</code>).
7995
7996
7997
7998
7999<p>
8000<hr><h3><a name="pdf-os.difftime"><code>os.difftime (t2, t1)</code></a></h3>
8001
8002
8003<p>
8004Returns the number of seconds from time <code>t1</code> to time <code>t2</code>.
8005In POSIX, Windows, and some other systems,
8006this value is exactly <code>t2</code><em>-</em><code>t1</code>.
8007
8008
8009
8010
8011<p>
8012<hr><h3><a name="pdf-os.execute"><code>os.execute ([command])</code></a></h3>
8013
8014
8015<p>
8016This function is equivalent to the C&nbsp;function <code>system</code>.
8017It passes <code>command</code> to be executed by an operating system shell.
8018It returns a status code, which is system-dependent.
8019If <code>command</code> is absent, then it returns nonzero if a shell is available
8020and zero otherwise.
8021
8022
8023
8024
8025<p>
8026<hr><h3><a name="pdf-os.exit"><code>os.exit ([code])</code></a></h3>
8027
8028
8029<p>
8030Calls the C&nbsp;function <code>exit</code>,
8031with an optional <code>code</code>,
8032to terminate the host program.
8033The default value for <code>code</code> is the success code.
8034
8035
8036
8037
8038<p>
8039<hr><h3><a name="pdf-os.getenv"><code>os.getenv (varname)</code></a></h3>
8040
8041
8042<p>
8043Returns the value of the process environment variable <code>varname</code>,
8044or <b>nil</b> if the variable is not defined.
8045
8046
8047
8048
8049<p>
8050<hr><h3><a name="pdf-os.remove"><code>os.remove (filename)</code></a></h3>
8051
8052
8053<p>
8054Deletes the file or directory with the given name.
8055Directories must be empty to be removed.
8056If this function fails, it returns <b>nil</b>,
8057plus a string describing the error.
8058
8059
8060
8061
8062<p>
8063<hr><h3><a name="pdf-os.rename"><code>os.rename (oldname, newname)</code></a></h3>
8064
8065
8066<p>
8067Renames file or directory named <code>oldname</code> to <code>newname</code>.
8068If this function fails, it returns <b>nil</b>,
8069plus a string describing the error.
8070
8071
8072
8073
8074<p>
8075<hr><h3><a name="pdf-os.setlocale"><code>os.setlocale (locale [, category])</code></a></h3>
8076
8077
8078<p>
8079Sets the current locale of the program.
8080<code>locale</code> is a string specifying a locale;
8081<code>category</code> is an optional string describing which category to change:
8082<code>"all"</code>, <code>"collate"</code>, <code>"ctype"</code>,
8083<code>"monetary"</code>, <code>"numeric"</code>, or <code>"time"</code>;
8084the default category is <code>"all"</code>.
8085The function returns the name of the new locale,
8086or <b>nil</b> if the request cannot be honored.
8087
8088
8089<p>
8090If <code>locale</code> is the empty string,
8091the current locale is set to an implementation-defined native locale.
8092If <code>locale</code> is the string "<code>C</code>",
8093the current locale is set to the standard C locale.
8094
8095
8096<p>
8097When called with <b>nil</b> as the first argument,
8098this function only returns the name of the current locale
8099for the given category.
8100
8101
8102
8103
8104<p>
8105<hr><h3><a name="pdf-os.time"><code>os.time ([table])</code></a></h3>
8106
8107
8108<p>
8109Returns the current time when called without arguments,
8110or a time representing the date and time specified by the given table.
8111This table must have fields <code>year</code>, <code>month</code>, and <code>day</code>,
8112and may have fields <code>hour</code>, <code>min</code>, <code>sec</code>, and <code>isdst</code>
8113(for a description of these fields, see the <a href="#pdf-os.date"><code>os.date</code></a> function).
8114
8115
8116<p>
8117The returned value is a number, whose meaning depends on your system.
8118In POSIX, Windows, and some other systems, this number counts the number
8119of seconds since some given start time (the "epoch").
8120In other systems, the meaning is not specified,
8121and the number returned by <code>time</code> can be used only as an argument to
8122<code>date</code> and <code>difftime</code>.
8123
8124
8125
8126
8127<p>
8128<hr><h3><a name="pdf-os.tmpname"><code>os.tmpname ()</code></a></h3>
8129
8130
8131<p>
8132Returns a string with a file name that can
8133be used for a temporary file.
8134The file must be explicitly opened before its use
8135and explicitly removed when no longer needed.
8136
8137
8138<p>
8139On some systems (POSIX),
8140this function also creates a file with that name,
8141to avoid security risks.
8142(Someone else might create the file with wrong permissions
8143in the time between getting the name and creating the file.)
8144You still have to open the file to use it
8145and to remove it (even if you do not use it).
8146
8147
8148<p>
8149When possible,
8150you may prefer to use <a href="#pdf-io.tmpfile"><code>io.tmpfile</code></a>,
8151which automatically removes the file when the program ends.
8152
8153
8154
8155
8156
8157
8158
8159<h2>5.9 - <a name="5.9">The Debug Library</a></h2>
8160
8161<p>
8162This library provides
8163the functionality of the debug interface to Lua programs.
8164You should exert care when using this library.
8165The functions provided here should be used exclusively for debugging
8166and similar tasks, such as profiling.
8167Please resist the temptation to use them as a
8168usual programming tool:
8169they can be very slow.
8170Moreover, several of these functions
8171violate some assumptions about Lua code
8172(e.g., that variables local to a function
8173cannot be accessed from outside or
8174that userdata metatables cannot be changed by Lua code)
8175and therefore can compromise otherwise secure code.
8176
8177
8178<p>
8179All functions in this library are provided
8180inside the <a name="pdf-debug"><code>debug</code></a> table.
8181All functions that operate over a thread
8182have an optional first argument which is the
8183thread to operate over.
8184The default is always the current thread.
8185
8186
8187<p>
8188<hr><h3><a name="pdf-debug.debug"><code>debug.debug ()</code></a></h3>
8189
8190
8191<p>
8192Enters an interactive mode with the user,
8193running each string that the user enters.
8194Using simple commands and other debug facilities,
8195the user can inspect global and local variables,
8196change their values, evaluate expressions, and so on.
8197A line containing only the word <code>cont</code> finishes this function,
8198so that the caller continues its execution.
8199
8200
8201<p>
8202Note that commands for <code>debug.debug</code> are not lexically nested
8203within any function, and so have no direct access to local variables.
8204
8205
8206
8207
8208<p>
8209<hr><h3><a name="pdf-debug.getfenv"><code>debug.getfenv (o)</code></a></h3>
8210Returns the environment of object <code>o</code>.
8211
8212
8213
8214
8215<p>
8216<hr><h3><a name="pdf-debug.gethook"><code>debug.gethook ([thread])</code></a></h3>
8217
8218
8219<p>
8220Returns the current hook settings of the thread, as three values:
8221the current hook function, the current hook mask,
8222and the current hook count
8223(as set by the <a href="#pdf-debug.sethook"><code>debug.sethook</code></a> function).
8224
8225
8226
8227
8228<p>
8229<hr><h3><a name="pdf-debug.getinfo"><code>debug.getinfo ([thread,] function [, what])</code></a></h3>
8230
8231
8232<p>
8233Returns a table with information about a function.
8234You can give the function directly,
8235or you can give a number as the value of <code>function</code>,
8236which means the function running at level <code>function</code> of the call stack
8237of the given thread:
8238level&nbsp;0 is the current function (<code>getinfo</code> itself);
8239level&nbsp;1 is the function that called <code>getinfo</code>;
8240and so on.
8241If <code>function</code> is a number larger than the number of active functions,
8242then <code>getinfo</code> returns <b>nil</b>.
8243
8244
8245<p>
8246The returned table can contain all the fields returned by <a href="#lua_getinfo"><code>lua_getinfo</code></a>,
8247with the string <code>what</code> describing which fields to fill in.
8248The default for <code>what</code> is to get all information available,
8249except the table of valid lines.
8250If present,
8251the option '<code>f</code>'
8252adds a field named <code>func</code> with the function itself.
8253If present,
8254the option '<code>L</code>'
8255adds a field named <code>activelines</code> with the table of
8256valid lines.
8257
8258
8259<p>
8260For instance, the expression <code>debug.getinfo(1,"n").name</code> returns
8261a table with a name for the current function,
8262if a reasonable name can be found,
8263and the expression <code>debug.getinfo(print)</code>
8264returns a table with all available information
8265about the <a href="#pdf-print"><code>print</code></a> function.
8266
8267
8268
8269
8270<p>
8271<hr><h3><a name="pdf-debug.getlocal"><code>debug.getlocal ([thread,] level, local)</code></a></h3>
8272
8273
8274<p>
8275This function returns the name and the value of the local variable
8276with index <code>local</code> of the function at level <code>level</code> of the stack.
8277(The first parameter or local variable has index&nbsp;1, and so on,
8278until the last active local variable.)
8279The function returns <b>nil</b> if there is no local
8280variable with the given index,
8281and raises an error when called with a <code>level</code> out of range.
8282(You can call <a href="#pdf-debug.getinfo"><code>debug.getinfo</code></a> to check whether the level is valid.)
8283
8284
8285<p>
8286Variable names starting with '<code>(</code>' (open parentheses)
8287represent internal variables
8288(loop control variables, temporaries, and C&nbsp;function locals).
8289
8290
8291
8292
8293<p>
8294<hr><h3><a name="pdf-debug.getmetatable"><code>debug.getmetatable (object)</code></a></h3>
8295
8296
8297<p>
8298Returns the metatable of the given <code>object</code>
8299or <b>nil</b> if it does not have a metatable.
8300
8301
8302
8303
8304<p>
8305<hr><h3><a name="pdf-debug.getregistry"><code>debug.getregistry ()</code></a></h3>
8306
8307
8308<p>
8309Returns the registry table (see <a href="#3.5">&sect;3.5</a>).
8310
8311
8312
8313
8314<p>
8315<hr><h3><a name="pdf-debug.getupvalue"><code>debug.getupvalue (func, up)</code></a></h3>
8316
8317
8318<p>
8319This function returns the name and the value of the upvalue
8320with index <code>up</code> of the function <code>func</code>.
8321The function returns <b>nil</b> if there is no upvalue with the given index.
8322
8323
8324
8325
8326<p>
8327<hr><h3><a name="pdf-debug.setfenv"><code>debug.setfenv (object, table)</code></a></h3>
8328
8329
8330<p>
8331Sets the environment of the given <code>object</code> to the given <code>table</code>.
8332Returns <code>object</code>.
8333
8334
8335
8336
8337<p>
8338<hr><h3><a name="pdf-debug.sethook"><code>debug.sethook ([thread,] hook, mask [, count])</code></a></h3>
8339
8340
8341<p>
8342Sets the given function as a hook.
8343The string <code>mask</code> and the number <code>count</code> describe
8344when the hook will be called.
8345The string mask may have the following characters,
8346with the given meaning:
8347
8348<ul>
8349<li><b><code>"c"</code>:</b> the hook is called every time Lua calls a function;</li>
8350<li><b><code>"r"</code>:</b> the hook is called every time Lua returns from a function;</li>
8351<li><b><code>"l"</code>:</b> the hook is called every time Lua enters a new line of code.</li>
8352</ul><p>
8353With a <code>count</code> different from zero,
8354the hook is called after every <code>count</code> instructions.
8355
8356
8357<p>
8358When called without arguments,
8359<a href="#pdf-debug.sethook"><code>debug.sethook</code></a> turns off the hook.
8360
8361
8362<p>
8363When the hook is called, its first parameter is a string
8364describing the event that has triggered its call:
8365<code>"call"</code>, <code>"return"</code> (or <code>"tail return"</code>,
8366when simulating a return from a tail call),
8367<code>"line"</code>, and <code>"count"</code>.
8368For line events,
8369the hook also gets the new line number as its second parameter.
8370Inside a hook,
8371you can call <code>getinfo</code> with level&nbsp;2 to get more information about
8372the running function
8373(level&nbsp;0 is the <code>getinfo</code> function,
8374and level&nbsp;1 is the hook function),
8375unless the event is <code>"tail return"</code>.
8376In this case, Lua is only simulating the return,
8377and a call to <code>getinfo</code> will return invalid data.
8378
8379
8380
8381
8382<p>
8383<hr><h3><a name="pdf-debug.setlocal"><code>debug.setlocal ([thread,] level, local, value)</code></a></h3>
8384
8385
8386<p>
8387This function assigns the value <code>value</code> to the local variable
8388with index <code>local</code> of the function at level <code>level</code> of the stack.
8389The function returns <b>nil</b> if there is no local
8390variable with the given index,
8391and raises an error when called with a <code>level</code> out of range.
8392(You can call <code>getinfo</code> to check whether the level is valid.)
8393Otherwise, it returns the name of the local variable.
8394
8395
8396
8397
8398<p>
8399<hr><h3><a name="pdf-debug.setmetatable"><code>debug.setmetatable (object, table)</code></a></h3>
8400
8401
8402<p>
8403Sets the metatable for the given <code>object</code> to the given <code>table</code>
8404(which can be <b>nil</b>).
8405
8406
8407
8408
8409<p>
8410<hr><h3><a name="pdf-debug.setupvalue"><code>debug.setupvalue (func, up, value)</code></a></h3>
8411
8412
8413<p>
8414This function assigns the value <code>value</code> to the upvalue
8415with index <code>up</code> of the function <code>func</code>.
8416The function returns <b>nil</b> if there is no upvalue
8417with the given index.
8418Otherwise, it returns the name of the upvalue.
8419
8420
8421
8422
8423<p>
8424<hr><h3><a name="pdf-debug.traceback"><code>debug.traceback ([thread,] [message] [, level])</code></a></h3>
8425
8426
8427<p>
8428Returns a string with a traceback of the call stack.
8429An optional <code>message</code> string is appended
8430at the beginning of the traceback.
8431An optional <code>level</code> number tells at which level
8432to start the traceback
8433(default is 1, the function calling <code>traceback</code>).
8434
8435
8436
8437
8438
8439
8440
8441<h1>6 - <a name="6">Lua Stand-alone</a></h1>
8442
8443<p>
8444Although Lua has been designed as an extension language,
8445to be embedded in a host C&nbsp;program,
8446it is also frequently used as a stand-alone language.
8447An interpreter for Lua as a stand-alone language,
8448called simply <code>lua</code>,
8449is provided with the standard distribution.
8450The stand-alone interpreter includes
8451all standard libraries, including the debug library.
8452Its usage is:
8453
8454<pre>
8455 lua [options] [script [args]]
8456</pre><p>
8457The options are:
8458
8459<ul>
8460<li><b><code>-e <em>stat</em></code>:</b> executes string <em>stat</em>;</li>
8461<li><b><code>-l <em>mod</em></code>:</b> "requires" <em>mod</em>;</li>
8462<li><b><code>-i</code>:</b> enters interactive mode after running <em>script</em>;</li>
8463<li><b><code>-v</code>:</b> prints version information;</li>
8464<li><b><code>--</code>:</b> stops handling options;</li>
8465<li><b><code>-</code>:</b> executes <code>stdin</code> as a file and stops handling options.</li>
8466</ul><p>
8467After handling its options, <code>lua</code> runs the given <em>script</em>,
8468passing to it the given <em>args</em> as string arguments.
8469When called without arguments,
8470<code>lua</code> behaves as <code>lua -v -i</code>
8471when the standard input (<code>stdin</code>) is a terminal,
8472and as <code>lua -</code> otherwise.
8473
8474
8475<p>
8476Before running any argument,
8477the interpreter checks for an environment variable <a name="pdf-LUA_INIT"><code>LUA_INIT</code></a>.
8478If its format is <code>@<em>filename</em></code>,
8479then <code>lua</code> executes the file.
8480Otherwise, <code>lua</code> executes the string itself.
8481
8482
8483<p>
8484All options are handled in order, except <code>-i</code>.
8485For instance, an invocation like
8486
8487<pre>
8488 $ lua -e'a=1' -e 'print(a)' script.lua
8489</pre><p>
8490will first set <code>a</code> to 1, then print the value of <code>a</code> (which is '<code>1</code>'),
8491and finally run the file <code>script.lua</code> with no arguments.
8492(Here <code>$</code> is the shell prompt. Your prompt may be different.)
8493
8494
8495<p>
8496Before starting to run the script,
8497<code>lua</code> collects all arguments in the command line
8498in a global table called <code>arg</code>.
8499The script name is stored at index 0,
8500the first argument after the script name goes to index 1,
8501and so on.
8502Any arguments before the script name
8503(that is, the interpreter name plus the options)
8504go to negative indices.
8505For instance, in the call
8506
8507<pre>
8508 $ lua -la b.lua t1 t2
8509</pre><p>
8510the interpreter first runs the file <code>a.lua</code>,
8511then creates a table
8512
8513<pre>
8514 arg = { [-2] = "lua", [-1] = "-la",
8515 [0] = "b.lua",
8516 [1] = "t1", [2] = "t2" }
8517</pre><p>
8518and finally runs the file <code>b.lua</code>.
8519The script is called with <code>arg[1]</code>, <code>arg[2]</code>, &middot;&middot;&middot;
8520as arguments;
8521it can also access these arguments with the vararg expression '<code>...</code>'.
8522
8523
8524<p>
8525In interactive mode,
8526if you write an incomplete statement,
8527the interpreter waits for its completion
8528by issuing a different prompt.
8529
8530
8531<p>
8532If the global variable <a name="pdf-_PROMPT"><code>_PROMPT</code></a> contains a string,
8533then its value is used as the prompt.
8534Similarly, if the global variable <a name="pdf-_PROMPT2"><code>_PROMPT2</code></a> contains a string,
8535its value is used as the secondary prompt
8536(issued during incomplete statements).
8537Therefore, both prompts can be changed directly on the command line
8538or in any Lua programs by assigning to <code>_PROMPT</code>.
8539See the next example:
8540
8541<pre>
8542 $ lua -e"_PROMPT='myprompt&gt; '" -i
8543</pre><p>
8544(The outer pair of quotes is for the shell,
8545the inner pair is for Lua.)
8546Note the use of <code>-i</code> to enter interactive mode;
8547otherwise,
8548the program would just end silently
8549right after the assignment to <code>_PROMPT</code>.
8550
8551
8552<p>
8553To allow the use of Lua as a
8554script interpreter in Unix systems,
8555the stand-alone interpreter skips
8556the first line of a chunk if it starts with <code>#</code>.
8557Therefore, Lua scripts can be made into executable programs
8558by using <code>chmod +x</code> and the&nbsp;<code>#!</code> form,
8559as in
8560
8561<pre>
8562 #!/usr/local/bin/lua
8563</pre><p>
8564(Of course,
8565the location of the Lua interpreter may be different in your machine.
8566If <code>lua</code> is in your <code>PATH</code>,
8567then
8568
8569<pre>
8570 #!/usr/bin/env lua
8571</pre><p>
8572is a more portable solution.)
8573
8574
8575
8576<h1>7 - <a name="7">Incompatibilities with the Previous Version</a></h1>
8577
8578<p>
8579Here we list the incompatibilities that you may find when moving a program
8580from Lua&nbsp;5.0 to Lua&nbsp;5.1.
8581You can avoid most of the incompatibilities compiling Lua with
8582appropriate options (see file <code>luaconf.h</code>).
8583However,
8584all these compatibility options will be removed in the next version of Lua.
8585
8586
8587
8588<h2>7.1 - <a name="7.1">Changes in the Language</a></h2>
8589<ul>
8590
8591<li>
8592The vararg system changed from the pseudo-argument <code>arg</code> with a
8593table with the extra arguments to the vararg expression.
8594(See compile-time option <code>LUA_COMPAT_VARARG</code> in <code>luaconf.h</code>.)
8595</li>
8596
8597<li>
8598There was a subtle change in the scope of the implicit
8599variables of the <b>for</b> statement and for the <b>repeat</b> statement.
8600</li>
8601
8602<li>
8603The long string/long comment syntax (<code>[[<em>string</em>]]</code>)
8604does not allow nesting.
8605You can use the new syntax (<code>[=[<em>string</em>]=]</code>) in these cases.
8606(See compile-time option <code>LUA_COMPAT_LSTR</code> in <code>luaconf.h</code>.)
8607</li>
8608
8609</ul>
8610
8611
8612
8613
8614<h2>7.2 - <a name="7.2">Changes in the Libraries</a></h2>
8615<ul>
8616
8617<li>
8618Function <code>string.gfind</code> was renamed <a href="#pdf-string.gmatch"><code>string.gmatch</code></a>.
8619(See compile-time option <code>LUA_COMPAT_GFIND</code> in <code>luaconf.h</code>.)
8620</li>
8621
8622<li>
8623When <a href="#pdf-string.gsub"><code>string.gsub</code></a> is called with a function as its
8624third argument,
8625whenever this function returns <b>nil</b> or <b>false</b> the
8626replacement string is the whole match,
8627instead of the empty string.
8628</li>
8629
8630<li>
8631Function <code>table.setn</code> was deprecated.
8632Function <code>table.getn</code> corresponds
8633to the new length operator (<code>#</code>);
8634use the operator instead of the function.
8635(See compile-time option <code>LUA_COMPAT_GETN</code> in <code>luaconf.h</code>.)
8636</li>
8637
8638<li>
8639Function <code>loadlib</code> was renamed <a href="#pdf-package.loadlib"><code>package.loadlib</code></a>.
8640(See compile-time option <code>LUA_COMPAT_LOADLIB</code> in <code>luaconf.h</code>.)
8641</li>
8642
8643<li>
8644Function <code>math.mod</code> was renamed <a href="#pdf-math.fmod"><code>math.fmod</code></a>.
8645(See compile-time option <code>LUA_COMPAT_MOD</code> in <code>luaconf.h</code>.)
8646</li>
8647
8648<li>
8649Functions <code>table.foreach</code> and <code>table.foreachi</code> are deprecated.
8650You can use a for loop with <code>pairs</code> or <code>ipairs</code> instead.
8651</li>
8652
8653<li>
8654There were substantial changes in function <a href="#pdf-require"><code>require</code></a> due to
8655the new module system.
8656However, the new behavior is mostly compatible with the old,
8657but <code>require</code> gets the path from <a href="#pdf-package.path"><code>package.path</code></a> instead
8658of from <code>LUA_PATH</code>.
8659</li>
8660
8661<li>
8662Function <a href="#pdf-collectgarbage"><code>collectgarbage</code></a> has different arguments.
8663Function <code>gcinfo</code> is deprecated;
8664use <code>collectgarbage("count")</code> instead.
8665</li>
8666
8667</ul>
8668
8669
8670
8671
8672<h2>7.3 - <a name="7.3">Changes in the API</a></h2>
8673<ul>
8674
8675<li>
8676The <code>luaopen_*</code> functions (to open libraries)
8677cannot be called directly,
8678like a regular C function.
8679They must be called through Lua,
8680like a Lua function.
8681</li>
8682
8683<li>
8684Function <code>lua_open</code> was replaced by <a href="#lua_newstate"><code>lua_newstate</code></a> to
8685allow the user to set a memory-allocation function.
8686You can use <a href="#luaL_newstate"><code>luaL_newstate</code></a> from the standard library to
8687create a state with a standard allocation function
8688(based on <code>realloc</code>).
8689</li>
8690
8691<li>
8692Functions <code>luaL_getn</code> and <code>luaL_setn</code>
8693(from the auxiliary library) are deprecated.
8694Use <a href="#lua_objlen"><code>lua_objlen</code></a> instead of <code>luaL_getn</code>
8695and nothing instead of <code>luaL_setn</code>.
8696</li>
8697
8698<li>
8699Function <code>luaL_openlib</code> was replaced by <a href="#luaL_register"><code>luaL_register</code></a>.
8700</li>
8701
8702<li>
8703Function <code>luaL_checkudata</code> now throws an error when the given value
8704is not a userdata of the expected type.
8705(In Lua&nbsp;5.0 it returned <code>NULL</code>.)
8706</li>
8707
8708</ul>
8709
8710
8711
8712
8713<h1>8 - <a name="8">The Complete Syntax of Lua</a></h1>
8714
8715<p>
8716Here is the complete syntax of Lua in extended BNF.
8717(It does not describe operator precedences.)
8718
8719
8720
8721
8722<pre>
8723
8724 chunk ::= {stat [`<b>;</b>&acute;]} [laststat [`<b>;</b>&acute;]]
8725
8726 block ::= chunk
8727
8728 stat ::= varlist `<b>=</b>&acute; explist |
8729 functioncall |
8730 <b>do</b> block <b>end</b> |
8731 <b>while</b> exp <b>do</b> block <b>end</b> |
8732 <b>repeat</b> block <b>until</b> exp |
8733 <b>if</b> exp <b>then</b> block {<b>elseif</b> exp <b>then</b> block} [<b>else</b> block] <b>end</b> |
8734 <b>for</b> Name `<b>=</b>&acute; exp `<b>,</b>&acute; exp [`<b>,</b>&acute; exp] <b>do</b> block <b>end</b> |
8735 <b>for</b> namelist <b>in</b> explist <b>do</b> block <b>end</b> |
8736 <b>function</b> funcname funcbody |
8737 <b>local</b> <b>function</b> Name funcbody |
8738 <b>local</b> namelist [`<b>=</b>&acute; explist]
8739
8740 laststat ::= <b>return</b> [explist] | <b>break</b>
8741
8742 funcname ::= Name {`<b>.</b>&acute; Name} [`<b>:</b>&acute; Name]
8743
8744 varlist ::= var {`<b>,</b>&acute; var}
8745
8746 var ::= Name | prefixexp `<b>[</b>&acute; exp `<b>]</b>&acute; | prefixexp `<b>.</b>&acute; Name
8747
8748 namelist ::= Name {`<b>,</b>&acute; Name}
8749
8750 explist ::= {exp `<b>,</b>&acute;} exp
8751
8752 exp ::= <b>nil</b> | <b>false</b> | <b>true</b> | Number | String | `<b>...</b>&acute; | function |
8753 prefixexp | tableconstructor | exp binop exp | unop exp
8754
8755 prefixexp ::= var | functioncall | `<b>(</b>&acute; exp `<b>)</b>&acute;
8756
8757 functioncall ::= prefixexp args | prefixexp `<b>:</b>&acute; Name args
8758
8759 args ::= `<b>(</b>&acute; [explist] `<b>)</b>&acute; | tableconstructor | String
8760
8761 function ::= <b>function</b> funcbody
8762
8763 funcbody ::= `<b>(</b>&acute; [parlist] `<b>)</b>&acute; block <b>end</b>
8764
8765 parlist ::= namelist [`<b>,</b>&acute; `<b>...</b>&acute;] | `<b>...</b>&acute;
8766
8767 tableconstructor ::= `<b>{</b>&acute; [fieldlist] `<b>}</b>&acute;
8768
8769 fieldlist ::= field {fieldsep field} [fieldsep]
8770
8771 field ::= `<b>[</b>&acute; exp `<b>]</b>&acute; `<b>=</b>&acute; exp | Name `<b>=</b>&acute; exp | exp
8772
8773 fieldsep ::= `<b>,</b>&acute; | `<b>;</b>&acute;
8774
8775 binop ::= `<b>+</b>&acute; | `<b>-</b>&acute; | `<b>*</b>&acute; | `<b>/</b>&acute; | `<b>^</b>&acute; | `<b>%</b>&acute; | `<b>..</b>&acute; |
8776 `<b>&lt;</b>&acute; | `<b>&lt;=</b>&acute; | `<b>&gt;</b>&acute; | `<b>&gt;=</b>&acute; | `<b>==</b>&acute; | `<b>~=</b>&acute; |
8777 <b>and</b> | <b>or</b>
8778
8779 unop ::= `<b>-</b>&acute; | <b>not</b> | `<b>#</b>&acute;
8780
8781</pre>
8782
8783<p>
8784
8785
8786
8787
8788
8789
8790
8791<HR>
8792<SMALL>
8793Last update:
8794Mon Aug 18 13:25:46 BRT 2008
8795</SMALL>
8796<!--
8797Last change: revised for Lua 5.1.4
8798-->
8799
8800</body></html>
8801