| blob | 118d9059ffba751062da7651b25b0e3e3e3d3020 |
2 <html>
4 <head>
9 </head>
11 <body>
13 <hr>
14 <h1>
16 Lua 5.1 Reference Manual
17 </h1>
19 by Roberto Ierusalimschy, Luiz Henrique de Figueiredo, Waldemar Celes
20 <p>
21 <small>
23 Freely available under the terms of the
25 </small>
26 <hr>
27 <p>
30 ·
33 <!-- ====================================================================== -->
34 <p>
36 <!-- $Id: manual.of,v 1.48 2008/08/18 15:24:20 roberto Exp $ -->
43 <p>
44 Lua is an extension programming language designed to support
45 general procedural programming with data description
46 facilities.
47 It also offers good support for object-oriented programming,
48 functional programming, and data-driven programming.
49 Lua is intended to be used as a powerful, light-weight
50 scripting language for any program that needs one.
52 (that is, in the common subset of ANSI C and C++).
55 <p>
56 Being an extension language, Lua has no notion of a "main" program:
59 This host program can invoke functions to execute a piece of Lua code,
60 can write and read Lua variables,
61 and can register C functions to be called by Lua code.
62 Through the use of C functions, Lua can be augmented to cope with
63 a wide range of different domains,
64 thus creating customized programming languages sharing a syntactical framework.
66 which uses the Lua library to offer a complete, stand-alone Lua interpreter.
69 <p>
70 Lua is free software,
71 and is provided as usual with no guarantees,
72 as stated in its license.
73 The implementation described in this manual is available
77 <p>
78 Like any other reference manual,
79 this document is dry in places.
80 For a discussion of the decisions behind the design of Lua,
81 see the technical papers available at Lua's web site.
82 For a detailed introduction to programming in Lua,
89 <p>
90 This section describes the lexis, the syntax, and the semantics of Lua.
91 In other words,
92 this section describes
93 which tokens are valid,
94 how they can be combined,
95 and what their combinations mean.
98 <p>
99 The language constructs will be explained using the usual extended BNF notation,
100 in which
103 Non-terminals are shown like non-terminal,
107 at the end of this manual.
113 <p>
116 in Lua can be any string of letters,
117 digits, and underscores,
118 not beginning with a digit.
119 This coincides with the definition of names in most languages.
120 (The definition of letter depends on the current locale:
121 any character considered alphabetic by the current locale
122 can be used in an identifier.)
123 Identifiers are used to name variables and table fields.
126 <p>
128 and cannot be used as names:
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>
138 <p>
139 Lua is a case-sensitive language:
141 are two different, valid names.
142 As a convention, names starting with an underscore followed by
144 are reserved for internal global variables used by Lua.
147 <p>
148 The following strings denote other tokens:
150 <pre>
151 + - * / % ^ #
153 ( ) { } [ ]
154 ; : , . .. ...
155 </pre>
157 <p>
159 can be delimited by matching single or double quotes,
160 and can contain the following C-like escape sequences:
170 and '<code>\'</code>' (apostrophe [single quote]).
171 Moreover, a backslash followed by a real newline
172 results in a newline in the string.
173 A character in a string can also be specified by its numerical value
174 using the escape sequence <code>\<em>ddd</em></code>,
175 where <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,
177 it must be expressed using exactly three digits.)
178 Strings in Lua can contain any 8-bit value, including embedded zeros,
179 which can be specified as '<code>\0</code>'.
182 <p>
183 Literal strings can also be defined using a long format
184 enclosed by <em>long brackets</em>.
185 We define an <em>opening long bracket of level <em>n</em></em> as an opening
186 square bracket followed by <em>n</em> equal signs followed by another
187 opening square bracket.
188 So, an opening long bracket of level 0 is written as <code>[[</code>,
189 an opening long bracket of level 1 is written as <code>[=[</code>,
190 and so on.
191 A <em>closing long bracket</em> is defined similarly;
192 for instance, a closing long bracket of level 4 is written as <code>]====]</code>.
193 A long string starts with an opening long bracket of any level and
194 ends at the first closing long bracket of the same level.
195 Literals in this bracketed form can run for several lines,
196 do not interpret any escape sequences,
197 and ignore long brackets of any other level.
198 They can contain anything except a closing bracket of the proper level.
201 <p>
202 For convenience,
203 when the opening long bracket is immediately followed by a newline,
204 the newline is not included in the string.
205 As an example, in a system using ASCII
206 (in which '<code>a</code>' is coded as 97,
207 newline is coded as 10, and '<code>1</code>' is coded as 49),
208 the five literal strings below denote the same string:
210 <pre>
211 a = 'alo\n123"'
213 a = '\97lo\10\04923"'
214 a = [[alo
216 a = [==[
217 alo
218 123"]==]
219 </pre>
221 <p>
223 and an optional decimal exponent.
224 Lua also accepts integer hexadecimal constants,
226 Examples of valid numerical constants are
228 <pre>
230 </pre>
232 <p>
234 anywhere outside a string.
237 which runs until the end of the line.
239 which runs until the corresponding closing long bracket.
240 Long comments are frequently used to disable code temporarily.
248 <p>
250 This means that
251 variables do not have types; only values do.
252 There are no type definitions in the language.
253 All values carry their own type.
256 <p>
258 This means that all values can be stored in variables,
259 passed as arguments to other functions, and returned as results.
262 <p>
263 There are eight basic types in Lua:
268 whose main property is to be different from any other value;
269 it usually represents the absence of a useful value.
272 any other value makes it true.
274 (It is easy to build Lua interpreters that use other
275 internal representations for numbers,
276 such as single-precision float or long integers;
280 Lua is 8-bit clean:
281 strings can contain any 8-bit character,
285 <p>
286 Lua can call (and manipulate) functions written in Lua and
287 functions written in C
291 <p>
293 be stored in Lua variables.
294 This type corresponds to a block of raw memory
295 and has no pre-defined operations in Lua,
296 except assignment and identity test.
298 the programmer can define operations for userdata values
300 Userdata values cannot be created or modified in Lua,
301 only through the C API.
302 This guarantees the integrity of data owned by the host program.
305 <p>
308 Do not confuse Lua threads with operating-system threads.
309 Lua supports coroutines on all systems,
310 even those that do not support threads.
313 <p>
315 that is, arrays that can be indexed not only with numbers,
319 Tables are the sole data structuring mechanism in Lua;
320 they can be used to represent ordinary arrays,
321 symbol tables, sets, records, graphs, trees, etc.
322 To represent records, Lua uses the field name as an index.
323 The language supports this representation by
325 There are several convenient ways to create tables in Lua
329 <p>
330 Like indices,
332 In particular,
333 because functions are first-class values,
334 table fields can contain functions.
338 <p>
342 Assignment, parameter passing, and function returns
343 always manipulate references to such values;
344 these operations do not imply any kind of copy.
347 <p>
348 The library function <a href="#pdf-type"><code>type</code></a> returns a string describing the type
349 of a given value.
355 <p>
356 Lua provides automatic conversion between
357 string and number values at run time.
358 Any arithmetic operation applied to a string tries to convert
359 this string to a number, following the usual conversion rules.
360 Conversely, whenever a number is used where a string is expected,
361 the number is converted to a string, in a reasonable format.
362 For complete control over how numbers are converted to strings,
374 <p>
375 Variables are places that store values.
377 There are three kinds of variables in Lua:
378 global variables, local variables, and table fields.
381 <p>
382 A single name can denote a global variable or a local variable
383 (or a function's formal parameter,
384 which is a particular kind of local variable):
386 <pre>
387 var ::= Name
388 </pre><p>
392 <p>
393 Any variable is assumed to be global unless explicitly declared
396 local variables can be freely accessed by functions
400 <p>
404 <p>
405 Square brackets are used to index a table:
407 <pre>
409 </pre><p>
410 The meaning of accesses to global variables
411 and table fields can be changed via metatables.
416 This function is not defined or callable in Lua.
417 We use it here only for explanatory purposes.)
420 <p>
424 <pre>
426 </pre>
428 <p>
429 All global variables live as fields in ordinary Lua tables,
432 Each function has its own reference to an environment,
433 so that all global variables in this function
434 will refer to this environment table.
435 When a function is created,
436 it inherits the environment from the function that created it.
437 To get the environment table of a Lua function,
439 To replace it,
441 (You can only manipulate the environment of C functions
445 <p>
448 which in turn is equivalent to
450 <pre>
451 gettable_event(_env, "x")
452 </pre><p>
456 This function is not defined or callable in Lua.
458 We use them here only for explanatory purposes.)
466 <p>
467 Lua supports an almost conventional set of statements,
468 similar to those in Pascal or C.
469 This set includes
470 assignments, control structures, function calls,
471 and variable declarations.
477 <p>
479 A chunk is simply a sequence of statements,
480 which are executed sequentially.
481 Each statement can be optionally followed by a semicolon:
483 <pre>
485 </pre><p>
489 <p>
490 Lua handles a chunk as the body of an anonymous function
491 with a variable number of arguments
493 As such, chunks can define local variables,
494 receive arguments, and return values.
497 <p>
498 A chunk can be stored in a file or in a string inside the host program.
499 To execute a chunk,
500 Lua first pre-compiles the chunk into instructions for a virtual machine,
501 and then it executes the compiled code
502 with an interpreter for the virtual machine.
505 <p>
506 Chunks can also be pre-compiled into binary form;
508 Programs in source and compiled forms are interchangeable;
509 Lua automatically detects the file type and acts accordingly.
517 A block is a list of statements;
518 syntactically, a block is the same as a chunk:
520 <pre>
521 block ::= chunk
522 </pre>
524 <p>
525 A block can be explicitly delimited to produce a single statement:
527 <pre>
529 </pre><p>
530 Explicit blocks are useful
531 to control the scope of variable declarations.
532 Explicit blocks are also sometimes used to
542 <p>
543 Lua allows multiple assignments.
544 Therefore, the syntax for assignment
545 defines a list of variables on the left side
546 and a list of expressions on the right side.
547 The elements in both lists are separated by commas:
549 <pre>
553 </pre><p>
557 <p>
558 Before the assignment,
560 the list of variables.
561 If there are more values than needed,
562 the excess values are thrown away.
563 If there are fewer values than needed,
565 If the list of expressions ends with a function call,
566 then all values returned by that call enter the list of values,
567 before the adjustment
571 <p>
572 The assignment statement first evaluates all its expressions
573 and only then are the assignments performed.
574 Thus the code
576 <pre>
577 i = 3
579 </pre><p>
583 Similarly, the line
585 <pre>
586 x, y = y, x
587 </pre><p>
589 and
591 <pre>
592 x, y, z = y, z, x
593 </pre><p>
597 <p>
598 The meaning of assignments to global variables
599 and table fields can be changed via metatables.
604 This function is not defined or callable in Lua.
605 We use it here only for explanatory purposes.)
608 <p>
610 is equivalent to the assignment
612 which in turn is equivalent to
614 <pre>
615 settable_event(_env, "x", val)
616 </pre><p>
619 We use it here only for explanatory purposes.)
626 The control structures
628 familiar syntax:
633 <pre>
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>
641 <p>
642 The condition expression of a
643 control structure can return any value.
646 (in particular, the number 0 and the empty string are also true).
649 <p>
652 but only after the condition.
653 So, the condition can refer to local variables
654 declared inside the loop block.
657 <p>
659 from a function or a chunk (which is just a function).
661 Functions and chunks can return more than one value,
664 <pre>
666 </pre>
668 <p>
671 skipping to the next statement after the loop:
674 <pre>
676 </pre><p>
680 <p>
684 middle of a block,
685 then an explicit inner block can be used,
686 as in the idioms
689 their (inner) blocks.
697 <p>
700 one numeric and one generic.
703 <p>
705 control variable runs through an arithmetic progression.
706 It has the following syntax:
708 <pre>
709 stat ::= <b>for</b> Name `<b>=</b>´ exp `<b>,</b>´ exp [`<b>,</b>´ exp] <b>do</b> block <b>end</b>
710 </pre><p>
716 <pre>
718 </pre><p>
719 is equivalent to the code:
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>)
725 while (<em>step</em> > 0 and <em>var</em> <= <em>limit</em>) or (<em>step</em> <= 0 and <em>var</em> >= <em>limit</em>) do
729 end
730 end
731 </pre><p>
732 Note the following:
734 <ul>
736 <li>
737 All three control expressions are evaluated only once,
738 before the loop starts.
739 They must all result in numbers.
740 </li>
742 <li>
743 <code><em>var</em></code>, <code><em>limit</em></code>, and <code><em>step</em></code> are invisible variables.
744 The names shown here are for explanatory purposes only.
745 </li>
747 <li>
748 If the third expression (the step) is absent,
750 </li>
752 <li>
754 </li>
756 <li>
759 If you need this value,
760 assign it to another variable before breaking or exiting the loop.
761 </li>
763 </ul>
765 <p>
768 On each iteration, the iterator function is called to produce a new value,
772 <pre>
775 </pre><p>
778 <pre>
779 for <em>var_1</em>, ···, <em>var_n</em> in <em>explist</em> do <em>block</em> end
780 </pre><p>
781 is equivalent to the code:
783 <pre>
784 do
786 while true do
787 local <em>var_1</em>, ···, <em>var_n</em> = <em>f</em>(<em>s</em>, <em>var</em>)
791 end
792 end
793 </pre><p>
794 Note the following:
796 <ul>
798 <li>
803 </li>
805 <li>
806 <code><em>f</em></code>, <code><em>s</em></code>, and <code><em>var</em></code> are invisible variables.
807 The names are here for explanatory purposes only.
808 </li>
810 <li>
812 </li>
814 <li>
817 If you need these values,
818 then assign them to other variables before breaking or exiting the loop.
819 </li>
821 </ul>
827 To allow possible side-effects,
828 function calls can be executed as statements:
830 <pre>
831 stat ::= functioncall
832 </pre><p>
833 In this case, all returned values are thrown away.
841 Local variables can be declared anywhere inside a block.
842 The declaration can include an initial assignment:
844 <pre>
846 </pre><p>
847 If present, an initial assignment has the same semantics
852 <p>
854 and so local variables can be declared in a chunk outside any explicit block.
855 The scope of such local variables extends until the end of the chunk.
858 <p>
869 <p>
870 The basic expressions in Lua are the following:
872 <pre>
873 exp ::= prefixexp
875 exp ::= Number
876 exp ::= String
877 exp ::= function
878 exp ::= tableconstructor
880 exp ::= exp binop exp
881 exp ::= unop exp
883 </pre>
885 <p>
891 Vararg expressions,
893 directly inside a vararg function;
897 <p>
899 relational operators (see <a href="#2.5.2">§2.5.2</a>), logical operators (see <a href="#2.5.3">§2.5.3</a>),
906 <p>
907 Both function calls and vararg expressions can result in multiple values.
908 If an expression is used as a statement
910 then its return list is adjusted to zero elements,
911 thus discarding all returned values.
912 If an expression is used as the last (or the only) element
913 of a list of expressions,
914 then no adjustment is made
915 (unless the call is enclosed in parentheses).
916 In all other contexts,
917 Lua adjusts the result list to one element,
918 discarding all values except the first one.
921 <p>
922 Here are some examples:
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)
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>
943 <p>
944 Any expression enclosed in parentheses always results in only one value.
945 Thus,
954 Lua supports the usual arithmetic operators:
959 If the operands are numbers, or strings that can be converted to
961 then all operations have the usual meaning.
962 Exponentiation works for any exponent.
964 Modulo is defined as
966 <pre>
967 a % b == a - math.floor(a/b)*b
968 </pre><p>
969 That is, it is the remainder of a division that rounds
970 the quotient towards minus infinity.
977 The relational operators in Lua are
979 <pre>
981 </pre><p>
985 <p>
988 Otherwise, the values of the operands are compared.
989 Numbers and strings are compared in the usual way.
990 Objects (tables, userdata, threads, and functions)
993 Every time you create a new object
994 (a table, userdata, thread, or function),
995 this new object is different from any previously existing object.
998 <p>
999 You can change the way that Lua compares tables and userdata
1003 <p>
1008 entries in a table.
1011 <p>
1015 <p>
1016 The order operators work as follows.
1017 If both arguments are numbers, then they are compared as such.
1018 Otherwise, if both arguments are strings,
1019 then their values are compared according to the current locale.
1030 The logical operators in Lua are
1034 and anything else as true.
1037 <p>
1046 that is,
1047 the second operand is evaluated only if necessary.
1048 Here are some examples:
1050 <pre>
1055 false and error() --> false
1056 false and nil --> false
1057 false or nil --> nil
1059 </pre><p>
1060 (In this manual,
1068 The string concatenation operator in Lua is
1070 If both operands are strings or numbers, then they are converted to
1080 <p>
1082 The length of a string is its number of bytes
1083 (that is, the usual meaning of string length when each
1084 character is one byte).
1087 <p>
1094 the index of its last value.
1095 If the array has "holes"
1100 the array).
1107 Operator precedence in Lua follows the table below,
1108 from lower to higher priority:
1110 <pre>
1111 or
1112 and
1114 ..
1115 + -
1116 * / %
1117 not # - (unary)
1118 ^
1119 </pre><p>
1120 As usual,
1121 you can use parentheses to change the precedences of an expression.
1123 operators are right associative.
1124 All other binary operators are left associative.
1131 Table constructors are expressions that create tables.
1132 Every time a constructor is evaluated, a new table is created.
1133 A constructor can be used to create an empty table
1134 or to create a table and initialize some of its fields.
1135 The general syntax for constructors is
1137 <pre>
1139 fieldlist ::= field {fieldsep field} [fieldsep]
1140 field ::= `<b>[</b>´ exp `<b>]</b>´ `<b>=</b>´ exp | Name `<b>=</b>´ exp | exp
1142 </pre>
1144 <p>
1151 starting with 1.
1152 Fields in the other formats do not affect this counting.
1153 For example,
1155 <pre>
1157 </pre><p>
1158 is equivalent to
1160 <pre>
1161 do
1162 local t = {}
1163 t[f(1)] = g
1170 a = t
1171 end
1172 </pre>
1174 <p>
1176 and the expression is a function call or a vararg expression,
1177 then all values returned by this expression enter the list consecutively
1179 To avoid this,
1180 enclose the function call or the vararg expression
1184 <p>
1185 The field list can have an optional trailing separator,
1186 as a convenience for machine-generated code.
1193 A function call in Lua has the following syntax:
1195 <pre>
1196 functioncall ::= prefixexp args
1197 </pre><p>
1198 In a function call,
1199 first prefixexp and args are evaluated.
1201 then this function is called
1202 with the given arguments.
1203 Otherwise, the prefixexp "call" metamethod is called,
1204 having as first parameter the value of prefixexp,
1205 followed by the original call arguments
1209 <p>
1210 The form
1212 <pre>
1214 </pre><p>
1215 can be used to call "methods".
1221 <p>
1222 Arguments have the following syntax:
1224 <pre>
1226 args ::= tableconstructor
1227 args ::= String
1228 </pre><p>
1229 All argument expressions are evaluated before the call.
1232 that is, the argument list is a single new table.
1236 that is, the argument list is a single literal string.
1239 <p>
1240 As an exception to the free-format syntax of Lua,
1242 This restriction avoids some ambiguities in the language.
1243 If you write
1245 <pre>
1246 a = f
1247 (g).x(a)
1248 </pre><p>
1250 So, if you want two statements, you must add a semi-colon between them.
1255 <p>
1260 in a tail call,
1261 the called function reuses the stack entry of the calling function.
1262 Therefore, there is no limit on the number of nested tail calls that
1263 a program can execute.
1264 However, a tail call erases any debug information about the
1265 calling function.
1266 Note that a tail call only happens with a particular syntax,
1268 this syntax makes the calling function return exactly
1269 the returns of the called function.
1270 So, none of the following examples are tail calls:
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>
1285 <p>
1286 The syntax for function definition is
1288 <pre>
1291 </pre>
1293 <p>
1294 The following syntactic sugar simplifies function definitions:
1296 <pre>
1300 </pre><p>
1301 The statement
1303 <pre>
1305 </pre><p>
1306 translates to
1308 <pre>
1310 </pre><p>
1311 The statement
1313 <pre>
1315 </pre><p>
1316 translates to
1318 <pre>
1320 </pre><p>
1321 The statement
1323 <pre>
1325 </pre><p>
1326 translates to
1328 <pre>
1330 </pre><p>
1333 <pre>
1335 </pre><p>
1336 (This only makes a difference when the body of the function
1340 <p>
1341 A function definition is an executable expression,
1343 When Lua pre-compiles a chunk,
1344 all its function bodies are pre-compiled too.
1345 Then, whenever Lua executes the function definition,
1348 is the final value of the expression.
1349 Different instances of the same function
1350 can refer to different external local variables
1351 and can have different environment tables.
1354 <p>
1355 Parameters act as local variables that are
1356 initialized with the argument values:
1358 <pre>
1360 </pre><p>
1361 When a function is called,
1362 the list of arguments is adjusted to
1363 the length of the list of parameters,
1365 which is
1367 A vararg function does not adjust its argument list;
1368 instead, it collects all extra arguments and supplies them
1370 which is also written as three dots.
1371 The value of this expression is a list of all actual extra arguments,
1372 similar to a function with multiple results.
1373 If a vararg expression is used inside another expression
1374 or in the middle of a list of expressions,
1375 then its return list is adjusted to one element.
1376 If the expression is used as the last element of a list of expressions,
1377 then no adjustment is made
1378 (unless that last expression is enclosed in parentheses).
1381 <p>
1382 As an example, consider the following definitions:
1384 <pre>
1385 function f(a, b) end
1386 function g(a, b, ...) end
1388 </pre><p>
1389 Then, we have the following mapping from arguments to parameters and
1390 to the vararg expression:
1392 <pre>
1393 CALL PARAMETERS
1405 </pre>
1407 <p>
1409 If control reaches the end of a function
1411 then the function returns with no results.
1414 <p>
1418 Thus, the statement
1420 <pre>
1422 </pre><p>
1423 is syntactic sugar for
1425 <pre>
1427 </pre>
1436 <p>
1438 Lua is a lexically scoped language.
1440 their declaration and lasts until the end of the innermost block that
1441 includes the declaration.
1442 Consider the following example:
1444 <pre>
1445 x = 10 -- global variable
1446 do -- new block
1447 local x = x -- new 'x', with value 10
1449 x = x+1
1450 do -- another block
1451 local x = x+1 -- another 'x'
1453 end
1455 end
1457 </pre>
1459 <p>
1465 <p>
1466 Because of the lexical scoping rules,
1467 local variables can be freely accessed by functions
1468 defined inside their scope.
1469 A local variable used by an inner function is called
1471 inside the inner function.
1474 <p>
1476 defines new local variables.
1477 Consider the following example:
1479 <pre>
1480 a = {}
1481 local x = 20
1483 local y = 0
1484 a[i] = function () y=y+1; return x+y end
1485 end
1486 </pre><p>
1487 The loop creates ten closures
1488 (that is, ten instances of the anonymous function).
1498 <p>
1499 Because Lua is an embedded extension language,
1500 all Lua actions start from C code in the host program
1502 Whenever an error occurs during Lua compilation or execution,
1503 control returns to C,
1504 which can take appropriate measures
1505 (such as printing an error message).
1508 <p>
1509 Lua code can explicitly generate an error by calling the
1511 If you need to catch errors in Lua,
1520 <p>
1523 that defines the behavior of the original value
1524 under certain special operations.
1525 You can change several aspects of the behavior
1526 of operations over a value by setting specific fields in its metatable.
1527 For instance, when a non-numeric value is the operand of an addition,
1529 If it finds one,
1530 Lua calls this function to perform the addition.
1533 <p>
1537 and the metamethod is the function that performs the addition.
1540 <p>
1541 You can query the metatable of any value
1545 <p>
1546 You can replace the metatable of tables
1548 function.
1549 You cannot change the metatable of other types from Lua
1550 (except by using the debug library);
1551 you must use the C API for that.
1554 <p>
1555 Tables and full userdata have individual metatables
1556 (although multiple tables and userdata can share their metatables).
1557 Values of all other types share one single metatable per type;
1558 that is, there is one single metatable for all numbers,
1559 one for all strings, etc.
1562 <p>
1563 A metatable controls how an object behaves in arithmetic operations,
1564 order comparisons, concatenation, length operation, and indexing.
1565 A metatable also can define a function to be called when a userdata
1566 is garbage collected.
1567 For each of these operations Lua associates a specific key
1569 When Lua performs one of these operations over a value,
1570 it checks whether this value has a metatable with the corresponding event.
1571 If so, the value associated with that key (the metamethod)
1572 controls how Lua will perform the operation.
1575 <p>
1576 Metatables control the operations listed next.
1577 Each operation is identified by its corresponding name.
1578 The key for each operation is a string with its name prefixed by
1580 for instance, the key for operation "add" is the
1582 The semantics of these operations is better explained by a Lua function
1583 describing how the interpreter executes the operation.
1586 <p>
1587 The code shown here in Lua is only illustrative;
1588 the real behavior is hard coded in the interpreter
1589 and it is much more efficient than this simulation.
1590 All functions used in these descriptions
1591 (<a href="#pdf-rawget"><code>rawget</code></a>, <a href="#pdf-tonumber"><code>tonumber</code></a>, etc.)
1593 In particular, to retrieve the metamethod of a given object,
1594 we use the expression
1596 <pre>
1597 metatable(obj)[event]
1598 </pre><p>
1599 This should be read as
1601 <pre>
1602 rawget(getmetatable(obj) or {}, event)
1603 </pre><p>
1605 That is, the access to a metamethod does not invoke other metamethods,
1606 and the access to objects with no metatables does not fail
1611 <ul>
1618 <p>
1620 for a binary operation.
1621 First, Lua tries the first operand.
1622 If its type does not define a handler for the operation,
1623 then Lua tries the second operand.
1625 <pre>
1626 function getbinhandler (op1, op2, event)
1627 return metatable(op1)[event] or metatable(op2)[event]
1628 end
1629 </pre><p>
1630 By using this function,
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(···)
1645 end
1646 end
1647 end
1648 </pre><p>
1649 </li>
1654 Behavior similar to the "add" operation.
1655 </li>
1660 Behavior similar to the "add" operation.
1661 </li>
1666 Behavior similar to the "add" operation.
1667 </li>
1672 Behavior similar to the "add" operation,
1673 with the operation
1675 </li>
1680 Behavior similar to the "add" operation,
1682 as the primitive operation.
1683 </li>
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(···)
1702 end
1703 end
1704 end
1705 </pre><p>
1706 </li>
1712 <pre>
1713 function concat_event (op1, op2)
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(···)
1723 end
1724 end
1725 end
1726 </pre><p>
1727 </li>
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(···)
1746 end
1747 end
1748 end
1749 </pre><p>
1751 </li>
1757 for comparison operators.
1758 A metamethod only is selected when both objects
1759 being compared have the same type
1760 and the same metamethod for the selected operation.
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>
1770 The "eq" event is defined as follows:
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>
1790 </li>
1796 <pre>
1797 function lt_event (op1, op2)
1799 return op1 < op2 -- numeric comparison
1801 return op1 < 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(···)
1808 end
1809 end
1810 end
1811 </pre><p>
1813 </li>
1819 <pre>
1820 function le_event (op1, op2)
1822 return op1 <= op2 -- numeric comparison
1824 return op1 <= 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(···)
1835 end
1836 end
1837 end
1838 end
1839 </pre><p>
1841 Note that, in the absence of a "le" metamethod,
1844 </li>
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(···)
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>
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(···)
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>
1899 called when Lua calls a value.
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(···)
1912 end
1913 end
1914 end
1915 </pre><p>
1916 </li>
1918 </ul>
1925 <p>
1926 Besides metatables,
1927 objects of types thread, function, and userdata
1928 have another table associated with them,
1930 Like metatables, environments are regular tables and
1931 multiple objects can share the same environment.
1934 <p>
1935 Threads are created sharing the environment of the creating thread.
1936 Userdata and C functions are created sharing the environment
1937 of the creating C function.
1938 Non-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>)
1940 are created sharing the environment of the creating thread.
1941 Nested Lua functions are created sharing the environment of
1942 the creating Lua function.
1945 <p>
1946 Environments associated with userdata have no meaning for Lua.
1947 It is only a convenience feature for programmers to associate a table to
1948 a userdata.
1951 <p>
1952 Environments associated with threads are called
1954 They are used as the default environment for threads and
1955 non-nested Lua functions created by the thread
1959 <p>
1960 The environment associated with a C function can be directly
1962 It is used as the default environment for other C functions
1963 and userdata created by the function.
1966 <p>
1967 Environments associated with Lua functions are used to resolve
1969 They are used as the default environment for nested Lua functions
1970 created by the function.
1973 <p>
1974 You can change the environment of a Lua function or the
1976 You can get the environment of a Lua function or the running thread
1978 To manipulate the environment of other objects
1979 (userdata, C functions, other threads) you must
1980 use the C API.
1988 <p>
1989 Lua performs automatic memory management.
1990 This means that
1991 you have to worry neither about allocating memory for new objects
1992 nor about freeing it when the objects are no longer needed.
1993 Lua manages memory automatically by running
1996 (that is, objects that are no longer accessible from Lua).
1997 All memory used by Lua is subject to automatic management:
1998 tables, userdata, functions, threads, strings, etc.
2001 <p>
2002 Lua implements an incremental mark-and-sweep collector.
2003 It uses two numbers to control its garbage-collection cycles:
2006 Both use percentage points as units
2010 <p>
2011 The garbage-collector pause
2012 controls how long the collector waits before starting a new cycle.
2013 Larger values make the collector less aggressive.
2014 Values smaller than 100 mean the collector will not wait to
2015 start a new cycle.
2016 A value of 200 means that the collector waits for the total memory in use
2017 to double before starting a new cycle.
2020 <p>
2021 The step multiplier
2022 controls the relative speed of the collector relative to
2023 memory allocation.
2024 Larger values make the collector more aggressive but also increase
2025 the size of each incremental step.
2026 Values smaller than 100 make the collector too slow and
2027 can result in the collector never finishing a cycle.
2029 the speed of memory allocation.
2032 <p>
2035 With these functions you can also control
2036 the collector directly (e.g., stop and restart it).
2042 <p>
2043 Using the C API,
2046 Finalizers allow you to coordinate Lua's garbage collection
2047 with external resource management
2048 (such as closing files, network or database connections,
2049 or freeing your own memory).
2052 <p>
2054 collected immediately by the garbage collector.
2055 Instead, Lua puts them in a list.
2056 After the collection,
2057 Lua does the equivalent of the following function
2058 for each userdata in that list:
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>
2069 <p>
2070 At the end of each garbage-collection cycle,
2072 order of their creation,
2073 among those collected in that cycle.
2074 That is, the first finalizer to be called is the one associated
2075 with the userdata created last in the program.
2076 The userdata itself is freed only in the next garbage-collection cycle.
2084 <p>
2087 A weak reference is ignored by the garbage collector.
2088 In other words,
2089 if the only references to an object are weak references,
2090 then the garbage collector will collect this object.
2093 <p>
2094 A weak table can have weak keys, weak values, or both.
2095 A table with weak keys allows the collection of its keys,
2096 but prevents the collection of its values.
2097 A table with both weak keys and weak values allows the collection of
2098 both keys and values.
2099 In any case, if either the key or the value is collected,
2100 the whole pair is removed from the table.
2101 The weakness of a table is controlled by the
2104 the keys in the table are weak.
2106 the values in the table are weak.
2109 <p>
2110 After you use a table as a metatable,
2112 Otherwise, the weak behavior of the tables controlled by this
2113 metatable is undefined.
2123 <p>
2124 Lua supports coroutines,
2126 A coroutine in Lua represents an independent thread of execution.
2127 Unlike threads in multithread systems, however,
2128 a coroutine only suspends its execution by explicitly calling
2129 a yield function.
2132 <p>
2133 You create a coroutine with a call to <a href="#pdf-coroutine.create"><code>coroutine.create</code></a>.
2134 Its sole argument is a function
2135 that is the main function of the coroutine.
2138 it does not start the coroutine execution.
2141 <p>
2143 passing as its first argument
2145 the coroutine starts its execution,
2146 at the first line of its main function.
2147 Extra arguments passed to <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a> are passed on
2148 to the coroutine main function.
2149 After the coroutine starts running,
2153 <p>
2154 A coroutine can terminate its execution in two ways:
2155 normally, when its main function returns
2156 (explicitly or implicitly, after the last instruction);
2157 and abnormally, if there is an unprotected error.
2158 In the first case, <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a> returns <b>true</b>,
2159 plus any values returned by the coroutine main function.
2160 In case of errors, <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a> returns <b>false</b>
2161 plus an error message.
2164 <p>
2166 When a coroutine yields,
2167 the corresponding <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a> returns immediately,
2168 even if the yield happens inside nested function calls
2169 (that is, not in the main function,
2170 but in a function directly or indirectly called by the main function).
2171 In the case of a yield, <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a> also returns <b>true</b>,
2173 The next time you resume the same coroutine,
2174 it continues its execution from the point where it yielded,
2175 with the call to <a href="#pdf-coroutine.yield"><code>coroutine.yield</code></a> returning any extra
2179 <p>
2181 the <a href="#pdf-coroutine.wrap"><code>coroutine.wrap</code></a> function also creates a coroutine,
2182 but instead of returning the coroutine itself,
2183 it returns a function that, when called, resumes the coroutine.
2184 Any arguments passed to this function
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>,
2187 except the first one (the boolean error code).
2190 any error is propagated to the caller.
2193 <p>
2194 As an example,
2195 consider the following code:
2197 <pre>
2198 function foo (a)
2199 print("foo", a)
2200 return coroutine.yield(2*a)
2201 end
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)
2216 </pre><p>
2217 When you run it, it produces the following output:
2219 <pre>
2220 co-body 1 10
2221 foo 2
2223 main true 4
2224 co-body r
2226 co-body x y
2227 main true 10 end
2228 main false cannot resume dead coroutine
2229 </pre>
2236 <p>
2238 This section describes the C API for Lua, that is,
2239 the set of C functions available to the host program to communicate
2240 with Lua.
2241 All API functions and related types and constants
2245 <p>
2246 Even when we use the term "function",
2247 any facility in the API may be provided as a macro instead.
2248 All such macros use each of their arguments exactly once
2249 (except for the first argument, which is always a Lua state),
2250 and so do not generate any hidden side-effects.
2253 <p>
2254 As in most C libraries,
2255 the Lua API functions do not check their arguments for validity or consistency.
2256 However, you can change this behavior by compiling Lua
2257 with a proper definition for the macro <a name="pdf-luai_apicheck"><code>luai_apicheck</code></a>,
2264 <p>
2266 Each element in this stack represents a Lua value
2270 <p>
2271 Whenever Lua calls C, the called function gets a new stack,
2272 which is independent of previous stacks and of stacks of
2273 C functions that are still active.
2274 This stack initially contains any arguments to the C function
2275 and it is where the C function pushes its results
2279 <p>
2280 For convenience,
2281 most query operations in the API do not follow a strict stack discipline.
2282 Instead, they can refer to any element in the stack
2289 (that is, the element that was pushed onto the stack first)
2290 and
2293 (that is, the element at the top)
2306 <p>
2307 When you interact with Lua API,
2308 you are responsible for ensuring consistency.
2309 In particular,
2312 to grow the stack size.
2315 <p>
2316 Whenever Lua calls C,
2317 it ensures that at least <a name="pdf-LUA_MINSTACK"><code>LUA_MINSTACK</code></a> stack positions are available.
2319 so that usually you do not have to worry about stack space
2320 unless your code has loops pushing elements onto the stack.
2323 <p>
2324 Most query functions accept as indices any value inside the
2325 available stack space, that is, indices up to the maximum stack size
2329 as follows:
2331 <pre>
2334 </pre><p>
2335 Note that 0 is never an acceptable index.
2343 <p>
2344 Unless otherwise noted,
2345 any function that accepts valid indices can also be called with
2347 which represent some Lua values that are accessible to C code
2348 but which are not in the stack.
2349 Pseudo-indices are used to access the thread environment,
2350 the function environment,
2351 the registry,
2355 <p>
2356 The thread environment (where global variables live) is
2358 The environment of the running C function is always
2362 <p>
2363 To access and change the value of global variables,
2364 you can use regular table operations over an environment table.
2365 For instance, to access the value of a global variable, do
2367 <pre>
2368 lua_getfield(L, LUA_GLOBALSINDEX, varname);
2369 </pre>
2376 <p>
2377 When a C function is created,
2378 it is possible to associate some values with it,
2381 accessible to the function whenever it is called
2385 <p>
2386 Whenever a C function is called,
2387 its upvalues are located at specific pseudo-indices.
2388 These pseudo-indices are produced by the macro
2390 The first value associated with a function is at position
2394 current function (but not greater than 256),
2395 produces an acceptable (but invalid) index.
2403 <p>
2405 a pre-defined table that can be used by any C code to
2406 store whatever Lua value it needs to store.
2407 This table is always located at pseudo-index
2409 Any C library can store data into this table,
2410 but it should take care to choose keys different from those used
2411 by other libraries, to avoid collisions.
2412 Typically, you should use as key a string containing your library name
2413 or a light userdata with the address of a C object in your code.
2416 <p>
2417 The integer keys in the registry are used by the reference mechanism,
2418 implemented by the auxiliary library,
2419 and therefore should not be used for other purposes.
2427 <p>
2429 (You can also choose to use exceptions if you use C++;
2431 When Lua faces any error
2432 (such as memory allocation errors, type errors, syntax errors,
2433 and runtime errors)
2435 that is, it does a long jump.
2437 to set a recover point;
2438 any error jumps to the most recent active recover point.
2441 <p>
2442 Most functions in the API can throw an error,
2443 for instance due to a memory allocation error.
2444 The documentation for each function indicates whether
2445 it can throw errors.
2448 <p>
2449 Inside a C function you can throw an error by calling <a href="#lua_error"><code>lua_error</code></a>.
2457 <p>
2458 Here we list all functions and types from the C API in
2459 alphabetical order.
2460 Each function has an indicator like this:
2464 <p>
2466 is how many elements the function pops from the stack.
2468 is how many elements the function pushes onto the stack.
2469 (Any function always pushes its results after popping its arguments.)
2472 depending on the situation;
2474 we cannot know how many elements the function pops/pushes
2475 by looking only at its arguments
2476 (e.g., they may depend on what is on the stack).
2478 tells whether the function may throw errors:
2481 only due to not enough memory;
2488 <pre>typedef void * (*lua_Alloc) (void *ud,
2489 void *ptr,
2490 size_t osize,
2491 size_t nsize);</pre>
2493 <p>
2494 The type of the memory-allocation function used by Lua states.
2495 The allocator function must provide a
2497 but not exactly the same.
2498 Its arguments are
2499 <code>ud</code>, an opaque pointer passed to <a href="#lua_newstate"><code>lua_newstate</code></a>;
2508 if and only if it cannot fill the request.
2513 Lua assumes that the allocator never fails when
2517 <p>
2518 Here is a simple implementation for the allocator function.
2519 It is used in the auxiliary library by <a href="#luaL_newstate"><code>luaL_newstate</code></a>.
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>
2533 This code assumes
2536 ANSI C ensures both behaviors.
2546 <p>
2547 Sets a new panic function and returns the old one.
2550 <p>
2551 If an error happens outside any protected environment,
2554 thus exiting the host application.
2555 Your panic function can avoid this exit by
2556 never returning (e.g., doing a long jump).
2559 <p>
2560 The panic function can access the error message at the top of the stack.
2570 <p>
2571 Calls a function.
2574 <p>
2575 To call a function you must use the following protocol:
2576 first, the function to be called is pushed onto the stack;
2577 then, the arguments to the function are pushed
2578 in direct order;
2579 that is, the first argument is pushed first.
2582 All arguments and the function value are popped from the stack
2583 when the function is called.
2584 The function results are pushed onto the stack when the function returns.
2588 Lua takes care that the returned values fit into the stack space.
2589 The function results are pushed onto the stack in direct order
2590 (the first result is pushed first),
2591 so that after the call the last result is on the top of the stack.
2594 <p>
2595 Any error inside the called function is propagated upwards
2599 <p>
2600 The following example shows how the host program can do the
2601 equivalent to this Lua code:
2603 <pre>
2605 </pre><p>
2606 Here it is in C:
2608 <pre>
2609 lua_getfield(L, LUA_GLOBALSINDEX, "f"); /* function to be called */
2611 lua_getfield(L, LUA_GLOBALSINDEX, "t"); /* table to be indexed */
2613 lua_remove(L, -2); /* remove 't' from the stack */
2616 lua_setfield(L, LUA_GLOBALSINDEX, "a"); /* set global 'a' */
2617 </pre><p>
2618 Note that the code above is "balanced":
2619 at its end, the stack is back to its original configuration.
2620 This is considered good programming practice.
2629 <p>
2630 Type for C functions.
2633 <p>
2634 In order to communicate properly with Lua,
2635 a C function must use the following protocol,
2636 which defines the way parameters and results are passed:
2637 a C function receives its arguments from Lua in its stack
2638 in direct order (the first argument is pushed first).
2639 So, when the function starts,
2641 The first argument (if any) is at index 1
2643 To return values to Lua, a C function just pushes them onto the stack,
2644 in direct order (the first result is pushed first),
2645 and returns the number of results.
2646 Any other value in the stack below the results will be properly
2647 discarded by Lua.
2648 Like a Lua function, a C function called by Lua can also return
2649 many results.
2652 <p>
2653 As an example, the following function receives a variable number
2654 of numerical arguments and returns their average and sum:
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;
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>
2681 <p>
2683 It returns false if it cannot grow the stack to that size.
2684 This function never shrinks the stack;
2685 if the stack is already larger than the new size,
2686 it is left unchanged.
2696 <p>
2697 Destroys all objects in the given Lua state
2698 (calling the corresponding garbage-collection metamethods, if any)
2699 and frees all dynamic memory used by this state.
2700 On several platforms, you may not need to call this function,
2701 because all resources are naturally released when the host program ends.
2702 On the other hand, long-running programs,
2703 such as a daemon or a web server,
2704 might need to release states as soon as they are not needed,
2705 to avoid growing too large.
2715 <p>
2717 pops them, and leaves the result at the top.
2719 (that is, the function does nothing);
2721 Concatenation is performed following the usual semantics of Lua
2732 <p>
2736 In 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>,
2738 plus the error object on the top of the stack;
2739 otherwise, it returns zero, and does not change the stack.
2750 <p>
2751 Creates a new empty table and pushes it onto the stack.
2752 The new table has space pre-allocated
2754 This pre-allocation is useful when you know exactly how many elements
2755 the table will have.
2766 <p>
2767 Dumps a function as a binary chunk.
2768 Receives a Lua function on the top of the stack
2769 and produces a binary chunk that,
2770 if loaded again,
2771 results in a function equivalent to the one dumped.
2772 As 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>)
2775 to write them.
2778 <p>
2779 The value returned is the error code returned by the last
2780 call to the writer;
2784 <p>
2785 This function does not pop the Lua function from the stack.
2795 <p>
2799 (that is, may call metamethods).
2811 <p>
2812 Generates a Lua error.
2813 The error message (which can actually be a Lua value of any type)
2814 must be on the stack top.
2815 This function does a long jump,
2816 and therefore never returns.
2827 <p>
2828 Controls the garbage collector.
2831 <p>
2832 This function performs several tasks,
2835 <ul>
2838 stops the garbage collector.
2839 </li>
2842 restarts the garbage collector.
2843 </li>
2846 performs a full garbage-collection cycle.
2847 </li>
2850 returns the current amount of memory (in Kbytes) in use by Lua.
2851 </li>
2854 returns the remainder of dividing the current amount of bytes of
2855 memory in use by Lua by 1024.
2856 </li>
2859 performs an incremental step of garbage collection.
2861 (larger values mean more steps) in a non-specified way.
2862 If you want to control the step size
2864 The function returns 1 if the step finished a
2865 garbage-collection cycle.
2866 </li>
2871 The function returns the previous value of the pause.
2872 </li>
2877 The function returns the previous value of the step multiplier.
2878 </li>
2880 </ul>
2889 <p>
2890 Returns the memory-allocation function of a given state.
2902 <p>
2903 Pushes onto the stack the environment table of
2904 the value at the given index.
2914 <p>
2917 As in Lua, this function may trigger a metamethod
2928 <p>
2930 It is defined as a macro:
2932 <pre>
2933 #define lua_getglobal(L,s) lua_getfield(L, LUA_GLOBALSINDEX, s)
2934 </pre>
2943 <p>
2944 Pushes onto the stack the metatable of the value at the given
2945 acceptable index.
2946 If the index is not valid,
2947 or if the value does not have a metatable,
2958 <p>
2964 <p>
2965 This function pops the key from the stack
2966 (putting the resulting value in its place).
2967 As in Lua, this function may trigger a metamethod
2978 <p>
2979 Returns the index of the top element in the stack.
2981 this result is equal to the number of elements in the stack
2992 <p>
2993 Moves the top element into the given valid index,
2994 shifting up the elements above this index to open space.
2995 Cannot be called with a pseudo-index,
2996 because a pseudo-index is not an actual stack position.
3005 <p>
3006 The type used by the Lua API to represent integral values.
3009 <p>
3011 which is usually the largest signed integral type the machine handles
3012 "comfortably".
3022 <p>
3023 Returns 1 if the value at the given acceptable index has type boolean,
3034 <p>
3046 <p>
3047 Returns 1 if the value at the given acceptable index is a function
3058 <p>
3059 Returns 1 if the value at the given acceptable index is a light userdata,
3070 <p>
3082 <p>
3083 Returns 1 if the given acceptable index is not valid
3084 (that is, it refers to an element outside the current stack),
3095 <p>
3096 Returns 1 if the given acceptable index is not valid
3097 (that is, it refers to an element outside the current stack)
3109 <p>
3110 Returns 1 if the value at the given acceptable index is a number
3111 or a string convertible to a number,
3122 <p>
3123 Returns 1 if the value at the given acceptable index is a string
3124 or a number (which is always convertible to a string),
3135 <p>
3136 Returns 1 if the value at the given acceptable index is a table,
3147 <p>
3148 Returns 1 if the value at the given acceptable index is a thread,
3159 <p>
3160 Returns 1 if the value at the given acceptable index is a userdata
3171 <p>
3175 (that is, may call metamethods).
3185 <pre>int lua_load (lua_State *L,
3186 lua_Reader reader,
3187 void *data,
3188 const char *chunkname);</pre>
3190 <p>
3191 Loads a Lua chunk.
3192 If there are no errors,
3194 function on top of the stack.
3195 Otherwise, it pushes an error message.
3198 <ul>
3203 syntax error during pre-compilation;</li>
3206 memory allocation error.</li>
3208 </ul>
3210 <p>
3211 This function only loads a chunk;
3212 it does not run it.
3215 <p>
3216 <a href="#lua_load"><code>lua_load</code></a> automatically detects whether the chunk is text or binary,
3220 <p>
3221 The <a href="#lua_load"><code>lua_load</code></a> function uses a user-supplied <code>reader</code> function
3226 <p>
3238 <p>
3239 Creates a new, independent state.
3241 (due to lack of memory).
3243 Lua does all memory allocation for this state through this function.
3245 simply passes to the allocator in every call.
3255 <p>
3256 Creates a new empty table and pushes it onto the stack.
3267 <p>
3268 Creates a new thread, pushes it on the stack,
3269 and returns a pointer to a <a href="#lua_State"><code>lua_State</code></a> that represents this new thread.
3270 The new state returned by this function shares with the original state
3271 all global objects (such as tables),
3272 but has an independent execution stack.
3275 <p>
3276 There is no explicit function to close or to destroy a thread.
3277 Threads are subject to garbage collection,
3278 like any Lua object.
3288 <p>
3289 This function allocates a new block of memory with the given size,
3290 pushes onto the stack a new full userdata with the block address,
3291 and returns this address.
3294 <p>
3295 Userdata represent C values in Lua.
3297 It is an object (like a table):
3298 you must create it, it can have its own metatable,
3299 and you can detect when it is being collected.
3300 A full userdata is only equal to itself (under raw equality).
3303 <p>
3305 Lua calls the metamethod and marks the userdata as finalized.
3306 When this userdata is collected again then
3307 Lua frees its corresponding memory.
3317 <p>
3318 Pops a key from the stack,
3319 and pushes a key-value pair from the table at the given index
3320 (the "next" pair after the given key).
3321 If there are no more elements in the table,
3325 <p>
3326 A typical traversal looks like this:
3328 <pre>
3329 /* table is in the stack at index 't' */
3330 lua_pushnil(L); /* first key */
3331 while (lua_next(L, t) != 0) {
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>
3341 <p>
3342 While traversing a table,
3344 unless you know that the key is actually a string.
3346 the value at the given index;
3356 <p>
3357 The type of numbers in Lua.
3361 <p>
3362 Through the configuration file you can change
3363 Lua to operate with another type for numbers (e.g., float or long).
3373 <p>
3374 Returns the "length" of the value at the given acceptable index:
3375 for strings, this is the string length;
3377 for userdata, this is the size of the block of memory allocated
3378 for the userdata;
3389 <p>
3390 Calls a function in protected mode.
3393 <p>
3396 If 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>.
3398 However, if there is any error,
3400 pushes a single value on the stack (the error message),
3401 and returns an error code.
3404 and its arguments from the stack.
3407 <p>
3409 then the error message returned on the stack
3410 is exactly the original error message.
3413 (In the current implementation, this index cannot be a pseudo-index.)
3414 In case of runtime errors,
3415 this function will be called with the error message
3416 and its return value will be the message returned on the stack by <a href="#lua_pcall"><code>lua_pcall</code></a>.
3419 <p>
3420 Typically, the error handler function is used to add more debug
3421 information to the error message, such as a stack traceback.
3422 Such information cannot be gathered after the return of <a href="#lua_pcall"><code>lua_pcall</code></a>,
3423 since by then the stack has unwound.
3426 <p>
3428 or one of the following error codes
3431 <ul>
3434 a runtime error.
3435 </li>
3438 memory allocation error.
3439 For such errors, Lua does not call the error handler function.
3440 </li>
3443 error while running the error handler function.
3444 </li>
3446 </ul>
3455 <p>
3466 <p>
3477 <p>
3478 Pushes a new C closure onto the stack.
3481 <p>
3482 When a C function is created,
3483 it is possible to associate some values with it,
3485 these values are then accessible to the function whenever it is called.
3486 To associate values with a C function,
3487 first these values should be pushed onto the stack
3488 (when there are multiple values, the first value is pushed first).
3490 is called to create and push the C function onto the stack,
3492 associated with the function.
3493 <a href="#lua_pushcclosure"><code>lua_pushcclosure</code></a> also pops these values from the stack.
3496 <p>
3507 <p>
3508 Pushes a C function onto the stack.
3509 This function receives a pointer to a C function
3511 when called, invokes the corresponding C function.
3514 <p>
3515 Any function to be registered in Lua must
3516 follow the correct protocol to receive its parameters
3520 <p>
3523 <pre>
3524 #define lua_pushcfunction(L,f) lua_pushcclosure(L,f,0)
3525 </pre>
3534 <p>
3535 Pushes onto the stack a formatted string
3536 and returns a pointer to this string.
3538 but has some important differences:
3540 <ul>
3542 <li>
3543 You do not have to allocate space for the result:
3544 the result is a Lua string and Lua takes care of memory allocation
3545 (and deallocation, through garbage collection).
3546 </li>
3548 <li>
3549 The conversion specifiers are quite restricted.
3550 There are no flags, widths, or precisions.
3551 The conversion specifiers can only be
3558 </li>
3560 </ul>
3569 <p>
3580 <p>
3581 Pushes a light userdata onto the stack.
3584 <p>
3585 Userdata represent C values in Lua.
3587 It is a value (like a number):
3588 you do not create it, it has no individual metatable,
3589 and it is not collected (as it was never created).
3590 A light userdata is equal to "any"
3591 light userdata with the same C address.
3601 <p>
3604 In these cases, it automatically provides the string length.
3614 <p>
3616 onto the stack.
3617 Lua makes (or reuses) an internal copy of the given string,
3619 the function returns.
3620 The string can contain embedded zeros.
3630 <p>
3631 Pushes a nil value onto the stack.
3641 <p>
3652 <p>
3654 onto the stack.
3655 Lua makes (or reuses) an internal copy of the given string,
3657 the function returns.
3658 The string cannot contain embedded zeros;
3659 it is assumed to end at the first zero.
3669 <p>
3671 Returns 1 if this thread is the main thread of its state.
3681 <p>
3682 Pushes a copy of the element at the given valid index
3683 onto the stack.
3691 <pre>const char *lua_pushvfstring (lua_State *L,
3692 const char *fmt,
3693 va_list argp);</pre>
3695 <p>
3696 Equivalent to <a href="#lua_pushfstring"><code>lua_pushfstring</code></a>, except that it receives a <code>va_list</code>
3697 instead of a variable number of arguments.
3707 <p>
3710 (that is, without calling metamethods).
3722 <p>
3724 (i.e., without metamethods).
3734 <p>
3737 The access is raw;
3738 that is, it does not invoke metamethods.
3748 <p>
3750 (i.e., without metamethods).
3760 <p>
3766 <p>
3767 This function pops the value from the stack.
3768 The assignment is raw;
3769 that is, it does not invoke metamethods.
3776 <pre>typedef const char * (*lua_Reader) (lua_State *L,
3777 void *data,
3778 size_t *size);</pre>
3780 <p>
3782 Every time it needs another piece of the chunk,
3785 The reader must return a pointer to a block of memory
3786 with a new piece of the chunk
3788 The block must exist until the reader function is called again.
3789 To signal the end of the chunk,
3791 The reader function may return pieces of any size greater than zero.
3799 <pre>void lua_register (lua_State *L,
3800 const char *name,
3801 lua_CFunction f);</pre>
3803 <p>
3805 It is defined as a macro:
3807 <pre>
3808 #define lua_register(L,n,f) \
3809 (lua_pushcfunction(L, f), lua_setglobal(L, n))
3810 </pre>
3819 <p>
3820 Removes the element at the given valid index,
3821 shifting down the elements above this index to fill the gap.
3822 Cannot be called with a pseudo-index,
3823 because a pseudo-index is not an actual stack position.
3833 <p>
3834 Moves the top element into the given position (and pops it),
3835 without shifting any element
3836 (therefore replacing the value at the given position).
3846 <p>
3847 Starts and resumes a coroutine in a given thread.
3850 <p>
3851 To start a coroutine, you first create a new thread
3853 then you push onto its stack the main function plus any arguments;
3856 This call returns when the coroutine suspends or finishes its execution.
3857 When it returns, the stack contains all values passed to <a href="#lua_yield"><code>lua_yield</code></a>,
3858 or all values returned by the body function.
3861 0 if the coroutine finishes its execution
3862 without errors,
3864 In case of errors,
3865 the stack is not unwound,
3866 so you can use the debug API over it.
3867 The error message is on the top of the stack.
3868 To restart a coroutine, you put on its stack only the values to
3880 <p>
3892 <p>
3893 Pops a table from the stack and sets it as
3894 the new environment for the value at the given index.
3895 If the value at the given index is
3896 neither a function nor a thread nor a userdata,
3898 Otherwise it returns 1.
3908 <p>
3914 <p>
3915 This function pops the value from the stack.
3916 As in Lua, this function may trigger a metamethod
3927 <p>
3928 Pops a value from the stack and
3930 It is defined as a macro:
3932 <pre>
3933 #define lua_setglobal(L,s) lua_setfield(L, LUA_GLOBALSINDEX, s)
3934 </pre>
3943 <p>
3944 Pops a table from the stack and
3945 sets it as the new metatable for the value at the given
3946 acceptable index.
3956 <p>
3963 <p>
3964 This function pops both the key and the value from the stack.
3965 As in Lua, this function may trigger a metamethod
3976 <p>
3978 and sets the stack top to this index.
3979 If the new top is larger than the old one,
3990 <p>
3991 Opaque structure that keeps the whole state of a Lua interpreter.
3992 The Lua library is fully reentrant:
3993 it has no global variables.
3994 All information about a state is kept in this structure.
3997 <p>
3998 A pointer to this state must be passed as the first argument to
3999 every function in the library, except to <a href="#lua_newstate"><code>lua_newstate</code></a>,
4000 which creates a Lua state from scratch.
4010 <p>
4014 <p>
4015 The status can be 0 for a normal thread,
4016 an error code if the thread finished its execution with an error,
4027 <p>
4028 Converts the Lua value at the given acceptable index to a C boolean
4030 Like all tests in Lua,
4033 otherwise it returns 0.
4034 It also returns 0 when called with a non-valid index.
4035 (If you want to accept only actual boolean values,
4046 <p>
4047 Converts a value at the given acceptable index to a C function.
4048 That value must be a C function;
4059 <p>
4060 Converts the Lua value at the given acceptable index
4062 The Lua value must be a number or a string convertible to a number
4067 <p>
4068 If the number is not an integer,
4069 it is truncated in some non-specified way.
4079 <p>
4080 Converts the Lua value at the given acceptable index to a C string.
4083 The Lua value must be a string or a number;
4085 If the value is a number,
4089 when <a href="#lua_tolstring"><code>lua_tolstring</code></a> is applied to keys during a table traversal.)
4092 <p>
4094 to a string inside the Lua state.
4096 after its last character (as in C),
4097 but can contain other zeros in its body.
4098 Because Lua has garbage collection,
4099 there is no guarantee that the pointer returned by <a href="#lua_tolstring"><code>lua_tolstring</code></a>
4100 will be valid after the corresponding value is removed from the stack.
4110 <p>
4111 Converts the Lua value at the given acceptable index
4112 to the C type <a href="#lua_Number"><code>lua_Number</code></a> (see <a href="#lua_Number"><code>lua_Number</code></a>).
4113 The Lua value must be a number or a string convertible to a number
4125 <p>
4126 Converts the value at the given acceptable index to a generic
4128 The value can be a userdata, a table, a thread, or a function;
4130 Different objects will give different pointers.
4131 There is no way to convert the pointer back to its original value.
4134 <p>
4135 Typically this function is used only for debug information.
4145 <p>
4146 Equivalent to <a href="#lua_tolstring"><code>lua_tolstring</code></a> with <code>len</code> equal to <code>NULL</code>.
4156 <p>
4157 Converts the value at the given acceptable index to a Lua thread
4159 This value must be a thread;
4170 <p>
4171 If the value at the given acceptable index is a full userdata,
4172 returns its block address.
4173 If the value is a light userdata,
4174 returns its pointer.
4185 <p>
4186 Returns the type of the value in the given acceptable index,
4188 (that is, an index to an "empty" stack position).
4189 The types returned by <a href="#lua_type"><code>lua_type</code></a> are coded by the following constants
4199 and
4210 <p>
4219 <pre>typedef int (*lua_Writer) (lua_State *L,
4220 const void* p,
4221 size_t sz,
4222 void* ud);</pre>
4224 <p>
4226 Every time it produces another piece of chunk,
4233 <p>
4234 The writer returns an error code:
4237 calling the writer again.
4247 <p>
4251 <p>
4263 <p>
4264 Yields a coroutine.
4267 <p>
4268 This function should only be called as the
4269 return expression of a C function, as follows:
4271 <pre>
4272 return lua_yield (L, nresults);
4273 </pre><p>
4275 the running coroutine suspends its execution,
4276 and the call to <a href="#lua_resume"><code>lua_resume</code></a> that started this coroutine returns.
4288 <p>
4289 Lua has no built-in debugging facilities.
4290 Instead, it offers a special interface
4292 This interface allows the construction of different
4293 kinds of debuggers, profilers, and other tools
4294 that need "inside information" from the interpreter.
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 */
4312 } lua_Debug;</pre>
4314 <p>
4315 A structure used to carry different pieces of
4316 information about an active function.
4318 of this structure, for later use.
4319 To fill the other fields of <a href="#lua_Debug"><code>lua_Debug</code></a> with useful information,
4323 <p>
4326 <ul>
4329 If the function was defined in a string,
4331 If the function was defined in a file,
4333 </li>
4337 </li>
4340 the line number where the definition of the function starts.
4341 </li>
4344 the line number where the definition of the function ends.
4345 </li>
4352 In the latter case,
4353 Lua has no other information about the function.
4354 </li>
4357 the current line where the given function is executing.
4358 When no line information is available,
4360 </li>
4363 a reasonable name for the given function.
4364 Because functions in Lua are first-class values,
4365 they do not have a fixed name:
4366 some functions can be the value of multiple global variables,
4367 while others can be stored only in a table field.
4369 called to find a suitable name.
4370 If it cannot find a name,
4372 </li>
4379 according to how the function was called.
4380 (Lua uses the empty string when no other option seems to apply.)
4381 </li>
4384 the number of upvalues of the function.
4385 </li>
4387 </ul>
4396 <p>
4397 Returns the current hook function.
4407 <p>
4408 Returns the current hook count.
4418 <p>
4419 Returns the current hook mask.
4429 <p>
4430 Returns information about a specific function or function invocation.
4433 <p>
4434 To get information about a function invocation,
4440 <p>
4441 To get information about a function you push it onto the stack
4443 (In that case,
4446 you can write the following code:
4448 <pre>
4449 lua_Debug ar;
4450 lua_getfield(L, LUA_GLOBALSINDEX, "f"); /* get global 'f' */
4452 printf("%d\n", ar.linedefined);
4453 </pre>
4455 <p>
4458 a value to be pushed on the stack:
4460 <ul>
4463 </li>
4468 </li>
4471 </li>
4474 </li>
4477 pushes onto the stack the function that is
4478 running at the given level;
4479 </li>
4482 pushes onto the stack a table whose indices are the
4483 numbers of the lines that are valid on the function.
4485 that is, a line where you can put a break point.
4486 Non-valid lines include empty lines and comments.)
4487 </li>
4489 </ul>
4491 <p>
4492 This function returns 0 on error
4503 <p>
4504 Gets information about a local variable of a given activation record.
4509 (1 is the first parameter or active local variable, and so on,
4510 until the last active local variable).
4511 <a href="#lua_getlocal"><code>lua_getlocal</code></a> pushes the variable's value onto the stack
4512 and returns its name.
4515 <p>
4517 represent internal variables
4518 (loop control variables, temporaries, and C function locals).
4521 <p>
4523 when the index is greater than
4524 the number of active local variables.
4534 <p>
4535 Get information about the interpreter runtime stack.
4538 <p>
4541 of the function executing at a given level.
4545 when called with a level greater than the stack depth,
4546 it returns 0.
4556 <p>
4557 Gets information about a closure's upvalue.
4558 (For Lua functions,
4559 upvalues are the external local variables that the function uses,
4560 and 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,
4562 pushes the upvalue's value onto the stack,
4563 and returns its name.
4565 (Upvalues have no particular order,
4566 as they are active through the whole function.
4567 So, they are numbered in an arbitrary order.)
4570 <p>
4572 when the index is greater than the number of upvalues.
4574 as a name for all upvalues.
4583 <p>
4584 Type for debugging hook functions.
4587 <p>
4590 Lua 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>,
4599 In the latter case, Lua is simulating a return from
4600 a function that did a tail call;
4604 <p>
4605 While Lua is running a hook, it disables other calls to hooks.
4606 Therefore, if a hook calls back Lua to execute a function or a chunk,
4607 this execution occurs without any calls to hooks.
4617 <p>
4618 Sets the debugging hook function.
4621 <p>
4624 it is formed by a bitwise or of the constants
4631 For each event, the hook is called as explained below:
4633 <ul>
4636 The hook is called just after Lua enters the new function,
4637 before the function gets its arguments.
4638 </li>
4641 The hook is called just before Lua leaves the function.
4642 You have no access to the values to be returned by the function.
4643 </li>
4646 start the execution of a new line of code,
4647 or 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>
4653 (This event only happens while Lua is executing a Lua function.)
4654 </li>
4656 </ul>
4658 <p>
4669 <p>
4670 Sets the value of a local variable of a given activation record.
4671 Parameters <code>ar</code> and <code>n</code> are as in <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
4674 to the variable and returns its name.
4675 It also pops the value from the stack.
4678 <p>
4680 when the index is greater than
4681 the number of active local variables.
4691 <p>
4692 Sets the value of a closure's upvalue.
4693 It assigns the value at the top of the stack
4694 to the upvalue and returns its name.
4695 It also pops the value from the stack.
4696 Parameters <code>funcindex</code> and <code>n</code> are as in the <a href="#lua_getupvalue"><code>lua_getupvalue</code></a>
4700 <p>
4702 when the index is greater than the number of upvalues.
4712 <p>
4715 to interface C with Lua.
4716 While the basic API provides the primitive functions for all
4717 interactions between C and Lua,
4718 the auxiliary library provides higher-level functions for some
4719 common tasks.
4722 <p>
4723 All functions from the auxiliary library
4728 <p>
4729 All functions in the auxiliary library are built on
4730 top of the basic API,
4731 and so they provide nothing that cannot be done with this API.
4734 <p>
4735 Several functions in the auxiliary library are used to
4736 check C function arguments.
4738 All of these functions throw an error if the check is not satisfied.
4739 Because the error message is formatted for arguments
4740 (e.g., "<code>bad argument #1</code>"),
4741 you should not use these functions for other stack values.
4747 <p>
4748 Here we list all functions and types from the auxiliary library
4749 in alphabetical order.
4757 <p>
4769 <p>
4773 The string may contain embedded zeros.
4783 <p>
4796 <p>
4800 The string may not contain embedded zeros.
4810 <p>
4811 Adds the value at the top of the stack
4814 Pops the value.
4817 <p>
4818 This is the only function on string buffers that can (and must)
4819 be called with an extra element on the stack,
4820 which is the value to be added to the buffer.
4828 <pre>void luaL_argcheck (lua_State *L,
4829 int cond,
4830 int narg,
4831 const char *extramsg);</pre>
4833 <p>
4835 If not, raises an error with the following message,
4838 <pre>
4840 </pre>
4849 <p>
4850 Raises an error with the following message,
4853 <pre>
4855 </pre>
4857 <p>
4858 This function never returns,
4859 but it is an idiom to use it in C functions
4869 <p>
4873 <p>
4874 A string buffer allows C code to build Lua strings piecemeal.
4875 Its pattern of use is as follows:
4877 <ul>
4879 <li>First you declare a variable <code>b</code> of type <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>.</li>
4883 <li>
4884 Then you add string pieces to the buffer calling any of
4886 </li>
4888 <li>
4890 This call leaves the final string on the top of the stack.
4891 </li>
4893 </ul>
4895 <p>
4896 During its normal operation,
4897 a string buffer uses a variable number of stack slots.
4898 So, while using a buffer, you cannot assume that you know where
4899 the top of the stack is.
4900 You can use the stack between successive calls to buffer operations
4901 as long as that use is balanced;
4902 that is,
4903 when you call a buffer operation,
4904 the stack is at the same level
4905 it was immediately after the previous buffer operation.
4907 After calling <a href="#luaL_pushresult"><code>luaL_pushresult</code></a> the stack is back to its
4908 level when the buffer was initialized,
4909 plus the final string on its top.
4919 <p>
4921 This function does not allocate any space;
4922 the buffer must be declared as a variable
4933 <p>
4934 Calls a metamethod.
4937 <p>
4940 this function calls this field and passes the object as its only argument.
4941 In this case this function returns 1 and pushes onto the
4942 stack the value returned by the call.
4943 If there is no metatable or no metamethod,
4944 this function returns 0 (without pushing any value on the stack).
4954 <p>
4955 Checks whether the function has an argument
4966 <p>
4978 <p>
4990 <p>
5002 <p>
5004 and returns this string;
5006 with the string's length.
5009 <p>
5011 so all conversions and caveats of that function apply here.
5021 <p>
5023 and returns this number.
5031 <pre>int luaL_checkoption (lua_State *L,
5032 int narg,
5033 const char *def,
5034 const char *const lst[]);</pre>
5036 <p>
5039 (which must be NULL-terminated).
5040 Returns the index in the array where the string was found.
5041 Raises an error if the argument is not a string or
5042 if the string cannot be found.
5045 <p>
5051 <p>
5052 This is a useful function for mapping strings to C enums.
5053 (The usual convention in Lua libraries is
5054 to use strings instead of numbers to select options.)
5064 <p>
5066 raising an error if the stack cannot grow to that size.
5077 <p>
5079 and returns this string.
5082 <p>
5084 so all conversions and caveats of that function apply here.
5094 <p>
5096 See <a href="#lua_type"><code>lua_type</code></a> for the encoding of types for <code>t</code>.
5106 <p>
5108 of the type <code>tname</code> (see <a href="#luaL_newmetatable"><code>luaL_newmetatable</code></a>).
5118 <p>
5119 Loads and runs the given file.
5120 It is defined as the following macro:
5122 <pre>
5124 </pre><p>
5125 It returns 0 if there are no errors
5126 or 1 in case of errors.
5136 <p>
5137 Loads and runs the given string.
5138 It is defined as the following macro:
5140 <pre>
5142 </pre><p>
5143 It returns 0 if there are no errors
5144 or 1 in case of errors.
5154 <p>
5155 Raises an error.
5157 plus any extra arguments,
5159 It also adds at the beginning of the message the file name and
5160 the line number where the error occurred,
5161 if this information is available.
5164 <p>
5165 This function never returns,
5166 but it is an idiom to use it in C functions
5177 <p>
5180 If the object does not have a metatable,
5181 or if the metatable does not have this field,
5182 returns 0 and pushes nothing.
5192 <p>
5202 <pre>const char *luaL_gsub (lua_State *L,
5203 const char *s,
5204 const char *p,
5205 const char *r);</pre>
5207 <p>
5211 Pushes the resulting string on the stack and returns it.
5219 <pre>int luaL_loadbuffer (lua_State *L,
5220 const char *buff,
5221 size_t sz,
5222 const char *name);</pre>
5224 <p>
5225 Loads a buffer as a Lua chunk.
5230 <p>
5233 used for debug information and error messages.
5243 <p>
5244 Loads a file as a Lua chunk.
5248 then it loads from the standard input.
5252 <p>
5255 if it cannot open/read the file.
5258 <p>
5260 it does not run it.
5270 <p>
5271 Loads a string as a Lua chunk.
5276 <p>
5280 <p>
5282 it does not run it.
5292 <p>
5294 returns 0.
5295 Otherwise,
5296 creates a new table to be used as a metatable for userdata,
5298 and returns 1.
5301 <p>
5302 In both cases pushes onto the stack the final value associated
5313 <p>
5314 Creates a new Lua state.
5317 and then sets a panic function (see <a href="#lua_atpanic"><code>lua_atpanic</code></a>) that prints
5318 an error message to the standard error output in case of fatal
5319 errors.
5322 <p>
5323 Returns the new state,
5334 <p>
5335 Opens all standard Lua libraries into the given state.
5345 <p>
5350 Otherwise, raises an error.
5358 <pre>lua_Integer luaL_optinteger (lua_State *L,
5359 int narg,
5360 lua_Integer d);</pre>
5362 <p>
5367 Otherwise, raises an error.
5377 <p>
5382 Otherwise, raises an error.
5390 <pre>const char *luaL_optlstring (lua_State *L,
5391 int narg,
5392 const char *d,
5393 size_t *l);</pre>
5395 <p>
5397 returns this string.
5400 Otherwise, raises an error.
5403 <p>
5415 <p>
5417 returns this number.
5420 Otherwise, raises an error.
5428 <pre>const char *luaL_optstring (lua_State *L,
5429 int narg,
5430 const char *d);</pre>
5432 <p>
5434 returns this string.
5437 Otherwise, raises an error.
5447 <p>
5448 Returns an address to a space of size <a name="pdf-LUAL_BUFFERSIZE"><code>LUAL_BUFFERSIZE</code></a>
5451 After 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
5453 it to the buffer.
5463 <p>
5465 the top of the stack.
5475 <p>
5478 for the object at the top of the stack (and pops the object).
5481 <p>
5482 A reference is a unique integer key.
5487 Function <a href="#luaL_unref"><code>luaL_unref</code></a> frees a reference and its associated object.
5490 <p>
5492 <a href="#luaL_ref"><code>luaL_ref</code></a> returns the constant <a name="pdf-LUA_REFNIL"><code>LUA_REFNIL</code></a>.
5501 <pre>typedef struct luaL_Reg {
5502 const char *name;
5503 lua_CFunction func;
5504 } luaL_Reg;</pre>
5506 <p>
5507 Type for arrays of functions to be registered by
5510 the function.
5520 <pre>void luaL_register (lua_State *L,
5521 const char *libname,
5522 const luaL_Reg *l);</pre>
5524 <p>
5525 Opens a library.
5528 <p>
5534 <p>
5542 reuses this table instead of creating a new one.
5545 <p>
5546 In any case the function leaves the table
5547 on the top of the stack.
5557 <p>
5558 Returns the name of the type of the value at the given index.
5568 <p>
5569 Generates an error with a message like the following:
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>
5574 where <code><em>location</em></code> is produced by <a href="#luaL_where"><code>luaL_where</code></a>,
5586 <p>
5589 The entry is removed from the table,
5590 so that the referred object can be collected.
5594 <p>
5595 If <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>,
5606 <p>
5607 Pushes onto the stack a string identifying the current position
5609 Typically this string has the following format:
5611 <pre>
5613 </pre><p>
5616 etc.
5619 <p>
5620 This function is used to build a prefix for error messages.
5630 <p>
5631 The standard Lua libraries provide useful functions
5632 that are implemented directly through the C API.
5633 Some 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>);
5635 others provide access to "outside" services (e.g., I/O);
5636 and others could be implemented in Lua itself,
5637 but are quite useful or have critical performance requirements that
5641 <p>
5642 All libraries are implemented through the official C API
5643 and are provided as separate C modules.
5644 Currently, Lua has the following standard libraries:
5646 <ul>
5664 </ul><p>
5665 Except for the basic and package libraries,
5666 each library provides all its functions as fields of a global table
5667 or as methods of its objects.
5670 <p>
5671 To have access to these libraries,
5672 the C host program should call the <a href="#luaL_openlibs"><code>luaL_openlibs</code></a> function,
5673 which opens all standard libraries.
5674 Alternatively,
5675 it can open them individually by calling
5685 and should not be called directly:
5686 you must call them like any other Lua C function,
5693 <p>
5694 The basic library provides some core functions to Lua.
5695 If you do not include this library in your application,
5696 you should check carefully whether you need to provide
5697 implementations for some of its facilities.
5700 <p>
5702 Issues an error when
5704 otherwise, returns all its arguments.
5706 when absent, it defaults to "assertion failed!"
5711 <p>
5715 <p>
5716 This function is a generic interface to the garbage collector.
5719 <ul>
5722 stops the garbage collector.
5723 </li>
5726 restarts the garbage collector.
5727 </li>
5730 performs a full garbage-collection cycle.
5731 </li>
5734 returns the total memory in use by Lua (in Kbytes).
5735 </li>
5738 performs a garbage-collection step.
5740 (larger values mean more steps) in a non-specified way.
5741 If you want to control the step size
5744 </li>
5750 </li>
5756 </li>
5758 </ul>
5762 <p>
5764 Opens the named file and executes its contents as a Lua chunk.
5765 When called without arguments,
5767 Returns all values returned by the chunk.
5774 <p>
5776 Terminates the last protected function called
5781 <p>
5783 at the beginning of the message.
5790 to the message.
5795 <p>
5797 A global variable (not a function) that
5799 Lua itself does not use this variable;
5800 changing its value does not affect any environment,
5801 nor vice-versa.
5807 <p>
5809 Returns the current environment in use by the function.
5811 that specifies the function at that stack level:
5813 If the given function is not a Lua function,
5821 <p>
5825 <p>
5827 Otherwise,
5829 returns the associated value.
5830 Otherwise, returns the metatable of the given object.
5835 <p>
5839 <p>
5841 so that the construction
5843 <pre>
5845 </pre><p>
5846 will iterate over the pairs (<code>1,t[1]</code>), (<code>2,t[2]</code>), ···,
5847 up to the first integer key absent from the table.
5852 <p>
5856 <p>
5859 with previous results.
5863 <p>
5864 If there are no errors,
5865 returns the compiled chunk as a function;
5867 The environment of the returned function is the global environment.
5870 <p>
5872 and debug information.
5873 When absent,
5874 it defaults to "<code>=(load)</code>".
5879 <p>
5883 <p>
5886 or from the standard input,
5887 if no file name is given.
5892 <p>
5896 <p>
5898 but gets the chunk from the given string.
5901 <p>
5902 To load and run a given string, use the idiom
5904 <pre>
5905 assert(loadstring(s))()
5906 </pre>
5908 <p>
5909 When absent,
5915 <p>
5919 <p>
5920 Allows a program to traverse all fields of a table.
5921 Its first argument is a table and its second argument
5922 is an index in this table.
5924 and its associated value.
5927 and its associated value.
5928 When called with the last index,
5932 In particular,
5936 <p>
5937 The order in which the indices are enumerated is not specified,
5939 (To traverse a table in numeric order,
5943 <p>
5945 during the traversal,
5946 you assign any value to a non-existent field in the table.
5947 You may however modify existing fields.
5948 In particular, you may clear existing fields.
5953 <p>
5957 <p>
5958 Returns three values: the <a href="#pdf-next"><code>next</code></a> function, the table <code>t</code>, and <b>nil</b>,
5959 so that the construction
5961 <pre>
5963 </pre><p>
5967 <p>
5969 the table during its traversal.
5974 <p>
5978 <p>
5983 and returns a status code.
5984 Its first result is the status code (a boolean),
5985 which is true if the call succeeds without errors.
5987 after this first result.
5993 <p>
5995 Receives any number of arguments,
5997 using the <a href="#pdf-tostring"><code>tostring</code></a> function to convert them to strings.
5999 but only as a quick way to show a value,
6000 typically for debugging.
6006 <p>
6009 without invoking any metamethod.
6010 Returns a boolean.
6015 <p>
6018 without invoking any metamethod.
6025 <p>
6028 without invoking any metamethod.
6034 <p>
6040 <p>
6044 <p>
6053 <p>
6057 <p>
6058 Sets the environment to be used by the given function.
6060 that specifies the function at that stack level:
6065 <p>
6067 the environment of the running thread.
6073 <p>
6077 <p>
6078 Sets the metatable for the given table.
6079 (You cannot change the metatable of other types from Lua, only from C.)
6081 removes the metatable of the given table.
6083 raises an error.
6086 <p>
6092 <p>
6094 Tries to convert its argument to a number.
6095 If the argument is already a number or a string convertible
6100 <p>
6101 An optional argument specifies the base to interpret the numeral.
6106 In base 10 (the default), the number can have a decimal part,
6108 In other bases, only unsigned integers are accepted.
6113 <p>
6115 Receives an argument of any type and
6116 converts it to a string in a reasonable format.
6117 For complete control of how numbers are converted,
6121 <p>
6125 and uses the result of the call as its result.
6130 <p>
6132 Returns the type of its only argument, coded as a string.
6133 The possible results of this function are
6135 "<code>number</code>",
6136 "<code>string</code>",
6137 "<code>boolean</code>",
6138 "<code>table</code>",
6139 "<code>function</code>",
6140 "<code>thread</code>",
6141 and "<code>userdata</code>".
6146 <p>
6148 Returns the elements from the given table.
6149 This function is equivalent to
6151 <pre>
6153 </pre><p>
6154 except that the above code can be written only for a fixed number
6155 of elements.
6162 <p>
6164 A global variable (not a function) that
6165 holds a string containing the current interpreter version.
6166 The current contents of this variable is "<code>Lua 5.1</code>".
6171 <p>
6175 <p>
6177 except that you can set a new error handler.
6180 <p>
6186 and returns a status code.
6187 Its first result is the status code (a boolean),
6188 which is true if the call succeeds without errors.
6190 after this first result.
6191 In case of any error,
6202 <p>
6203 The operations related to coroutines comprise a sub-library of
6204 the basic library and come inside the table <a name="pdf-coroutine"><code>coroutine</code></a>.
6208 <p>
6212 <p>
6215 Returns this new coroutine,
6221 <p>
6222 <hr><h3><a name="pdf-coroutine.resume"><code>coroutine.resume (co [, val1, ···])</code></a></h3>
6225 <p>
6227 The first time you resume a coroutine,
6228 it starts running its body.
6230 as the arguments to the body function.
6231 If the coroutine has yielded,
6234 as the results from the yield.
6237 <p>
6238 If the coroutine runs without any errors,
6240 (if the coroutine yields) or any values returned by the body function
6241 (if the coroutine terminates).
6242 If there is any error,
6248 <p>
6252 <p>
6253 Returns the running coroutine,
6259 <p>
6263 <p>
6268 or if it has not started running yet;
6270 (that is, it has resumed another coroutine);
6272 or if it has stopped with an error.
6277 <p>
6281 <p>
6284 Returns a function that resumes the coroutine each time it is called.
6285 Any arguments passed to the function behave as the
6288 except the first boolean.
6289 In case of error, propagates the error.
6294 <p>
6295 <hr><h3><a name="pdf-coroutine.yield"><code>coroutine.yield (···)</code></a></h3>
6298 <p>
6299 Suspends the execution of the calling coroutine.
6300 The coroutine cannot be running a C function,
6301 a metamethod, or an iterator.
6312 <p>
6313 The package library provides basic
6314 facilities for loading and building modules in Lua.
6315 It 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>.
6320 <p>
6324 <p>
6325 Creates a module.
6327 this table is the module.
6329 this table is the module.
6336 (the full module name minus last component; see below).
6342 <p>
6344 (that is, one with components separated by dots),
6346 tables for each component.
6352 <p>
6354 the module name,
6355 where each option is a function to be applied over the module.
6360 <p>
6364 <p>
6365 Loads the given module.
6366 The function starts by looking into the <a href="#pdf-package.loaded"><code>package.loaded</code></a> table
6373 <p>
6374 To find a loader,
6375 <code>require</code> is guided by the <a href="#pdf-package.loaders"><code>package.loaders</code></a> array.
6376 By changing this array,
6378 The following explanation is based on the default configuration
6382 <p>
6384 If it has a value,
6385 this value (which should be a function) is the loader.
6388 If that also fails, it searches for a C loader using the
6390 If that also fails,
6391 it tries an <em>all-in-one</em> loader (see <a href="#pdf-package.loaders"><code>package.loaders</code></a>).
6394 <p>
6395 Once a loader is found,
6397 If the loader returns any value,
6399 If the loader returns no value and
6406 <p>
6407 If there is any error loading or running the module,
6408 or if it cannot find any loader for the module,
6414 <p>
6418 <p>
6419 The path used by <a href="#pdf-require"><code>require</code></a> to search for a C loader.
6422 <p>
6423 Lua initializes the C path <a href="#pdf-package.cpath"><code>package.cpath</code></a> in the same way
6431 <p>
6436 <p>
6438 modules are already loaded.
6446 <p>
6450 <p>
6451 A table used by <a href="#pdf-require"><code>require</code></a> to control how to load modules.
6454 <p>
6456 When looking for a module,
6457 <a href="#pdf-require"><code>require</code></a> calls each of these searchers in ascending order,
6458 with the module name (the argument given to <a href="#pdf-require"><code>require</code></a>) as its
6459 sole parameter.
6461 or a string explaining why it did not find that module
6463 Lua initializes this table with four functions.
6466 <p>
6467 The first searcher simply looks for a loader in the
6471 <p>
6472 The second searcher looks for a loader as a Lua library,
6475 For each template,
6476 the searcher will change each interrogation
6478 which is the module name with each dot replaced by a
6480 then it will try to open the resulting file name.
6481 So, for instance, if the Lua path is the string
6483 <pre>
6484 "./?.lua;./?.lc;/usr/local/?/init.lua"
6485 </pre><p>
6487 will try to open the files
6492 <p>
6493 The third searcher looks for a loader as a C library,
6494 using the path given by the variable <a href="#pdf-package.cpath"><code>package.cpath</code></a>.
6495 For instance,
6496 if the C path is the string
6498 <pre>
6499 "./?.so;./?.dll;/usr/local/?/init.so"
6500 </pre><p>
6504 Once it finds a C library,
6505 this searcher first uses a dynamic link facility to link the
6506 application with the library.
6507 Then it tries to find a C function inside the library to
6508 be used as the loader.
6510 concatenated with a copy of the module name where each dot
6511 is replaced by an underscore.
6512 Moreover, if the module name has a hyphen,
6513 its prefix up to (and including) the first hyphen is removed.
6518 <p>
6520 It searches the C path for a library for
6521 the root name of the given module.
6524 If found, it looks into it for an open function for
6525 the submodule;
6527 With this facility, a package can pack several C submodules
6528 into one single library,
6529 with each submodule keeping its original open function.
6534 <p>
6535 <hr><h3><a name="pdf-package.loadlib"><code>package.loadlib (libname, funcname)</code></a></h3>
6538 <p>
6541 and returns this function as a C function.
6542 (So, <code>funcname</code> must follow the protocol (see <a href="#lua_CFunction"><code>lua_CFunction</code></a>)).
6545 <p>
6546 This is a low-level function.
6547 It completely bypasses the package and module system.
6549 it does not perform any path searching and
6550 does not automatically adds extensions.
6552 including if necessary a path and extension.
6554 (which may depend on the C compiler and linker used).
6557 <p>
6558 This function is not supported by ANSI C.
6559 As such, it is only available on some platforms
6560 (Windows, Linux, Mac OS X, Solaris, BSD,
6566 <p>
6570 <p>
6574 <p>
6575 At start-up, Lua initializes this variable with
6578 if the environment variable is not defined.
6579 Any "<code>;;</code>" in the value of the environment variable
6580 is replaced by the default path.
6585 <p>
6589 <p>
6590 A table to store loaders for specific modules
6596 <p>
6600 <p>
6603 so that this module inherits values
6604 from the global environment.
6615 <p>
6616 This library provides generic functions for string manipulation,
6617 such as finding and extracting substrings, and pattern matching.
6620 Indices are allowed to be negative and are interpreted as indexing backwards,
6621 from the end of the string.
6622 Thus, the last character is at position -1, and so on.
6625 <p>
6626 The string library provides all its functions inside the table
6628 It also sets a metatable for strings
6630 Therefore, you can use the string functions in object-oriented style.
6635 <p>
6636 The string library assumes one-byte character encodings.
6639 <p>
6647 <p>
6648 Note that numerical codes are not necessarily portable across platforms.
6653 <p>
6655 Receives zero or more integers.
6656 Returns a string with length equal to the number of arguments,
6657 in which each character has the internal numerical code equal
6658 to its corresponding argument.
6661 <p>
6662 Note that numerical codes are not necessarily portable across platforms.
6667 <p>
6671 <p>
6672 Returns a string containing a binary representation of the given function,
6674 a copy of the function.
6680 <p>
6681 <hr><h3><a name="pdf-string.find"><code>string.find (s, pattern [, init [, plain]])</code></a></h3>
6682 Looks for the first match of
6685 where this occurrence starts and ends;
6688 where to start the search;
6691 turns off the pattern matching facilities,
6692 so the function does a plain "find substring" operation,
6697 <p>
6698 If the pattern has captures,
6699 then in a successful match
6700 the captured values are also returned,
6701 after the two indices.
6706 <p>
6707 <hr><h3><a name="pdf-string.format"><code>string.format (formatstring, ···)</code></a></h3>
6708 Returns a formatted version of its variable number of arguments
6709 following the description given in its first argument (which must be a string).
6711 standard C functions.
6712 The only differences are that the options/modifiers
6717 back by the Lua interpreter:
6718 the string is written between double quotes,
6719 and all double quotes, newlines, embedded zeros,
6720 and backslashes in the string
6721 are correctly escaped when written.
6722 For instance, the call
6724 <pre>
6725 string.format('%q', 'a string with "quotes" and \n new line')
6726 </pre><p>
6727 will produce the string:
6729 <pre>
6731 new line"
6732 </pre>
6734 <p>
6736 <code>g</code>, <code>G</code>, <code>i</code>, <code>o</code>, <code>u</code>, <code>X</code>, and <code>x</code> all
6737 expect a number as argument,
6741 <p>
6742 This function does not accept string values
6743 containing embedded zeros,
6749 <p>
6751 Returns an iterator function that,
6752 each time it is called,
6755 then the whole match is produced in each call.
6758 <p>
6759 As an example, the following loop
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>
6768 printing one per line.
6770 given string into a table:
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>
6780 <p>
6782 work as an anchor, as this would prevent the iteration.
6787 <p>
6793 which can be a string, a table, or a function.
6795 the total number of matches that occurred.
6798 <p>
6808 <p>
6810 using the first capture as the key;
6811 if the pattern specifies no captures,
6812 then the whole match is used as the key.
6815 <p>
6817 match occurs, with all captured substrings passed as arguments,
6818 in order;
6819 if the pattern specifies no captures,
6820 then the whole match is passed as a sole argument.
6823 <p>
6824 If the value returned by the table query or by the function call
6825 is a string or a number,
6826 then it is used as the replacement string;
6828 then there is no replacement
6829 (that is, the original match is kept in the string).
6832 <p>
6833 Here are some examples:
6835 <pre>
6849 return loadstring(s)()
6850 end)
6856 </pre>
6860 <p>
6862 Receives a string and returns its length.
6864 Embedded zeros are counted,
6870 <p>
6872 Receives a string and returns a copy of this string with all
6873 uppercase letters changed to lowercase.
6874 All other characters are left unchanged.
6875 The definition of what an uppercase letter is depends on the current locale.
6880 <p>
6885 the captures from the pattern;
6888 then the whole match is returned.
6890 where to start the search;
6896 <p>
6904 <p>
6911 <p>
6917 (which is the same as the string length).
6918 In particular,
6927 <p>
6929 Receives a string and returns a copy of this string with all
6930 lowercase letters changed to uppercase.
6931 All other characters are left unchanged.
6932 The definition of what a lowercase letter is depends on the current locale.
6941 The following combinations are allowed in describing a character class:
6943 <ul>
6949 </li>
6975 This is the standard way to escape the magic characters.
6976 Any punctuation character (even the non magic)
6978 when used to represent itself in a pattern.
6979 </li>
6982 represents the class which is the union of all
6984 A range of characters can be specified by
6990 represents all alphanumeric characters plus the underscore,
6996 <p>
6997 The interaction between ranges and classes is not defined.
6999 have no meaning.
7000 </li>
7005 </li>
7007 </ul><p>
7009 the corresponding uppercase letter represents the complement of the class.
7013 <p>
7014 The definitions of letter, space, and other character groups
7015 depend on the current locale.
7025 <ul>
7027 <li>
7028 a single character class,
7029 which matches any single character in the class;
7030 </li>
7032 <li>
7034 which matches 0 or more repetitions of characters in the class.
7035 These repetition items will always match the longest possible sequence;
7036 </li>
7038 <li>
7040 which matches 1 or more repetitions of characters in the class.
7041 These repetition items will always match the longest possible sequence;
7042 </li>
7044 <li>
7046 which also matches 0 or more repetitions of characters in the class.
7049 </li>
7051 <li>
7054 </li>
7056 <li>
7059 (see below);
7060 </li>
7062 <li>
7066 This means that, if one reads the string from left to right,
7070 balanced parentheses.
7071 </li>
7073 </ul>
7081 beginning of the subject string.
7083 end of the subject string.
7084 At other positions,
7092 A pattern can contain sub-patterns enclosed in parentheses;
7094 When a match succeeds, the substrings of the subject string
7096 Captures are numbered according to their left parentheses.
7104 <p>
7106 the current string position (a number).
7111 <p>
7125 This library provides generic functions for table manipulation.
7129 <p>
7130 Most functions in the table library assume that the table
7131 represents an array or a list.
7132 For these functions, when we talk about the "length" of a table
7133 we mean the result of the length operator.
7136 <p>
7137 <hr><h3><a name="pdf-table.concat"><code>table.concat (table [, sep [, i [, j]]])</code></a></h3>
7138 Given an array where all elements are strings or numbers,
7148 <p>
7152 <p>
7154 shifting up other elements to open space, if necessary.
7163 <p>
7167 <p>
7168 Returns the largest positive numerical index of the given table,
7169 or zero if the table has no positive numerical indices.
7170 (To do its job this function does a linear traversal of
7171 the whole table.)
7176 <p>
7180 <p>
7182 shifting down other elements to close the space, if necessary.
7183 Returns the value of the removed element.
7192 <p>
7198 then it must be a function that receives two table elements,
7199 and returns true
7200 when the first is less than the second
7206 <p>
7207 The sort algorithm is not stable;
7208 that is, elements considered equal by the given order
7209 may have their relative positions changed by the sort.
7219 <p>
7220 This library is an interface to the standard C math library.
7224 <p>
7228 <p>
7234 <p>
7238 <p>
7244 <p>
7248 <p>
7254 <p>
7258 <p>
7264 <p>
7268 <p>
7270 but uses the signs of both parameters to find the
7271 quadrant of the result.
7277 <p>
7281 <p>
7287 <p>
7291 <p>
7297 <p>
7301 <p>
7307 <p>
7311 <p>
7317 <p>
7321 <p>
7327 <p>
7331 <p>
7337 <p>
7341 <p>
7343 that rounds the quotient towards zero.
7348 <p>
7352 <p>
7361 <p>
7365 <p>
7367 a value larger than or equal to any other numerical value.
7372 <p>
7376 <p>
7382 <p>
7386 <p>
7392 <p>
7396 <p>
7402 <p>
7406 <p>
7407 Returns the maximum value among its arguments.
7412 <p>
7416 <p>
7417 Returns the minimum value among its arguments.
7422 <p>
7426 <p>
7427 Returns two numbers,
7433 <p>
7437 <p>
7443 <p>
7447 <p>
7454 <p>
7458 <p>
7464 <p>
7468 <p>
7469 This function is an interface to the simple
7471 (No guarantees can be given for its statistical properties.)
7474 <p>
7475 When called without arguments,
7476 returns a uniform pseudo-random real number
7488 <p>
7492 <p>
7494 for the pseudo-random generator:
7495 equal seeds produce equal sequences of numbers.
7500 <p>
7504 <p>
7510 <p>
7514 <p>
7520 <p>
7524 <p>
7531 <p>
7535 <p>
7541 <p>
7545 <p>
7556 <p>
7557 The I/O library provides two different styles for file manipulation.
7558 The first one uses implicit file descriptors;
7559 that is, there are operations to set a default input file and a
7560 default output file,
7561 and all input/output operations are over these default files.
7562 The second style uses explicit file descriptors.
7565 <p>
7566 When using implicit file descriptors,
7568 When using explicit file descriptors,
7570 and then all operations are supplied as methods of the file descriptor.
7573 <p>
7575 three 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>.
7577 The I/O library never closes these files.
7580 <p>
7581 Unless otherwise stated,
7583 (plus an error message as a second result and
7584 a system-dependent error code as a third result)
7588 <p>
7592 <p>
7599 <p>
7603 <p>
7609 <p>
7613 <p>
7614 When called with a file name, it opens the named file (in text mode),
7615 and sets its handle as the default input file.
7616 When called with a file handle,
7617 it simply sets this file handle as the default input file.
7618 When called without parameters,
7619 it returns the current default input file.
7622 <p>
7623 In case of errors this function raises the error,
7624 instead of returning an error code.
7629 <p>
7633 <p>
7634 Opens the given file name in read mode
7635 and returns an iterator function that,
7636 each time it is called,
7637 returns a new line from the file.
7638 Therefore, the construction
7640 <pre>
7642 </pre><p>
7643 will iterate over all lines of the file.
7644 When the iterator function detects the end of file,
7648 <p>
7651 that is, it iterates over the lines of the default input file.
7652 In this case it does not close the file when the loop ends.
7657 <p>
7661 <p>
7662 This function opens a file,
7664 It returns a new file handle,
7668 <p>
7671 <ul>
7678 writing is only allowed at the end of file.</li>
7679 </ul><p>
7681 which is needed in some systems to open the file in binary mode.
7682 This string is exactly what is used in the
7688 <p>
7692 <p>
7693 Similar to <a href="#pdf-io.input"><code>io.input</code></a>, but operates over the default output file.
7698 <p>
7702 <p>
7704 a file handle that you can use to read data from this program
7706 or to write data to this program
7710 <p>
7711 This function is system dependent and is not available
7712 on all platforms.
7717 <p>
7721 <p>
7727 <p>
7731 <p>
7732 Returns a handle for a temporary file.
7733 This file is opened in update mode
7734 and it is automatically removed when the program ends.
7739 <p>
7743 <p>
7752 <p>
7756 <p>
7762 <p>
7766 <p>
7768 Note that files are automatically closed when
7769 their handles are garbage collected,
7770 but that takes an unpredictable amount of time to happen.
7775 <p>
7779 <p>
7785 <p>
7789 <p>
7790 Returns an iterator function that,
7791 each time it is called,
7792 returns a new line from the file.
7793 Therefore, the construction
7795 <pre>
7797 </pre><p>
7798 will 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
7800 when the loop ends.)
7805 <p>
7809 <p>
7811 according to the given formats, which specify what to read.
7812 For each format,
7813 the function returns a string (or a number) with the characters read,
7815 When called without formats,
7816 it uses a default format that reads the entire next line
7817 (see below).
7820 <p>
7821 The available formats are
7823 <ul>
7826 reads a number;
7827 this is the only format that returns a number instead of a string.
7828 </li>
7831 reads the whole file, starting at the current position.
7832 On end of file, it returns the empty string.
7833 </li>
7836 reads the next line (skipping the end of line),
7838 This is the default format.
7839 </li>
7842 reads a string with up to this number of characters,
7844 If number is zero,
7845 it reads nothing and returns an empty string,
7847 </li>
7849 </ul>
7853 <p>
7857 <p>
7858 Sets and gets the file position,
7859 measured from the beginning of the file,
7863 <ul>
7867 </ul><p>
7869 measured in bytes from the beginning of the file.
7871 plus a string describing the error.
7874 <p>
7878 file position, without changing it;
7880 beginning of the file (and returns 0);
7882 end of the file, and returns its size.
7887 <p>
7891 <p>
7892 Sets the buffering mode for an output file.
7893 There are three available modes:
7895 <ul>
7898 no buffering; the result of any output operation appears immediately.
7899 </li>
7902 full buffering; output operation is performed only
7905 </li>
7908 line buffering; output is buffered until a newline is output
7909 or there is any input from some special files
7910 (such as a terminal device).
7911 </li>
7913 </ul><p>
7915 specifies the size of the buffer, in bytes.
7916 The default is an appropriate size.
7921 <p>
7925 <p>
7926 Writes the value of each of its arguments to
7928 The arguments must be strings or numbers.
7929 To write other values,
7930 use <a href="#pdf-tostring"><code>tostring</code></a> or <a href="#pdf-string.format"><code>string.format</code></a> before <code>write</code>.
7940 <p>
7944 <p>
7948 <p>
7949 Returns an approximation of the amount in seconds of CPU time
7950 used by the program.
7955 <p>
7959 <p>
7960 Returns a string or a table containing date and time,
7964 <p>
7966 this 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).
7971 <p>
7973 then the date is formatted in Coordinated Universal Time.
7974 After this optional character,
7984 <p>
7990 <p>
7991 When called without arguments,
7993 the host system and on the current locale
7999 <p>
8003 <p>
8005 In POSIX, Windows, and some other systems,
8011 <p>
8015 <p>
8018 It returns a status code, which is system-dependent.
8020 and zero otherwise.
8025 <p>
8029 <p>
8032 to terminate the host program.
8038 <p>
8042 <p>
8049 <p>
8053 <p>
8054 Deletes the file or directory with the given name.
8055 Directories must be empty to be removed.
8057 plus a string describing the error.
8062 <p>
8066 <p>
8069 plus a string describing the error.
8074 <p>
8078 <p>
8079 Sets the current locale of the program.
8085 The function returns the name of the new locale,
8089 <p>
8091 the current locale is set to an implementation-defined native locale.
8093 the current locale is set to the standard C locale.
8096 <p>
8098 this function only returns the name of the current locale
8099 for the given category.
8104 <p>
8108 <p>
8109 Returns the current time when called without arguments,
8110 or a time representing the date and time specified by the given table.
8112 and 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).
8116 <p>
8117 The returned value is a number, whose meaning depends on your system.
8118 In POSIX, Windows, and some other systems, this number counts the number
8119 of seconds since some given start time (the "epoch").
8120 In other systems, the meaning is not specified,
8127 <p>
8131 <p>
8132 Returns a string with a file name that can
8133 be used for a temporary file.
8134 The file must be explicitly opened before its use
8135 and explicitly removed when no longer needed.
8138 <p>
8139 On some systems (POSIX),
8140 this function also creates a file with that name,
8141 to avoid security risks.
8142 (Someone else might create the file with wrong permissions
8143 in the time between getting the name and creating the file.)
8144 You still have to open the file to use it
8145 and to remove it (even if you do not use it).
8148 <p>
8149 When possible,
8151 which automatically removes the file when the program ends.
8161 <p>
8162 This library provides
8163 the functionality of the debug interface to Lua programs.
8164 You should exert care when using this library.
8165 The functions provided here should be used exclusively for debugging
8166 and similar tasks, such as profiling.
8167 Please resist the temptation to use them as a
8168 usual programming tool:
8169 they can be very slow.
8170 Moreover, several of these functions
8171 violate some assumptions about Lua code
8172 (e.g., that variables local to a function
8173 cannot be accessed from outside or
8174 that userdata metatables cannot be changed by Lua code)
8175 and therefore can compromise otherwise secure code.
8178 <p>
8179 All functions in this library are provided
8181 All functions that operate over a thread
8182 have an optional first argument which is the
8183 thread to operate over.
8184 The default is always the current thread.
8187 <p>
8191 <p>
8192 Enters an interactive mode with the user,
8193 running each string that the user enters.
8194 Using simple commands and other debug facilities,
8195 the user can inspect global and local variables,
8196 change their values, evaluate expressions, and so on.
8198 so that the caller continues its execution.
8201 <p>
8203 within any function, and so have no direct access to local variables.
8208 <p>
8215 <p>
8219 <p>
8220 Returns the current hook settings of the thread, as three values:
8221 the current hook function, the current hook mask,
8222 and the current hook count
8228 <p>
8229 <hr><h3><a name="pdf-debug.getinfo"><code>debug.getinfo ([thread,] function [, what])</code></a></h3>
8232 <p>
8233 Returns a table with information about a function.
8234 You can give the function directly,
8237 of the given thread:
8240 and so on.
8245 <p>
8246 The returned table can contain all the fields returned by <a href="#lua_getinfo"><code>lua_getinfo</code></a>,
8249 except the table of valid lines.
8250 If present,
8253 If present,
8256 valid lines.
8259 <p>
8261 a table with a name for the current function,
8262 if a reasonable name can be found,
8264 returns a table with all available information
8270 <p>
8271 <hr><h3><a name="pdf-debug.getlocal"><code>debug.getlocal ([thread,] level, local)</code></a></h3>
8274 <p>
8275 This function returns the name and the value of the local variable
8278 until the last active local variable.)
8280 variable with the given index,
8282 (You can call <a href="#pdf-debug.getinfo"><code>debug.getinfo</code></a> to check whether the level is valid.)
8285 <p>
8287 represent internal variables
8288 (loop control variables, temporaries, and C function locals).
8293 <p>
8297 <p>
8304 <p>
8308 <p>
8314 <p>
8318 <p>
8319 This function returns the name and the value of the upvalue
8326 <p>
8330 <p>
8337 <p>
8338 <hr><h3><a name="pdf-debug.sethook"><code>debug.sethook ([thread,] hook, mask [, count])</code></a></h3>
8341 <p>
8342 Sets the given function as a hook.
8344 when the hook will be called.
8345 The string mask may have the following characters,
8346 with the given meaning:
8348 <ul>
8352 </ul><p>
8357 <p>
8358 When called without arguments,
8362 <p>
8363 When the hook is called, its first parameter is a string
8364 describing the event that has triggered its call:
8366 when simulating a return from a tail call),
8368 For line events,
8369 the hook also gets the new line number as its second parameter.
8370 Inside a hook,
8372 the running function
8376 In this case, Lua is only simulating the return,
8382 <p>
8383 <hr><h3><a name="pdf-debug.setlocal"><code>debug.setlocal ([thread,] level, local, value)</code></a></h3>
8386 <p>
8390 variable with the given index,
8393 Otherwise, it returns the name of the local variable.
8398 <p>
8399 <hr><h3><a name="pdf-debug.setmetatable"><code>debug.setmetatable (object, table)</code></a></h3>
8402 <p>
8409 <p>
8410 <hr><h3><a name="pdf-debug.setupvalue"><code>debug.setupvalue (func, up, value)</code></a></h3>
8413 <p>
8417 with the given index.
8418 Otherwise, it returns the name of the upvalue.
8423 <p>
8424 <hr><h3><a name="pdf-debug.traceback"><code>debug.traceback ([thread,] [message] [, level])</code></a></h3>
8427 <p>
8428 Returns a string with a traceback of the call stack.
8430 at the beginning of the traceback.
8432 to start the traceback
8443 <p>
8444 Although Lua has been designed as an extension language,
8445 to be embedded in a host C program,
8446 it is also frequently used as a stand-alone language.
8447 An interpreter for Lua as a stand-alone language,
8449 is provided with the standard distribution.
8450 The stand-alone interpreter includes
8451 all standard libraries, including the debug library.
8452 Its usage is:
8454 <pre>
8455 lua [options] [script [args]]
8456 </pre><p>
8457 The options are:
8459 <ul>
8465 <li><b><code>-</code>:</b> executes <code>stdin</code> as a file and stops handling options.</li>
8466 </ul><p>
8469 When called without arguments,
8475 <p>
8476 Before running any argument,
8477 the interpreter checks for an environment variable <a name="pdf-LUA_INIT"><code>LUA_INIT</code></a>.
8483 <p>
8485 For instance, an invocation like
8487 <pre>
8488 $ lua -e'a=1' -e 'print(a)' script.lua
8489 </pre><p>
8490 will first set <code>a</code> to 1, then print the value of <code>a</code> (which is '<code>1</code>'),
8495 <p>
8496 Before starting to run the script,
8499 The script name is stored at index 0,
8500 the first argument after the script name goes to index 1,
8501 and so on.
8502 Any arguments before the script name
8503 (that is, the interpreter name plus the options)
8504 go to negative indices.
8505 For instance, in the call
8507 <pre>
8508 $ lua -la b.lua t1 t2
8509 </pre><p>
8511 then creates a table
8513 <pre>
8517 </pre><p>
8520 as arguments;
8524 <p>
8525 In interactive mode,
8526 if you write an incomplete statement,
8527 the interpreter waits for its completion
8528 by issuing a different prompt.
8531 <p>
8533 then its value is used as the prompt.
8534 Similarly, if the global variable <a name="pdf-_PROMPT2"><code>_PROMPT2</code></a> contains a string,
8535 its value is used as the secondary prompt
8536 (issued during incomplete statements).
8537 Therefore, both prompts can be changed directly on the command line
8539 See the next example:
8541 <pre>
8542 $ lua -e"_PROMPT='myprompt> '" -i
8543 </pre><p>
8544 (The outer pair of quotes is for the shell,
8545 the inner pair is for Lua.)
8547 otherwise,
8548 the program would just end silently
8552 <p>
8553 To allow the use of Lua as a
8554 script interpreter in Unix systems,
8555 the stand-alone interpreter skips
8557 Therefore, Lua scripts can be made into executable programs
8559 as in
8561 <pre>
8562 #!/usr/local/bin/lua
8563 </pre><p>
8564 (Of course,
8565 the location of the Lua interpreter may be different in your machine.
8567 then
8569 <pre>
8570 #!/usr/bin/env lua
8571 </pre><p>
8572 is a more portable solution.)
8578 <p>
8579 Here we list the incompatibilities that you may find when moving a program
8581 You can avoid most of the incompatibilities compiling Lua with
8583 However,
8584 all these compatibility options will be removed in the next version of Lua.
8589 <ul>
8591 <li>
8593 table with the extra arguments to the vararg expression.
8595 </li>
8597 <li>
8598 There was a subtle change in the scope of the implicit
8600 </li>
8602 <li>
8604 does not allow nesting.
8607 </li>
8609 </ul>
8615 <ul>
8617 <li>
8618 Function <code>string.gfind</code> was renamed <a href="#pdf-string.gmatch"><code>string.gmatch</code></a>.
8620 </li>
8622 <li>
8624 third argument,
8626 replacement string is the whole match,
8627 instead of the empty string.
8628 </li>
8630 <li>
8634 use the operator instead of the function.
8636 </li>
8638 <li>
8639 Function <code>loadlib</code> was renamed <a href="#pdf-package.loadlib"><code>package.loadlib</code></a>.
8641 </li>
8643 <li>
8644 Function <code>math.mod</code> was renamed <a href="#pdf-math.fmod"><code>math.fmod</code></a>.
8646 </li>
8648 <li>
8651 </li>
8653 <li>
8654 There were substantial changes in function <a href="#pdf-require"><code>require</code></a> due to
8655 the new module system.
8656 However, the new behavior is mostly compatible with the old,
8657 but <code>require</code> gets the path from <a href="#pdf-package.path"><code>package.path</code></a> instead
8659 </li>
8661 <li>
8662 Function <a href="#pdf-collectgarbage"><code>collectgarbage</code></a> has different arguments.
8665 </li>
8667 </ul>
8673 <ul>
8675 <li>
8677 cannot be called directly,
8678 like a regular C function.
8679 They must be called through Lua,
8680 like a Lua function.
8681 </li>
8683 <li>
8684 Function <code>lua_open</code> was replaced by <a href="#lua_newstate"><code>lua_newstate</code></a> to
8685 allow the user to set a memory-allocation function.
8686 You can use <a href="#luaL_newstate"><code>luaL_newstate</code></a> from the standard library to
8687 create a state with a standard allocation function
8689 </li>
8691 <li>
8693 (from the auxiliary library) are deprecated.
8696 </li>
8698 <li>
8699 Function <code>luaL_openlib</code> was replaced by <a href="#luaL_register"><code>luaL_register</code></a>.
8700 </li>
8702 <li>
8704 is not a userdata of the expected type.
8706 </li>
8708 </ul>
8715 <p>
8716 Here is the complete syntax of Lua in extended BNF.
8717 (It does not describe operator precedences.)
8722 <pre>
8726 block ::= chunk
8729 functioncall |
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>´ exp `<b>,</b>´ exp [`<b>,</b>´ exp] <b>do</b> block <b>end</b> |
8746 var ::= Name | prefixexp `<b>[</b>´ exp `<b>]</b>´ | prefixexp `<b>.</b>´ Name
8752 exp ::= <b>nil</b> | <b>false</b> | <b>true</b> | Number | String | `<b>...</b>´ | function |
8753 prefixexp | tableconstructor | exp binop exp | unop exp
8769 fieldlist ::= field {fieldsep field} [fieldsep]
8771 field ::= `<b>[</b>´ exp `<b>]</b>´ `<b>=</b>´ exp | Name `<b>=</b>´ exp | exp
8775 binop ::= `<b>+</b>´ | `<b>-</b>´ | `<b>*</b>´ | `<b>/</b>´ | `<b>^</b>´ | `<b>%</b>´ | `<b>..</b>´ |
8776 `<b><</b>´ | `<b><=</b>´ | `<b>></b>´ | `<b>>=</b>´ | `<b>==</b>´ | `<b>~=</b>´ |
8781 </pre>
8783 <p>
8791 <HR>
8792 <SMALL>
8793 Last update:
8795 </SMALL>
8796 <!--
8797 Last change: revised for Lua 5.1.4
8798 -->
8800 </body></html>