| blob | 6b137ff6e6f4e00a56af8ca196c48aec314e398a |
2 <html>
4 <head>
8 </head>
10 <body>
12 <hr>
13 <h1>
15 Lua 5.1 Reference Manual
16 </h1>
18 by Roberto Ierusalimschy, Luiz Henrique de Figueiredo, Waldemar Celes
19 <p>
20 <small>
22 Freely available under the terms of the
24 </small>
25 <hr>
26 <p>
29 ·
32 <!-- ====================================================================== -->
33 <p>
41 <p>
42 Lua is an extension programming language designed to support
43 general procedural programming with data description
44 facilities.
45 It also offers good support for object-oriented programming,
46 functional programming, and data-driven programming.
47 Lua is intended to be used as a powerful, light-weight
48 scripting language for any program that needs one.
50 (that is, in the common subset of ANSI C and C++).
53 <p>
54 Being an extension language, Lua has no notion of a "main" program:
57 This host program can invoke functions to execute a piece of Lua code,
58 can write and read Lua variables,
59 and can register C functions to be called by Lua code.
60 Through the use of C functions, Lua can be augmented to cope with
61 a wide range of different domains,
62 thus creating customized programming languages sharing a syntactical framework.
64 which uses the Lua library to offer a complete, stand-alone Lua interpreter.
67 <p>
68 Lua is free software,
69 and is provided as usual with no guarantees,
70 as stated in its license.
71 The implementation described in this manual is available
75 <p>
76 Like any other reference manual,
77 this document is dry in places.
78 For a discussion of the decisions behind the design of Lua,
79 see the technical papers available at Lua's web site.
80 For a detailed introduction to programming in Lua,
87 <p>
88 This section describes the lexis, the syntax, and the semantics of Lua.
89 In other words,
90 this section describes
91 which tokens are valid,
92 how they can be combined,
93 and what their combinations mean.
96 <p>
97 The language constructs will be explained using the usual extended BNF notation,
98 in which
101 Non-terminals are shown like non-terminal,
104 The complete syntax of Lua can be found at the end of this manual.
110 <p>
113 in Lua can be any string of letters,
114 digits, and underscores,
115 not beginning with a digit.
116 This coincides with the definition of names in most languages.
117 (The definition of letter depends on the current locale:
118 any character considered alphabetic by the current locale
119 can be used in an identifier.)
120 Identifiers are used to name variables and table fields.
123 <p>
125 and cannot be used as names:
128 <pre>
129 and break do else elseif
130 end false for function if
131 in local nil not or
132 repeat return then true until while
133 </pre>
135 <p>
136 Lua is a case-sensitive language:
138 are two different, valid names.
139 As a convention, names starting with an underscore followed by
141 are reserved for internal global variables used by Lua.
144 <p>
145 The following strings denote other tokens:
147 <pre>
148 + - * / % ^ #
150 ( ) { } [ ]
151 ; : , . .. ...
152 </pre>
154 <p>
156 can be delimited by matching single or double quotes,
157 and can contain the following C-like escape sequences:
167 and '<code>\'</code>' (apostrophe [single quote]).
168 Moreover, a backslash followed by a real newline
169 results in a newline in the string.
170 A character in a string may also be specified by its numerical value
171 using the escape sequence <code>\<em>ddd</em></code>,
172 where <em>ddd</em> is a sequence of up to three decimal digits.
173 (Note that if a numerical escape is to be followed by a digit,
174 it must be expressed using exactly three digits.)
175 Strings in Lua may contain any 8-bit value, including embedded zeros,
176 which can be specified as '<code>\0</code>'.
179 <p>
180 To put a double (single) quote, a newline, a backslash,
181 or an embedded zero
182 inside a literal string enclosed by double (single) quotes
183 you must use an escape sequence.
184 Any other character may be directly inserted into the literal.
185 (Some control characters may cause problems for the file system,
186 but Lua has no problem with them.)
189 <p>
190 Literal strings can also be defined using a long format
191 enclosed by <em>long brackets</em>.
192 We define an <em>opening long bracket of level <em>n</em></em> as an opening
193 square bracket followed by <em>n</em> equal signs followed by another
194 opening square bracket.
195 So, an opening long bracket of level 0 is written as <code>[[</code>,
196 an opening long bracket of level 1 is written as <code>[=[</code>,
197 and so on.
198 A <em>closing long bracket</em> is defined similarly;
199 for instance, a closing long bracket of level 4 is written as <code>]====]</code>.
200 A long string starts with an opening long bracket of any level and
201 ends at the first closing long bracket of the same level.
202 Literals in this bracketed form may run for several lines,
203 do not interpret any escape sequences,
204 and ignore long brackets of any other level.
205 They may contain anything except a closing bracket of the proper level.
208 <p>
209 For convenience,
210 when the opening long bracket is immediately followed by a newline,
211 the newline is not included in the string.
212 As an example, in a system using ASCII
213 (in which '<code>a</code>' is coded as 97,
214 newline is coded as 10, and '<code>1</code>' is coded as 49),
215 the five literals below denote the same string:
217 <pre>
218 a = 'alo\n123"'
220 a = '\97lo\10\04923"'
221 a = [[alo
223 a = [==[
224 alo
225 123"]==]
226 </pre>
228 <p>
230 and an optional decimal exponent.
231 Lua also accepts integer hexadecimal constants,
233 Examples of valid numerical constants are
235 <pre>
237 </pre>
239 <p>
241 anywhere outside a string.
244 which runs until the end of the line.
246 which runs until the corresponding closing long bracket.
247 Long comments are frequently used to disable code temporarily.
255 <p>
257 This means that
258 variables do not have types; only values do.
259 There are no type definitions in the language.
260 All values carry their own type.
263 <p>
265 This means that all values can be stored in variables,
266 passed as arguments to other functions, and returned as results.
269 <p>
270 There are eight basic types in Lua:
275 whose main property is to be different from any other value;
276 it usually represents the absence of a useful value.
279 any other value makes it true.
281 (It is easy to build Lua interpreters that use other
282 internal representations for numbers,
283 such as single-precision float or long integers;
287 Lua is 8-bit clean:
288 strings may contain any 8-bit character,
292 <p>
293 Lua can call (and manipulate) functions written in Lua and
294 functions written in C
298 <p>
300 be stored in Lua variables.
301 This type corresponds to a block of raw memory
302 and has no pre-defined operations in Lua,
303 except assignment and identity test.
305 the programmer can define operations for userdata values
307 Userdata values cannot be created or modified in Lua,
308 only through the C API.
309 This guarantees the integrity of data owned by the host program.
312 <p>
315 Do not confuse Lua threads with operating-system threads.
316 Lua supports coroutines on all systems,
317 even those that do not support threads.
320 <p>
322 that is, arrays that can be indexed not only with numbers,
326 Tables are the sole data structuring mechanism in Lua;
327 they may be used to represent ordinary arrays,
328 symbol tables, sets, records, graphs, trees, etc.
329 To represent records, Lua uses the field name as an index.
330 The language supports this representation by
332 There are several convenient ways to create tables in Lua
336 <p>
337 Like indices,
339 In particular,
340 because functions are first-class values,
341 table fields may contain functions.
345 <p>
349 Assignment, parameter passing, and function returns
350 always manipulate references to such values;
351 these operations do not imply any kind of copy.
354 <p>
355 The library function <a href="#pdf-type"><code>type</code></a> returns a string describing the type
356 of a given value.
362 <p>
363 Lua provides automatic conversion between
364 string and number values at run time.
365 Any arithmetic operation applied to a string tries to convert
366 this string to a number, following the usual conversion rules.
367 Conversely, whenever a number is used where a string is expected,
368 the number is converted to a string, in a reasonable format.
369 For complete control over how numbers are converted to strings,
381 <p>
382 Variables are places that store values.
384 There are three kinds of variables in Lua:
385 global variables, local variables, and table fields.
388 <p>
389 A single name can denote a global variable or a local variable
390 (or a function's formal parameter,
391 which is a particular kind of local variable):
393 <pre>
394 var ::= Name
395 </pre><p>
399 <p>
400 Any variable is assumed to be global unless explicitly declared
403 local variables can be freely accessed by functions
407 <p>
411 <p>
412 Square brackets are used to index a table:
414 <pre>
416 </pre><p>
417 The meaning of accesses to global variables
418 and table fields can be changed via metatables.
423 This function is not defined or callable in Lua.
424 We use it here only for explanatory purposes.)
427 <p>
431 <pre>
433 </pre>
435 <p>
436 All global variables live as fields in ordinary Lua tables,
439 Each function has its own reference to an environment,
440 so that all global variables in this function
441 will refer to this environment table.
442 When a function is created,
443 it inherits the environment from the function that created it.
444 To get the environment table of a Lua function,
446 To replace it,
448 (You can only manipulate the environment of C functions
452 <p>
455 which in turn is equivalent to
457 <pre>
458 gettable_event(_env, "x")
459 </pre><p>
463 This function is not defined or callable in Lua.
465 We use them here only for explanatory purposes.)
473 <p>
474 Lua supports an almost conventional set of statements,
475 similar to those in Pascal or C.
476 This set includes
477 assignment, control structures, function calls,
478 and variable declarations.
484 <p>
486 A chunk is simply a sequence of statements,
487 which are executed sequentially.
488 Each statement can be optionally followed by a semicolon:
490 <pre>
492 </pre><p>
496 <p>
497 Lua handles a chunk as the body of an anonymous function
498 with a variable number of arguments
500 As such, chunks can define local variables,
501 receive arguments, and return values.
504 <p>
505 A chunk may be stored in a file or in a string inside the host program.
506 When a chunk is executed, first it is pre-compiled into instructions for
507 a virtual machine,
508 and then the compiled code is executed
509 by an interpreter for the virtual machine.
512 <p>
513 Chunks may also be pre-compiled into binary form;
515 Programs in source and compiled forms are interchangeable;
516 Lua automatically detects the file type and acts accordingly.
524 A block is a list of statements;
525 syntactically, a block is the same as a chunk:
527 <pre>
528 block ::= chunk
529 </pre>
531 <p>
532 A block may be explicitly delimited to produce a single statement:
534 <pre>
536 </pre><p>
537 Explicit blocks are useful
538 to control the scope of variable declarations.
539 Explicit blocks are also sometimes used to
549 <p>
550 Lua allows multiple assignment.
551 Therefore, the syntax for assignment
552 defines a list of variables on the left side
553 and a list of expressions on the right side.
554 The elements in both lists are separated by commas:
556 <pre>
560 </pre><p>
564 <p>
565 Before the assignment,
567 the list of variables.
568 If there are more values than needed,
569 the excess values are thrown away.
570 If there are fewer values than needed,
572 If the list of expressions ends with a function call,
573 then all values returned by this call enter in the list of values,
574 before the adjustment
578 <p>
579 The assignment statement first evaluates all its expressions
580 and only then are the assignments performed.
581 Thus the code
583 <pre>
584 i = 3
586 </pre><p>
590 Similarly, the line
592 <pre>
593 x, y = y, x
594 </pre><p>
598 <p>
599 The meaning of assignments to global variables
600 and table fields can be changed via metatables.
605 This function is not defined or callable in Lua.
606 We use it here only for explanatory purposes.)
609 <p>
611 is equivalent to the assignment
613 which in turn is equivalent to
615 <pre>
616 settable_event(_env, "x", val)
617 </pre><p>
620 We use it here only for explanatory purposes.)
627 The control structures
629 familiar syntax:
634 <pre>
637 stat ::= <b>if</b> exp <b>then</b> block {<b>elseif</b> exp <b>then</b> block} [<b>else</b> block] <b>end</b>
638 </pre><p>
642 <p>
643 The condition expression of a
644 control structure may return any value.
647 (in particular, the number 0 and the empty string are also true).
650 <p>
653 but only after the condition.
654 So, the condition can refer to local variables
655 declared inside the loop block.
658 <p>
660 from a function or a chunk (which is just a function).
662 Functions and chunks may return more than one value,
665 <pre>
667 </pre>
669 <p>
672 skipping to the next statement after the loop:
675 <pre>
677 </pre><p>
681 <p>
685 middle of a block,
686 then an explicit inner block can be used,
687 as in the idioms
690 their (inner) blocks.
698 <p>
701 one numeric and one generic.
704 <p>
706 control variable runs through an arithmetic progression.
707 It has the following syntax:
709 <pre>
710 stat ::= <b>for</b> Name `<b>=</b>´ exp `<b>,</b>´ exp [`<b>,</b>´ exp] <b>do</b> block <b>end</b>
711 </pre><p>
717 <pre>
719 </pre><p>
720 is equivalent to the code:
722 <pre>
723 do
724 local <em>var</em>, <em>limit</em>, <em>step</em> = tonumber(<em>e1</em>), tonumber(<em>e2</em>), tonumber(<em>e3</em>)
726 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
730 end
731 end
732 </pre><p>
733 Note the following:
735 <ul>
737 <li>
738 All three control expressions are evaluated only once,
739 before the loop starts.
740 They must all result in numbers.
741 </li>
743 <li>
744 <code><em>var</em></code>, <code><em>limit</em></code>, and <code><em>step</em></code> are invisible variables.
745 The names are here for explanatory purposes only.
746 </li>
748 <li>
749 If the third expression (the step) is absent,
751 </li>
753 <li>
755 </li>
757 <li>
760 If you need this value,
761 assign it to another variable before breaking or exiting the loop.
762 </li>
764 </ul>
766 <p>
769 On each iteration, the iterator function is called to produce a new value,
773 <pre>
776 </pre><p>
779 <pre>
780 for <em>var_1</em>, ···, <em>var_n</em> in <em>explist</em> do <em>block</em> end
781 </pre><p>
782 is equivalent to the code:
784 <pre>
785 do
787 while true do
788 local <em>var_1</em>, ···, <em>var_n</em> = <em>f</em>(<em>s</em>, <em>var</em>)
792 end
793 end
794 </pre><p>
795 Note the following:
797 <ul>
799 <li>
804 </li>
806 <li>
807 <code><em>f</em></code>, <code><em>s</em></code>, and <code><em>var</em></code> are invisible variables.
808 The names are here for explanatory purposes only.
809 </li>
811 <li>
813 </li>
815 <li>
818 If you need these values,
819 then assign them to other variables before breaking or exiting the loop.
820 </li>
822 </ul>
828 To allow possible side-effects,
829 function calls can be executed as statements:
831 <pre>
832 stat ::= functioncall
833 </pre><p>
834 In this case, all returned values are thrown away.
842 Local variables may be declared anywhere inside a block.
843 The declaration may include an initial assignment:
845 <pre>
847 </pre><p>
848 If present, an initial assignment has the same semantics
853 <p>
855 and so local variables can be declared in a chunk outside any explicit block.
856 The scope of such local variables extends until the end of the chunk.
859 <p>
870 <p>
871 The basic expressions in Lua are the following:
873 <pre>
874 exp ::= prefixexp
876 exp ::= Number
877 exp ::= String
878 exp ::= function
879 exp ::= tableconstructor
881 exp ::= exp binop exp
882 exp ::= unop exp
884 </pre>
886 <p>
892 Vararg expressions,
894 directly inside a vararg function;
898 <p>
900 relational operators (see <a href="#2.5.2">§2.5.2</a>), logical operators (see <a href="#2.5.3">§2.5.3</a>),
907 <p>
908 Both function calls and vararg expressions may result in multiple values.
910 (only possible for function calls),
911 then its return list is adjusted to zero elements,
912 thus discarding all returned values.
913 If the expression is used as the last (or the only) element
914 of a list of expressions,
915 then no adjustment is made
916 (unless the call is enclosed in parentheses).
917 In all other contexts,
918 Lua adjusts the result list to one element,
919 discarding all values except the first one.
922 <p>
923 Here are some examples:
925 <pre>
926 f() -- adjusted to 0 results
927 g(f(), x) -- f() is adjusted to 1 result
928 g(x, f()) -- g gets x plus all results from f()
929 a,b,c = f(), x -- f() is adjusted to 1 result (c gets nil)
930 a,b = ... -- a gets the first vararg parameter, b gets
931 -- the second (both a and b may get nil if there
932 -- is no corresponding vararg parameter)
934 a,b,c = x, f() -- f() is adjusted to 2 results
935 a,b,c = f() -- f() is adjusted to 3 results
936 return f() -- returns all results from f()
937 return ... -- returns all received vararg parameters
938 return x,y,f() -- returns x, y, and all results from f()
939 {f()} -- creates a list with all results from f()
940 {...} -- creates a list with all vararg parameters
941 {f(), nil} -- f() is adjusted to 1 result
942 </pre>
944 <p>
945 An expression enclosed in parentheses always results in only one value.
946 Thus,
955 Lua supports the usual arithmetic operators:
960 If the operands are numbers, or strings that can be converted to
962 then all operations have the usual meaning.
963 Exponentiation works for any exponent.
965 Modulo is defined as
967 <pre>
968 a % b == a - math.floor(a/b)*b
969 </pre><p>
970 That is, it is the remainder of a division that rounds
971 the quotient towards minus infinity.
978 The relational operators in Lua are
980 <pre>
982 </pre><p>
986 <p>
989 Otherwise, the values of the operands are compared.
990 Numbers and strings are compared in the usual way.
991 Objects (tables, userdata, threads, and functions)
994 Every time you create a new object
995 (a table, userdata, thread, or function),
996 this new object is different from any previously existing object.
999 <p>
1000 You can change the way that Lua compares tables and userdata
1004 <p>
1009 entries in a table.
1012 <p>
1016 <p>
1017 The order operators work as follows.
1018 If both arguments are numbers, then they are compared as such.
1019 Otherwise, if both arguments are strings,
1020 then their values are compared according to the current locale.
1029 The logical operators in Lua are
1033 and anything else as true.
1036 <p>
1045 that is,
1046 the second operand is evaluated only if necessary.
1047 Here are some examples:
1049 <pre>
1054 false and error() --> false
1055 false and nil --> false
1056 false or nil --> nil
1058 </pre><p>
1059 (In this manual,
1060 --> indicates the result of the preceding expression.)
1067 The string concatenation operator in Lua is
1069 If both operands are strings or numbers, then they are converted to
1079 <p>
1081 The length of a string is its number of bytes
1082 (that is, the usual meaning of string length when each
1083 character is one byte).
1086 <p>
1093 the index of its last value.
1094 If the array has "holes"
1099 the array).
1106 Operator precedence in Lua follows the table below,
1107 from lower to higher priority:
1109 <pre>
1110 or
1111 and
1113 ..
1114 + -
1115 * / %
1116 not # - (unary)
1117 ^
1118 </pre><p>
1119 As usual,
1120 you can use parentheses to change the precedences of an expression.
1122 operators are right associative.
1123 All other binary operators are left associative.
1130 Table constructors are expressions that create tables.
1131 Every time a constructor is evaluated, a new table is created.
1132 Constructors can be used to create empty tables,
1133 or to create a table and initialize some of its fields.
1134 The general syntax for constructors is
1136 <pre>
1138 fieldlist ::= field {fieldsep field} [fieldsep]
1139 field ::= `<b>[</b>´ exp `<b>]</b>´ `<b>=</b>´ exp | Name `<b>=</b>´ exp | exp
1141 </pre>
1143 <p>
1150 starting with 1.
1151 Fields in the other formats do not affect this counting.
1152 For example,
1154 <pre>
1156 </pre><p>
1157 is equivalent to
1159 <pre>
1160 do
1161 local t = {}
1162 t[f(1)] = g
1169 a = t
1170 end
1171 </pre>
1173 <p>
1175 and the expression is a function call or a vararg expression,
1176 then all values returned by this expression enter the list consecutively
1178 To avoid this,
1179 enclose the function call (or the vararg expression)
1183 <p>
1184 The field list may have an optional trailing separator,
1185 as a convenience for machine-generated code.
1192 A function call in Lua has the following syntax:
1194 <pre>
1195 functioncall ::= prefixexp args
1196 </pre><p>
1197 In a function call,
1198 first prefixexp and args are evaluated.
1200 then this function is called
1201 with the given arguments.
1202 Otherwise, the prefixexp "call" metamethod is called,
1203 having as first parameter the value of prefixexp,
1204 followed by the original call arguments
1208 <p>
1209 The form
1211 <pre>
1213 </pre><p>
1214 can be used to call "methods".
1220 <p>
1221 Arguments have the following syntax:
1223 <pre>
1225 args ::= tableconstructor
1226 args ::= String
1227 </pre><p>
1228 All argument expressions are evaluated before the call.
1231 that is, the argument list is a single new table.
1235 that is, the argument list is a single literal string.
1238 <p>
1239 As an exception to the free-format syntax of Lua,
1241 This restriction avoids some ambiguities in the language.
1242 If you write
1244 <pre>
1245 a = f
1246 (g).x(a)
1247 </pre><p>
1249 So, if you want two statements, you must add a semi-colon between them.
1254 <p>
1259 in a tail call,
1260 the called function reuses the stack entry of the calling function.
1261 Therefore, there is no limit on the number of nested tail calls that
1262 a program can execute.
1263 However, a tail call erases any debug information about the
1264 calling function.
1265 Note that a tail call only happens with a particular syntax,
1267 this syntax makes the calling function return exactly
1268 the returns of the called function.
1269 So, none of the following examples are tail calls:
1271 <pre>
1272 return (f(x)) -- results adjusted to 1
1273 return 2 * f(x)
1274 return x, f(x) -- additional results
1275 f(x); return -- results discarded
1276 return x or f(x) -- results adjusted to 1
1277 </pre>
1284 <p>
1285 The syntax for function definition is
1287 <pre>
1290 </pre>
1292 <p>
1293 The following syntactic sugar simplifies function definitions:
1295 <pre>
1299 </pre><p>
1300 The statement
1302 <pre>
1304 </pre><p>
1305 translates to
1307 <pre>
1309 </pre><p>
1310 The statement
1312 <pre>
1314 </pre><p>
1315 translates to
1317 <pre>
1319 </pre><p>
1320 The statement
1322 <pre>
1324 </pre><p>
1325 translates to
1327 <pre>
1329 </pre><p>
1332 <pre>
1334 </pre><p>
1335 (This only makes a difference when the body of the function
1339 <p>
1340 A function definition is an executable expression,
1342 When Lua pre-compiles a chunk,
1343 all its function bodies are pre-compiled too.
1344 Then, whenever Lua executes the function definition,
1347 is the final value of the expression.
1348 Different instances of the same function
1349 may refer to different external local variables
1350 and may have different environment tables.
1353 <p>
1354 Parameters act as local variables that are
1355 initialized with the argument values:
1357 <pre>
1359 </pre><p>
1360 When a function is called,
1361 the list of arguments is adjusted to
1362 the length of the list of parameters,
1364 which is
1366 A vararg function does not adjust its argument list;
1367 instead, it collects all extra arguments and supplies them
1369 which is also written as three dots.
1370 The value of this expression is a list of all actual extra arguments,
1371 similar to a function with multiple results.
1372 If a vararg expression is used inside another expression
1373 or in the middle of a list of expressions,
1374 then its return list is adjusted to one element.
1375 If the expression is used as the last element of a list of expressions,
1376 then no adjustment is made
1377 (unless the call is enclosed in parentheses).
1380 <p>
1381 As an example, consider the following definitions:
1383 <pre>
1384 function f(a, b) end
1385 function g(a, b, ...) end
1387 </pre><p>
1388 Then, we have the following mapping from arguments to parameters and
1389 to the vararg expression:
1391 <pre>
1392 CALL PARAMETERS
1404 </pre>
1406 <p>
1408 If control reaches the end of a function
1410 then the function returns with no results.
1413 <p>
1417 Thus, the statement
1419 <pre>
1421 </pre><p>
1422 is syntactic sugar for
1424 <pre>
1426 </pre>
1435 <p>
1437 Lua is a lexically scoped language.
1439 their declaration and lasts until the end of the innermost block that
1440 includes the declaration.
1441 Consider the following example:
1443 <pre>
1444 x = 10 -- global variable
1445 do -- new block
1446 local x = x -- new 'x', with value 10
1448 x = x+1
1449 do -- another block
1450 local x = x+1 -- another 'x'
1452 end
1454 end
1456 </pre>
1458 <p>
1464 <p>
1465 Because of the lexical scoping rules,
1466 local variables can be freely accessed by functions
1467 defined inside their scope.
1468 A local variable used by an inner function is called
1470 inside the inner function.
1473 <p>
1475 defines new local variables.
1476 Consider the following example:
1478 <pre>
1479 a = {}
1480 local x = 20
1482 local y = 0
1483 a[i] = function () y=y+1; return x+y end
1484 end
1485 </pre><p>
1486 The loop creates ten closures
1487 (that is, ten instances of the anonymous function).
1497 <p>
1498 Because Lua is an embedded extension language,
1499 all Lua actions start from C code in the host program
1501 Whenever an error occurs during Lua compilation or execution,
1502 control returns to C,
1503 which can take appropriate measures
1504 (such as printing an error message).
1507 <p>
1508 Lua code can explicitly generate an error by calling the
1510 If you need to catch errors in Lua,
1519 <p>
1522 that defines the behavior of the original value
1523 under certain special operations.
1524 You can change several aspects of the behavior
1525 of operations over a value by setting specific fields in its metatable.
1526 For instance, when a non-numeric value is the operand of an addition,
1528 If it finds one,
1529 Lua calls this function to perform the addition.
1532 <p>
1536 and the metamethod is the function that performs the addition.
1539 <p>
1540 You can query the metatable of any value
1544 <p>
1545 You can replace the metatable of tables
1547 function.
1548 You cannot change the metatable of other types from Lua
1549 (except using the debug library);
1550 you must use the C API for that.
1553 <p>
1554 Tables and userdata have individual metatables
1555 (although multiple tables and userdata can share their metatables);
1556 values of all other types share one single metatable per type.
1557 So, there is one single metatable for all numbers,
1558 and for all strings, etc.
1561 <p>
1562 A metatable may control how an object behaves in arithmetic operations,
1563 order comparisons, concatenation, length operation, and indexing.
1564 A metatable can also define a function to be called when a userdata
1565 is garbage collected.
1566 For each of these operations Lua associates a specific key
1568 When Lua performs one of these operations over a value,
1569 it checks whether this value has a metatable with the corresponding event.
1570 If so, the value associated with that key (the metamethod)
1571 controls how Lua will perform the operation.
1574 <p>
1575 Metatables control the operations listed next.
1576 Each operation is identified by its corresponding name.
1577 The key for each operation is a string with its name prefixed by
1579 for instance, the key for operation "add" is the
1581 The semantics of these operations is better explained by a Lua function
1582 describing how the interpreter executes the operation.
1585 <p>
1586 The code shown here in Lua is only illustrative;
1587 the real behavior is hard coded in the interpreter
1588 and it is much more efficient than this simulation.
1589 All functions used in these descriptions
1590 (<a href="#pdf-rawget"><code>rawget</code></a>, <a href="#pdf-tonumber"><code>tonumber</code></a>, etc.)
1592 In particular, to retrieve the metamethod of a given object,
1593 we use the expression
1595 <pre>
1596 metatable(obj)[event]
1597 </pre><p>
1598 This should be read as
1600 <pre>
1601 rawget(getmetatable(obj) or {}, event)
1602 </pre><p>
1604 That is, the access to a metamethod does not invoke other metamethods,
1605 and the access to objects with no metatables does not fail
1610 <ul>
1617 <p>
1619 for a binary operation.
1620 First, Lua tries the first operand.
1621 If its type does not define a handler for the operation,
1622 then Lua tries the second operand.
1624 <pre>
1625 function getbinhandler (op1, op2, event)
1626 return metatable(op1)[event] or metatable(op2)[event]
1627 end
1628 </pre><p>
1629 By using this function,
1632 <pre>
1633 function add_event (op1, op2)
1634 local o1, o2 = tonumber(op1), tonumber(op2)
1635 if o1 and o2 then -- both operands are numeric?
1636 return o1 + o2 -- '+' here is the primitive 'add'
1637 else -- at least one of the operands is not numeric
1638 local h = getbinhandler(op1, op2, "__add")
1639 if h then
1640 -- call the handler with both operands
1641 return h(op1, op2)
1642 else -- no handler available: default behavior
1643 error(···)
1644 end
1645 end
1646 end
1647 </pre><p>
1648 </li>
1653 Behavior similar to the "add" operation.
1654 </li>
1659 Behavior similar to the "add" operation.
1660 </li>
1665 Behavior similar to the "add" operation.
1666 </li>
1671 Behavior similar to the "add" operation,
1672 with the operation
1674 </li>
1679 Behavior similar to the "add" operation,
1681 as the primitive operation.
1682 </li>
1688 <pre>
1689 function unm_event (op)
1690 local o = tonumber(op)
1691 if o then -- operand is numeric?
1692 return -o -- '-' here is the primitive 'unm'
1693 else -- the operand is not numeric.
1694 -- Try to get a handler from the operand
1695 local h = metatable(op).__unm
1696 if h then
1697 -- call the handler with the operand
1698 return h(op)
1699 else -- no handler available: default behavior
1700 error(···)
1701 end
1702 end
1703 end
1704 </pre><p>
1705 </li>
1711 <pre>
1712 function concat_event (op1, op2)
1715 return op1 .. op2 -- primitive string concatenation
1716 else
1717 local h = getbinhandler(op1, op2, "__concat")
1718 if h then
1719 return h(op1, op2)
1720 else
1721 error(···)
1722 end
1723 end
1724 end
1725 </pre><p>
1726 </li>
1732 <pre>
1733 function len_event (op)
1734 if type(op) == "string" then
1735 return strlen(op) -- primitive string length
1736 elseif type(op) == "table" then
1737 return #op -- primitive table length
1738 else
1739 local h = metatable(op).__len
1740 if h then
1741 -- call the handler with the operand
1742 return h(op)
1743 else -- no handler available: default behavior
1744 error(···)
1745 end
1746 end
1747 end
1748 </pre><p>
1750 </li>
1756 for comparison operators.
1757 A metamethod only is selected when both objects
1758 being compared have the same type
1759 and the same metamethod for the selected operation.
1761 <pre>
1762 function getcomphandler (op1, op2, event)
1763 if type(op1) ~= type(op2) then return nil end
1764 local mm1 = metatable(op1)[event]
1765 local mm2 = metatable(op2)[event]
1766 if mm1 == mm2 then return mm1 else return nil end
1767 end
1768 </pre><p>
1769 The "eq" event is defined as follows:
1771 <pre>
1772 function eq_event (op1, op2)
1773 if type(op1) ~= type(op2) then -- different types?
1774 return false -- different objects
1775 end
1776 if op1 == op2 then -- primitive equal?
1777 return true -- objects are equal
1778 end
1779 -- try metamethod
1780 local h = getcomphandler(op1, op2, "__eq")
1781 if h then
1782 return h(op1, op2)
1783 else
1784 return false
1785 end
1786 end
1787 </pre><p>
1789 </li>
1795 <pre>
1796 function lt_event (op1, op2)
1798 return op1 < op2 -- numeric comparison
1800 return op1 < op2 -- lexicographic comparison
1801 else
1802 local h = getcomphandler(op1, op2, "__lt")
1803 if h then
1804 return h(op1, op2)
1805 else
1806 error(···);
1807 end
1808 end
1809 end
1810 </pre><p>
1812 </li>
1818 <pre>
1819 function le_event (op1, op2)
1821 return op1 <= op2 -- numeric comparison
1823 return op1 <= op2 -- lexicographic comparison
1824 else
1825 local h = getcomphandler(op1, op2, "__le")
1826 if h then
1827 return h(op1, op2)
1828 else
1829 h = getcomphandler(op1, op2, "__lt")
1830 if h then
1831 return not h(op2, op1)
1832 else
1833 error(···);
1834 end
1835 end
1836 end
1837 end
1838 </pre><p>
1840 Note that, in the absence of a "le" metamethod,
1843 </li>
1849 <pre>
1850 function gettable_event (table, key)
1851 local h
1852 if type(table) == "table" then
1853 local v = rawget(table, key)
1854 if v ~= nil then return v end
1855 h = metatable(table).__index
1856 if h == nil then return nil end
1857 else
1858 h = metatable(table).__index
1859 if h == nil then
1860 error(···);
1861 end
1862 end
1863 if type(h) == "function" then
1864 return h(table, key) -- call the handler
1865 else return h[key] -- or repeat operation on it
1866 end
1867 end
1868 </pre><p>
1869 </li>
1875 <pre>
1876 function settable_event (table, key, value)
1877 local h
1878 if type(table) == "table" then
1879 local v = rawget(table, key)
1880 if v ~= nil then rawset(table, key, value); return end
1881 h = metatable(table).__newindex
1882 if h == nil then rawset(table, key, value); return end
1883 else
1884 h = metatable(table).__newindex
1885 if h == nil then
1886 error(···);
1887 end
1888 end
1889 if type(h) == "function" then
1890 return h(table, key,value) -- call the handler
1891 else h[key] = value -- or repeat operation on it
1892 end
1893 end
1894 </pre><p>
1895 </li>
1898 called when Lua calls a value.
1901 <pre>
1902 function function_event (func, ...)
1903 if type(func) == "function" then
1904 return func(...) -- primitive call
1905 else
1906 local h = metatable(func).__call
1907 if h then
1908 return h(func, ...)
1909 else
1910 error(···)
1911 end
1912 end
1913 end
1914 </pre><p>
1915 </li>
1917 </ul>
1924 <p>
1925 Besides metatables,
1926 objects of types thread, function, and userdata
1927 have another table associated with them,
1929 Like metatables, environments are regular tables and
1930 multiple objects can share the same environment.
1933 <p>
1934 Environments associated with userdata have no meaning for Lua.
1935 It is only a convenience feature for programmers to associate a table to
1936 a userdata.
1939 <p>
1940 Environments associated with threads are called
1942 They are used as the default environment for their threads and
1943 non-nested functions created by the thread
1944 (through <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>)
1948 <p>
1949 Environments associated with C functions can be directly
1951 They are used as the default environment for other C functions
1952 created by the function.
1955 <p>
1956 Environments associated with Lua functions are used to resolve
1958 They are used as the default environment for other Lua functions
1959 created by the function.
1962 <p>
1963 You can change the environment of a Lua function or the
1965 You can get the environment of a Lua function or the running thread
1967 To manipulate the environment of other objects
1968 (userdata, C functions, other threads) you must
1969 use the C API.
1977 <p>
1978 Lua performs automatic memory management.
1979 This means that
1980 you have to worry neither about allocating memory for new objects
1981 nor about freeing it when the objects are no longer needed.
1982 Lua manages memory automatically by running
1985 (that is, these objects that are no longer accessible from Lua).
1986 All objects in Lua are subject to automatic management:
1987 tables, userdata, functions, threads, and strings.
1990 <p>
1991 Lua implements an incremental mark-and-sweep collector.
1992 It uses two numbers to control its garbage-collection cycles:
1997 <p>
1998 The garbage-collector pause
1999 controls how long the collector waits before starting a new cycle.
2000 Larger values make the collector less aggressive.
2001 Values smaller than 1 mean the collector will not wait to
2002 start a new cycle.
2003 A value of 2 means that the collector waits for the total memory in use
2004 to double before starting a new cycle.
2007 <p>
2008 The step multiplier
2009 controls the relative speed of the collector relative to
2010 memory allocation.
2011 Larger values make the collector more aggressive but also increase
2012 the size of each incremental step.
2013 Values smaller than 1 make the collector too slow and
2014 may result in the collector never finishing a cycle.
2016 the speed of memory allocation.
2019 <p>
2022 Both get percentage points as arguments
2024 With these functions you can also control
2025 the collector directly (e.g., stop and restart it).
2031 <p>
2032 Using the C API,
2035 Finalizers allow you to coordinate Lua's garbage collection
2036 with external resource management
2037 (such as closing files, network or database connections,
2038 or freeing your own memory).
2041 <p>
2043 collected immediately by the garbage collector.
2044 Instead, Lua puts them in a list.
2045 After the collection,
2046 Lua does the equivalent of the following function
2047 for each userdata in that list:
2049 <pre>
2050 function gc_event (udata)
2051 local h = metatable(udata).__gc
2052 if h then
2053 h(udata)
2054 end
2055 end
2056 </pre>
2058 <p>
2059 At the end of each garbage-collection cycle,
2061 order of their creation,
2062 among those collected in that cycle.
2063 That is, the first finalizer to be called is the one associated
2064 with the userdata created last in the program.
2072 <p>
2075 A weak reference is ignored by the garbage collector.
2076 In other words,
2077 if the only references to an object are weak references,
2078 then the garbage collector will collect this object.
2081 <p>
2082 A weak table can have weak keys, weak values, or both.
2083 A table with weak keys allows the collection of its keys,
2084 but prevents the collection of its values.
2085 A table with both weak keys and weak values allows the collection of
2086 both keys and values.
2087 In any case, if either the key or the value is collected,
2088 the whole pair is removed from the table.
2089 The weakness of a table is controlled by the
2092 the keys in the table are weak.
2094 the values in the table are weak.
2097 <p>
2098 After you use a table as a metatable,
2100 Otherwise, the weak behavior of the tables controlled by this
2101 metatable is undefined.
2111 <p>
2112 Lua supports coroutines,
2114 A coroutine in Lua represents an independent thread of execution.
2115 Unlike threads in multithread systems, however,
2116 a coroutine only suspends its execution by explicitly calling
2117 a yield function.
2120 <p>
2121 You create a coroutine with a call to <a href="#pdf-coroutine.create"><code>coroutine.create</code></a>.
2122 Its sole argument is a function
2123 that is the main function of the coroutine.
2126 it does not start the coroutine execution.
2129 <p>
2131 passing as its first argument
2133 the coroutine starts its execution,
2134 at the first line of its main function.
2135 Extra arguments passed to <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a> are passed on
2136 to the coroutine main function.
2137 After the coroutine starts running,
2141 <p>
2142 A coroutine can terminate its execution in two ways:
2143 normally, when its main function returns
2144 (explicitly or implicitly, after the last instruction);
2145 and abnormally, if there is an unprotected error.
2146 In the first case, <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a> returns <b>true</b>,
2147 plus any values returned by the coroutine main function.
2148 In case of errors, <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a> returns <b>false</b>
2149 plus an error message.
2152 <p>
2154 When a coroutine yields,
2155 the corresponding <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a> returns immediately,
2156 even if the yield happens inside nested function calls
2157 (that is, not in the main function,
2158 but in a function directly or indirectly called by the main function).
2159 In the case of a yield, <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a> also returns <b>true</b>,
2161 The next time you resume the same coroutine,
2162 it continues its execution from the point where it yielded,
2163 with the call to <a href="#pdf-coroutine.yield"><code>coroutine.yield</code></a> returning any extra
2167 <p>
2169 the <a href="#pdf-coroutine.wrap"><code>coroutine.wrap</code></a> function also creates a coroutine,
2170 but instead of returning the coroutine itself,
2171 it returns a function that, when called, resumes the coroutine.
2172 Any arguments passed to this function
2174 <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>,
2175 except the first one (the boolean error code).
2178 any error is propagated to the caller.
2181 <p>
2182 As an example,
2183 consider the following code:
2185 <pre>
2186 function foo (a)
2187 print("foo", a)
2188 return coroutine.yield(2*a)
2189 end
2191 co = coroutine.create(function (a,b)
2192 print("co-body", a, b)
2193 local r = foo(a+1)
2194 print("co-body", r)
2195 local r, s = coroutine.yield(a+b, a-b)
2196 print("co-body", r, s)
2197 return b, "end"
2198 end)
2204 </pre><p>
2205 When you run it, it produces the following output:
2207 <pre>
2208 co-body 1 10
2209 foo 2
2211 main true 4
2212 co-body r
2214 co-body x y
2215 main true 10 end
2216 main false cannot resume dead coroutine
2217 </pre>
2224 <p>
2226 This section describes the C API for Lua, that is,
2227 the set of C functions available to the host program to communicate
2228 with Lua.
2229 All API functions and related types and constants
2233 <p>
2234 Even when we use the term "function",
2235 any facility in the API may be provided as a macro instead.
2236 All such macros use each of their arguments exactly once
2237 (except for the first argument, which is always a Lua state),
2238 and so do not generate any hidden side-effects.
2241 <p>
2242 As in most C libraries,
2243 the Lua API functions do not check their arguments for validity or consistency.
2244 However, you can change this behavior by compiling Lua
2245 with a proper definition for the macro <a name="pdf-luai_apicheck"><code>luai_apicheck</code></a>,
2252 <p>
2254 Each element in this stack represents a Lua value
2258 <p>
2259 Whenever Lua calls C, the called function gets a new stack,
2260 which is independent of previous stacks and of stacks of
2261 C functions that are still active.
2262 This stack initially contains any arguments to the C function
2263 and it is where the C function pushes its results
2267 <p>
2268 For convenience,
2269 most query operations in the API do not follow a strict stack discipline.
2270 Instead, they can refer to any element in the stack
2277 (that is, the element that was pushed onto the stack first)
2278 and
2281 (that is, the element at the top)
2294 <p>
2295 When you interact with Lua API,
2296 you are responsible for ensuring consistency.
2297 In particular,
2300 to grow the stack size.
2303 <p>
2304 Whenever Lua calls C,
2305 it ensures that at least <a name="pdf-LUA_MINSTACK"><code>LUA_MINSTACK</code></a> stack positions are available.
2307 so that usually you do not have to worry about stack space
2308 unless your code has loops pushing elements onto the stack.
2311 <p>
2312 Most query functions accept as indices any value inside the
2313 available stack space, that is, indices up to the maximum stack size
2317 as follows:
2319 <pre>
2322 </pre><p>
2323 Note that 0 is never an acceptable index.
2331 <p>
2332 Unless otherwise noted,
2333 any function that accepts valid indices can also be called with
2335 which represent some Lua values that are accessible to C code
2336 but which are not in the stack.
2337 Pseudo-indices are used to access the thread environment,
2338 the function environment,
2339 the registry,
2343 <p>
2344 The thread environment (where global variables live) is
2346 The environment of the running C function is always
2350 <p>
2351 To access and change the value of global variables,
2352 you can use regular table operations over an environment table.
2353 For instance, to access the value of a global variable, do
2355 <pre>
2356 lua_getfield(L, LUA_GLOBALSINDEX, varname);
2357 </pre>
2364 <p>
2365 When a C function is created,
2366 it is possible to associate some values with it,
2369 accessible to the function whenever it is called
2373 <p>
2374 Whenever a C function is called,
2375 its upvalues are located at specific pseudo-indices.
2376 These pseudo-indices are produced by the macro
2378 The first value associated with a function is at position
2382 current function,
2383 produces an acceptable (but invalid) index.
2391 <p>
2393 a pre-defined table that can be used by any C code to
2394 store whatever Lua value it needs to store.
2395 This table is always located at pseudo-index
2397 Any C library can store data into this table,
2398 but it should take care to choose keys different from those used
2399 by other libraries, to avoid collisions.
2400 Typically, you should use as key a string containing your library name
2401 or a light userdata with the address of a C object in your code.
2404 <p>
2405 The integer keys in the registry are used by the reference mechanism,
2406 implemented by the auxiliary library,
2407 and therefore should not be used for other purposes.
2415 <p>
2417 (You can also choose to use exceptions if you use C++;
2419 When Lua faces any error
2420 (such as memory allocation errors, type errors, syntax errors,
2421 and runtime errors)
2423 that is, it does a long jump.
2425 to set a recover point;
2426 any error jumps to the most recent active recover point.
2429 <p>
2430 Almost any function in the API may raise an error,
2431 for instance due to a memory allocation error.
2432 The following functions run in protected mode
2433 (that is, they create a protected environment to run),
2434 so they never raise an error:
2435 <a href="#lua_newstate"><code>lua_newstate</code></a>, <a href="#lua_close"><code>lua_close</code></a>, <a href="#lua_load"><code>lua_load</code></a>,
2436 <a href="#lua_pcall"><code>lua_pcall</code></a>, and <a href="#lua_cpcall"><code>lua_cpcall</code></a>.
2439 <p>
2440 Inside a C function you can raise an error by calling <a href="#lua_error"><code>lua_error</code></a>.
2448 <p>
2449 Here we list all functions and types from the C API in
2450 alphabetical order.
2455 <pre>typedef void * (*lua_Alloc) (void *ud,
2456 void *ptr,
2457 size_t osize,
2458 size_t nsize);</pre>
2460 <p>
2461 The type of the memory-allocation function used by Lua states.
2462 The allocator function must provide a
2464 but not exactly the same.
2465 Its arguments are
2466 <code>ud</code>, an opaque pointer passed to <a href="#lua_newstate"><code>lua_newstate</code></a>;
2475 if and only if it cannot fill the request.
2480 Lua assumes that the allocator never fails when
2484 <p>
2485 Here is a simple implementation for the allocator function.
2486 It is used in the auxiliary library by <a href="#luaL_newstate"><code>luaL_newstate</code></a>.
2488 <pre>
2489 static void *l_alloc (void *ud, void *ptr, size_t osize,
2490 size_t nsize) {
2491 (void)ud; (void)osize; /* not used */
2492 if (nsize == 0) {
2493 free(ptr);
2494 return NULL;
2495 }
2496 else
2497 return realloc(ptr, nsize);
2498 }
2499 </pre><p>
2500 This code assumes
2503 ANSI C ensures both behaviors.
2512 <p>
2513 Sets a new panic function and returns the old one.
2516 <p>
2517 If an error happens outside any protected environment,
2520 thus exiting the host application.
2521 Your panic function may avoid this exit by
2522 never returning (e.g., doing a long jump).
2525 <p>
2526 The panic function can access the error message at the top of the stack.
2535 <p>
2536 Calls a function.
2539 <p>
2540 To call a function you must use the following protocol:
2541 first, the function to be called is pushed onto the stack;
2542 then, the arguments to the function are pushed
2543 in direct order;
2544 that is, the first argument is pushed first.
2547 All arguments and the function value are popped from the stack
2548 when the function is called.
2549 The function results are pushed onto the stack when the function returns.
2553 Lua takes care that the returned values fit into the stack space.
2554 The function results are pushed onto the stack in direct order
2555 (the first result is pushed first),
2556 so that after the call the last result is on the top of the stack.
2559 <p>
2560 Any error inside the called function is propagated upwards
2564 <p>
2565 The following example shows how the host program may do the
2566 equivalent to this Lua code:
2568 <pre>
2570 </pre><p>
2571 Here it is in C:
2573 <pre>
2574 lua_getfield(L, LUA_GLOBALSINDEX, "f"); /* function to be called */
2576 lua_getfield(L, LUA_GLOBALSINDEX, "t"); /* table to be indexed */
2578 lua_remove(L, -2); /* remove 't' from the stack */
2581 lua_setfield(L, LUA_GLOBALSINDEX, "a"); /* set global 'a' */
2582 </pre><p>
2583 Note that the code above is "balanced":
2584 at its end, the stack is back to its original configuration.
2585 This is considered good programming practice.
2594 <p>
2595 Type for C functions.
2598 <p>
2599 In order to communicate properly with Lua,
2600 a C function must use the following protocol,
2601 which defines the way parameters and results are passed:
2602 a C function receives its arguments from Lua in its stack
2603 in direct order (the first argument is pushed first).
2604 So, when the function starts,
2606 The first argument (if any) is at index 1
2608 To return values to Lua, a C function just pushes them onto the stack,
2609 in direct order (the first result is pushed first),
2610 and returns the number of results.
2611 Any other value in the stack below the results will be properly
2612 discarded by Lua.
2613 Like a Lua function, a C function called by Lua can also return
2614 many results.
2617 <p>
2618 As an example, the following function receives a variable number
2619 of numerical arguments and returns their average and sum:
2621 <pre>
2622 static int foo (lua_State *L) {
2623 int n = lua_gettop(L); /* number of arguments */
2624 lua_Number sum = 0;
2625 int i;
2627 if (!lua_isnumber(L, i)) {
2628 lua_pushstring(L, "incorrect argument");
2629 lua_error(L);
2630 }
2631 sum += lua_tonumber(L, i);
2632 }
2633 lua_pushnumber(L, sum/n); /* first result */
2634 lua_pushnumber(L, sum); /* second result */
2635 return 2; /* number of results */
2636 }
2637 </pre>
2645 <p>
2647 It returns false if it cannot grow the stack to that size.
2648 This function never shrinks the stack;
2649 if the stack is already larger than the new size,
2650 it is left unchanged.
2659 <p>
2660 Destroys all objects in the given Lua state
2661 (calling the corresponding garbage-collection metamethods, if any)
2662 and frees all dynamic memory used by this state.
2663 On several platforms, you may not need to call this function,
2664 because all resources are naturally released when the host program ends.
2665 On the other hand, long-running programs,
2666 such as a daemon or a web server,
2667 might need to release states as soon as they are not needed,
2668 to avoid growing too large.
2677 <p>
2679 pops them, and leaves the result at the top.
2681 (that is, the function does nothing);
2683 Concatenation is done following the usual semantics of Lua
2693 <p>
2697 In case of errors,
2698 <a href="#lua_cpcall"><code>lua_cpcall</code></a> returns the same error codes as <a href="#lua_pcall"><code>lua_pcall</code></a>,
2699 plus the error object on the top of the stack;
2700 otherwise, it returns zero, and does not change the stack.
2710 <p>
2711 Creates a new empty table and pushes it onto the stack.
2712 The new table has space pre-allocated
2714 This pre-allocation is useful when you know exactly how many elements
2715 the table will have.
2725 <p>
2726 Dumps a function as a binary chunk.
2727 Receives a Lua function on the top of the stack
2728 and produces a binary chunk that,
2729 if loaded again,
2730 results in a function equivalent to the one dumped.
2731 As it produces parts of the chunk,
2732 <a href="#lua_dump"><code>lua_dump</code></a> calls function <code>writer</code> (see <a href="#lua_Writer"><code>lua_Writer</code></a>)
2734 to write them.
2737 <p>
2738 The value returned is the error code returned by the last
2739 call to the writer;
2743 <p>
2744 This function does not pop the Lua function from the stack.
2753 <p>
2757 (that is, may call metamethods).
2768 <p>
2769 Generates a Lua error.
2770 The error message (which can actually be a Lua value of any type)
2771 must be on the stack top.
2772 This function does a long jump,
2773 and therefore never returns.
2783 <p>
2784 Controls the garbage collector.
2787 <p>
2788 This function performs several tasks,
2791 <ul>
2794 stops the garbage collector.
2795 </li>
2798 restarts the garbage collector.
2799 </li>
2802 performs a full garbage-collection cycle.
2803 </li>
2806 returns the current amount of memory (in Kbytes) in use by Lua.
2807 </li>
2810 returns the remainder of dividing the current amount of bytes of
2811 memory in use by Lua by 1024.
2812 </li>
2815 performs an incremental step of garbage collection.
2817 (larger values mean more steps) in a non-specified way.
2818 If you want to control the step size
2820 The function returns 1 if the step finished a
2821 garbage-collection cycle.
2822 </li>
2827 The function returns the previous value of the pause.
2828 </li>
2833 The function returns the previous value of the step multiplier.
2834 </li>
2836 </ul>
2844 <p>
2845 Returns the memory-allocation function of a given state.
2856 <p>
2857 Pushes onto the stack the environment table of
2858 the value at the given index.
2867 <p>
2870 As in Lua, this function may trigger a metamethod
2880 <p>
2882 It is defined as a macro:
2884 <pre>
2885 #define lua_getglobal(L,s) lua_getfield(L, LUA_GLOBALSINDEX, s)
2886 </pre>
2894 <p>
2895 Pushes onto the stack the metatable of the value at the given
2896 acceptable index.
2897 If the index is not valid,
2898 or if the value does not have a metatable,
2908 <p>
2914 <p>
2915 This function pops the key from the stack
2916 (putting the resulting value in its place).
2917 As in Lua, this function may trigger a metamethod
2927 <p>
2928 Returns the index of the top element in the stack.
2930 this result is equal to the number of elements in the stack
2940 <p>
2941 Moves the top element into the given valid index,
2942 shifting up the elements above this index to open space.
2943 Cannot be called with a pseudo-index,
2944 because a pseudo-index is not an actual stack position.
2953 <p>
2954 The type used by the Lua API to represent integral values.
2957 <p>
2959 which is usually the largest signed integral type the machine handles
2960 "comfortably".
2969 <p>
2970 Returns 1 if the value at the given acceptable index has type boolean,
2980 <p>
2991 <p>
2992 Returns 1 if the value at the given acceptable index is a function
3002 <p>
3003 Returns 1 if the value at the given acceptable index is a light userdata,
3013 <p>
3024 <p>
3025 Returns 1 if the the given acceptable index is not valid
3026 (that is, it refers to an element outside the current stack),
3036 <p>
3037 Returns 1 if the the given acceptable index is not valid
3038 (that is, it refers to an element outside the current stack)
3049 <p>
3050 Returns 1 if the value at the given acceptable index is a number
3051 or a string convertible to a number,
3061 <p>
3062 Returns 1 if the value at the given acceptable index is a string
3063 or a number (which is always convertible to a string),
3073 <p>
3074 Returns 1 if the value at the given acceptable index is a table,
3084 <p>
3085 Returns 1 if the value at the given acceptable index is a thread,
3095 <p>
3096 Returns 1 if the value at the given acceptable index is a userdata
3106 <p>
3110 (that is, may call metamethods).
3119 <pre>int lua_load (lua_State *L,
3120 lua_Reader reader,
3121 void *data,
3122 const char *chunkname);</pre>
3124 <p>
3125 Loads a Lua chunk.
3126 If there are no errors,
3128 function on top of the stack.
3129 Otherwise, it pushes an error message.
3132 <ul>
3137 syntax error during pre-compilation;</li>
3140 memory allocation error.</li>
3142 </ul>
3144 <p>
3145 This function only loads a chunk;
3146 it does not run it.
3149 <p>
3150 <a href="#lua_load"><code>lua_load</code></a> automatically detects whether the chunk is text or binary,
3154 <p>
3155 The <a href="#lua_load"><code>lua_load</code></a> function uses a user-supplied <code>reader</code> function
3160 <p>
3171 <p>
3172 Creates a new, independent state.
3174 (due to lack of memory).
3176 Lua does all memory allocation for this state through this function.
3178 simply passes to the allocator in every call.
3187 <p>
3188 Creates a new empty table and pushes it onto the stack.
3198 <p>
3199 Creates a new thread, pushes it on the stack,
3200 and returns a pointer to a <a href="#lua_State"><code>lua_State</code></a> that represents this new thread.
3201 The new state returned by this function shares with the original state
3202 all global objects (such as tables),
3203 but has an independent execution stack.
3206 <p>
3207 There is no explicit function to close or to destroy a thread.
3208 Threads are subject to garbage collection,
3209 like any Lua object.
3218 <p>
3219 This function allocates a new block of memory with the given size,
3220 pushes onto the stack a new full userdata with the block address,
3221 and returns this address.
3224 <p>
3225 Userdata represent C values in Lua.
3227 It is an object (like a table):
3228 you must create it, it can have its own metatable,
3229 and you can detect when it is being collected.
3230 A full userdata is only equal to itself (under raw equality).
3233 <p>
3235 Lua calls the metamethod and marks the userdata as finalized.
3236 When this userdata is collected again then
3237 Lua frees its corresponding memory.
3246 <p>
3247 Pops a key from the stack,
3248 and pushes a key-value pair from the table at the given index
3249 (the "next" pair after the given key).
3250 If there are no more elements in the table,
3254 <p>
3255 A typical traversal looks like this:
3257 <pre>
3258 /* table is in the stack at index 't' */
3259 lua_pushnil(L); /* first key */
3260 while (lua_next(L, t) != 0) {
3262 printf("%s - %s\n",
3263 lua_typename(L, lua_type(L, -2)),
3264 lua_typename(L, lua_type(L, -1)));
3265 /* removes 'value'; keeps 'key' for next iteration */
3266 lua_pop(L, 1);
3267 }
3268 </pre>
3270 <p>
3271 While traversing a table,
3273 unless you know that the key is actually a string.
3275 the value at the given index;
3285 <p>
3286 The type of numbers in Lua.
3290 <p>
3291 Through the configuration file you can change
3292 Lua to operate with another type for numbers (e.g., float or long).
3301 <p>
3302 Returns the "length" of the value at the given acceptable index:
3303 for strings, this is the string length;
3305 for userdata, this is the size of the block of memory allocated
3306 for the userdata;
3316 <p>
3317 Calls a function in protected mode.
3320 <p>
3323 If there are no errors during the call,
3324 <a href="#lua_pcall"><code>lua_pcall</code></a> behaves exactly like <a href="#lua_call"><code>lua_call</code></a>.
3325 However, if there is any error,
3327 pushes a single value on the stack (the error message),
3328 and returns an error code.
3331 and its arguments from the stack.
3334 <p>
3336 then the error message returned on the stack
3337 is exactly the original error message.
3340 (In the current implementation, this index cannot be a pseudo-index.)
3341 In case of runtime errors,
3342 this function will be called with the error message
3343 and its return value will be the message returned on the stack by <a href="#lua_pcall"><code>lua_pcall</code></a>.
3346 <p>
3347 Typically, the error handler function is used to add more debug
3348 information to the error message, such as a stack traceback.
3349 Such information cannot be gathered after the return of <a href="#lua_pcall"><code>lua_pcall</code></a>,
3350 since by then the stack has unwound.
3353 <p>
3355 or one of the following error codes
3358 <ul>
3361 a runtime error.
3362 </li>
3365 memory allocation error.
3366 For such errors, Lua does not call the error handler function.
3367 </li>
3370 error while running the error handler function.
3371 </li>
3373 </ul>
3381 <p>
3391 <p>
3401 <p>
3402 Pushes a new C closure onto the stack.
3405 <p>
3406 When a C function is created,
3407 it is possible to associate some values with it,
3409 these values are then accessible to the function whenever it is called.
3410 To associate values with a C function,
3411 first these values should be pushed onto the stack
3412 (when there are multiple values, the first value is pushed first).
3414 is called to create and push the C function onto the stack,
3416 associated with the function.
3417 <a href="#lua_pushcclosure"><code>lua_pushcclosure</code></a> also pops these values from the stack.
3426 <p>
3427 Pushes a C function onto the stack.
3428 This function receives a pointer to a C function
3430 when called, invokes the corresponding C function.
3433 <p>
3434 Any function to be registered in Lua must
3435 follow the correct protocol to receive its parameters
3439 <p>
3442 <pre>
3443 #define lua_pushcfunction(L,f) lua_pushcclosure(L,f,0)
3444 </pre>
3452 <p>
3453 Pushes onto the stack a formatted string
3454 and returns a pointer to this string.
3456 but has some important differences:
3458 <ul>
3460 <li>
3461 You do not have to allocate space for the result:
3462 the result is a Lua string and Lua takes care of memory allocation
3463 (and deallocation, through garbage collection).
3464 </li>
3466 <li>
3467 The conversion specifiers are quite restricted.
3468 There are no flags, widths, or precisions.
3469 The conversion specifiers can only be
3476 </li>
3478 </ul>
3486 <p>
3496 <p>
3497 Pushes a light userdata onto the stack.
3500 <p>
3501 Userdata represent C values in Lua.
3503 It is a value (like a number):
3504 you do not create it, it has no individual metatable,
3505 and it is not collected (as it was never created).
3506 A light userdata is equal to "any"
3507 light userdata with the same C address.
3516 <p>
3518 onto the stack.
3519 Lua makes (or reuses) an internal copy of the given string,
3521 the function returns.
3522 The string can contain embedded zeros.
3531 <p>
3532 Pushes a nil value onto the stack.
3541 <p>
3551 <p>
3553 onto the stack.
3554 Lua makes (or reuses) an internal copy of the given string,
3556 the function returns.
3557 The string cannot contain embedded zeros;
3558 it is assumed to end at the first zero.
3567 <p>
3569 Returns 1 if this thread is the main thread of its state.
3578 <p>
3579 Pushes a copy of the element at the given valid index
3580 onto the stack.
3587 <pre>const char *lua_pushvfstring (lua_State *L,
3588 const char *fmt,
3589 va_list argp);</pre>
3591 <p>
3592 Equivalent to <a href="#lua_pushfstring"><code>lua_pushfstring</code></a>, except that it receives a <code>va_list</code>
3593 instead of a variable number of arguments.
3602 <p>
3605 (that is, without calling metamethods).
3616 <p>
3618 (i.e., without metamethods).
3627 <p>
3630 The access is raw;
3631 that is, it does not invoke metamethods.
3640 <p>
3642 (i.e., without metamethods).
3651 <p>
3657 <p>
3658 This function pops the value from the stack.
3659 The assignment is raw;
3660 that is, it does not invoke metamethods.
3667 <pre>typedef const char * (*lua_Reader) (lua_State *L,
3668 void *data,
3669 size_t *size);</pre>
3671 <p>
3673 Every time it needs another piece of the chunk,
3676 The reader must return a pointer to a block of memory
3677 with a new piece of the chunk
3679 The block must exist until the reader function is called again.
3681 The reader function may return pieces of any size greater than zero.
3688 <pre>void lua_register (lua_State *L,
3689 const char *name,
3690 lua_CFunction f);</pre>
3692 <p>
3694 It is defined as a macro:
3696 <pre>
3697 #define lua_register(L,n,f) \
3698 (lua_pushcfunction(L, f), lua_setglobal(L, n))
3699 </pre>
3707 <p>
3708 Removes the element at the given valid index,
3709 shifting down the elements above this index to fill the gap.
3710 Cannot be called with a pseudo-index,
3711 because a pseudo-index is not an actual stack position.
3720 <p>
3721 Moves the top element into the given position (and pops it),
3722 without shifting any element
3723 (therefore replacing the value at the given position).
3732 <p>
3733 Starts and resumes a coroutine in a given thread.
3736 <p>
3737 To start a coroutine, you first create a new thread
3739 then you push onto its stack the main function plus any arguments;
3742 This call returns when the coroutine suspends or finishes its execution.
3743 When it returns, the stack contains all values passed to <a href="#lua_yield"><code>lua_yield</code></a>,
3744 or all values returned by the body function.
3747 0 if the coroutine finishes its execution
3748 without errors,
3750 In case of errors,
3751 the stack is not unwound,
3752 so you can use the debug API over it.
3753 The error message is on the top of the stack.
3754 To restart a coroutine, you put on its stack only the values to
3765 <p>
3776 <p>
3777 Pops a table from the stack and sets it as
3778 the new environment for the value at the given index.
3779 If the value at the given index is
3780 neither a function nor a thread nor a userdata,
3782 Otherwise it returns 1.
3791 <p>
3797 <p>
3798 This function pops the value from the stack.
3799 As in Lua, this function may trigger a metamethod
3809 <p>
3810 Pops a value from the stack and
3812 It is defined as a macro:
3814 <pre>
3815 #define lua_setglobal(L,s) lua_setfield(L, LUA_GLOBALSINDEX, s)
3816 </pre>
3824 <p>
3825 Pops a table from the stack and
3826 sets it as the new metatable for the value at the given
3827 acceptable index.
3836 <p>
3843 <p>
3844 This function pops both the key and the value from the stack.
3845 As in Lua, this function may trigger a metamethod
3855 <p>
3857 and sets the stack top to this index.
3858 If the new top is larger than the old one,
3869 <p>
3870 Opaque structure that keeps the whole state of a Lua interpreter.
3871 The Lua library is fully reentrant:
3872 it has no global variables.
3873 All information about a state is kept in this structure.
3876 <p>
3877 A pointer to this state must be passed as the first argument to
3878 every function in the library, except to <a href="#lua_newstate"><code>lua_newstate</code></a>,
3879 which creates a Lua state from scratch.
3888 <p>
3892 <p>
3893 The status can be 0 for a normal thread,
3894 an error code if the thread finished its execution with an error,
3904 <p>
3905 Converts the Lua value at the given acceptable index to a C boolean
3907 Like all tests in Lua,
3910 otherwise it returns 0.
3911 It also returns 0 when called with a non-valid index.
3912 (If you want to accept only actual boolean values,
3922 <p>
3923 Converts a value at the given acceptable index to a C function.
3924 That value must be a C function;
3934 <p>
3935 Converts the Lua value at the given acceptable index
3937 The Lua value must be a number or a string convertible to a number
3942 <p>
3943 If the number is not an integer,
3944 it is truncated in some non-specified way.
3953 <p>
3954 Converts the Lua value at the given acceptable index to a C string.
3957 The Lua value must be a string or a number;
3959 If the value is a number,
3963 when <a href="#lua_tolstring"><code>lua_tolstring</code></a> is applied to keys during a table traversal.)
3966 <p>
3968 to a string inside the Lua state.
3970 after its last character (as in C),
3971 but may contain other zeros in its body.
3972 Because Lua has garbage collection,
3973 there is no guarantee that the pointer returned by <a href="#lua_tolstring"><code>lua_tolstring</code></a>
3974 will be valid after the corresponding value is removed from the stack.
3983 <p>
3984 Converts the Lua value at the given acceptable index
3985 to the C type <a href="#lua_Number"><code>lua_Number</code></a> (see <a href="#lua_Number"><code>lua_Number</code></a>).
3986 The Lua value must be a number or a string convertible to a number
3997 <p>
3998 Converts the value at the given acceptable index to a generic
4000 The value may be a userdata, a table, a thread, or a function;
4002 Different objects will give different pointers.
4003 There is no way to convert the pointer back to its original value.
4006 <p>
4007 Typically this function is used only for debug information.
4016 <p>
4017 Equivalent to <a href="#lua_tolstring"><code>lua_tolstring</code></a> with <code>len</code> equal to <code>NULL</code>.
4026 <p>
4027 Converts the value at the given acceptable index to a Lua thread
4029 This value must be a thread;
4039 <p>
4040 If the value at the given acceptable index is a full userdata,
4041 returns its block address.
4042 If the value is a light userdata,
4043 returns its pointer.
4053 <p>
4054 Returns the type of the value in the given acceptable index,
4056 (that is, an index to an "empty" stack position).
4057 The types returned by <a href="#lua_type"><code>lua_type</code></a> are coded by the following constants
4067 and
4077 <p>
4086 <pre>typedef int (*lua_Writer) (lua_State *L,
4087 const void* p,
4088 size_t sz,
4089 void* ud);</pre>
4091 <p>
4093 Every time it produces another piece of chunk,
4100 <p>
4101 The writer returns an error code:
4104 calling the writer again.
4113 <p>
4117 <p>
4128 <p>
4129 Yields a coroutine.
4132 <p>
4133 This function should only be called as the
4134 return expression of a C function, as follows:
4136 <pre>
4137 return lua_yield (L, nresults);
4138 </pre><p>
4140 the running coroutine suspends its execution,
4141 and the call to <a href="#lua_resume"><code>lua_resume</code></a> that started this coroutine returns.
4153 <p>
4154 Lua has no built-in debugging facilities.
4155 Instead, it offers a special interface
4157 This interface allows the construction of different
4158 kinds of debuggers, profilers, and other tools
4159 that need "inside information" from the interpreter.
4164 <pre>typedef struct lua_Debug {
4165 int event;
4166 const char *name; /* (n) */
4167 const char *namewhat; /* (n) */
4168 const char *what; /* (S) */
4169 const char *source; /* (S) */
4170 int currentline; /* (l) */
4171 int nups; /* (u) number of upvalues */
4172 int linedefined; /* (S) */
4173 int lastlinedefined; /* (S) */
4174 char short_src[LUA_IDSIZE]; /* (S) */
4175 /* private part */
4177 } lua_Debug;</pre>
4179 <p>
4180 A structure used to carry different pieces of
4181 information about an active function.
4183 of this structure, for later use.
4184 To fill the other fields of <a href="#lua_Debug"><code>lua_Debug</code></a> with useful information,
4188 <p>
4191 <ul>
4194 If the function was defined in a string,
4196 If the function was defined in a file,
4198 </li>
4202 </li>
4205 the line number where the definition of the function starts.
4206 </li>
4209 the line number where the definition of the function ends.
4210 </li>
4217 In the latter case,
4218 Lua has no other information about the function.
4219 </li>
4222 the current line where the given function is executing.
4223 When no line information is available,
4225 </li>
4228 a reasonable name for the given function.
4229 Because functions in Lua are first-class values,
4230 they do not have a fixed name:
4231 some functions may be the value of multiple global variables,
4232 while others may be stored only in a table field.
4234 called to find a suitable name.
4235 If it cannot find a name,
4237 </li>
4244 according to how the function was called.
4245 (Lua uses the empty string when no other option seems to apply.)
4246 </li>
4249 the number of upvalues of the function.
4250 </li>
4252 </ul>
4260 <p>
4261 Returns the current hook function.
4270 <p>
4271 Returns the current hook count.
4280 <p>
4281 Returns the current hook mask.
4290 <p>
4291 Returns information about a specific function or function invocation.
4294 <p>
4295 To get information about a function invocation,
4301 <p>
4302 To get information about a function you push it onto the stack
4304 (In that case,
4307 you can write the following code:
4309 <pre>
4310 lua_Debug ar;
4311 lua_getfield(L, LUA_GLOBALSINDEX, "f"); /* get global 'f' */
4313 printf("%d\n", ar.linedefined);
4314 </pre>
4316 <p>
4319 a value to be pushed on the stack:
4321 <ul>
4324 </li>
4329 </li>
4332 </li>
4335 </li>
4338 pushes onto the stack the function that is
4339 running at the given level;
4340 </li>
4343 pushes onto the stack a table whose indices are the
4344 numbers of the lines that are valid on the function.
4346 that is, a line where you can put a break point.
4347 Non-valid lines include empty lines and comments.)
4348 </li>
4350 </ul>
4352 <p>
4353 This function returns 0 on error
4363 <p>
4364 Gets information about a local variable of a given activation record.
4369 (1 is the first parameter or active local variable, and so on,
4370 until the last active local variable).
4371 <a href="#lua_getlocal"><code>lua_getlocal</code></a> pushes the variable's value onto the stack
4372 and returns its name.
4375 <p>
4377 represent internal variables
4378 (loop control variables, temporaries, and C function locals).
4381 <p>
4383 when the index is greater than
4384 the number of active local variables.
4393 <p>
4394 Get information about the interpreter runtime stack.
4397 <p>
4400 of the function executing at a given level.
4404 when called with a level greater than the stack depth,
4405 it returns 0.
4414 <p>
4415 Gets information about a closure's upvalue.
4416 (For Lua functions,
4417 upvalues are the external local variables that the function uses,
4418 and that are consequently included in its closure.)
4419 <a href="#lua_getupvalue"><code>lua_getupvalue</code></a> gets the index <code>n</code> of an upvalue,
4420 pushes the upvalue's value onto the stack,
4421 and returns its name.
4423 (Upvalues have no particular order,
4424 as they are active through the whole function.
4425 So, they are numbered in an arbitrary order.)
4428 <p>
4430 when the index is greater than the number of upvalues.
4432 as a name for all upvalues.
4441 <p>
4442 Type for debugging hook functions.
4445 <p>
4448 Lua identifies these events with the following constants:
4449 <a name="pdf-LUA_HOOKCALL"><code>LUA_HOOKCALL</code></a>, <a name="pdf-LUA_HOOKRET"><code>LUA_HOOKRET</code></a>,
4450 <a name="pdf-LUA_HOOKTAILRET"><code>LUA_HOOKTAILRET</code></a>, <a name="pdf-LUA_HOOKLINE"><code>LUA_HOOKLINE</code></a>,
4457 In the latter case, Lua is simulating a return from
4458 a function that did a tail call;
4462 <p>
4463 While Lua is running a hook, it disables other calls to hooks.
4464 Therefore, if a hook calls back Lua to execute a function or a chunk,
4465 this execution occurs without any calls to hooks.
4474 <p>
4475 Sets the debugging hook function.
4478 <p>
4481 it is formed by a bitwise or of the constants
4488 For each event, the hook is called as explained below:
4490 <ul>
4493 The hook is called just after Lua enters the new function,
4494 before the function gets its arguments.
4495 </li>
4498 The hook is called just before Lua leaves the function.
4499 You have no access to the values to be returned by the function.
4500 </li>
4503 start the execution of a new line of code,
4504 or when it jumps back in the code (even to the same line).
4505 (This event only happens while Lua is executing a Lua function.)
4506 </li>
4510 (This event only happens while Lua is executing a Lua function.)
4511 </li>
4513 </ul>
4515 <p>
4525 <p>
4526 Sets the value of a local variable of a given activation record.
4527 Parameters <code>ar</code> and <code>n</code> are as in <a href="#lua_getlocal"><code>lua_getlocal</code></a>
4529 <a href="#lua_setlocal"><code>lua_setlocal</code></a> assigns the value at the top of the stack
4530 to the variable and returns its name.
4531 It also pops the value from the stack.
4534 <p>
4536 when the index is greater than
4537 the number of active local variables.
4546 <p>
4547 Sets the value of a closure's upvalue.
4548 It assigns the value at the top of the stack
4549 to the upvalue and returns its name.
4550 It also pops the value from the stack.
4551 Parameters <code>funcindex</code> and <code>n</code> are as in the <a href="#lua_getupvalue"><code>lua_getupvalue</code></a>
4555 <p>
4557 when the index is greater than the number of upvalues.
4567 <p>
4570 to interface C with Lua.
4571 While the basic API provides the primitive functions for all
4572 interactions between C and Lua,
4573 the auxiliary library provides higher-level functions for some
4574 common tasks.
4577 <p>
4578 All functions from the auxiliary library
4583 <p>
4584 All functions in the auxiliary library are built on
4585 top of the basic API,
4586 and so they provide nothing that cannot be done with this API.
4589 <p>
4590 Several functions in the auxiliary library are used to
4591 check C function arguments.
4593 All of these functions raise an error if the check is not satisfied.
4594 Because the error message is formatted for arguments
4595 (e.g., "<code>bad argument #1</code>"),
4596 you should not use these functions for other stack values.
4602 <p>
4603 Here we list all functions and types from the auxiliary library
4604 in alphabetical order.
4611 <p>
4622 <p>
4626 The string may contain embedded zeros.
4635 <p>
4647 <p>
4651 The string may not contain embedded zeros.
4660 <p>
4661 Adds the value at the top of the stack
4664 Pops the value.
4667 <p>
4668 This is the only function on string buffers that can (and must)
4669 be called with an extra element on the stack,
4670 which is the value to be added to the buffer.
4677 <pre>void luaL_argcheck (lua_State *L,
4678 int cond,
4679 int narg,
4680 const char *extramsg);</pre>
4682 <p>
4684 If not, raises an error with the following message,
4687 <pre>
4689 </pre>
4697 <p>
4698 Raises an error with the following message,
4701 <pre>
4703 </pre>
4705 <p>
4706 This function never returns,
4707 but it is an idiom to use it in C functions
4717 <p>
4721 <p>
4722 A string buffer allows C code to build Lua strings piecemeal.
4723 Its pattern of use is as follows:
4725 <ul>
4727 <li>First you declare a variable <code>b</code> of type <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>.</li>
4731 <li>
4732 Then you add string pieces to the buffer calling any of
4734 </li>
4736 <li>
4738 This call leaves the final string on the top of the stack.
4739 </li>
4741 </ul>
4743 <p>
4744 During its normal operation,
4745 a string buffer uses a variable number of stack slots.
4746 So, while using a buffer, you cannot assume that you know where
4747 the top of the stack is.
4748 You can use the stack between successive calls to buffer operations
4749 as long as that use is balanced;
4750 that is,
4751 when you call a buffer operation,
4752 the stack is at the same level
4753 it was immediately after the previous buffer operation.
4755 After calling <a href="#luaL_pushresult"><code>luaL_pushresult</code></a> the stack is back to its
4756 level when the buffer was initialized,
4757 plus the final string on its top.
4766 <p>
4768 This function does not allocate any space;
4769 the buffer must be declared as a variable
4779 <p>
4780 Calls a metamethod.
4783 <p>
4786 this function calls this field and passes the object as its only argument.
4787 In this case this function returns 1 and pushes onto the
4788 stack the value returned by the call.
4789 If there is no metatable or no metamethod,
4790 this function returns 0 (without pushing any value on the stack).
4799 <p>
4800 Checks whether the function has an argument
4810 <p>
4821 <p>
4832 <p>
4843 <p>
4845 and returns this string;
4847 with the string's length.
4856 <p>
4858 and returns this number.
4865 <pre>int luaL_checkoption (lua_State *L,
4866 int narg,
4867 const char *def,
4868 const char *const lst[]);</pre>
4870 <p>
4873 (which must be NULL-terminated).
4874 Returns the index in the array where the string was found.
4875 Raises an error if the argument is not a string or
4876 if the string cannot be found.
4879 <p>
4885 <p>
4886 This is a useful function for mapping strings to C enums.
4887 (The usual convention in Lua libraries is
4888 to use strings instead of numbers to select options.)
4897 <p>
4899 raising an error if the stack cannot grow to that size.
4909 <p>
4911 and returns this string.
4920 <p>
4930 <p>
4932 of the type <code>tname</code> (see <a href="#luaL_newmetatable"><code>luaL_newmetatable</code></a>).
4941 <p>
4942 Loads and runs the given file.
4943 It is defined as the following macro:
4945 <pre>
4947 </pre><p>
4948 It returns 0 if there are no errors
4949 or 1 in case of errors.
4958 <p>
4959 Loads and runs the given string.
4960 It is defined as the following macro:
4962 <pre>
4964 </pre><p>
4965 It returns 0 if there are no errors
4966 or 1 in case of errors.
4975 <p>
4976 Raises an error.
4978 plus any extra arguments,
4980 It also adds at the beginning of the message the file name and
4981 the line number where the error occurred,
4982 if this information is available.
4985 <p>
4986 This function never returns,
4987 but it is an idiom to use it in C functions
4997 <p>
5000 If the object does not have a metatable,
5001 or if the metatable does not have this field,
5002 returns 0 and pushes nothing.
5011 <p>
5020 <pre>const char *luaL_gsub (lua_State *L,
5021 const char *s,
5022 const char *p,
5023 const char *r);</pre>
5025 <p>
5029 Pushes the resulting string on the stack and returns it.
5036 <pre>int luaL_loadbuffer (lua_State *L,
5037 const char *buff,
5038 size_t sz,
5039 const char *name);</pre>
5041 <p>
5042 Loads a buffer as a Lua chunk.
5047 <p>
5050 used for debug information and error messages.
5059 <p>
5060 Loads a file as a Lua chunk.
5064 then it loads from the standard input.
5068 <p>
5071 if it cannot open/read the file.
5074 <p>
5076 it does not run it.
5085 <p>
5086 Loads a string as a Lua chunk.
5091 <p>
5095 <p>
5097 it does not run it.
5106 <p>
5108 returns 0.
5109 Otherwise,
5110 creates a new table to be used as a metatable for userdata,
5112 and returns 1.
5115 <p>
5116 In both cases pushes onto the stack the final value associated
5126 <p>
5127 Creates a new Lua state.
5130 and then sets a panic function (see <a href="#lua_atpanic"><code>lua_atpanic</code></a>) that prints
5131 an error message to the standard error output in case of fatal
5132 errors.
5135 <p>
5136 Returns the new state,
5146 <p>
5147 Opens all standard Lua libraries into the given state.
5156 <p>
5161 Otherwise, raises an error.
5168 <pre>lua_Integer luaL_optinteger (lua_State *L,
5169 int narg,
5170 lua_Integer d);</pre>
5172 <p>
5177 Otherwise, raises an error.
5186 <p>
5191 Otherwise, raises an error.
5198 <pre>const char *luaL_optlstring (lua_State *L,
5199 int narg,
5200 const char *d,
5201 size_t *l);</pre>
5203 <p>
5205 returns this string.
5208 Otherwise, raises an error.
5211 <p>
5222 <p>
5224 returns this number.
5227 Otherwise, raises an error.
5234 <pre>const char *luaL_optstring (lua_State *L,
5235 int narg,
5236 const char *d);</pre>
5238 <p>
5240 returns this string.
5243 Otherwise, raises an error.
5252 <p>
5253 Returns an address to a space of size <a name="pdf-LUAL_BUFFERSIZE"><code>LUAL_BUFFERSIZE</code></a>
5256 After copying the string into this space you must call
5257 <a href="#luaL_addsize"><code>luaL_addsize</code></a> with the size of the string to actually add
5258 it to the buffer.
5267 <p>
5269 the top of the stack.
5278 <p>
5281 for the object at the top of the stack (and pops the object).
5284 <p>
5285 A reference is a unique integer key.
5290 Function <a href="#luaL_unref"><code>luaL_unref</code></a> frees a reference and its associated object.
5293 <p>
5295 <a href="#luaL_ref"><code>luaL_ref</code></a> returns the constant <a name="pdf-LUA_REFNIL"><code>LUA_REFNIL</code></a>.
5304 <pre>typedef struct luaL_Reg {
5305 const char *name;
5306 lua_CFunction func;
5307 } luaL_Reg;</pre>
5309 <p>
5310 Type for arrays of functions to be registered by
5313 the function.
5322 <pre>void luaL_register (lua_State *L,
5323 const char *libname,
5324 const luaL_Reg *l);</pre>
5326 <p>
5327 Opens a library.
5330 <p>
5336 <p>
5344 reuses this table instead of creating a new one.
5347 <p>
5348 In any case the function leaves the table
5349 on the top of the stack.
5358 <p>
5368 <p>
5369 Generates an error with a message like the following:
5371 <pre>
5372 <em>location</em>: bad argument <em>narg</em> to '<em>func</em>' (<em>tname</em> expected, got <em>rt</em>)
5373 </pre><p>
5374 where <code><em>location</em></code> is produced by <a href="#luaL_where"><code>luaL_where</code></a>,
5385 <p>
5388 The entry is removed from the table,
5389 so that the referred object can be collected.
5393 <p>
5394 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>,
5404 <p>
5405 Pushes onto the stack a string identifying the current position
5407 Typically this string has the following format:
5409 <pre>
5411 </pre><p>
5414 etc.
5417 <p>
5418 This function is used to build a prefix for error messages.
5428 <p>
5429 The standard Lua libraries provide useful functions
5430 that are implemented directly through the C API.
5431 Some of these functions provide essential services to the language
5432 (e.g., <a href="#pdf-type"><code>type</code></a> and <a href="#pdf-getmetatable"><code>getmetatable</code></a>);
5433 others provide access to "outside" services (e.g., I/O);
5434 and others could be implemented in Lua itself,
5435 but are quite useful or have critical performance requirements that
5439 <p>
5440 All libraries are implemented through the official C API
5441 and are provided as separate C modules.
5442 Currently, Lua has the following standard libraries:
5444 <ul>
5462 </ul><p>
5463 Except for the basic and package libraries,
5464 each library provides all its functions as fields of a global table
5465 or as methods of its objects.
5468 <p>
5469 To have access to these libraries,
5470 the C host program should call the <a href="#luaL_openlibs"><code>luaL_openlibs</code></a> function,
5471 which opens all standard libraries.
5472 Alternatively,
5473 it can open them individually by calling
5479 <a name="pdf-luaopen_io"><code>luaopen_io</code></a> (for the I/O and the Operating System libraries),
5482 and should not be called directly:
5483 you must call them like any other Lua C function,
5490 <p>
5491 The basic library provides some core functions to Lua.
5492 If you do not include this library in your application,
5493 you should check carefully whether you need to provide
5494 implementations for some of its facilities.
5497 <p>
5499 Issues an error when
5501 otherwise, returns all its arguments.
5503 when absent, it defaults to "assertion failed!"
5508 <p>
5512 <p>
5513 This function is a generic interface to the garbage collector.
5516 <ul>
5519 stops the garbage collector.
5520 </li>
5523 restarts the garbage collector.
5524 </li>
5527 performs a full garbage-collection cycle.
5528 </li>
5531 returns the total memory in use by Lua (in Kbytes).
5532 </li>
5535 performs a garbage-collection step.
5537 (larger values mean more steps) in a non-specified way.
5538 If you want to control the step size
5541 </li>
5546 </li>
5551 </li>
5553 </ul>
5557 <p>
5559 Opens the named file and executes its contents as a Lua chunk.
5560 When called without arguments,
5562 Returns all values returned by the chunk.
5569 <p>
5571 Terminates the last protected function called
5576 <p>
5578 at the beginning of the message.
5585 to the message.
5590 <p>
5592 A global variable (not a function) that
5594 Lua itself does not use this variable;
5595 changing its value does not affect any environment,
5596 nor vice-versa.
5602 <p>
5604 Returns the current environment in use by the function.
5606 that specifies the function at that stack level:
5608 If the given function is not a Lua function,
5616 <p>
5620 <p>
5622 Otherwise,
5624 returns the associated value.
5625 Otherwise, returns the metatable of the given object.
5630 <p>
5634 <p>
5636 so that the construction
5638 <pre>
5640 </pre><p>
5641 will iterate over the pairs (<code>1,t[1]</code>), (<code>2,t[2]</code>), ···,
5642 up to the first integer key absent from the table.
5647 <p>
5651 <p>
5654 with previous results.
5658 <p>
5659 If there are no errors,
5660 returns the compiled chunk as a function;
5662 The environment of the returned function is the global environment.
5665 <p>
5667 and debug information.
5672 <p>
5676 <p>
5679 or from the standard input,
5680 if no file name is given.
5685 <p>
5689 <p>
5691 but gets the chunk from the given string.
5694 <p>
5695 To load and run a given string, use the idiom
5697 <pre>
5698 assert(loadstring(s))()
5699 </pre>
5703 <p>
5707 <p>
5708 Allows a program to traverse all fields of a table.
5709 Its first argument is a table and its second argument
5710 is an index in this table.
5712 and its associated value.
5715 and its associated value.
5716 When called with the last index,
5720 In particular,
5724 <p>
5725 The order in which the indices are enumerated is not specified,
5727 (To traverse a table in numeric order,
5731 <p>
5733 during the traversal,
5734 you assign any value to a non-existent field in the table.
5735 You may however modify existing fields.
5736 In particular, you may clear existing fields.
5741 <p>
5745 <p>
5746 Returns three values: the <a href="#pdf-next"><code>next</code></a> function, the table <code>t</code>, and <b>nil</b>,
5747 so that the construction
5749 <pre>
5751 </pre><p>
5755 <p>
5757 the table during its traversal.
5762 <p>
5766 <p>
5771 and returns a status code.
5772 Its first result is the status code (a boolean),
5773 which is true if the call succeeds without errors.
5775 after this first result.
5781 <p>
5783 Receives any number of arguments,
5785 using the <a href="#pdf-tostring"><code>tostring</code></a> function to convert them to strings.
5787 but only as a quick way to show a value,
5788 typically for debugging.
5794 <p>
5797 without invoking any metamethod.
5798 Returns a boolean.
5803 <p>
5806 without invoking any metamethod.
5813 <p>
5816 without invoking any metamethod.
5822 <p>
5828 <p>
5832 <p>
5841 <p>
5845 <p>
5846 Sets the environment to be used by the given function.
5848 that specifies the function at that stack level:
5853 <p>
5855 the environment of the running thread.
5861 <p>
5865 <p>
5866 Sets the metatable for the given table.
5867 (You cannot change the metatable of other types from Lua, only from C.)
5869 removes the metatable of the given table.
5871 raises an error.
5874 <p>
5880 <p>
5882 Tries to convert its argument to a number.
5883 If the argument is already a number or a string convertible
5888 <p>
5889 An optional argument specifies the base to interpret the numeral.
5894 In base 10 (the default), the number may have a decimal part,
5896 In other bases, only unsigned integers are accepted.
5901 <p>
5903 Receives an argument of any type and
5904 converts it to a string in a reasonable format.
5905 For complete control of how numbers are converted,
5909 <p>
5913 and uses the result of the call as its result.
5918 <p>
5920 Returns the type of its only argument, coded as a string.
5921 The possible results of this function are
5923 "<code>number</code>",
5924 "<code>string</code>",
5925 "<code>boolean</code>",
5926 "<code>table</code>",
5927 "<code>function</code>",
5928 "<code>thread</code>",
5929 and "<code>userdata</code>".
5934 <p>
5936 Returns the elements from the given table.
5937 This function is equivalent to
5939 <pre>
5941 </pre><p>
5942 except that the above code can be written only for a fixed number
5943 of elements.
5950 <p>
5952 A global variable (not a function) that
5953 holds a string containing the current interpreter version.
5954 The current contents of this variable is "<code>Lua 5.1</code>".
5959 <p>
5963 <p>
5965 except that you can set a new error handler.
5968 <p>
5974 and returns a status code.
5975 Its first result is the status code (a boolean),
5976 which is true if the call succeeds without errors.
5978 after this first result.
5979 In case of any error,
5990 <p>
5991 The operations related to coroutines comprise a sub-library of
5992 the basic library and come inside the table <a name="pdf-coroutine"><code>coroutine</code></a>.
5996 <p>
6000 <p>
6003 Returns this new coroutine,
6009 <p>
6010 <hr><h3><a name="pdf-coroutine.resume"><code>coroutine.resume (co [, val1, ···])</code></a></h3>
6013 <p>
6015 The first time you resume a coroutine,
6016 it starts running its body.
6018 as the arguments to the body function.
6019 If the coroutine has yielded,
6022 as the results from the yield.
6025 <p>
6026 If the coroutine runs without any errors,
6028 (if the coroutine yields) or any values returned by the body function
6029 (if the coroutine terminates).
6030 If there is any error,
6036 <p>
6040 <p>
6041 Returns the running coroutine,
6047 <p>
6051 <p>
6056 or if it has not started running yet;
6058 (that is, it has resumed another coroutine);
6060 or if it has stopped with an error.
6065 <p>
6069 <p>
6072 Returns a function that resumes the coroutine each time it is called.
6073 Any arguments passed to the function behave as the
6076 except the first boolean.
6077 In case of error, propagates the error.
6082 <p>
6083 <hr><h3><a name="pdf-coroutine.yield"><code>coroutine.yield (···)</code></a></h3>
6086 <p>
6087 Suspends the execution of the calling coroutine.
6088 The coroutine cannot be running a C function,
6089 a metamethod, or an iterator.
6100 <p>
6101 The package library provides basic
6102 facilities for loading and building modules in Lua.
6103 It exports two of its functions directly in the global environment:
6104 <a href="#pdf-require"><code>require</code></a> and <a href="#pdf-module"><code>module</code></a>.
6108 <p>
6112 <p>
6113 Creates a module.
6115 this table is the module.
6117 this table is the module.
6124 (the full module name minus last component; see below).
6130 <p>
6132 (that is, one with components separated by dots),
6134 tables for each component.
6140 <p>
6142 the module name,
6143 where each option is a function to be applied over the module.
6148 <p>
6152 <p>
6153 Loads the given module.
6154 The function starts by looking into the <a href="#pdf-package.loaded"><code>package.loaded</code></a> table
6161 <p>
6162 To find a loader,
6164 If it has a value,
6165 this value (which should be a function) is the loader.
6168 If that also fails, it searches for a C loader using the
6170 If that also fails,
6174 <p>
6175 When loading a C library,
6177 application with the library.
6178 Then it tries to find a C function inside this library to
6179 be used as the loader.
6181 concatenated with a copy of the module name where each dot
6182 is replaced by an underscore.
6183 Moreover, if the module name has a hyphen,
6184 its prefix up to (and including) the first hyphen is removed.
6189 <p>
6191 C library for a module,
6193 This loader searches the C path for a library for
6194 the root name of the given module.
6197 If found, it looks into it for an open function for
6198 the submodule;
6200 With this facility, a package can pack several C submodules
6201 into one single library,
6202 with each submodule keeping its original open function.
6205 <p>
6206 Once a loader is found,
6208 If the loader returns any value,
6210 If the loader returns no value and
6217 <p>
6218 If there is any error loading or running the module,
6219 or if it cannot find any loader for the module,
6225 <p>
6229 <p>
6230 The path used by <a href="#pdf-require"><code>require</code></a> to search for a C loader.
6233 <p>
6234 Lua initializes the C path <a href="#pdf-package.cpath"><code>package.cpath</code></a> in the same way
6242 <p>
6247 <p>
6249 modules are already loaded.
6257 <p>
6258 <hr><h3><a name="pdf-package.loadlib"><code>package.loadlib (libname, funcname)</code></a></h3>
6261 <p>
6264 and returns this function as a C function.
6265 (So, <code>funcname</code> must follow the protocol (see <a href="#lua_CFunction"><code>lua_CFunction</code></a>)).
6268 <p>
6269 This is a low-level function.
6270 It completely bypasses the package and module system.
6272 it does not perform any path searching and
6273 does not automatically adds extensions.
6275 including if necessary a path and extension.
6277 (which may depend on the C compiler and linker used).
6280 <p>
6281 This function is not supported by ANSI C.
6282 As such, it is only available on some platforms
6283 (Windows, Linux, Mac OS X, Solaris, BSD,
6289 <p>
6293 <p>
6297 <p>
6298 At start-up, Lua initializes this variable with
6301 if the environment variable is not defined.
6302 Any "<code>;;</code>" in the value of the environment variable
6303 is replaced by the default path.
6306 <p>
6308 For each template, <a href="#pdf-require"><code>require</code></a> will change each interrogation
6312 then it will try to load the resulting file name.
6313 So, for instance, if the Lua path is
6315 <pre>
6316 "./?.lua;./?.lc;/usr/local/?/init.lua"
6317 </pre><p>
6319 will try to load the files
6326 <p>
6330 <p>
6331 A table to store loaders for specific modules
6337 <p>
6341 <p>
6344 so that this module inherits values
6345 from the global environment.
6356 <p>
6357 This library provides generic functions for string manipulation,
6358 such as finding and extracting substrings, and pattern matching.
6361 Indices are allowed to be negative and are interpreted as indexing backwards,
6362 from the end of the string.
6363 Thus, the last character is at position -1, and so on.
6366 <p>
6367 The string library provides all its functions inside the table
6369 It also sets a metatable for strings
6371 Therefore, you can use the string functions in object-oriented style.
6376 <p>
6384 <p>
6385 Note that numerical codes are not necessarily portable across platforms.
6390 <p>
6392 Receives zero or more integers.
6393 Returns a string with length equal to the number of arguments,
6394 in which each character has the internal numerical code equal
6395 to its corresponding argument.
6398 <p>
6399 Note that numerical codes are not necessarily portable across platforms.
6404 <p>
6408 <p>
6409 Returns a string containing a binary representation of the given function,
6411 a copy of the function.
6417 <p>
6418 <hr><h3><a name="pdf-string.find"><code>string.find (s, pattern [, init [, plain]])</code></a></h3>
6419 Looks for the first match of
6422 where this occurrence starts and ends;
6425 where to start the search;
6428 turns off the pattern matching facilities,
6429 so the function does a plain "find substring" operation,
6434 <p>
6435 If the pattern has captures,
6436 then in a successful match
6437 the captured values are also returned,
6438 after the two indices.
6443 <p>
6444 <hr><h3><a name="pdf-string.format"><code>string.format (formatstring, ···)</code></a></h3>
6445 Returns a formatted version of its variable number of arguments
6446 following the description given in its first argument (which must be a string).
6448 standard C functions.
6449 The only differences are that the options/modifiers
6454 back by the Lua interpreter:
6455 the string is written between double quotes,
6456 and all double quotes, newlines, embedded zeros,
6457 and backslashes in the string
6458 are correctly escaped when written.
6459 For instance, the call
6461 <pre>
6462 string.format('%q', 'a string with "quotes" and \n new line')
6463 </pre><p>
6464 will produce the string:
6466 <pre>
6468 new line"
6469 </pre>
6471 <p>
6473 <code>g</code>, <code>G</code>, <code>i</code>, <code>o</code>, <code>u</code>, <code>X</code>, and <code>x</code> all
6474 expect a number as argument,
6478 <p>
6479 This function does not accept string values
6480 containing embedded zeros,
6486 <p>
6488 Returns an iterator function that,
6489 each time it is called,
6492 then the whole match is produced in each call.
6495 <p>
6496 As an example, the following loop
6498 <pre>
6499 s = "hello world from Lua"
6500 for w in string.gmatch(s, "%a+") do
6501 print(w)
6502 end
6503 </pre><p>
6505 printing one per line.
6507 given string into a table:
6509 <pre>
6510 t = {}
6511 s = "from=world, to=Lua"
6512 for k, v in string.gmatch(s, "(%w+)=(%w+)") do
6513 t[k] = v
6514 end
6515 </pre>
6517 <p>
6519 work as an anchor, as this would prevent the iteration.
6524 <p>
6529 which may be a string, a table, or a function.
6531 the total number of substitutions made.
6534 <p>
6544 <p>
6546 using the first capture as the key;
6547 if the pattern specifies no captures,
6548 then the whole match is used as the key.
6551 <p>
6553 match occurs, with all captured substrings passed as arguments,
6554 in order;
6555 if the pattern specifies no captures,
6556 then the whole match is passed as a sole argument.
6559 <p>
6560 If the value returned by the table query or by the function call
6561 is a string or a number,
6562 then it is used as the replacement string;
6564 then there is no replacement
6565 (that is, the original match is kept in the string).
6568 <p>
6570 the maximum number of substitutions to occur.
6575 <p>
6576 Here are some examples:
6578 <pre>
6592 return loadstring(s)()
6593 end)
6599 </pre>
6603 <p>
6605 Receives a string and returns its length.
6607 Embedded zeros are counted,
6613 <p>
6615 Receives a string and returns a copy of this string with all
6616 uppercase letters changed to lowercase.
6617 All other characters are left unchanged.
6618 The definition of what an uppercase letter is depends on the current locale.
6623 <p>
6628 the captures from the pattern;
6631 then the whole match is returned.
6633 where to start the search;
6639 <p>
6647 <p>
6654 <p>
6660 (which is the same as the string length).
6661 In particular,
6670 <p>
6672 Receives a string and returns a copy of this string with all
6673 lowercase letters changed to uppercase.
6674 All other characters are left unchanged.
6675 The definition of what a lowercase letter is depends on the current locale.
6684 The following combinations are allowed in describing a character class:
6686 <ul>
6692 </li>
6718 This is the standard way to escape the magic characters.
6719 Any punctuation character (even the non magic)
6721 when used to represent itself in a pattern.
6722 </li>
6725 represents the class which is the union of all
6727 A range of characters may be specified by
6733 represents all alphanumeric characters plus the underscore,
6739 <p>
6740 The interaction between ranges and classes is not defined.
6742 have no meaning.
6743 </li>
6748 </li>
6750 </ul><p>
6752 the corresponding uppercase letter represents the complement of the class.
6756 <p>
6757 The definitions of letter, space, and other character groups
6758 depend on the current locale.
6768 <ul>
6770 <li>
6771 a single character class,
6772 which matches any single character in the class;
6773 </li>
6775 <li>
6777 which matches 0 or more repetitions of characters in the class.
6778 These repetition items will always match the longest possible sequence;
6779 </li>
6781 <li>
6783 which matches 1 or more repetitions of characters in the class.
6784 These repetition items will always match the longest possible sequence;
6785 </li>
6787 <li>
6789 which also matches 0 or more repetitions of characters in the class.
6792 </li>
6794 <li>
6797 </li>
6799 <li>
6802 (see below);
6803 </li>
6805 <li>
6809 This means that, if one reads the string from left to right,
6813 balanced parentheses.
6814 </li>
6816 </ul>
6824 beginning of the subject string.
6826 end of the subject string.
6827 At other positions,
6835 A pattern may contain sub-patterns enclosed in parentheses;
6837 When a match succeeds, the substrings of the subject string
6839 Captures are numbered according to their left parentheses.
6847 <p>
6849 the current string position (a number).
6854 <p>
6868 This library provides generic functions for table manipulation.
6872 <p>
6873 Most functions in the table library assume that the table
6874 represents an array or a list.
6875 For these functions, when we talk about the "length" of a table
6876 we mean the result of the length operator.
6879 <p>
6880 <hr><h3><a name="pdf-table.concat"><code>table.concat (table [, sep [, i [, j]]])</code></a></h3>
6881 Given an array where all elements are strings or numbers,
6891 <p>
6895 <p>
6897 shifting up other elements to open space, if necessary.
6906 <p>
6910 <p>
6911 Returns the largest positive numerical index of the given table,
6912 or zero if the table has no positive numerical indices.
6913 (To do its job this function does a linear traversal of
6914 the whole table.)
6919 <p>
6923 <p>
6925 shifting down other elements to close the space, if necessary.
6926 Returns the value of the removed element.
6935 <p>
6941 then it must be a function that receives two table elements,
6942 and returns true
6943 when the first is less than the second
6949 <p>
6950 The sort algorithm is not stable;
6951 that is, elements considered equal by the given order
6952 may have their relative positions changed by the sort.
6962 <p>
6963 This library is an interface to the standard C math library.
6967 <p>
6971 <p>
6977 <p>
6981 <p>
6987 <p>
6991 <p>
6997 <p>
7001 <p>
7007 <p>
7011 <p>
7013 but uses the signs of both parameters to find the
7014 quadrant of the result.
7020 <p>
7024 <p>
7030 <p>
7034 <p>
7040 <p>
7044 <p>
7050 <p>
7054 <p>
7060 <p>
7064 <p>
7070 <p>
7074 <p>
7080 <p>
7084 <p>
7090 <p>
7094 <p>
7103 <p>
7107 <p>
7109 a value larger than or equal to any other numerical value.
7114 <p>
7118 <p>
7124 <p>
7128 <p>
7134 <p>
7138 <p>
7144 <p>
7148 <p>
7149 Returns the maximum value among its arguments.
7154 <p>
7158 <p>
7159 Returns the minimum value among its arguments.
7164 <p>
7168 <p>
7169 Returns two numbers,
7175 <p>
7179 <p>
7185 <p>
7189 <p>
7196 <p>
7200 <p>
7206 <p>
7210 <p>
7211 This function is an interface to the simple
7213 (No guarantees can be given for its statistical properties.)
7216 <p>
7217 When called without arguments,
7218 returns a pseudo-random real number
7230 <p>
7234 <p>
7236 for the pseudo-random generator:
7237 equal seeds produce equal sequences of numbers.
7242 <p>
7246 <p>
7252 <p>
7256 <p>
7262 <p>
7266 <p>
7273 <p>
7277 <p>
7283 <p>
7287 <p>
7298 <p>
7299 The I/O library provides two different styles for file manipulation.
7300 The first one uses implicit file descriptors;
7301 that is, there are operations to set a default input file and a
7302 default output file,
7303 and all input/output operations are over these default files.
7304 The second style uses explicit file descriptors.
7307 <p>
7308 When using implicit file descriptors,
7310 When using explicit file descriptors,
7312 and then all operations are supplied as methods of the file descriptor.
7315 <p>
7317 three predefined file descriptors with their usual meanings from C:
7318 <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>.
7321 <p>
7322 Unless otherwise stated,
7324 (plus an error message as a second result and
7325 a system-dependent error code as a third result)
7329 <p>
7333 <p>
7340 <p>
7344 <p>
7350 <p>
7354 <p>
7355 When called with a file name, it opens the named file (in text mode),
7356 and sets its handle as the default input file.
7357 When called with a file handle,
7358 it simply sets this file handle as the default input file.
7359 When called without parameters,
7360 it returns the current default input file.
7363 <p>
7364 In case of errors this function raises the error,
7365 instead of returning an error code.
7370 <p>
7374 <p>
7375 Opens the given file name in read mode
7376 and returns an iterator function that,
7377 each time it is called,
7378 returns a new line from the file.
7379 Therefore, the construction
7381 <pre>
7383 </pre><p>
7384 will iterate over all lines of the file.
7385 When the iterator function detects the end of file,
7389 <p>
7392 that is, it iterates over the lines of the default input file.
7393 In this case it does not close the file when the loop ends.
7398 <p>
7402 <p>
7403 This function opens a file,
7405 It returns a new file handle,
7409 <p>
7412 <ul>
7419 writing is only allowed at the end of file.</li>
7420 </ul><p>
7422 which is needed in some systems to open the file in binary mode.
7423 This string is exactly what is used in the
7429 <p>
7433 <p>
7434 Similar to <a href="#pdf-io.input"><code>io.input</code></a>, but operates over the default output file.
7439 <p>
7443 <p>
7445 a file handle that you can use to read data from this program
7447 or to write data to this program
7451 <p>
7452 This function is system dependent and is not available
7453 on all platforms.
7458 <p>
7462 <p>
7468 <p>
7472 <p>
7473 Returns a handle for a temporary file.
7474 This file is opened in update mode
7475 and it is automatically removed when the program ends.
7480 <p>
7484 <p>
7493 <p>
7497 <p>
7503 <p>
7507 <p>
7509 Note that files are automatically closed when
7510 their handles are garbage collected,
7511 but that takes an unpredictable amount of time to happen.
7516 <p>
7520 <p>
7526 <p>
7530 <p>
7531 Returns an iterator function that,
7532 each time it is called,
7533 returns a new line from the file.
7534 Therefore, the construction
7536 <pre>
7538 </pre><p>
7539 will iterate over all lines of the file.
7540 (Unlike <a href="#pdf-io.lines"><code>io.lines</code></a>, this function does not close the file
7541 when the loop ends.)
7546 <p>
7550 <p>
7552 according to the given formats, which specify what to read.
7553 For each format,
7554 the function returns a string (or a number) with the characters read,
7556 When called without formats,
7557 it uses a default format that reads the entire next line
7558 (see below).
7561 <p>
7562 The available formats are
7564 <ul>
7567 reads a number;
7568 this is the only format that returns a number instead of a string.
7569 </li>
7572 reads the whole file, starting at the current position.
7573 On end of file, it returns the empty string.
7574 </li>
7577 reads the next line (skipping the end of line),
7579 This is the default format.
7580 </li>
7583 reads a string with up to this number of characters,
7585 If number is zero,
7586 it reads nothing and returns an empty string,
7588 </li>
7590 </ul>
7594 <p>
7598 <p>
7599 Sets and gets the file position,
7600 measured from the beginning of the file,
7604 <ul>
7608 </ul><p>
7610 measured in bytes from the beginning of the file.
7612 plus a string describing the error.
7615 <p>
7619 file position, without changing it;
7621 beginning of the file (and returns 0);
7623 end of the file, and returns its size.
7628 <p>
7632 <p>
7633 Sets the buffering mode for an output file.
7634 There are three available modes:
7636 <ul>
7639 no buffering; the result of any output operation appears immediately.
7640 </li>
7643 full buffering; output operation is performed only
7646 </li>
7649 line buffering; output is buffered until a newline is output
7650 or there is any input from some special files
7651 (such as a terminal device).
7652 </li>
7654 </ul><p>
7656 specifies the size of the buffer, in bytes.
7657 The default is an appropriate size.
7662 <p>
7666 <p>
7667 Writes the value of each of its arguments to
7669 The arguments must be strings or numbers.
7670 To write other values,
7671 use <a href="#pdf-tostring"><code>tostring</code></a> or <a href="#pdf-string.format"><code>string.format</code></a> before <code>write</code>.
7681 <p>
7685 <p>
7689 <p>
7690 Returns an approximation of the amount in seconds of CPU time
7691 used by the program.
7696 <p>
7700 <p>
7701 Returns a string or a table containing date and time,
7705 <p>
7707 this is the time to be formatted
7708 (see the <a href="#pdf-os.time"><code>os.time</code></a> function for a description of this value).
7712 <p>
7714 then the date is formatted in Coordinated Universal Time.
7715 After this optional character,
7725 <p>
7731 <p>
7732 When called without arguments,
7734 the host system and on the current locale
7740 <p>
7744 <p>
7746 In POSIX, Windows, and some other systems,
7752 <p>
7756 <p>
7759 It returns a status code, which is system-dependent.
7761 and zero otherwise.
7766 <p>
7770 <p>
7773 to terminate the host program.
7779 <p>
7783 <p>
7790 <p>
7794 <p>
7795 Deletes the file or directory with the given name.
7796 Directories must be empty to be removed.
7798 plus a string describing the error.
7803 <p>
7807 <p>
7810 plus a string describing the error.
7815 <p>
7819 <p>
7820 Sets the current locale of the program.
7826 The function returns the name of the new locale,
7830 <p>
7832 the current locate is set to an implementation-defined native locale.
7834 the current locate is set to the standard C locale.
7837 <p>
7839 this function only returns the name of the current locale
7840 for the given category.
7845 <p>
7849 <p>
7850 Returns the current time when called without arguments,
7851 or a time representing the date and time specified by the given table.
7853 and may have fields <code>hour</code>, <code>min</code>, <code>sec</code>, and <code>isdst</code>
7854 (for a description of these fields, see the <a href="#pdf-os.date"><code>os.date</code></a> function).
7857 <p>
7858 The returned value is a number, whose meaning depends on your system.
7859 In POSIX, Windows, and some other systems, this number counts the number
7860 of seconds since some given start time (the "epoch").
7861 In other systems, the meaning is not specified,
7868 <p>
7872 <p>
7873 Returns a string with a file name that can
7874 be used for a temporary file.
7875 The file must be explicitly opened before its use
7876 and explicitly removed when no longer needed.
7886 <p>
7887 This library provides
7888 the functionality of the debug interface to Lua programs.
7889 You should exert care when using this library.
7890 The functions provided here should be used exclusively for debugging
7891 and similar tasks, such as profiling.
7892 Please resist the temptation to use them as a
7893 usual programming tool:
7894 they can be very slow.
7895 Moreover, several of its functions
7896 violate some assumptions about Lua code
7897 (e.g., that variables local to a function
7898 cannot be accessed from outside or
7899 that userdata metatables cannot be changed by Lua code)
7900 and therefore can compromise otherwise secure code.
7903 <p>
7904 All functions in this library are provided
7906 All functions that operate over a thread
7907 have an optional first argument which is the
7908 thread to operate over.
7909 The default is always the current thread.
7912 <p>
7916 <p>
7917 Enters an interactive mode with the user,
7918 running each string that the user enters.
7919 Using simple commands and other debug facilities,
7920 the user can inspect global and local variables,
7921 change their values, evaluate expressions, and so on.
7923 so that the caller continues its execution.
7926 <p>
7928 within any function, and so have no direct access to local variables.
7933 <p>
7940 <p>
7944 <p>
7945 Returns the current hook settings of the thread, as three values:
7946 the current hook function, the current hook mask,
7947 and the current hook count
7953 <p>
7954 <hr><h3><a name="pdf-debug.getinfo"><code>debug.getinfo ([thread,] function [, what])</code></a></h3>
7957 <p>
7958 Returns a table with information about a function.
7959 You can give the function directly,
7962 of the given thread:
7965 and so on.
7970 <p>
7971 The returned table may contain all the fields returned by <a href="#lua_getinfo"><code>lua_getinfo</code></a>,
7974 except the table of valid lines.
7975 If present,
7978 If present,
7981 valid lines.
7984 <p>
7986 a name of the current function, if a reasonable name can be found,
7988 returns a table with all available information
7994 <p>
7995 <hr><h3><a name="pdf-debug.getlocal"><code>debug.getlocal ([thread,] level, local)</code></a></h3>
7998 <p>
7999 This function returns the name and the value of the local variable
8002 until the last active local variable.)
8004 variable with the given index,
8006 (You can call <a href="#pdf-debug.getinfo"><code>debug.getinfo</code></a> to check whether the level is valid.)
8009 <p>
8011 represent internal variables
8012 (loop control variables, temporaries, and C function locals).
8017 <p>
8021 <p>
8028 <p>
8032 <p>
8038 <p>
8042 <p>
8043 This function returns the name and the value of the upvalue
8050 <p>
8054 <p>
8061 <p>
8062 <hr><h3><a name="pdf-debug.sethook"><code>debug.sethook ([thread,] hook, mask [, count])</code></a></h3>
8065 <p>
8066 Sets the given function as a hook.
8068 when the hook will be called.
8069 The string mask may have the following characters,
8070 with the given meaning:
8072 <ul>
8076 </ul><p>
8081 <p>
8082 When called without arguments,
8086 <p>
8087 When the hook is called, its first parameter is a string
8088 describing the event that has triggered its call:
8091 For line events,
8092 the hook also gets the new line number as its second parameter.
8093 Inside a hook,
8095 the running function
8099 In this case, Lua is only simulating the return,
8105 <p>
8106 <hr><h3><a name="pdf-debug.setlocal"><code>debug.setlocal ([thread,] level, local, value)</code></a></h3>
8109 <p>
8113 variable with the given index,
8116 Otherwise, it returns the name of the local variable.
8121 <p>
8122 <hr><h3><a name="pdf-debug.setmetatable"><code>debug.setmetatable (object, table)</code></a></h3>
8125 <p>
8132 <p>
8133 <hr><h3><a name="pdf-debug.setupvalue"><code>debug.setupvalue (func, up, value)</code></a></h3>
8136 <p>
8140 with the given index.
8141 Otherwise, it returns the name of the upvalue.
8146 <p>
8147 <hr><h3><a name="pdf-debug.traceback"><code>debug.traceback ([thread,] [message] [, level])</code></a></h3>
8150 <p>
8151 Returns a string with a traceback of the call stack.
8153 at the beginning of the traceback.
8155 to start the traceback
8166 <p>
8167 Although Lua has been designed as an extension language,
8168 to be embedded in a host C program,
8169 it is also frequently used as a stand-alone language.
8170 An interpreter for Lua as a stand-alone language,
8172 is provided with the standard distribution.
8173 The stand-alone interpreter includes
8174 all standard libraries, including the debug library.
8175 Its usage is:
8177 <pre>
8178 lua [options] [script [args]]
8179 </pre><p>
8180 The options are:
8182 <ul>
8188 <li><b><code>-</code>:</b> executes <code>stdin</code> as a file and stops handling options.</li>
8189 </ul><p>
8192 When called without arguments,
8198 <p>
8199 Before running any argument,
8200 the interpreter checks for an environment variable <a name="pdf-LUA_INIT"><code>LUA_INIT</code></a>.
8206 <p>
8208 For instance, an invocation like
8210 <pre>
8211 $ lua -e'a=1' -e 'print(a)' script.lua
8212 </pre><p>
8213 will first set <code>a</code> to 1, then print the value of <code>a</code> (which is '<code>1</code>'),
8218 <p>
8219 Before starting to run the script,
8222 The script name is stored at index 0,
8223 the first argument after the script name goes to index 1,
8224 and so on.
8225 Any arguments before the script name
8226 (that is, the interpreter name plus the options)
8227 go to negative indices.
8228 For instance, in the call
8230 <pre>
8231 $ lua -la b.lua t1 t2
8232 </pre><p>
8234 then creates a table
8236 <pre>
8240 </pre><p>
8243 as arguments;
8247 <p>
8248 In interactive mode,
8249 if you write an incomplete statement,
8250 the interpreter waits for its completion
8251 by issuing a different prompt.
8254 <p>
8256 then its value is used as the prompt.
8257 Similarly, if the global variable <a name="pdf-_PROMPT2"><code>_PROMPT2</code></a> contains a string,
8258 its value is used as the secondary prompt
8259 (issued during incomplete statements).
8260 Therefore, both prompts can be changed directly on the command line.
8261 For instance,
8263 <pre>
8264 $ lua -e"_PROMPT='myprompt> '" -i
8265 </pre><p>
8266 (the outer pair of quotes is for the shell,
8267 the inner pair is for Lua),
8273 <p>
8274 To allow the use of Lua as a
8275 script interpreter in Unix systems,
8276 the stand-alone interpreter skips
8278 Therefore, Lua scripts can be made into executable programs
8280 as in
8282 <pre>
8283 #!/usr/local/bin/lua
8284 </pre><p>
8285 (Of course,
8286 the location of the Lua interpreter may be different in your machine.
8288 then
8290 <pre>
8291 #!/usr/bin/env lua
8292 </pre><p>
8293 is a more portable solution.)
8299 <p>
8300 Here we list the incompatibilities that you may found when moving a program
8302 You can avoid most of the incompatibilities compiling Lua with
8304 However,
8305 all these compatibility options will be removed in the next version of Lua.
8310 <ul>
8312 <li>
8314 table with the extra arguments to the vararg expression.
8316 </li>
8318 <li>
8319 There was a subtle change in the scope of the implicit
8321 </li>
8323 <li>
8325 does not allow nesting.
8328 </li>
8330 </ul>
8336 <ul>
8338 <li>
8339 Function <code>string.gfind</code> was renamed <a href="#pdf-string.gmatch"><code>string.gmatch</code></a>.
8341 </li>
8343 <li>
8345 third argument,
8347 replacement string is the whole match,
8348 instead of the empty string.
8349 </li>
8351 <li>
8355 use the operator instead of the function.
8357 </li>
8359 <li>
8360 Function <code>loadlib</code> was renamed <a href="#pdf-package.loadlib"><code>package.loadlib</code></a>.
8362 </li>
8364 <li>
8365 Function <code>math.mod</code> was renamed <a href="#pdf-math.fmod"><code>math.fmod</code></a>.
8367 </li>
8369 <li>
8372 </li>
8374 <li>
8375 There were substantial changes in function <a href="#pdf-require"><code>require</code></a> due to
8376 the new module system.
8377 However, the new behavior is mostly compatible with the old,
8378 but <code>require</code> gets the path from <a href="#pdf-package.path"><code>package.path</code></a> instead
8380 </li>
8382 <li>
8383 Function <a href="#pdf-collectgarbage"><code>collectgarbage</code></a> has different arguments.
8386 </li>
8388 </ul>
8394 <ul>
8396 <li>
8398 cannot be called directly,
8399 like a regular C function.
8400 They must be called through Lua,
8401 like a Lua function.
8402 </li>
8404 <li>
8405 Function <code>lua_open</code> was replaced by <a href="#lua_newstate"><code>lua_newstate</code></a> to
8406 allow the user to set a memory-allocation function.
8407 You can use <a href="#luaL_newstate"><code>luaL_newstate</code></a> from the standard library to
8408 create a state with a standard allocation function
8410 </li>
8412 <li>
8414 (from the auxiliary library) are deprecated.
8417 </li>
8419 <li>
8420 Function <code>luaL_openlib</code> was replaced by <a href="#luaL_register"><code>luaL_register</code></a>.
8421 </li>
8423 <li>
8425 is not a userdata of the expected type.
8427 </li>
8429 </ul>
8436 <p>
8437 Here is the complete syntax of Lua in extended BNF.
8438 (It does not describe operator precedences.)
8443 <pre>
8447 block ::= chunk
8450 functioncall |
8454 <b>if</b> exp <b>then</b> block {<b>elseif</b> exp <b>then</b> block} [<b>else</b> block] <b>end</b> |
8455 <b>for</b> Name `<b>=</b>´ exp `<b>,</b>´ exp [`<b>,</b>´ exp] <b>do</b> block <b>end</b> |
8467 var ::= Name | prefixexp `<b>[</b>´ exp `<b>]</b>´ | prefixexp `<b>.</b>´ Name
8473 exp ::= <b>nil</b> | <b>false</b> | <b>true</b> | Number | String | `<b>...</b>´ | function |
8474 prefixexp | tableconstructor | exp binop exp | unop exp
8490 fieldlist ::= field {fieldsep field} [fieldsep]
8492 field ::= `<b>[</b>´ exp `<b>]</b>´ `<b>=</b>´ exp | Name `<b>=</b>´ exp | exp
8496 binop ::= `<b>+</b>´ | `<b>-</b>´ | `<b>*</b>´ | `<b>/</b>´ | `<b>^</b>´ | `<b>%</b>´ | `<b>..</b>´ |
8497 `<b><</b>´ | `<b><=</b>´ | `<b>></b>´ | `<b>>=</b>´ | `<b>==</b>´ | `<b>~=</b>´ |
8502 </pre>
8504 <p>
8511 <HR>
8512 <SMALL>
8513 Last update:
8515 </SMALL>
8516 <!--
8517 Last change: ready for Lua 5.1.2
8518 -->
8520 </body></html>