Lines Matching +full:- +full:a
1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
8 <META HTTP-EQUIV="content-type" CONTENT="text/html; charset=iso-8859-1">
15 <a href="http://www.lua.org/"><img src="logo.gif" alt="" border="0"></a>
22 Copyright © 2006–2012 Lua.org, PUC-Rio.
24 <a href="http://www.lua.org/license.html">Lua license</a>.
29 <a href="contents.html#contents">contents</A>
31 <a href="contents.html#index">index</A>
33 <A HREF="http://www.lua.org/manual/">other versions</A>
35 <!-- ====================================================================== -->
38 <!-- $Id: manual.of,v 1.49.1.2 2012/01/13 20:23:26 roberto Exp $ -->
43 <h1>1 - <a name="1">Introduction</a></h1>
49 It also offers good support for object-oriented programming,
50 functional programming, and data-driven programming.
51 Lua is intended to be used as a powerful, light-weight
53 Lua is implemented as a library, written in <em>clean</em> C
58 Being an extension language, Lua has no notion of a "main" program:
59 it only works <em>embedded</em> in a host client,
61 This host program can invoke functions to execute a piece of Lua code,
65 a wide range of different domains,
66 thus creating customized programming languages sharing a syntactical framework.
67 The Lua distribution includes a sample host program called <code>lua</code>,
68 which uses the Lua library to offer a complete, stand-alone Lua interpreter.
82 For a discussion of the decisions behind the design of Lua,
84 For a detailed introduction to programming in Lua,
89 <h1>2 - <a name="2">The Language</a></h1>
103 {<em>a</em>} means 0 or more <em>a</em>'s, and
104 [<em>a</em>] means an optional <em>a</em>.
105 Non-terminals are shown like non-terminal,
108 The complete syntax of Lua can be found in <a href="#8">§8</a>
113 <h2>2.1 - <a name="2.1">Lexical Conventions</a></h2>
120 not beginning with a digit.
141 Lua is a case-sensitive language:
142 <code>and</code> is a reserved word, but <code>And</code> and <code>AND</code>
144 As a convention, names starting with an underscore followed by
145 uppercase letters (such as <a href="#pdf-_VERSION"><code>_VERSION</code></a>)
153 + - * / % ^ #
162 and can contain the following C-like escape sequences:
163 '<code>\a</code>' (bell),
173 Moreover, a backslash followed by a real newline
174 results in a newline in the string.
175 A character in a string can also be specified by its numerical value
177 where <em>ddd</em> is a sequence of up to three decimal digits.
178 (Note that if a numerical escape is to be followed by a digit,
180 Strings in Lua can contain any 8-bit value, including embedded zeros,
185 Literal strings can also be defined using a long format
193 A <em>closing long bracket</em> is defined similarly;
194 for instance, a closing long bracket of level 4 is written as <code>]====]</code>.
195 A long string starts with an opening long bracket of any level and
200 They can contain anything except a closing bracket of the proper level.
205 when the opening long bracket is immediately followed by a newline,
207 As an example, in a system using ASCII
208 (in which '<code>a</code>' is coded as 97,
213 a = 'alo\n123"'
214 a = "alo\n123\""
215 a = '\97lo\10\04923"'
216 a = [[alo
218 a = [==[
224 A <em>numerical constant</em> can be written with an optional decimal part
231 3 3.0 3.1416 314.16e-2 0.31416E1 0xff 0x56
235 A <em>comment</em> starts with a double hyphen (<code>--</code>)
236 anywhere outside a string.
237 If the text immediately after <code>--</code> is not an opening long bracket,
238 the comment is a <em>short comment</em>,
240 Otherwise, it is a <em>long comment</em>,
248 <h2>2.2 - <a name="2.2">Values and Types</a></h2>
251 Lua is a <em>dynamically typed language</em>.
259 All values in Lua are <em>first-class values</em>.
271 it usually represents the absence of a useful value.
273 Both <b>nil</b> and <b>false</b> make a condition false;
275 <em>Number</em> represents real (double-precision floating-point) numbers.
278 such as single-precision float or long integers;
282 Lua is 8-bit clean:
283 strings can contain any 8-bit character,
284 including embedded zeros ('<code>\0</code>') (see <a href="#2.1">§2.1</a>).
290 (see <a href="#2.5.8">§2.5.8</a>).
296 This type corresponds to a block of raw memory
297 and has no pre-defined operations in Lua,
301 (see <a href="#2.8">§2.8</a>).
309 and it is used to implement coroutines (see <a href="#2.11">§2.11</a>).
310 Do not confuse Lua threads with operating-system threads.
326 providing <code>a.name</code> as syntactic sugar for <code>a["name"]</code>.
328 (see <a href="#2.5.7">§2.5.7</a>).
333 the value of a table field can be of any type (except <b>nil</b>).
335 because functions are first-class values,
337 Thus tables can also carry <em>methods</em> (see <a href="#2.5.9">§2.5.9</a>).
350 The library function <a href="#pdf-type"><code>type</code></a> returns a string describing the type
351 of a given value.
355 <h3>2.2.1 - <a name="2.2.1">Coercion</a></h3>
360 Any arithmetic operation applied to a string tries to convert
361 this string to a number, following the usual conversion rules.
362 Conversely, whenever a number is used where a string is expected,
363 the number is converted to a string, in a reasonable format.
366 (see <a href="#pdf-string.format"><code>string.format</code></a>).
374 <h2>2.3 - <a name="2.3">Variables</a></h2>
384 A single name can denote a global variable or a local variable
385 (or a function's formal parameter,
386 which is a particular kind of local variable):
391 Name denotes identifiers, as defined in <a href="#2.1">§2.1</a>.
396 as a local (see <a href="#2.4.7">§2.4.7</a>).
399 defined inside their scope (see <a href="#2.6">§2.6</a>).
403 Before the first assignment to a variable, its value is <b>nil</b>.
407 Square brackets are used to index a table:
415 a call <code>gettable_event(t,i)</code>.
416 (See <a href="#2.8">§2.8</a> for a complete description of the
433 <em>environments</em> (see <a href="#2.9">§2.9</a>).
437 When a function is created,
439 To get the environment table of a Lua function,
440 you call <a href="#pdf-getfenv"><code>getfenv</code></a>.
442 you call <a href="#pdf-setfenv"><code>setfenv</code></a>.
444 through the debug library; (see <a href="#5.9">§5.9</a>).)
448 An access to a global variable <code>x</code>
456 (See <a href="#2.8">§2.8</a> for a complete description of the
466 <h2>2.4 - <a name="2.4">Statements</a></h2>
477 <h3>2.4.1 - <a name="2.4.1">Chunks</a></h3>
480 The unit of execution of Lua is called a <em>chunk</em>.
481 A chunk is simply a sequence of statements,
483 Each statement can be optionally followed by a semicolon:
492 Lua handles a chunk as the body of an anonymous function
493 with a variable number of arguments
494 (see <a href="#2.5.9">§2.5.9</a>).
500 A chunk can be stored in a file or in a string inside the host program.
501 To execute a chunk,
502 Lua first pre-compiles the chunk into instructions for a virtual machine,
508 Chunks can also be pre-compiled into binary form;
518 <h3>2.4.2 - <a name="2.4.2">Blocks</a></h3><p>
519 A block is a list of statements;
520 syntactically, a block is the same as a chunk:
527 A block can be explicitly delimited to produce a single statement:
535 add a <b>return</b> or <b>break</b> statement in the middle
536 of another block (see <a href="#2.4.4">§2.4.4</a>).
542 <h3>2.4.3 - <a name="2.4.3">Assignment</a></h3>
547 defines a list of variables on the left side
548 and a list of expressions on the right side.
556 Expressions are discussed in <a href="#2.5">§2.5</a>.
567 If the list of expressions ends with a function call,
570 (except when the call is enclosed in parentheses; see <a href="#2.5">§2.5</a>).
580 i, a[i] = i+1, 20
582 sets <code>a[3]</code> to 20, without affecting <code>a[4]</code>
583 because the <code>i</code> in <code>a[i]</code> is evaluated (to 3)
604 (See <a href="#2.8">§2.8</a> for a complete description of the
611 An assignment to a global variable <code>x = val</code>
627 <h3>2.4.4 - <a name="2.4.4">Control Structures</a></h3><p>
640 Lua also has a <b>for</b> statement, in two flavors (see <a href="#2.4.5">§2.4.5</a>).
644 The condition expression of a
661 from a function or a chunk (which is just a function).
671 The <b>break</b> statement is used to terminate the execution of a
679 A <b>break</b> ends the innermost enclosing loop.
684 statements can only be written as the <em>last</em> statement of a block.
686 middle of a block,
697 <h3>2.4.5 - <a name="2.4.5">For Statement</a></h3>
706 The numeric <b>for</b> loop repeats a block of code while a
716 More precisely, a <b>for</b> statement like
751 then a step of 1 is used.
755 You can use <b>break</b> to exit a <b>for</b> loop.
770 On each iteration, the iterator function is called to produce a new value,
778 A <b>for</b> statement like
803 a <em>state</em>,
813 You can use <b>break</b> to exit a <b>for</b> loop.
828 <h3>2.4.6 - <a name="2.4.6">Function Calls as Statements</a></h3><p>
829 To allow possible side-effects,
836 Function calls are explained in <a href="#2.5.8">§2.5.8</a>.
842 <h3>2.4.7 - <a name="2.4.7">Local Declarations</a></h3><p>
843 Local variables can be declared anywhere inside a block.
850 of a multiple assignment (see <a href="#2.4.3">§2.4.3</a>).
855 A chunk is also a block (see <a href="#2.4.1">§2.4.1</a>),
856 and so local variables can be declared in a chunk outside any explicit block.
861 The visibility rules for local variables are explained in <a href="#2.6">§2.6</a>.
869 <h2>2.5 - <a name="2.5">Expressions</a></h2>
888 Numbers and literal strings are explained in <a href="#2.1">§2.1</a>;
889 variables are explained in <a href="#2.3">§2.3</a>;
890 function definitions are explained in <a href="#2.5.9">§2.5.9</a>;
891 function calls are explained in <a href="#2.5.8">§2.5.8</a>;
892 table constructors are explained in <a href="#2.5.7">§2.5.7</a>.
895 directly inside a vararg function;
896 they are explained in <a href="#2.5.9">§2.5.9</a>.
900 Binary operators comprise arithmetic operators (see <a href="#2.5.1">§2.5.1</a>),
901 relational operators (see <a href="#2.5.2">§2.5.2</a>), logical operators (see <a href="#2.5.3…
902 and the concatenation operator (see <a href="#2.5.4">§2.5.4</a>).
903 Unary operators comprise the unary minus (see <a href="#2.5.1">§2.5.1</a>),
904 the unary <b>not</b> (see <a href="#2.5.3">§2.5.3</a>),
905 and the unary <em>length operator</em> (see <a href="#2.5.5">§2.5.5</a>).
910 If an expression is used as a statement
911 (only possible for function calls (see <a href="#2.4.6">§2.4.6</a>)),
915 of a list of expressions,
927 f() -- adjusted to 0 results
928 g(f(), x) -- f() is adjusted to 1 result
929 g(x, f()) -- g gets x plus all results from f()
930 a,b,c = f(), x -- f() is adjusted to 1 result (c gets nil)
931 a,b = ... -- a gets the first vararg parameter, b gets
932 -- the second (both a and b can get nil if there
933 -- is no corresponding vararg parameter)
935 a,b,c = x, f() -- f() is adjusted to 2 results
936 a,b,c = f() -- f() is adjusted to 3 results
937 return f() -- returns all results from f()
938 return ... -- returns all received vararg parameters
939 return x,y,f() -- returns x, y, and all results from f()
940 {f()} -- creates a list with all results from f()
941 {...} -- creates a list with all vararg parameters
942 {f(), nil} -- f() is adjusted to 1 result
948 <code>(f(x,y,z))</code> is always a single value,
955 <h3>2.5.1 - <a name="2.5.1">Arithmetic Operators</a></h3><p>
958 <code>-</code> (subtraction), <code>*</code> (multiplication),
960 and unary <code>-</code> (negation).
962 numbers (see <a href="#2.2.1">§2.2.1</a>),
965 For instance, <code>x^(-0.5)</code> computes the inverse of the square root of <code>x</code>.
969 a % b == a - math.floor(a/b)*b
971 That is, it is the remainder of a division that rounds
978 <h3>2.5.2 - <a name="2.5.2">Relational Operators</a></h3><p>
995 Every time you create a new object
996 (a table, userdata, thread, or function),
1002 by using the "eq" metamethod (see <a href="#2.8">§2.8</a>).
1006 The conversion rules of <a href="#2.2.1">§2.2.1</a>
1010 entries in a table.
1023 metamethod (see <a href="#2.8">§2.8</a>).
1024 A comparison <code>a > b</code> is translated to <code>b < a</code>
1025 and <code>a >= b</code> is translated to <code>b <= a</code>.
1031 <h3>2.5.3 - <a name="2.5.3">Logical Operators</a></h3><p>
1034 Like the control structures (see <a href="#2.4.4">§2.4.4</a>),
1047 Both <b>and</b> and <b>or</b> use short-cut evaluation;
1053 10 or 20 --> 10
1054 10 or error() --> 10
1055 nil or "a" --> "a"
1056 nil and 10 --> nil
1057 false and error() --> false
1058 false and nil --> false
1059 false or nil --> nil
1060 10 and 20 --> 20
1063 <code>--></code> indicates the result of the preceding expression.)
1069 <h3>2.5.4 - <a name="2.5.4">Concatenation</a></h3><p>
1073 strings according to the rules mentioned in <a href="#2.2.1">§2.2.1</a>.
1074 Otherwise, the "concat" metamethod is called (see <a href="#2.8">§2.8</a>).
1080 <h3>2.5.5 - <a name="2.5.5">The Length Operator</a></h3>
1084 The length of a string is its number of bytes
1090 The length of a table <code>t</code> is defined to be any
1094 For a regular array, with non-nil values from 1 to a given <code>n</code>,
1098 (that is, <b>nil</b> values between other non-nil values),
1100 directly precedes a <b>nil</b> value
1108 <h3>2.5.6 - <a name="2.5.6">Precedence</a></h3><p>
1117 + -
1119 not # - (unary)
1132 <h3>2.5.7 - <a name="2.5.7">Table Constructors</a></h3><p>
1134 Every time a constructor is evaluated, a new table is created.
1135 A constructor can be used to create an empty table
1136 or to create a table and initialize some of its fields.
1149 A field of the form <code>name = exp</code> is equivalent to
1158 a = { [f(1)] = g; "x", "y"; x = 1, f(x), [30] = 23; 45 }
1166 t[1] = "x" -- 1st exp
1167 t[2] = "y" -- 2nd exp
1168 t.x = 1 -- t["x"] = 1
1169 t[3] = f(x) -- 3rd exp
1171 t[4] = 45 -- 4th exp
1172 a = t
1178 and the expression is a function call or a vararg expression,
1180 (see <a href="#2.5.8">§2.5.8</a>).
1183 in parentheses (see <a href="#2.5">§2.5</a>).
1188 as a convenience for machine-generated code.
1194 <h3>2.5.8 - <a name="2.5.8">Function Calls</a></h3><p>
1195 A function call in Lua has the following syntax:
1200 In a function call,
1208 (see <a href="#2.8">§2.8</a>).
1218 A call <code>v:name(<em>args</em>)</code>
1232 A call of the form <code>f{<em>fields</em>}</code> is
1234 that is, the argument list is a single new table.
1235 A call of the form <code>f'<em>string</em>'</code>
1238 that is, the argument list is a single literal string.
1242 As an exception to the free-format syntax of Lua,
1243 you cannot put a line break before the '<code>(</code>' in a function call.
1248 a = f
1249 (g).x(a)
1251 Lua would see that as a single statement, <code>a = f(g).x(a)</code>.
1252 So, if you want two statements, you must add a semi-colon between them.
1258 A call of the form <code>return</code> <em>functioncall</em> is called
1259 a <em>tail call</em>.
1262 in a tail call,
1265 a program can execute.
1266 However, a tail call erases any debug information about the
1268 Note that a tail call only happens with a particular syntax,
1275 return (f(x)) -- results adjusted to 1
1277 return x, f(x) -- additional results
1278 f(x); return -- results discarded
1279 return x or f(x) -- results adjusted to 1
1285 <h3>2.5.9 - <a name="2.5.9">Function Definitions</a></h3>
1316 function t.a.b.c.f () <em>body</em> end
1321 t.a.b.c.f = function () <em>body</em> end
1338 (This only makes a difference when the body of the function
1343 A function definition is an executable expression,
1345 When Lua pre-compiles a chunk,
1346 all its function bodies are pre-compiled too.
1363 When a function is called,
1366 unless the function is a variadic or <em>vararg function</em>,
1369 A vararg function does not adjust its argument list;
1371 to the function through a <em>vararg expression</em>,
1373 The value of this expression is a list of all actual extra arguments,
1374 similar to a function with multiple results.
1375 If a vararg expression is used inside another expression
1376 or in the middle of a list of expressions,
1378 If the expression is used as the last element of a list of expressions,
1387 function f(a, b) end
1388 function g(a, b, ...) end
1397 f(3) a=3, b=nil
1398 f(3, 4) a=3, b=4
1399 f(3, 4, 5) a=3, b=4
1400 f(r(), 10) a=1, b=10
1401 f(r()) a=1, b=2
1403 g(3) a=3, b=nil, ... --> (nothing)
1404 g(3, 4) a=3, b=4, ... --> (nothing)
1405 g(3, 4, 5, 8) a=3, b=4, ... --> 5 8
1406 g(5, r()) a=5, b=1, ... --> 2 3
1410 Results are returned using the <b>return</b> statement (see <a href="#2.4.4">§2.4.4</a>).
1411 If control reaches the end of a function
1412 without encountering a <b>return</b> statement,
1423 function t.a.b.c:f (<em>params</em>) <em>body</em> end
1428 t.a.b.c.f = function (self, <em>params</em>) <em>body</em> end
1436 <h2>2.6 - <a name="2.6">Visibility Rules</a></h2>
1440 Lua is a lexically scoped language.
1447 x = 10 -- global variable
1448 do -- new block
1449 local x = x -- new 'x', with value 10
1450 print(x) --> 10
1452 do -- another block
1453 local x = x+1 -- another 'x'
1454 print(x) --> 12
1456 print(x) --> 11
1458 print(x) --> 10 (the global one)
1462 Notice that, in a declaration like <code>local x = x</code>,
1471 A local variable used by an inner function is called
1477 Notice that each execution of a <b>local</b> statement
1482 a = {}
1486 a[i] = function () y=y+1; return x+y end
1491 Each of these closures uses a different <code>y</code> variable,
1498 <h2>2.7 - <a name="2.7">Error Handling</a></h2>
1503 calling a function from the Lua library (see <a href="#lua_pcall"><code>lua_pcall</code></a>).
1512 <a href="#pdf-error"><code>error</code></a> function.
1514 you can use the <a href="#pdf-pcall"><code>pcall</code></a> function.
1520 <h2>2.8 - <a name="2.8">Metatables</a></h2>
1523 Every value in Lua can have a <em>metatable</em>.
1528 of operations over a value by setting specific fields in its metatable.
1529 For instance, when a non-numeric value is the operand of an addition,
1530 Lua checks for a function in the field <code>"__add"</code> in its metatable.
1536 We call the keys in a metatable <em>events</em>
1544 through the <a href="#pdf-getmetatable"><code>getmetatable</code></a> function.
1549 through the <a href="#pdf-setmetatable"><code>setmetatable</code></a>
1565 A metatable controls how an object behaves in arithmetic operations,
1567 A metatable also can define a function to be called when a userdata
1569 For each of these operations Lua associates a specific key
1571 When Lua performs one of these operations over a value,
1572 it checks whether this value has a metatable with the corresponding event.
1580 The key for each operation is a string with its name prefixed by
1584 The semantics of these operations is better explained by a Lua function
1593 (<a href="#pdf-rawget"><code>rawget</code></a>, <a href="#pdf-tonumber"><code>tonumber</code></a>, …
1594 are described in <a href="#5.1">§5.1</a>.
1595 In particular, to retrieve the metamethod of a given object,
1607 That is, the access to a metamethod does not invoke other metamethods,
1621 The function <code>getbinhandler</code> below defines how Lua chooses a handler
1622 for a binary operation.
1624 If its type does not define a handler for the operation,
1638 if o1 and o2 then -- both operands are numeric?
1639 return o1 + o2 -- '+' here is the primitive 'add'
1640 else -- at least one of the operands is not numeric
1643 -- call the handler with both operands
1645 else -- no handler available: default behavior
1654 the <code>-</code> operation.
1676 <code>o1 - floor(o1/o2)*o2</code> as the primitive operation.
1688 the unary <code>-</code> operation.
1694 if o then -- operand is numeric?
1695 return -o -- '-' here is the primitive 'unm'
1696 else -- the operand is not numeric.
1697 -- Try to get a handler from the operand
1700 -- call the handler with the operand
1702 else -- no handler available: default behavior
1718 return op1 .. op2 -- primitive string concatenation
1738 return strlen(op) -- primitive string length
1740 return #op -- primitive table length
1744 -- call the handler with the operand
1746 else -- no handler available: default behavior
1752 See <a href="#2.5.5">§2.5.5</a> for a description of the length of a table.
1758 The function <code>getcomphandler</code> defines how Lua chooses a metamethod
1760 A metamethod only is selected when both objects
1776 if type(op1) ~= type(op2) then -- different types?
1777 return false -- different objects
1779 if op1 == op2 then -- primitive equal?
1780 return true -- objects are equal
1782 -- try metamethod
1791 <code>a ~= b</code> is equivalent to <code>not (a == b)</code>.
1801 return op1 < op2 -- numeric comparison
1803 return op1 < op2 -- lexicographic comparison
1814 <code>a > b</code> is equivalent to <code>b < a</code>.
1824 return op1 <= op2 -- numeric comparison
1826 return op1 <= op2 -- lexicographic comparison
1842 <code>a >= b</code> is equivalent to <code>b <= a</code>.
1843 Note that, in the absence of a "le" metamethod,
1844 Lua tries the "lt", assuming that <code>a <= b</code> is
1845 equivalent to <code>not (b < a)</code>.
1867 return (h(table, key)) -- call the handler
1868 else return h[key] -- or repeat operation on it
1893 h(table, key,value) -- call the handler
1894 else h[key] = value -- or repeat operation on it
1901 called when Lua calls a value.
1907 return func(...) -- primitive call
1925 <h2>2.9 - <a name="2.9">Environments</a></h2>
1940 Non-nested Lua functions
1941 …y <a href="#pdf-loadfile"><code>loadfile</code></a>, <a href="#pdf-loadstring"><code>loadstring</c…
1949 It is only a convenience feature for programmers to associate a table to
1950 a userdata.
1957 non-nested Lua functions created by the thread
1958 and can be directly accessed by C code (see <a href="#3.3">§3.3</a>).
1962 The environment associated with a C function can be directly
1963 accessed by C code (see <a href="#3.3">§3.3</a>).
1970 all accesses to global variables within the function (see <a href="#2.3">§2.3</a>).
1976 You can change the environment of a Lua function or the
1977 running thread by calling <a href="#pdf-setfenv"><code>setfenv</code></a>.
1978 You can get the environment of a Lua function or the running thread
1979 by calling <a href="#pdf-getfenv"><code>getfenv</code></a>.
1988 <h2>2.10 - <a name="2.10">Garbage Collection</a></h2>
1996 a <em>garbage collector</em> from time to time
2004 Lua implements an incremental mark-and-sweep collector.
2005 It uses two numbers to control its garbage-collection cycles:
2006 the <em>garbage-collector pause</em> and
2007 the <em>garbage-collector step multiplier</em>.
2009 (so that a value of 100 means an internal value of 1).
2013 The garbage-collector pause
2014 controls how long the collector waits before starting a new cycle.
2017 start a new cycle.
2018 A value of 200 means that the collector waits for the total memory in use
2019 to double before starting a new cycle.
2029 can result in the collector never finishing a cycle.
2035 You can change these numbers by calling <a href="#lua_gc"><code>lua_gc</code></a> in C
2036 or <a href="#pdf-collectgarbage"><code>collectgarbage</code></a> in Lua.
2042 <h3>2.10.1 - <a name="2.10.1">Garbage-Collection Metamethods</a></h3>
2046 you can set garbage-collector metamethods for userdata (see <a href="#2.8">§2.8</a>).
2055 Garbage userdata with a field <code>__gc</code> in their metatables are not
2057 Instead, Lua puts them in a list.
2072 At the end of each garbage-collection cycle,
2078 The userdata itself is freed only in the next garbage-collection cycle.
2084 <h3>2.10.2 - <a name="2.10.2">Weak Tables</a></h3>
2087 A <em>weak table</em> is a table whose elements are
2089 A weak reference is ignored by the garbage collector.
2096 A weak table can have weak keys, weak values, or both.
2097 A table with weak keys allows the collection of its keys,
2099 A table with both weak keys and weak values allows the collection of
2103 The weakness of a table is controlled by the
2105 If the <code>__mode</code> field is a string containing the character '<code>k</code>',
2112 After you use a table as a metatable,
2123 <h2>2.11 - <a name="2.11">Coroutines</a></h2>
2128 A coroutine in Lua represents an independent thread of execution.
2130 a coroutine only suspends its execution by explicitly calling
2131 a yield function.
2135 You create a coroutine with a call to <a href="#pdf-coroutine.create"><code>coroutine.create</code>…
2136 Its sole argument is a function
2138 The <code>create</code> function only creates a new coroutine and
2139 returns a handle to it (an object of type <em>thread</em>);
2144 When you first call <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a>,
2146 a thread returned by <a href="#pdf-coroutine.create"><code>coroutine.create</code></a>,
2149 Extra arguments passed to <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a> are pas…
2156 A coroutine can terminate its execution in two ways:
2160 In the first case, <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a> returns <b>tru…
2162 In case of errors, <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a> returns <b>fal…
2167 A coroutine yields by calling <a href="#pdf-coroutine.yield"><code>coroutine.yield</code></a>.
2168 When a coroutine yields,
2169 the corresponding <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a> returns immedia…
2172 but in a function directly or indirectly called by the main function).
2173 In the case of a yield, <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a> also retu…
2174 plus any values passed to <a href="#pdf-coroutine.yield"><code>coroutine.yield</code></a>.
2177 with the call to <a href="#pdf-coroutine.yield"><code>coroutine.yield</code></a> returning any extra
2178 arguments passed to <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a>.
2182 Like <a href="#pdf-coroutine.create"><code>coroutine.create</code></a>,
2183 the <a href="#pdf-coroutine.wrap"><code>coroutine.wrap</code></a> function also creates a coroutine,
2185 it returns a function that, when called, resumes the coroutine.
2187 go as extra arguments to <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a>.
2188 …a href="#pdf-coroutine.wrap"><code>coroutine.wrap</code></a> returns all the values returned by <a…
2190 Unlike <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a>,
2191 <a href="#pdf-coroutine.wrap"><code>coroutine.wrap</code></a> does not catch errors;
2200 function foo (a)
2201 print("foo", a)
2202 return coroutine.yield(2*a)
2205 co = coroutine.create(function (a,b)
2206 print("co-body", a, b)
2207 local r = foo(a+1)
2208 print("co-body", r)
2209 local r, s = coroutine.yield(a+b, a-b)
2210 print("co-body", r, s)
2222 co-body 1 10
2226 co-body r
2227 main true 11 -9
2228 co-body x y
2236 <h1>3 - <a name="3">The Application Program Interface</a></h1>
2244 are declared in the header file <a name="pdf-lua.h"><code>lua.h</code></a>.
2249 any facility in the API may be provided as a macro instead.
2251 (except for the first argument, which is always a Lua state),
2252 and so do not generate any hidden side-effects.
2259 with a proper definition for the macro <a name="pdf-luai_apicheck"><code>luai_apicheck</code></a>,
2264 <h2>3.1 - <a name="3.1">The Stack</a></h2>
2267 Lua uses a <em>virtual stack</em> to pass values to and from C.
2268 Each element in this stack represents a Lua value
2273 Whenever Lua calls C, the called function gets a new stack,
2278 to be returned to the caller (see <a href="#lua_CFunction"><code>lua_CFunction</code></a>).
2283 most query operations in the API do not follow a strict stack discipline.
2286 A positive index represents an <em>absolute</em> stack position
2288 a negative index represents an <em>offset</em> relative to the top of the stack.
2294 index -1 also represents the last element
2296 and index <em>-n</em> represents the first element.
2306 <h2>3.2 - <a name="3.2">Stack Size</a></h2>
2313 You can use the function <a href="#lua_checkstack"><code>lua_checkstack</code></a>
2319 it ensures that at least <a name="pdf-LUA_MINSTACK"><code>LUA_MINSTACK</code></a> stack positions a…
2328 you have set through <a href="#lua_checkstack"><code>lua_checkstack</code></a>.
2343 <h2>3.3 - <a name="3.3">Pseudo-Indices</a></h2>
2348 <em>pseudo-indices</em>,
2351 Pseudo-indices are used to access the thread environment,
2354 and the upvalues of a C function (see <a href="#3.4">§3.4</a>).
2359 always at pseudo-index <a name="pdf-LUA_GLOBALSINDEX"><code>LUA_GLOBALSINDEX</code></a>.
2361 at pseudo-index <a name="pdf-LUA_ENVIRONINDEX"><code>LUA_ENVIRONINDEX</code></a>.
2367 For instance, to access the value of a global variable, do
2376 <h2>3.4 - <a name="3.4">C Closures</a></h2>
2379 When a C function is created,
2381 thus creating a <em>C closure</em>;
2384 (see <a href="#lua_pushcclosure"><code>lua_pushcclosure</code></a>).
2388 Whenever a C function is called,
2389 its upvalues are located at specific pseudo-indices.
2390 These pseudo-indices are produced by the macro
2391 <a name="lua_upvalueindex"><code>lua_upvalueindex</code></a>.
2392 The first value associated with a function is at position
2403 <h2>3.5 - <a name="3.5">Registry</a></h2>
2406 Lua provides a <em>registry</em>,
2407 a pre-defined table that can be used by any C code to
2409 This table is always located at pseudo-index
2410 <a name="pdf-LUA_REGISTRYINDEX"><code>LUA_REGISTRYINDEX</code></a>.
2414 Typically, you should use as key a string containing your library name
2415 or a light userdata with the address of a C object in your code.
2427 <h2>3.6 - <a name="3.6">Error Handling in C</a></h2>
2437 that is, it does a long jump.
2438 A <em>protected environment</em> uses <code>setjmp</code>
2439 to set a recover point;
2445 for instance due to a memory allocation error.
2451 Inside a C function you can throw an error by calling <a href="#lua_error"><code>lua_error</co…
2457 <h2>3.7 - <a name="3.7">Functions and Types</a></h2>
2463 <span class="apii">[-o, +p, <em>x</em>]</span>
2472 A field in the form <code>x|y</code> means the function can push (or pop)
2481 '<code>-</code>' means the function never throws any error;
2489 <hr><h3><a name="lua_Alloc"><code>lua_Alloc</code></a></h3>
2496 The type of the memory-allocation function used by Lua states.
2497 The allocator function must provide a
2501 <code>ud</code>, an opaque pointer passed to <a href="#lua_newstate"><code>lua_newstate</code></a>;
2502 <code>ptr</code>, a pointer to the block being allocated/reallocated/freed;
2520 Here is a simple implementation for the allocator function.
2521 It is used in the auxiliary library by <a href="#luaL_newstate"><code>luaL_newstate</code></a>.
2544 <hr><h3><a name="lua_atpanic"><code>lua_atpanic</code></a></h3><p>
2545 <span class="apii">[-0, +0, <em>-</em>]</span>
2549 Sets a new panic function and returns the old one.
2554 Lua calls a <em>panic function</em>
2558 never returning (e.g., doing a long jump).
2568 <hr><h3><a name="lua_call"><code>lua_call</code></a></h3><p>
2569 <span class="apii">[-(nargs + 1), +nresults, <em>e</em>]</span>
2573 Calls a function.
2577 To call a function you must use the following protocol:
2582 Finally you call <a href="#lua_call"><code>lua_call</code></a>;
2588 unless <code>nresults</code> is <a name="pdf-LUA_MULTRET"><code>LUA_MULTRET</code></a>.
2598 (with a <code>longjmp</code>).
2606 a = f("how", t.x, 14)
2614 lua_getfield(L, -1, "x"); /* push result of t.x (2nd arg) */
2615 lua_remove(L, -2); /* remove 't' from the stack */
2618 lua_setfield(L, LUA_GLOBALSINDEX, "a"); /* set global 'a' */
2628 <hr><h3><a name="lua_CFunction"><code>lua_CFunction</code></a></h3>
2637 a C function must use the following protocol,
2639 a C function receives its arguments from Lua in its stack
2645 To return values to Lua, a C function just pushes them onto the stack,
2650 Like a Lua function, a C function called by Lua can also return
2655 As an example, the following function receives a variable number
2679 <hr><h3><a name="lua_checkstack"><code>lua_checkstack</code></a></h3><p>
2680 <span class="apii">[-0, +0, <em>m</em>]</span>
2694 <hr><h3><a name="lua_close"><code>lua_close</code></a></h3><p>
2695 <span class="apii">[-0, +0, <em>-</em>]</span>
2700 (calling the corresponding garbage-collection metamethods, if any)
2704 On the other hand, long-running programs,
2705 such as a daemon or a web server,
2713 <hr><h3><a name="lua_concat"><code>lua_concat</code></a></h3><p>
2714 <span class="apii">[-n, +1, <em>e</em>]</span>
2724 (see <a href="#2.5.4">§2.5.4</a>).
2730 <hr><h3><a name="lua_cpcall"><code>lua_cpcall</code></a></h3><p>
2731 <span class="apii">[-0, +(0|1), <em>-</em>]</span>
2737 a light userdata containing <code>ud</code>.
2739 <a href="#lua_cpcall"><code>lua_cpcall</code></a> returns the same error codes as <a href="#lua_pca…
2748 <hr><h3><a name="lua_createtable"><code>lua_createtable</code></a></h3><p>
2749 <span class="apii">[-0, +1, <em>m</em>]</span>
2753 Creates a new empty table and pushes it onto the stack.
2754 The new table has space pre-allocated
2755 for <code>narr</code> array elements and <code>nrec</code> non-array elements.
2756 This pre-allocation is useful when you know exactly how many elements
2758 Otherwise you can use the function <a href="#lua_newtable"><code>lua_newtable</code></a>.
2764 <hr><h3><a name="lua_dump"><code>lua_dump</code></a></h3><p>
2765 <span class="apii">[-0, +0, <em>m</em>]</span>
2769 Dumps a function as a binary chunk.
2770 Receives a Lua function on the top of the stack
2771 and produces a binary chunk that,
2773 results in a function equivalent to the one dumped.
2775 <a href="#lua_dump"><code>lua_dump</code></a> calls function <code>writer</code> (see <a href="#lua…
2793 <hr><h3><a name="lua_equal"><code>lua_equal</code></a></h3><p>
2794 <span class="apii">[-0, +0, <em>e</em>]</span>
2809 <hr><h3><a name="lua_error"><code>lua_error</code></a></h3><p>
2810 <span class="apii">[-1, +0, <em>v</em>]</span>
2814 Generates a Lua error.
2815 The error message (which can actually be a Lua value of any type)
2817 This function does a long jump,
2819 (see <a href="#luaL_error"><code>luaL_error</code></a>).
2825 <hr><h3><a name="lua_gc"><code>lua_gc</code></a></h3><p>
2826 <span class="apii">[-0, +0, <em>e</em>]</span>
2848 performs a full garbage-collection cycle.
2863 (larger values mean more steps) in a non-specified way.
2866 The function returns 1 if the step finished a
2867 garbage-collection cycle.
2872 for the <em>pause</em> of the collector (see <a href="#2.10">§2.10</a>).
2878 the collector (see <a href="#2.10">§2.10</a>).
2887 <hr><h3><a name="lua_getallocf"><code>lua_getallocf</code></a></h3><p>
2888 <span class="apii">[-0, +0, <em>-</em>]</span>
2892 Returns the memory-allocation function of a given state.
2894 opaque pointer passed to <a href="#lua_newstate"><code>lua_newstate</code></a>.
2900 <hr><h3><a name="lua_getfenv"><code>lua_getfenv</code></a></h3><p>
2901 <span class="apii">[-0, +1, <em>-</em>]</span>
2912 <hr><h3><a name="lua_getfield"><code>lua_getfield</code></a></h3><p>
2913 <span class="apii">[-0, +1, <em>e</em>]</span>
2919 As in Lua, this function may trigger a metamethod
2920 for the "index" event (see <a href="#2.8">§2.8</a>).
2926 <hr><h3><a name="lua_getglobal"><code>lua_getglobal</code></a></h3><p>
2927 <span class="apii">[-0, +1, <em>e</em>]</span>
2932 It is defined as a macro:
2941 <hr><h3><a name="lua_getmetatable"><code>lua_getmetatable</code></a></h3><p>
2942 <span class="apii">[-0, +(0|1), <em>-</em>]</span>
2949 or if the value does not have a metatable,
2956 <hr><h3><a name="lua_gettable"><code>lua_gettable</code></a></h3><p>
2957 <span class="apii">[-1, +1, <em>e</em>]</span>
2969 As in Lua, this function may trigger a metamethod
2970 for the "index" event (see <a href="#2.8">§2.8</a>).
2976 <hr><h3><a name="lua_gettop"><code>lua_gettop</code></a></h3><p>
2977 <span class="apii">[-0, +0, <em>-</em>]</span>
2990 <hr><h3><a name="lua_insert"><code>lua_insert</code></a></h3><p>
2991 <span class="apii">[-1, +1, <em>-</em>]</span>
2997 Cannot be called with a pseudo-index,
2998 because a pseudo-index is not an actual stack position.
3004 <hr><h3><a name="lua_Integer"><code>lua_Integer</code></a></h3>
3012 By default it is a <code>ptrdiff_t</code>,
3020 <hr><h3><a name="lua_isboolean"><code>lua_isboolean</code></a></h3><p>
3021 <span class="apii">[-0, +0, <em>-</em>]</span>
3032 <hr><h3><a name="lua_iscfunction"><code>lua_iscfunction</code></a></h3><p>
3033 <span class="apii">[-0, +0, <em>-</em>]</span>
3037 Returns 1 if the value at the given acceptable index is a C function,
3044 <hr><h3><a name="lua_isfunction"><code>lua_isfunction</code></a></h3><p>
3045 <span class="apii">[-0, +0, <em>-</em>]</span>
3049 Returns 1 if the value at the given acceptable index is a function
3056 <hr><h3><a name="lua_islightuserdata"><code>lua_islightuserdata</code></a></h3><p>
3057 <span class="apii">[-0, +0, <em>-</em>]</span>
3061 Returns 1 if the value at the given acceptable index is a light userdata,
3068 <hr><h3><a name="lua_isnil"><code>lua_isnil</code></a></h3><p>
3069 <span class="apii">[-0, +0, <em>-</em>]</span>
3080 <hr><h3><a name="lua_isnone"><code>lua_isnone</code></a></h3><p>
3081 <span class="apii">[-0, +0, <em>-</em>]</span>
3093 <hr><h3><a name="lua_isnoneornil"><code>lua_isnoneornil</code></a></h3><p>
3094 <span class="apii">[-0, +0, <em>-</em>]</span>
3107 <hr><h3><a name="lua_isnumber"><code>lua_isnumber</code></a></h3><p>
3108 <span class="apii">[-0, +0, <em>-</em>]</span>
3112 Returns 1 if the value at the given acceptable index is a number
3113 or a string convertible to a number,
3120 <hr><h3><a name="lua_isstring"><code>lua_isstring</code></a></h3><p>
3121 <span class="apii">[-0, +0, <em>-</em>]</span>
3125 Returns 1 if the value at the given acceptable index is a string
3126 or a number (which is always convertible to a string),
3133 <hr><h3><a name="lua_istable"><code>lua_istable</code></a></h3><p>
3134 <span class="apii">[-0, +0, <em>-</em>]</span>
3138 Returns 1 if the value at the given acceptable index is a table,
3145 <hr><h3><a name="lua_isthread"><code>lua_isthread</code></a></h3><p>
3146 <span class="apii">[-0, +0, <em>-</em>]</span>
3150 Returns 1 if the value at the given acceptable index is a thread,
3157 <hr><h3><a name="lua_isuserdata"><code>lua_isuserdata</code></a></h3><p>
3158 <span class="apii">[-0, +0, <em>-</em>]</span>
3162 Returns 1 if the value at the given acceptable index is a userdata
3169 <hr><h3><a name="lua_lessthan"><code>lua_lessthan</code></a></h3><p>
3170 <span class="apii">[-0, +0, <em>e</em>]</span>
3185 <hr><h3><a name="lua_load"><code>lua_load</code></a></h3><p>
3186 <span class="apii">[-0, +1, <em>-</em>]</span>
3193 Loads a Lua chunk.
3195 <a href="#lua_load"><code>lua_load</code></a> pushes the compiled chunk as a Lua
3198 The return values of <a href="#lua_load"><code>lua_load</code></a> are:
3204 <li><b><a name="pdf-LUA_ERRSYNTAX"><code>LUA_ERRSYNTAX</code></a>:</b>
3205 syntax error during pre-compilation;</li>
3207 <li><b><a href="#pdf-LUA_ERRMEM"><code>LUA_ERRMEM</code></a>:</b>
3213 This function only loads a chunk;
3218 <a href="#lua_load"><code>lua_load</code></a> automatically detects whether the chunk is text or bi…
3223 The <a href="#lua_load"><code>lua_load</code></a> function uses a user-supplied <code>reader</code>…
3224 to read the chunk (see <a href="#lua_Reader"><code>lua_Reader</code></a>).
3229 The <code>chunkname</code> argument gives a name to the chunk,
3230 which is used for error messages and in debug information (see <a href="#3.8">§3.8</a>).
3236 <hr><h3><a name="lua_newstate"><code>lua_newstate</code></a></h3><p>
3237 <span class="apii">[-0, +0, <em>-</em>]</span>
3241 Creates a new, independent state.
3253 <hr><h3><a name="lua_newtable"><code>lua_newtable</code></a></h3><p>
3254 <span class="apii">[-0, +1, <em>m</em>]</span>
3258 Creates a new empty table and pushes it onto the stack.
3265 <hr><h3><a name="lua_newthread"><code>lua_newthread</code></a></h3><p>
3266 <span class="apii">[-0, +1, <em>m</em>]</span>
3270 Creates a new thread, pushes it on the stack,
3271 and returns a pointer to a <a href="#lua_State"><code>lua_State</code></a> that represents this new…
3278 There is no explicit function to close or to destroy a thread.
3286 <hr><h3><a name="lua_newuserdata"><code>lua_newuserdata</code></a></h3><p>
3287 <span class="apii">[-0, +1, <em>m</em>]</span>
3291 This function allocates a new block of memory with the given size,
3292 pushes onto the stack a new full userdata with the block address,
3298 A <em>full userdata</em> represents a block of memory.
3299 It is an object (like a table):
3302 A full userdata is only equal to itself (under raw equality).
3306 When Lua collects a full userdata with a <code>gc</code> metamethod,
3315 <hr><h3><a name="lua_next"><code>lua_next</code></a></h3><p>
3316 <span class="apii">[-1, +(2|0), <em>e</em>]</span>
3320 Pops a key from the stack,
3321 and pushes a key-value pair from the table at the given index
3324 then <a href="#lua_next"><code>lua_next</code></a> returns 0 (and pushes nothing).
3328 A typical traversal looks like this:
3334 /* uses 'key' (at index -2) and 'value' (at index -1) */
3335 printf("%s - %s\n",
3336 lua_typename(L, lua_type(L, -2)),
3337 lua_typename(L, lua_type(L, -1)));
3344 While traversing a table,
3345 do not call <a href="#lua_tolstring"><code>lua_tolstring</code></a> directly on a key,
3346 unless you know that the key is actually a string.
3347 Recall that <a href="#lua_tolstring"><code>lua_tolstring</code></a> <em>changes</em>
3349 this confuses the next call to <a href="#lua_next"><code>lua_next</code></a>.
3355 <hr><h3><a name="lua_Number"><code>lua_Number</code></a></h3>
3371 <hr><h3><a name="lua_objlen"><code>lua_objlen</code></a></h3><p>
3372 <span class="apii">[-0, +0, <em>-</em>]</span>
3387 <hr><h3><a name="lua_pcall"><code>lua_pcall</code></a></h3><p>
3388 <span class="apii">[-(nargs + 1), +(nresults|1), <em>-</em>]</span>
3392 Calls a function in protected mode.
3397 in <a href="#lua_call"><code>lua_call</code></a>.
3399 <a href="#lua_pcall"><code>lua_pcall</code></a> behaves exactly like <a href="#lua_call"><code>lua_…
3401 <a href="#lua_pcall"><code>lua_pcall</code></a> catches it,
3402 pushes a single value on the stack (the error message),
3404 Like <a href="#lua_call"><code>lua_call</code></a>,
3405 <a href="#lua_pcall"><code>lua_pcall</code></a> always removes the function
3415 (In the current implementation, this index cannot be a pseudo-index.)
3418 …n value will be the message returned on the stack by <a href="#lua_pcall"><code>lua_pcall</code></…
3423 information to the error message, such as a stack traceback.
3424 …h information cannot be gathered after the return of <a href="#lua_pcall"><code>lua_pcall</code></…
3429 The <a href="#lua_pcall"><code>lua_pcall</code></a> function returns 0 in case of success
3435 <li><b><a name="pdf-LUA_ERRRUN"><code>LUA_ERRRUN</code></a>:</b>
3436 a runtime error.
3439 <li><b><a name="pdf-LUA_ERRMEM"><code>LUA_ERRMEM</code></a>:</b>
3444 <li><b><a name="pdf-LUA_ERRERR"><code>LUA_ERRERR</code></a>:</b>
3453 <hr><h3><a name="lua_pop"><code>lua_pop</code></a></h3><p>
3454 <span class="apii">[-n, +0, <em>-</em>]</span>
3464 <hr><h3><a name="lua_pushboolean"><code>lua_pushboolean</code></a></h3><p>
3465 <span class="apii">[-0, +1, <em>-</em>]</span>
3469 Pushes a boolean value with value <code>b</code> onto the stack.
3475 <hr><h3><a name="lua_pushcclosure"><code>lua_pushcclosure</code></a></h3><p>
3476 <span class="apii">[-n, +1, <em>m</em>]</span>
3480 Pushes a new C closure onto the stack.
3484 When a C function is created,
3486 thus creating a C closure (see <a href="#3.4">§3.4</a>);
3488 To associate values with a C function,
3491 Then <a href="#lua_pushcclosure"><code>lua_pushcclosure</code></a>
3495 <a href="#lua_pushcclosure"><code>lua_pushcclosure</code></a> also pops these values from the stack.
3505 <hr><h3><a name="lua_pushcfunction"><code>lua_pushcfunction</code></a></h3><p>
3506 <span class="apii">[-0, +1, <em>m</em>]</span>
3510 Pushes a C function onto the stack.
3511 This function receives a pointer to a C function
3512 and pushes onto the stack a Lua value of type <code>function</code> that,
3519 and return its results (see <a href="#lua_CFunction"><code>lua_CFunction</code></a>).
3523 <code>lua_pushcfunction</code> is defined as a macro:
3532 <hr><h3><a name="lua_pushfstring"><code>lua_pushfstring</code></a></h3><p>
3533 <span class="apii">[-0, +1, <em>m</em>]</span>
3537 Pushes onto the stack a formatted string
3538 and returns a pointer to this string.
3546 the result is a Lua string and Lua takes care of memory allocation
3554 '<code>%%</code>' (inserts a '<code>%</code>' in the string),
3555 '<code>%s</code>' (inserts a zero-terminated string, with no size restrictions),
3556 '<code>%f</code>' (inserts a <a href="#lua_Number"><code>lua_Number</code></a>),
3557 '<code>%p</code>' (inserts a pointer as a hexadecimal numeral),
3559 '<code>%c</code>' (inserts an <code>int</code> as a character).
3567 <hr><h3><a name="lua_pushinteger"><code>lua_pushinteger</code></a></h3><p>
3568 <span class="apii">[-0, +1, <em>-</em>]</span>
3572 Pushes a number with value <code>n</code> onto the stack.
3578 <hr><h3><a name="lua_pushlightuserdata"><code>lua_pushlightuserdata</code></a></h3><p>
3579 <span class="apii">[-0, +1, <em>-</em>]</span>
3583 Pushes a light userdata onto the stack.
3588 A <em>light userdata</em> represents a pointer.
3589 It is a value (like a number):
3592 A light userdata is equal to "any"
3599 <hr><h3><a name="lua_pushliteral"><code>lua_pushliteral</code></a></h3><p>
3600 <span class="apii">[-0, +1, <em>m</em>]</span>
3604 This macro is equivalent to <a href="#lua_pushlstring"><code>lua_pushlstring</code></a>,
3605 but can be used only when <code>s</code> is a literal string.
3612 <hr><h3><a name="lua_pushlstring"><code>lua_pushlstring</code></a></h3><p>
3613 <span class="apii">[-0, +1, <em>m</em>]</span>
3628 <hr><h3><a name="lua_pushnil"><code>lua_pushnil</code></a></h3><p>
3629 <span class="apii">[-0, +1, <em>-</em>]</span>
3633 Pushes a nil value onto the stack.
3639 <hr><h3><a name="lua_pushnumber"><code>lua_pushnumber</code></a></h3><p>
3640 <span class="apii">[-0, +1, <em>-</em>]</span>
3644 Pushes a number with value <code>n</code> onto the stack.
3650 <hr><h3><a name="lua_pushstring"><code>lua_pushstring</code></a></h3><p>
3651 <span class="apii">[-0, +1, <em>m</em>]</span>
3655 Pushes the zero-terminated string pointed to by <code>s</code>
3667 <hr><h3><a name="lua_pushthread"><code>lua_pushthread</code></a></h3><p>
3668 <span class="apii">[-0, +1, <em>-</em>]</span>
3679 <hr><h3><a name="lua_pushvalue"><code>lua_pushvalue</code></a></h3><p>
3680 <span class="apii">[-0, +1, <em>-</em>]</span>
3684 Pushes a copy of the element at the given valid index
3691 <hr><h3><a name="lua_pushvfstring"><code>lua_pushvfstring</code></a></h3><p>
3692 <span class="apii">[-0, +1, <em>m</em>]</span>
3698 Equivalent to <a href="#lua_pushfstring"><code>lua_pushfstring</code></a>, except that it receives …
3699 instead of a variable number of arguments.
3705 <hr><h3><a name="lua_rawequal"><code>lua_rawequal</code></a></h3><p>
3706 <span class="apii">[-0, +0, <em>-</em>]</span>
3720 <hr><h3><a name="lua_rawget"><code>lua_rawget</code></a></h3><p>
3721 <span class="apii">[-1, +1, <em>-</em>]</span>
3725 Similar to <a href="#lua_gettable"><code>lua_gettable</code></a>, but does a raw access
3732 <hr><h3><a name="lua_rawgeti"><code>lua_rawgeti</code></a></h3><p>
3733 <span class="apii">[-0, +1, <em>-</em>]</span>
3746 <hr><h3><a name="lua_rawset"><code>lua_rawset</code></a></h3><p>
3747 <span class="apii">[-2, +0, <em>m</em>]</span>
3751 Similar to <a href="#lua_settable"><code>lua_settable</code></a>, but does a raw assignment
3758 <hr><h3><a name="lua_rawseti"><code>lua_rawseti</code></a></h3><p>
3759 <span class="apii">[-1, +0, <em>m</em>]</span>
3777 <hr><h3><a name="lua_Reader"><code>lua_Reader</code></a></h3>
3783 The reader function used by <a href="#lua_load"><code>lua_load</code></a>.
3785 <a href="#lua_load"><code>lua_load</code></a> calls the reader,
3787 The reader must return a pointer to a block of memory
3788 with a new piece of the chunk
3799 <hr><h3><a name="lua_register"><code>lua_register</code></a></h3><p>
3800 <span class="apii">[-0, +0, <em>e</em>]</span>
3807 It is defined as a macro:
3817 <hr><h3><a name="lua_remove"><code>lua_remove</code></a></h3><p>
3818 <span class="apii">[-1, +0, <em>-</em>]</span>
3824 Cannot be called with a pseudo-index,
3825 because a pseudo-index is not an actual stack position.
3831 <hr><h3><a name="lua_replace"><code>lua_replace</code></a></h3><p>
3832 <span class="apii">[-1, +0, <em>-</em>]</span>
3844 <hr><h3><a name="lua_resume"><code>lua_resume</code></a></h3><p>
3845 <span class="apii">[-?, +?, <em>-</em>]</span>
3849 Starts and resumes a coroutine in a given thread.
3853 To start a coroutine, you first create a new thread
3854 (see <a href="#lua_newthread"><code>lua_newthread</code></a>);
3856 then you call <a href="#lua_resume"><code>lua_resume</code></a>,
3859 … it returns, the stack contains all values passed to <a href="#lua_yield"><code>lua_yield</code></…
3861 <a href="#lua_resume"><code>lua_resume</code></a> returns
3862 <a href="#pdf-LUA_YIELD"><code>LUA_YIELD</code></a> if the coroutine yields,
3865 or an error code in case of errors (see <a href="#lua_pcall"><code>lua_pcall</code></a>).
3870 To restart a coroutine, you put on its stack only the values to
3872 and then call <a href="#lua_resume"><code>lua_resume</code></a>.
3878 <hr><h3><a name="lua_setallocf"><code>lua_setallocf</code></a></h3><p>
3879 <span class="apii">[-0, +0, <em>-</em>]</span>
3883 Changes the allocator function of a given state to <code>f</code>
3890 <hr><h3><a name="lua_setfenv"><code>lua_setfenv</code></a></h3><p>
3891 <span class="apii">[-1, +0, <em>-</em>]</span>
3895 Pops a table from the stack and sets it as
3898 neither a function nor a thread nor a userdata,
3899 <a href="#lua_setfenv"><code>lua_setfenv</code></a> returns 0.
3906 <hr><h3><a name="lua_setfield"><code>lua_setfield</code></a></h3><p>
3907 <span class="apii">[-1, +0, <em>e</em>]</span>
3918 As in Lua, this function may trigger a metamethod
3919 for the "newindex" event (see <a href="#2.8">§2.8</a>).
3925 <hr><h3><a name="lua_setglobal"><code>lua_setglobal</code></a></h3><p>
3926 <span class="apii">[-1, +0, <em>e</em>]</span>
3930 Pops a value from the stack and
3932 It is defined as a macro:
3941 <hr><h3><a name="lua_setmetatable"><code>lua_setmetatable</code></a></h3><p>
3942 <span class="apii">[-1, +0, <em>-</em>]</span>
3946 Pops a table from the stack and
3954 <hr><h3><a name="lua_settable"><code>lua_settable</code></a></h3><p>
3955 <span class="apii">[-2, +0, <em>e</em>]</span>
3967 As in Lua, this function may trigger a metamethod
3968 for the "newindex" event (see <a href="#2.8">§2.8</a>).
3974 <hr><h3><a name="lua_settop"><code>lua_settop</code></a></h3><p>
3975 <span class="apii">[-?, +?, <em>-</em>]</span>
3989 <hr><h3><a name="lua_State"><code>lua_State</code></a></h3>
3993 Opaque structure that keeps the whole state of a Lua interpreter.
3996 All information about a state is kept in this structure.
4000 A pointer to this state must be passed as the first argument to
4001 every function in the library, except to <a href="#lua_newstate"><code>lua_newstate</code></a>,
4002 which creates a Lua state from scratch.
4008 <hr><h3><a name="lua_status"><code>lua_status</code></a></h3><p>
4009 <span class="apii">[-0, +0, <em>-</em>]</span>
4017 The status can be 0 for a normal thread,
4019 or <a name="pdf-LUA_YIELD"><code>LUA_YIELD</code></a> if the thread is suspended.
4025 <hr><h3><a name="lua_toboolean"><code>lua_toboolean</code></a></h3><p>
4026 <span class="apii">[-0, +0, <em>-</em>]</span>
4030 Converts the Lua value at the given acceptable index to a C boolean
4033 <a href="#lua_toboolean"><code>lua_toboolean</code></a> returns 1 for any Lua value
4036 It also returns 0 when called with a non-valid index.
4038 use <a href="#lua_isboolean"><code>lua_isboolean</code></a> to test the value's type.)
4044 <hr><h3><a name="lua_tocfunction"><code>lua_tocfunction</code></a></h3><p>
4045 <span class="apii">[-0, +0, <em>-</em>]</span>
4049 Converts a value at the given acceptable index to a C function.
4050 That value must be a C function;
4057 <hr><h3><a name="lua_tointeger"><code>lua_tointeger</code></a></h3><p>
4058 <span class="apii">[-0, +0, <em>-</em>]</span>
4063 to the signed integral type <a href="#lua_Integer"><code>lua_Integer</code></a>.
4064 The Lua value must be a number or a string convertible to a number
4065 (see <a href="#2.2.1">§2.2.1</a>);
4066 otherwise, <a href="#lua_tointeger"><code>lua_tointeger</code></a> returns 0.
4071 it is truncated in some non-specified way.
4077 <hr><h3><a name="lua_tolstring"><code>lua_tolstring</code></a></h3><p>
4078 <span class="apii">[-0, +0, <em>m</em>]</span>
4082 Converts the Lua value at the given acceptable index to a C string.
4085 The Lua value must be a string or a number;
4087 If the value is a number,
4088 then <a href="#lua_tolstring"><code>lua_tolstring</code></a> also
4089 <em>changes the actual value in the stack to a string</em>.
4090 (This change confuses <a href="#lua_next"><code>lua_next</code></a>
4091 when <a href="#lua_tolstring"><code>lua_tolstring</code></a> is applied to keys during a table trav…
4095 <a href="#lua_tolstring"><code>lua_tolstring</code></a> returns a fully aligned pointer
4096 to a string inside the Lua state.
4097 This string always has a zero ('<code>\0</code>')
4101 …ere is no guarantee that the pointer returned by <a href="#lua_tolstring"><code>lua_tolstring</cod…
4108 <hr><h3><a name="lua_tonumber"><code>lua_tonumber</code></a></h3><p>
4109 <span class="apii">[-0, +0, <em>-</em>]</span>
4114 to the C type <a href="#lua_Number"><code>lua_Number</code></a> (see <a href="#lua_Number"><co…
4115 The Lua value must be a number or a string convertible to a number
4116 (see <a href="#2.2.1">§2.2.1</a>);
4117 otherwise, <a href="#lua_tonumber"><code>lua_tonumber</code></a> returns 0.
4123 <hr><h3><a name="lua_topointer"><code>lua_topointer</code></a></h3><p>
4124 <span class="apii">[-0, +0, <em>-</em>]</span>
4128 Converts the value at the given acceptable index to a generic
4130 The value can be a userdata, a table, a thread, or a function;
4131 otherwise, <a href="#lua_topointer"><code>lua_topointer</code></a> returns <code>NULL</code>.
4143 <hr><h3><a name="lua_tostring"><code>lua_tostring</code></a></h3><p>
4144 <span class="apii">[-0, +0, <em>m</em>]</span>
4148 Equivalent to <a href="#lua_tolstring"><code>lua_tolstring</code></a> with <code>len</code> equal t…
4154 <hr><h3><a name="lua_tothread"><code>lua_tothread</code></a></h3><p>
4155 <span class="apii">[-0, +0, <em>-</em>]</span>
4159 Converts the value at the given acceptable index to a Lua thread
4161 This value must be a thread;
4168 <hr><h3><a name="lua_touserdata"><code>lua_touserdata</code></a></h3><p>
4169 <span class="apii">[-0, +0, <em>-</em>]</span>
4173 If the value at the given acceptable index is a full userdata,
4175 If the value is a light userdata,
4183 <hr><h3><a name="lua_type"><code>lua_type</code></a></h3><p>
4184 <span class="apii">[-0, +0, <em>-</em>]</span>
4189 or <code>LUA_TNONE</code> for a non-valid index
4191 The types returned by <a href="#lua_type"><code>lua_type</code></a> are coded by the following cons…
4208 <hr><h3><a name="lua_typename"><code>lua_typename</code></a></h3><p>
4209 <span class="apii">[-0, +0, <em>-</em>]</span>
4214 which must be one the values returned by <a href="#lua_type"><code>lua_type</code></a>.
4220 <hr><h3><a name="lua_Writer"><code>lua_Writer</code></a></h3>
4227 The type of the writer function used by <a href="#lua_dump"><code>lua_dump</code></a>.
4229 <a href="#lua_dump"><code>lua_dump</code></a> calls the writer,
4232 and the <code>data</code> parameter supplied to <a href="#lua_dump"><code>lua_dump</code></a>.
4238 any other value means an error and stops <a href="#lua_dump"><code>lua_dump</code></a> from
4245 <hr><h3><a name="lua_xmove"><code>lua_xmove</code></a></h3><p>
4246 <span class="apii">[-?, +?, <em>-</em>]</span>
4261 <hr><h3><a name="lua_yield"><code>lua_yield</code></a></h3><p>
4262 <span class="apii">[-?, +?, <em>-</em>]</span>
4266 Yields a coroutine.
4271 return expression of a C function, as follows:
4276 When a C function calls <a href="#lua_yield"><code>lua_yield</code></a> in that way,
4278 and the call to <a href="#lua_resume"><code>lua_resume</code></a> that started this coroutine retur…
4280 that are passed as results to <a href="#lua_resume"><code>lua_resume</code></a>.
4288 <h2>3.8 - <a name="3.8">The Debug Interface</a></h2>
4291 Lua has no built-in debugging facilities.
4292 Instead, it offers a special interface
4300 <hr><h3><a name="lua_Debug"><code>lua_Debug</code></a></h3>
4317 A structure used to carry different pieces of
4319 <a href="#lua_getstack"><code>lua_getstack</code></a> fills only the private part
4321 To fill the other fields of <a href="#lua_Debug"><code>lua_Debug</code></a> with useful information,
4322 call <a href="#lua_getinfo"><code>lua_getinfo</code></a>.
4326 The fields of <a href="#lua_Debug"><code>lua_Debug</code></a> have the following meaning:
4331 If the function was defined in a string,
4333 If the function was defined in a file,
4334 then <code>source</code> starts with a '<code>@</code>' followed by the file name.
4338 a "printable" version of <code>source</code>, to be used in error messages.
4350 the string <code>"Lua"</code> if the function is a Lua function,
4351 <code>"C"</code> if it is a C function,
4352 <code>"main"</code> if it is the main part of a chunk,
4353 and <code>"tail"</code> if it was a function that did a tail call.
4361 <code>currentline</code> is set to -1.
4365 a reasonable name for the given function.
4366 Because functions in Lua are first-class values,
4367 they do not have a fixed name:
4369 while others can be stored only in a table field.
4371 called to find a suitable name.
4372 If it cannot find a name,
4394 <hr><h3><a name="lua_gethook"><code>lua_gethook</code></a></h3><p>
4395 <span class="apii">[-0, +0, <em>-</em>]</span>
4405 <hr><h3><a name="lua_gethookcount"><code>lua_gethookcount</code></a></h3><p>
4406 <span class="apii">[-0, +0, <em>-</em>]</span>
4416 <hr><h3><a name="lua_gethookmask"><code>lua_gethookmask</code></a></h3><p>
4417 <span class="apii">[-0, +0, <em>-</em>]</span>
4427 <hr><h3><a name="lua_getinfo"><code>lua_getinfo</code></a></h3><p>
4428 <span class="apii">[-(0|1), +(0|1|2), <em>m</em>]</span>
4432 Returns information about a specific function or function invocation.
4436 To get information about a function invocation,
4437 the parameter <code>ar</code> must be a valid activation record that was
4438 filled by a previous call to <a href="#lua_getstack"><code>lua_getstack</code></a> or
4439 given as argument to a hook (see <a href="#lua_Hook"><code>lua_Hook</code></a>).
4443 To get information about a function you push it onto the stack
4447 For instance, to know in which line a function <code>f</code> was defined,
4460 a value to be pushed on the stack:
4484 pushes onto the stack a table whose indices are the
4486 (A <em>valid line</em> is a line with some associated code,
4487 that is, a line where you can put a break point.
4488 Non-valid lines include empty lines and comments.)
4501 <hr><h3><a name="lua_getlocal"><code>lua_getlocal</code></a></h3><p>
4502 <span class="apii">[-0, +(0|1), <em>-</em>]</span>
4506 Gets information about a local variable of a given activation record.
4507 The parameter <code>ar</code> must be a valid activation record that was
4508 filled by a previous call to <a href="#lua_getstack"><code>lua_getstack</code></a> or
4509 given as argument to a hook (see <a href="#lua_Hook"><code>lua_Hook</code></a>).
4513 <a href="#lua_getlocal"><code>lua_getlocal</code></a> pushes the variable's value onto the stack
4532 <hr><h3><a name="lua_getstack"><code>lua_getstack</code></a></h3><p>
4533 <span class="apii">[-0, +0, <em>-</em>]</span>
4541 This function fills parts of a <a href="#lua_Debug"><code>lua_Debug</code></a> structure with
4543 of the function executing at a given level.
4546 When there are no errors, <a href="#lua_getstack"><code>lua_getstack</code></a> returns 1;
4547 when called with a level greater than the stack depth,
4554 <hr><h3><a name="lua_getupvalue"><code>lua_getupvalue</code></a></h3><p>
4555 <span class="apii">[-0, +(0|1), <em>-</em>]</span>
4559 Gets information about a closure's upvalue.
4563 <a href="#lua_getupvalue"><code>lua_getupvalue</code></a> gets the index <code>n</code> of an upval…
4576 as a name for all upvalues.
4582 <hr><h3><a name="lua_Hook"><code>lua_Hook</code></a></h3>
4590 Whenever a hook is called, its <code>ar</code> argument has its field
4593 <a name="pdf-LUA_HOOKCALL"><code>LUA_HOOKCALL</code></a>, <a name="pdf-LUA_HOOKRET"><code>LUA_HOOKR…
4594 <a name="pdf-LUA_HOOKTAILRET"><code>LUA_HOOKTAILRET</code></a>, <a name="pdf-LUA_HOOKLINE"><code>LU…
4595 and <a name="pdf-LUA_HOOKCOUNT"><code>LUA_HOOKCOUNT</code></a>.
4598 the hook must call <a href="#lua_getinfo"><code>lua_getinfo</code></a>.
4601 In the latter case, Lua is simulating a return from
4602 a function that did a tail call;
4603 in this case, it is useless to call <a href="#lua_getinfo"><code>lua_getinfo</code></a>.
4607 While Lua is running a hook, it disables other calls to hooks.
4608 Therefore, if a hook calls back Lua to execute a function or a chunk,
4615 <hr><h3><a name="lua_sethook"><code>lua_sethook</code></a></h3><p>
4616 <span class="apii">[-0, +0, <em>-</em>]</span>
4626 it is formed by a bitwise or of the constants
4627 <a name="pdf-LUA_MASKCALL"><code>LUA_MASKCALL</code></a>,
4628 <a name="pdf-LUA_MASKRET"><code>LUA_MASKRET</code></a>,
4629 <a name="pdf-LUA_MASKLINE"><code>LUA_MASKLINE</code></a>,
4630 and <a name="pdf-LUA_MASKCOUNT"><code>LUA_MASKCOUNT</code></a>.
4637 <li><b>The call hook:</b> is called when the interpreter calls a function.
4642 <li><b>The return hook:</b> is called when the interpreter returns from a function.
4648 start the execution of a new line of code,
4650 (This event only happens while Lua is executing a Lua function.)
4655 (This event only happens while Lua is executing a Lua function.)
4661 A hook is disabled by setting <code>mask</code> to zero.
4667 <hr><h3><a name="lua_setlocal"><code>lua_setlocal</code></a></h3><p>
4668 <span class="apii">[-(0|1), +0, <em>-</em>]</span>
4672 Sets the value of a local variable of a given activation record.
4673 …ters <code>ar</code> and <code>n</code> are as in <a href="#lua_getlocal"><code>lua_getlocal</code…
4674 (see <a href="#lua_getlocal"><code>lua_getlocal</code></a>).
4675 <a href="#lua_setlocal"><code>lua_setlocal</code></a> assigns the value at the top of the stack
4689 <hr><h3><a name="lua_setupvalue"><code>lua_setupvalue</code></a></h3><p>
4690 <span class="apii">[-(0|1), +0, <em>-</em>]</span>
4694 Sets the value of a closure's upvalue.
4698 …ncindex</code> and <code>n</code> are as in the <a href="#lua_getupvalue"><code>lua_getupvalue</co…
4699 (see <a href="#lua_getupvalue"><code>lua_getupvalue</code></a>).
4712 <h1>4 - <a name="4">The Auxiliary Library</a></h1>
4720 the auxiliary library provides higher-level functions for some
4727 have a prefix <code>luaL_</code>.
4747 <h2>4.1 - <a name="4.1">Functions and Types</a></h2>
4755 <hr><h3><a name="luaL_addchar"><code>luaL_addchar</code></a></h3><p>
4756 <span class="apii">[-0, +0, <em>m</em>]</span>
4761 (see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>).
4767 <hr><h3><a name="luaL_addlstring"><code>luaL_addlstring</code></a></h3><p>
4768 <span class="apii">[-0, +0, <em>m</em>]</span>
4774 (see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>).
4781 <hr><h3><a name="luaL_addsize"><code>luaL_addsize</code></a></h3><p>
4782 <span class="apii">[-0, +0, <em>m</em>]</span>
4786 Adds to the buffer <code>B</code> (see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>)
4787 a string of length <code>n</code> previously copied to the
4788 buffer area (see <a href="#luaL_prepbuffer"><code>luaL_prepbuffer</code></a>).
4794 <hr><h3><a name="luaL_addstring"><code>luaL_addstring</code></a></h3><p>
4795 <span class="apii">[-0, +0, <em>m</em>]</span>
4799 Adds the zero-terminated string pointed to by <code>s</code>
4801 (see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>).
4808 <hr><h3><a name="luaL_addvalue"><code>luaL_addvalue</code></a></h3><p>
4809 <span class="apii">[-1, +0, <em>m</em>]</span>
4815 (see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>).
4828 <hr><h3><a name="luaL_argcheck"><code>luaL_argcheck</code></a></h3><p>
4829 <span class="apii">[-0, +0, <em>v</em>]</span>
4847 <hr><h3><a name="luaL_argerror"><code>luaL_argerror</code></a></h3><p>
4848 <span class="apii">[-0, +0, <em>v</em>]</span>
4868 <hr><h3><a name="luaL_Buffer"><code>luaL_Buffer</code></a></h3>
4872 Type for a <em>string buffer</em>.
4876 A string buffer allows C code to build Lua strings piecemeal.
4881 <li>First you declare a variable <code>b</code> of type <a href="#luaL_Buffer"><code>luaL_Buffer</c…
4883 <li>Then you initialize it with a call <code>luaL_buffinit(L, &b)</code>.</li>
4899 a string buffer uses a variable number of stack slots.
4900 So, while using a buffer, you cannot assume that you know where
4905 when you call a buffer operation,
4908 (The only exception to this rule is <a href="#luaL_addvalue"><code>luaL_addvalue</code></a>.)
4909 After calling <a href="#luaL_pushresult"><code>luaL_pushresult</code></a> the stack is back to its
4917 <hr><h3><a name="luaL_buffinit"><code>luaL_buffinit</code></a></h3><p>
4918 <span class="apii">[-0, +0, <em>-</em>]</span>
4922 Initializes a buffer <code>B</code>.
4924 the buffer must be declared as a variable
4925 (see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>).
4931 <hr><h3><a name="luaL_callmeta"><code>luaL_callmeta</code></a></h3><p>
4932 <span class="apii">[-0, +(0|1), <em>e</em>]</span>
4936 Calls a metamethod.
4940 If the object at index <code>obj</code> has a metatable and this
4941 metatable has a field <code>e</code>,
4952 <hr><h3><a name="luaL_checkany"><code>luaL_checkany</code></a></h3><p>
4953 <span class="apii">[-0, +0, <em>v</em>]</span>
4964 <hr><h3><a name="luaL_checkint"><code>luaL_checkint</code></a></h3><p>
4965 <span class="apii">[-0, +0, <em>v</em>]</span>
4969 Checks whether the function argument <code>narg</code> is a number
4976 <hr><h3><a name="luaL_checkinteger"><code>luaL_checkinteger</code></a></h3><p>
4977 <span class="apii">[-0, +0, <em>v</em>]</span>
4981 Checks whether the function argument <code>narg</code> is a number
4982 and returns this number cast to a <a href="#lua_Integer"><code>lua_Integer</code></a>.
4988 <hr><h3><a name="luaL_checklong"><code>luaL_checklong</code></a></h3><p>
4989 <span class="apii">[-0, +0, <em>v</em>]</span>
4993 Checks whether the function argument <code>narg</code> is a number
4994 and returns this number cast to a <code>long</code>.
5000 <hr><h3><a name="luaL_checklstring"><code>luaL_checklstring</code></a></h3><p>
5001 <span class="apii">[-0, +0, <em>v</em>]</span>
5005 Checks whether the function argument <code>narg</code> is a string
5012 This function uses <a href="#lua_tolstring"><code>lua_tolstring</code></a> to get its result,
5019 <hr><h3><a name="luaL_checknumber"><code>luaL_checknumber</code></a></h3><p>
5020 <span class="apii">[-0, +0, <em>v</em>]</span>
5024 Checks whether the function argument <code>narg</code> is a number
5031 <hr><h3><a name="luaL_checkoption"><code>luaL_checkoption</code></a></h3><p>
5032 <span class="apii">[-0, +0, <em>v</em>]</span>
5039 Checks whether the function argument <code>narg</code> is a string and
5041 (which must be NULL-terminated).
5043 Raises an error if the argument is not a string or
5049 the function uses <code>def</code> as a default value when
5054 This is a useful function for mapping strings to C enums.
5062 <hr><h3><a name="luaL_checkstack"><code>luaL_checkstack</code></a></h3><p>
5063 <span class="apii">[-0, +0, <em>v</em>]</span>
5075 <hr><h3><a name="luaL_checkstring"><code>luaL_checkstring</code></a></h3><p>
5076 <span class="apii">[-0, +0, <em>v</em>]</span>
5080 Checks whether the function argument <code>narg</code> is a string
5085 This function uses <a href="#lua_tolstring"><code>lua_tolstring</code></a> to get its result,
5092 <hr><h3><a name="luaL_checktype"><code>luaL_checktype</code></a></h3><p>
5093 <span class="apii">[-0, +0, <em>v</em>]</span>
5098 See <a href="#lua_type"><code>lua_type</code></a> for the encoding of types for <code>t</code>.
5104 <hr><h3><a name="luaL_checkudata"><code>luaL_checkudata</code></a></h3><p>
5105 <span class="apii">[-0, +0, <em>v</em>]</span>
5109 Checks whether the function argument <code>narg</code> is a userdata
5110 of the type <code>tname</code> (see <a href="#luaL_newmetatable"><code>luaL_newmetatable</code></a>…
5116 <hr><h3><a name="luaL_dofile"><code>luaL_dofile</code></a></h3><p>
5117 <span class="apii">[-0, +?, <em>m</em>]</span>
5134 <hr><h3><a name="luaL_dostring"><code>luaL_dostring</code></a></h3><p>
5135 <span class="apii">[-0, +?, <em>m</em>]</span>
5152 <hr><h3><a name="luaL_error"><code>luaL_error</code></a></h3><p>
5153 <span class="apii">[-0, +0, <em>v</em>]</span>
5160 following the same rules of <a href="#lua_pushfstring"><code>lua_pushfstring</code></a>.
5175 <hr><h3><a name="luaL_getmetafield"><code>luaL_getmetafield</code></a></h3><p>
5176 <span class="apii">[-0, +(0|1), <em>m</em>]</span>
5182 If the object does not have a metatable,
5190 <hr><h3><a name="luaL_getmetatable"><code>luaL_getmetatable</code></a></h3><p>
5191 <span class="apii">[-0, +1, <em>-</em>]</span>
5196 in the registry (see <a href="#luaL_newmetatable"><code>luaL_newmetatable</code></a>).
5202 <hr><h3><a name="luaL_gsub"><code>luaL_gsub</code></a></h3><p>
5203 <span class="apii">[-0, +1, <em>m</em>]</span>
5210 Creates a copy of string <code>s</code> by replacing
5219 <hr><h3><a name="luaL_loadbuffer"><code>luaL_loadbuffer</code></a></h3><p>
5220 <span class="apii">[-0, +1, <em>m</em>]</span>
5227 Loads a buffer as a Lua chunk.
5228 This function uses <a href="#lua_load"><code>lua_load</code></a> to load the chunk in the
5233 This function returns the same results as <a href="#lua_load"><code>lua_load</code></a>.
5241 <hr><h3><a name="luaL_loadfile"><code>luaL_loadfile</code></a></h3><p>
5242 <span class="apii">[-0, +1, <em>m</em>]</span>
5246 Loads a file as a Lua chunk.
5247 This function uses <a href="#lua_load"><code>lua_load</code></a> to load the chunk in the file
5251 The first line in the file is ignored if it starts with a <code>#</code>.
5255 This function returns the same results as <a href="#lua_load"><code>lua_load</code></a>,
5256 but it has an extra error code <a name="pdf-LUA_ERRFILE"><code>LUA_ERRFILE</code></a>
5261 As <a href="#lua_load"><code>lua_load</code></a>, this function only loads the chunk;
5268 <hr><h3><a name="luaL_loadstring"><code>luaL_loadstring</code></a></h3><p>
5269 <span class="apii">[-0, +1, <em>m</em>]</span>
5273 Loads a string as a Lua chunk.
5274 This function uses <a href="#lua_load"><code>lua_load</code></a> to load the chunk in
5275 the zero-terminated string <code>s</code>.
5279 This function returns the same results as <a href="#lua_load"><code>lua_load</code></a>.
5283 Also as <a href="#lua_load"><code>lua_load</code></a>, this function only loads the chunk;
5290 <hr><h3><a name="luaL_newmetatable"><code>luaL_newmetatable</code></a></h3><p>
5291 <span class="apii">[-0, +1, <em>m</em>]</span>
5298 creates a new table to be used as a metatable for userdata,
5311 <hr><h3><a name="luaL_newstate"><code>luaL_newstate</code></a></h3><p>
5312 <span class="apii">[-0, +0, <em>-</em>]</span>
5316 Creates a new Lua state.
5317 It calls <a href="#lua_newstate"><code>lua_newstate</code></a> with an
5319 and then sets a panic function (see <a href="#lua_atpanic"><code>lua_atpanic</code></a>) that prints
5326 or <code>NULL</code> if there is a memory allocation error.
5332 <hr><h3><a name="luaL_openlibs"><code>luaL_openlibs</code></a></h3><p>
5333 <span class="apii">[-0, +0, <em>m</em>]</span>
5343 <hr><h3><a name="luaL_optint"><code>luaL_optint</code></a></h3><p>
5344 <span class="apii">[-0, +0, <em>v</em>]</span>
5348 If the function argument <code>narg</code> is a number,
5358 <hr><h3><a name="luaL_optinteger"><code>luaL_optinteger</code></a></h3><p>
5359 <span class="apii">[-0, +0, <em>v</em>]</span>
5365 If the function argument <code>narg</code> is a number,
5366 returns this number cast to a <a href="#lua_Integer"><code>lua_Integer</code></a>.
5375 <hr><h3><a name="luaL_optlong"><code>luaL_optlong</code></a></h3><p>
5376 <span class="apii">[-0, +0, <em>v</em>]</span>
5380 If the function argument <code>narg</code> is a number,
5381 returns this number cast to a <code>long</code>.
5390 <hr><h3><a name="luaL_optlstring"><code>luaL_optlstring</code></a></h3><p>
5391 <span class="apii">[-0, +0, <em>v</em>]</span>
5398 If the function argument <code>narg</code> is a string,
5413 <hr><h3><a name="luaL_optnumber"><code>luaL_optnumber</code></a></h3><p>
5414 <span class="apii">[-0, +0, <em>v</em>]</span>
5418 If the function argument <code>narg</code> is a number,
5428 <hr><h3><a name="luaL_optstring"><code>luaL_optstring</code></a></h3><p>
5429 <span class="apii">[-0, +0, <em>v</em>]</span>
5435 If the function argument <code>narg</code> is a string,
5445 <hr><h3><a name="luaL_prepbuffer"><code>luaL_prepbuffer</code></a></h3><p>
5446 <span class="apii">[-0, +0, <em>-</em>]</span>
5450 Returns an address to a space of size <a name="pdf-LUAL_BUFFERSIZE"><code>LUAL_BUFFERSIZE</code></a>
5451 where you can copy a string to be added to buffer <code>B</code>
5452 (see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>).
5454 <a href="#luaL_addsize"><code>luaL_addsize</code></a> with the size of the string to actually add
5461 <hr><h3><a name="luaL_pushresult"><code>luaL_pushresult</code></a></h3><p>
5462 <span class="apii">[-?, +1, <em>m</em>]</span>
5473 <hr><h3><a name="luaL_ref"><code>luaL_ref</code></a></h3><p>
5474 <span class="apii">[-1, +0, <em>m</em>]</span>
5478 Creates and returns a <em>reference</em>,
5484 A reference is a unique integer key.
5486 <a href="#luaL_ref"><code>luaL_ref</code></a> ensures the uniqueness of the key it returns.
5489 Function <a href="#luaL_unref"><code>luaL_unref</code></a> frees a reference and its associated obj…
5494 <a href="#luaL_ref"><code>luaL_ref</code></a> returns the constant <a name="pdf-LUA_REFNIL"><code>L…
5495 The constant <a name="pdf-LUA_NOREF"><code>LUA_NOREF</code></a> is guaranteed to be different
5496 from any reference returned by <a href="#luaL_ref"><code>luaL_ref</code></a>.
5502 <hr><h3><a name="luaL_Reg"><code>luaL_Reg</code></a></h3>
5510 <a href="#luaL_register"><code>luaL_register</code></a>.
5511 <code>name</code> is the function name and <code>func</code> is a pointer to
5513 Any array of <a href="#luaL_Reg"><code>luaL_Reg</code></a> must end with an sentinel entry
5520 <hr><h3><a name="luaL_register"><code>luaL_register</code></a></h3><p>
5521 <span class="apii">[-(0|1), +1, <em>m</em>]</span>
5527 Opens a library.
5533 (see <a href="#luaL_Reg"><code>luaL_Reg</code></a>) into the table on the top of the stack.
5537 When called with a non-null <code>libname</code>,
5538 <code>luaL_register</code> creates a new table <code>t</code>,
5542 If there is a table in <code>package.loaded[libname]</code> or in
5544 reuses this table instead of creating a new one.
5555 <hr><h3><a name="luaL_typename"><code>luaL_typename</code></a></h3><p>
5556 <span class="apii">[-0, +0, <em>-</em>]</span>
5566 <hr><h3><a name="luaL_typerror"><code>luaL_typerror</code></a></h3><p>
5567 <span class="apii">[-0, +0, <em>v</em>]</span>
5571 Generates an error with a message like the following:
5576 where <code><em>location</em></code> is produced by <a href="#luaL_where"><code>luaL_where</code></…
5584 <hr><h3><a name="luaL_unref"><code>luaL_unref</code></a></h3><p>
5585 <span class="apii">[-0, +0, <em>-</em>]</span>
5590 (see <a href="#luaL_ref"><code>luaL_ref</code></a>).
5597 …f <code>ref</code> is <a href="#pdf-LUA_NOREF"><code>LUA_NOREF</code></a> or <a href="#pdf-LUA_REF…
5598 <a href="#luaL_unref"><code>luaL_unref</code></a> does nothing.
5604 <hr><h3><a name="luaL_where"><code>luaL_where</code></a></h3><p>
5605 <span class="apii">[-0, +1, <em>m</em>]</span>
5609 Pushes onto the stack a string identifying the current position
5622 This function is used to build a prefix for error messages.
5630 <h1>5 - <a name="5">Standard Libraries</a></h1>
5636 (e.g., <a href="#pdf-type"><code>type</code></a> and <a href="#pdf-getmetatable"><code>getmetatable…
5640 deserve an implementation in C (e.g., <a href="#pdf-table.sort"><code>table.sort</code></a>).
5650 <li>basic library, which includes the coroutine sub-library;</li>
5668 each library provides all its functions as fields of a global table
5674 the C host program should call the <a href="#luaL_openlibs"><code>luaL_openlibs</code></a> fun…
5678 <a name="pdf-luaopen_base"><code>luaopen_base</code></a> (for the basic library),
5679 <a name="pdf-luaopen_package"><code>luaopen_package</code></a> (for the package library),
5680 <a name="pdf-luaopen_string"><code>luaopen_string</code></a> (for the string library),
5681 <a name="pdf-luaopen_table"><code>luaopen_table</code></a> (for the table library),
5682 <a name="pdf-luaopen_math"><code>luaopen_math</code></a> (for the mathematical library),
5683 <a name="pdf-luaopen_io"><code>luaopen_io</code></a> (for the I/O library),
5684 <a name="pdf-luaopen_os"><code>luaopen_os</code></a> (for the Operating System library),
5685 and <a name="pdf-luaopen_debug"><code>luaopen_debug</code></a> (for the debug library).
5686 These functions are declared in <a name="pdf-lualib.h"><code>lualib.h</code></a>
5689 e.g., by using <a href="#lua_call"><code>lua_call</code></a>.
5693 <h2>5.1 - <a name="5.1">Basic Functions</a></h2>
5703 <hr><h3><a name="pdf-assert"><code>assert (v [, message])</code></a></h3>
5714 <hr><h3><a name="pdf-collectgarbage"><code>collectgarbage ([opt [, arg]])</code></a></h3>
5718 This function is a generic interface to the garbage collector.
5724 performs a full garbage-collection cycle.
5741 performs a garbage-collection step.
5743 (larger values mean more steps) in a non-specified way.
5746 Returns <b>true</b> if the step finished a collection cycle.
5751 the collector (see <a href="#2.10">§2.10</a>).
5757 the collector (see <a href="#2.10">§2.10</a>).
5766 <hr><h3><a name="pdf-dofile"><code>dofile ([filename])</code></a></h3>
5767 Opens the named file and executes its contents as a Lua chunk.
5778 <hr><h3><a name="pdf-error"><code>error (message [, level])</code></a></h3>
5792 Passing a level 0 avoids the addition of error position information
5799 <hr><h3><a name="pdf-_G"><code>_G</code></a></h3>
5800 A global variable (not a function) that
5804 nor vice-versa.
5805 (Use <a href="#pdf-setfenv"><code>setfenv</code></a> to change environments.)
5811 <hr><h3><a name="pdf-getfenv"><code>getfenv ([f])</code></a></h3>
5813 <code>f</code> can be a Lua function or a number
5816 If the given function is not a Lua function,
5825 <hr><h3><a name="pdf-getmetatable"><code>getmetatable (object)</code></a></h3>
5829 If <code>object</code> does not have a metatable, returns <b>nil</b>.
5831 if the object's metatable has a <code>"__metatable"</code> field,
5839 <hr><h3><a name="pdf-ipairs"><code>ipairs (t)</code></a></h3>
5856 <hr><h3><a name="pdf-load"><code>load (func [, chunkname])</code></a></h3>
5860 Loads a chunk using function <code>func</code> to get its pieces.
5861 Each call to <code>func</code> must return a string that concatenates
5863 A return of an empty string, <b>nil</b>, or no value signals the end of the chunk.
5868 returns the compiled chunk as a function;
5883 <hr><h3><a name="pdf-loadfile"><code>loadfile ([filename])</code></a></h3>
5887 Similar to <a href="#pdf-load"><code>load</code></a>,
5896 <hr><h3><a name="pdf-loadstring"><code>loadstring (string [, chunkname])</code></a></h3>
5900 Similar to <a href="#pdf-load"><code>load</code></a>,
5905 To load and run a given string, use the idiom
5919 <hr><h3><a name="pdf-next"><code>next (table [, index])</code></a></h3>
5923 Allows a program to traverse all fields of a table.
5924 Its first argument is a table and its second argument
5936 you can use <code>next(t)</code> to check whether a table is empty.
5942 (To traverse a table in numeric order,
5943 use a numerical <b>for</b> or the <a href="#pdf-ipairs"><code>ipairs</code></a> function.)
5949 you assign any value to a non-existent field in the table.
5957 <hr><h3><a name="pdf-pairs"><code>pairs (t)</code></a></h3>
5961 Returns three values: the <a href="#pdf-next"><code>next</code></a> function, the table <code>t</co…
5971 See function <a href="#pdf-next"><code>next</code></a> for the caveats of modifying
5978 <hr><h3><a name="pdf-pcall"><code>pcall (f, arg1, ···)</code></a></h3>
5986 and returns a status code.
5987 Its first result is the status code (a boolean),
5997 <hr><h3><a name="pdf-print"><code>print (···)</code></a></h3>
6000 using the <a href="#pdf-tostring"><code>tostring</code></a> function to convert them to strings.
6002 but only as a quick way to show a value,
6004 For formatted output, use <a href="#pdf-string.format"><code>string.format</code></a>.
6010 <hr><h3><a name="pdf-rawequal"><code>rawequal (v1, v2)</code></a></h3>
6013 Returns a boolean.
6019 <hr><h3><a name="pdf-rawget"><code>rawget (table, index)</code></a></h3>
6022 <code>table</code> must be a table;
6029 <hr><h3><a name="pdf-rawset"><code>rawset (table, index, value)</code></a></h3>
6032 <code>table</code> must be a table,
6044 <hr><h3><a name="pdf-select"><code>select (index, ···)</code></a></h3>
6048 If <code>index</code> is a number,
6057 <hr><h3><a name="pdf-setfenv"><code>setfenv (f, table)</code></a></h3>
6062 <code>f</code> can be a Lua function or a number
6069 As a special case, when <code>f</code> is 0 <code>setfenv</code> changes
6077 <hr><h3><a name="pdf-setmetatable"><code>setmetatable (table, metatable)</code></a></h3>
6085 If the original metatable has a <code>"__metatable"</code> field,
6096 <hr><h3><a name="pdf-tonumber"><code>tonumber (e [, base])</code></a></h3>
6097 Tries to convert its argument to a number.
6098 If the argument is already a number or a string convertible
6099 to a number, then <code>tonumber</code> returns this number;
6106 In bases above 10, the letter '<code>A</code>' (in either upper or lower case)
6109 In base 10 (the default), the number can have a decimal part,
6110 as well as an optional exponent part (see <a href="#2.1">§2.1</a>).
6117 <hr><h3><a name="pdf-tostring"><code>tostring (e)</code></a></h3>
6119 converts it to a string in a reasonable format.
6121 use <a href="#pdf-string.format"><code>string.format</code></a>.
6125 If the metatable of <code>e</code> has a <code>"__tostring"</code> field,
6134 <hr><h3><a name="pdf-type"><code>type (v)</code></a></h3>
6135 Returns the type of its only argument, coded as a string.
6137 "<code>nil</code>" (a string, not the value <b>nil</b>),
6150 <hr><h3><a name="pdf-unpack"><code>unpack (list [, i [, j]])</code></a></h3>
6157 except that the above code can be written only for a fixed number
6160 as defined by the length operator (see <a href="#2.5.5">§2.5.5</a>).
6166 <hr><h3><a name="pdf-_VERSION"><code>_VERSION</code></a></h3>
6167 A global variable (not a function) that
6168 holds a string containing the current interpreter version.
6175 <hr><h3><a name="pdf-xpcall"><code>xpcall (f, err)</code></a></h3>
6179 This function is similar to <a href="#pdf-pcall"><code>pcall</code></a>,
6180 except that you can set a new error handler.
6189 and returns a status code.
6190 Its first result is the status code (a boolean),
6203 <h2>5.2 - <a name="5.2">Coroutine Manipulation</a></h2>
6206 The operations related to coroutines comprise a sub-library of
6207 the basic library and come inside the table <a name="pdf-coroutine"><code>coroutine</code></a>.
6208 See <a href="#2.11">§2.11</a> for a general description of coroutines.
6212 <hr><h3><a name="pdf-coroutine.create"><code>coroutine.create (f)</code></a></h3>
6216 Creates a new coroutine, with body <code>f</code>.
6217 <code>f</code> must be a Lua function.
6225 <hr><h3><a name="pdf-coroutine.resume"><code>coroutine.resume (co [, val1, ···…
6230 The first time you resume a coroutine,
6252 <hr><h3><a name="pdf-coroutine.running"><code>coroutine.running ()</code></a></h3>
6263 <hr><h3><a name="pdf-coroutine.status"><code>coroutine.status (co)</code></a></h3>
6267 Returns the status of coroutine <code>co</code>, as a string:
6270 <code>"suspended"</code>, if the coroutine is suspended in a call to <code>yield</code>,
6281 <hr><h3><a name="pdf-coroutine.wrap"><code>coroutine.wrap (f)</code></a></h3>
6285 Creates a new coroutine, with body <code>f</code>.
6286 <code>f</code> must be a Lua function.
6287 Returns a function that resumes the coroutine each time it is called.
6298 <hr><h3><a name="pdf-coroutine.yield"><code>coroutine.yield (···)</code></a></…
6303 The coroutine cannot be running a C function,
6304 a metamethod, or an iterator.
6313 <h2>5.3 - <a name="5.3">Modules</a></h2>
6319 <a href="#pdf-require"><code>require</code></a> and <a href="#pdf-module"><code>module</code></a>.
6320 Everything else is exported in a table <a name="pdf-package"><code>package</code></a>.
6324 <hr><h3><a name="pdf-module"><code>module (name [, ···])</code></a></h3>
6328 Creates a module.
6329 If there is a table in <code>package.loaded[name]</code>,
6331 Otherwise, if there is a global table <code>t</code> with the given name,
6333 Otherwise creates a new table <code>t</code> and
6342 so that <a href="#pdf-require"><code>require</code></a> returns <code>t</code>.
6346 If <code>name</code> is a compound name
6350 For instance, if <code>name</code> is <code>a.b.c</code>,
6352 field <code>b</code> of global <code>a</code>.
6358 where each option is a function to be applied over the module.
6364 <hr><h3><a name="pdf-require"><code>require (modname)</code></a></h3>
6369 The function starts by looking into the <a href="#pdf-package.loaded"><code>package.loaded</code></…
6373 Otherwise, it tries to find a <em>loader</em> for the module.
6377 To find a loader,
6378 <code>require</code> is guided by the <a href="#pdf-package.loaders"><code>package.loaders</code></…
6380 we can change how <code>require</code> looks for a module.
6382 for <a href="#pdf-package.loaders"><code>package.loaders</code></a>.
6387 If it has a value,
6388 this value (which should be a function) is the loader.
6389 Otherwise <code>require</code> searches for a Lua loader using the
6390 path stored in <a href="#pdf-package.path"><code>package.path</code></a>.
6391 If that also fails, it searches for a C loader using the
6392 path stored in <a href="#pdf-package.cpath"><code>package.cpath</code></a>.
6394 it tries an <em>all-in-one</em> loader (see <a href="#pdf-package.loaders"><code>package.loaders</c…
6398 Once a loader is found,
6399 <code>require</code> calls the loader with a single argument, <code>modname</code>.
6418 <hr><h3><a name="pdf-package.cpath"><code>package.cpath</code></a></h3>
6422 The path used by <a href="#pdf-require"><code>require</code></a> to search for a C loader.
6426 Lua initializes the C path <a href="#pdf-package.cpath"><code>package.cpath</code></a> in the …
6427 it initializes the Lua path <a href="#pdf-package.path"><code>package.path</code></a>,
6428 using the environment variable <a name="pdf-LUA_CPATH"><code>LUA_CPATH</code></a>
6429 or a default path defined in <code>luaconf.h</code>.
6436 <hr><h3><a name="pdf-package.loaded"><code>package.loaded</code></a></h3>
6440 A table used by <a href="#pdf-require"><code>require</code></a> to control which
6442 When you require a module <code>modname</code> and
6444 <a href="#pdf-require"><code>require</code></a> simply returns the value stored there.
6450 <hr><h3><a name="pdf-package.loaders"><code>package.loaders</code></a></h3>
6454 A table used by <a href="#pdf-require"><code>require</code></a> to control how to load modules.
6458 Each entry in this table is a <em>searcher function</em>.
6459 When looking for a module,
6460 <a href="#pdf-require"><code>require</code></a> calls each of these searchers in ascending order,
6461 with the module name (the argument given to <a href="#pdf-require"><code>require</code></a>) as its
6464 or a string explaining why it did not find that module
6470 The first searcher simply looks for a loader in the
6471 <a href="#pdf-package.preload"><code>package.preload</code></a> table.
6475 The second searcher looks for a loader as a Lua library,
6476 using the path stored at <a href="#pdf-package.path"><code>package.path</code></a>.
6477 A path is a sequence of <em>templates</em> separated by semicolons.
6481 which is the module name with each dot replaced by a
6489 the search for a Lua file for module <code>foo</code>
6496 The third searcher looks for a loader as a C library,
6497 using the path given by the variable <a href="#pdf-package.cpath"><code>package.cpath</code></a>.
6507 Once it finds a C library,
6508 this searcher first uses a dynamic link facility to link the
6510 Then it tries to find a C function inside the library to
6513 concatenated with a copy of the module name where each dot
6515 Moreover, if the module name has a hyphen,
6517 For instance, if the module name is <code>a.v1-b.c</code>,
6522 The fourth searcher tries an <em>all-in-one loader</em>.
6523 It searches the C path for a library for
6525 For instance, when requiring <code>a.b.c</code>,
6526 it will search for a C library for <code>a</code>.
6530 With this facility, a package can pack several C submodules
6538 <hr><h3><a name="pdf-package.loadlib"><code>package.loadlib (libname, funcname)</code></a></h3>
6543 Inside this library, looks for a function <code>funcname</code>
6544 and returns this function as a C function.
6545 …de>funcname</code> must follow the protocol (see <a href="#lua_CFunction"><code>lua_CFunction</cod…
6549 This is a low-level function.
6551 Unlike <a href="#pdf-require"><code>require</code></a>,
6555 including if necessary a path and extension.
6570 <hr><h3><a name="pdf-package.path"><code>package.path</code></a></h3>
6574 The path used by <a href="#pdf-require"><code>require</code></a> to search for a Lua loader.
6578 At start-up, Lua initializes this variable with
6579 the value of the environment variable <a name="pdf-LUA_PATH"><code>LUA_PATH</code></a> or
6580 with a default path defined in <code>luaconf.h</code>,
6589 <hr><h3><a name="pdf-package.preload"><code>package.preload</code></a></h3>
6593 A table to store loaders for specific modules
6594 (see <a href="#pdf-require"><code>require</code></a>).
6600 <hr><h3><a name="pdf-package.seeall"><code>package.seeall (module)</code></a></h3>
6604 Sets a metatable for <code>module</code> with
6608 To be used as an option to function <a href="#pdf-module"><code>module</code></a>.
6616 <h2>5.4 - <a name="5.4">String Manipulation</a></h2>
6621 When indexing a string in Lua, the first character is at position 1
6625 Thus, the last character is at position -1, and so on.
6630 <a name="pdf-string"><code>string</code></a>.
6631 It also sets a metatable for strings
6633 Therefore, you can use the string functions in object-oriented style.
6639 The string library assumes one-byte character encodings.
6643 <hr><h3><a name="pdf-string.byte"><code>string.byte (s [, i [, j]])</code></a></h3>
6657 <hr><h3><a name="pdf-string.char"><code>string.char (···)</code></a></h3>
6659 Returns a string with length equal to the number of arguments,
6671 <hr><h3><a name="pdf-string.dump"><code>string.dump (function)</code></a></h3>
6675 Returns a string containing a binary representation of the given function,
6676 so that a later <a href="#pdf-loadstring"><code>loadstring</code></a> on this string returns
6677 a copy of the function.
6678 <code>function</code> must be a Lua function without upvalues.
6684 <hr><h3><a name="pdf-string.find"><code>string.find (s, pattern [, init [, plain]])</code></a></h3>
6687 If it finds a match, then <code>find</code> returns the indices of <code>s</code>
6690 A third, optional numerical argument <code>init</code> specifies
6693 A value of <b>true</b> as a fourth, optional argument <code>plain</code>
6695 so the function does a plain "find substring" operation,
6702 then in a successful match
6710 <hr><h3><a name="pdf-string.format"><code>string.format (formatstring, ···)</c…
6711 Returns a formatted version of its variable number of arguments
6712 following the description given in its first argument (which must be a string).
6719 The <code>q</code> option formats a string in a form suitable to be safely read
6728 string.format('%q', 'a string with "quotes" and \n new line')
6733 "a string with \"quotes\" and \
6740 expect a number as argument,
6741 whereas <code>q</code> and <code>s</code> expect a string.
6753 <hr><h3><a name="pdf-string.gmatch"><code>string.gmatch (s, pattern)</code></a></h3>
6766 for w in string.gmatch(s, "%a+") do
6773 given string into a table:
6784 For this function, a '<code>^</code>' at the start of a pattern does not
6791 <hr><h3><a name="pdf-string.gsub"><code>string.gsub (s, pattern, repl [, n])</code></a></h3>
6792 Returns a copy of <code>s</code>
6795 replaced by a replacement string specified by <code>repl</code>,
6796 which can be a string, a table, or a function.
6802 If <code>repl</code> is a string, then its value is used for replacement.
6806 stands for the value of the <em>n</em>-th captured substring (see below).
6808 The sequence <code>%%</code> stands for a single <code>%</code>.
6812 If <code>repl</code> is a table, then the table is queried for every match,
6819 If <code>repl</code> is a function, then this function is called every time a
6823 then the whole match is passed as a sole argument.
6828 is a string or a number,
6840 --> x="hello hello world world"
6843 --> x="hello hello world"
6846 --> x="world hello Lua from"
6849 --> x="home = /home/roberto, user = roberto"
6851 x = string.gsub("4+5 = $return 4+5$", "%$(.-)%$", function (s)
6854 --> x="4+5 = 9"
6857 x = string.gsub("$name-$version.tar.gz", "%$(%w+)", t)
6858 --> x="lua-5.1.tar.gz"
6864 <hr><h3><a name="pdf-string.len"><code>string.len (s)</code></a></h3>
6865 Receives a string and returns its length.
6868 so <code>"a\000bc\000"</code> has length 5.
6874 <hr><h3><a name="pdf-string.lower"><code>string.lower (s)</code></a></h3>
6875 Receives a string and returns a copy of this string with all
6884 <hr><h3><a name="pdf-string.match"><code>string.match (s, pattern [, init])</code></a></h3>
6892 A third, optional numerical argument <code>init</code> specifies
6900 <hr><h3><a name="pdf-string.rep"><code>string.rep (s, n)</code></a></h3>
6901 Returns a string that is the concatenation of <code>n</code> copies of
6908 <hr><h3><a name="pdf-string.reverse"><code>string.reverse (s)</code></a></h3>
6909 Returns a string that is the string <code>s</code> reversed.
6915 <hr><h3><a name="pdf-string.sub"><code>string.sub (s, i [, j])</code></a></h3>
6919 If <code>j</code> is absent, then it is assumed to be equal to -1
6922 the call <code>string.sub(s,1,j)</code> returns a prefix of <code>s</code>
6924 and <code>string.sub(s, -i)</code> returns a suffix of <code>s</code>
6931 <hr><h3><a name="pdf-string.upper"><code>string.upper (s)</code></a></h3>
6932 Receives a string and returns a copy of this string with all
6935 The definition of what a lowercase letter is depends on the current locale.
6939 <h3>5.4.1 - <a name="5.4.1">Patterns</a></h3>
6943 A <em>character class</em> is used to represent a set of characters.
6944 The following combinations are allowed in describing a character class:
6950 <code>^$()%.[]*+-?</code>)
6954 <li><b><code>.</code>:</b> (a dot) represents all characters.</li>
6956 <li><b><code>%a</code>:</b> represents all letters.</li>
6976 <li><b><code>%<em>x</em></code>:</b> (where <em>x</em> is any non-alphanumeric character)
6980 can be preceded by a '<code>%</code>'
6981 when used to represent itself in a pattern.
6987 A range of characters can be specified by
6988 separating the end characters of the range with a '<code>-</code>'.
6994 <code>[0-7]</code> represents the octal digits,
6995 and <code>[0-7%l%-]</code> represents the octal digits plus
6996 the lowercase letters plus the '<code>-</code>' character.
7001 Therefore, patterns like <code>[%a-z]</code> or <code>[a-%%]</code>
7011 For all classes represented by single letters (<code>%a</code>, <code>%c</code>, etc.),
7013 For instance, <code>%S</code> represents all non-space characters.
7019 In particular, the class <code>[a-z]</code> may not be equivalent to <code>%l</code>.
7026 A <em>pattern item</em> can be
7031 a single character class,
7036 a single character class followed by '<code>*</code>',
7042 a single character class followed by '<code>+</code>',
7048 a single character class followed by '<code>-</code>',
7055 a single character class followed by '<code>?</code>',
7056 which matches 0 or 1 occurrence of a character in the class;
7061 such item matches a substring equal to the <em>n</em>-th captured string
7070 counting <em>+1</em> for an <em>x</em> and <em>-1</em> for a <em>y</em>,
7082 A <em>pattern</em> is a sequence of pattern items.
7083 A '<code>^</code>' at the beginning of a pattern anchors the match at the
7085 A '<code>$</code>' at the end of a pattern anchors the match at the
7095 A pattern can contain sub-patterns enclosed in parentheses;
7097 When a match succeeds, the substrings of the subject string
7100 For instance, in the pattern <code>"(a*(.)%w(%s*))"</code>,
7101 the part of the string matching <code>"a*(.)%w(%s*)"</code> is
7108 As a special case, the empty capture <code>()</code> captures
7109 the current string position (a number).
7115 A pattern cannot contain embedded zeros. Use <code>%z</code> instead.
7127 <h2>5.5 - <a name="5.5">Table Manipulation</a></h2><p>
7129 It provides all its functions inside the table <a name="pdf-table"><code>table</code></a>.
7134 represents an array or a list.
7135 For these functions, when we talk about the "length" of a table
7140 <hr><h3><a name="pdf-table.concat"><code>table.concat (table [, sep [, i [, j]]])</code></a></h3>
7152 <hr><h3><a name="pdf-table.insert"><code>table.insert (table, [pos,] value)</code></a></h3>
7159 where <code>n</code> is the length of the table (see <a href="#2.5.5">§2.5.5</a>),
7160 so that a call <code>table.insert(t,x)</code> inserts <code>x</code> at the end
7167 <hr><h3><a name="pdf-table.maxn"><code>table.maxn (table)</code></a></h3>
7173 (To do its job this function does a linear traversal of
7180 <hr><h3><a name="pdf-table.remove"><code>table.remove (table [, pos])</code></a></h3>
7189 so that a call <code>table.remove(t)</code> removes the last element
7196 <hr><h3><a name="pdf-table.sort"><code>table.sort (table [, comp])</code></a></h3>
7197 Sorts table elements in a given order, <em>in-place</em>,
7201 then it must be a function that receives two table elements,
7204 (so that <code>not comp(a[i+1],a[i])</code> will be true after the sort).
7220 <h2>5.6 - <a name="5.6">Mathematical Functions</a></h2>
7224 It provides all its functions inside the table <a name="pdf-math"><code>math</code></a>.
7228 <hr><h3><a name="pdf-math.abs"><code>math.abs (x)</code></a></h3>
7238 <hr><h3><a name="pdf-math.acos"><code>math.acos (x)</code></a></h3>
7248 <hr><h3><a name="pdf-math.asin"><code>math.asin (x)</code></a></h3>
7258 <hr><h3><a name="pdf-math.atan"><code>math.atan (x)</code></a></h3>
7268 <hr><h3><a name="pdf-math.atan2"><code>math.atan2 (y, x)</code></a></h3>
7281 <hr><h3><a name="pdf-math.ceil"><code>math.ceil (x)</code></a></h3>
7291 <hr><h3><a name="pdf-math.cos"><code>math.cos (x)</code></a></h3>
7301 <hr><h3><a name="pdf-math.cosh"><code>math.cosh (x)</code></a></h3>
7311 <hr><h3><a name="pdf-math.deg"><code>math.deg (x)</code></a></h3>
7321 <hr><h3><a name="pdf-math.exp"><code>math.exp (x)</code></a></h3>
7331 <hr><h3><a name="pdf-math.floor"><code>math.floor (x)</code></a></h3>
7341 <hr><h3><a name="pdf-math.fmod"><code>math.fmod (x, y)</code></a></h3>
7352 <hr><h3><a name="pdf-math.frexp"><code>math.frexp (x)</code></a></h3>
7365 <hr><h3><a name="pdf-math.huge"><code>math.huge</code></a></h3>
7370 a value larger than or equal to any other numerical value.
7376 <hr><h3><a name="pdf-math.ldexp"><code>math.ldexp (m, e)</code></a></h3>
7386 <hr><h3><a name="pdf-math.log"><code>math.log (x)</code></a></h3>
7396 <hr><h3><a name="pdf-math.log10"><code>math.log10 (x)</code></a></h3>
7400 Returns the base-10 logarithm of <code>x</code>.
7406 <hr><h3><a name="pdf-math.max"><code>math.max (x, ···)</code></a></h3>
7416 <hr><h3><a name="pdf-math.min"><code>math.min (x, ···)</code></a></h3>
7426 <hr><h3><a name="pdf-math.modf"><code>math.modf (x)</code></a></h3>
7437 <hr><h3><a name="pdf-math.pi"><code>math.pi</code></a></h3>
7447 <hr><h3><a name="pdf-math.pow"><code>math.pow (x, y)</code></a></h3>
7458 <hr><h3><a name="pdf-math.rad"><code>math.rad (x)</code></a></h3>
7468 <hr><h3><a name="pdf-math.random"><code>math.random ([m [, n]])</code></a></h3>
7473 pseudo-random generator function <code>rand</code> provided by ANSI C.
7479 returns a uniform pseudo-random real number
7483 a uniform pseudo-random integer in the range <em>[1, m]</em>.
7485 <code>math.random</code> returns a uniform pseudo-random
7492 <hr><h3><a name="pdf-math.randomseed"><code>math.randomseed (x)</code></a></h3>
7497 for the pseudo-random generator:
7504 <hr><h3><a name="pdf-math.sin"><code>math.sin (x)</code></a></h3>
7514 <hr><h3><a name="pdf-math.sinh"><code>math.sinh (x)</code></a></h3>
7524 <hr><h3><a name="pdf-math.sqrt"><code>math.sqrt (x)</code></a></h3>
7535 <hr><h3><a name="pdf-math.tan"><code>math.tan (x)</code></a></h3>
7545 <hr><h3><a name="pdf-math.tanh"><code>math.tanh (x)</code></a></h3>
7557 <h2>5.7 - <a name="5.7">Input and Output Facilities</a></h2>
7562 that is, there are operations to set a default input file and a
7570 all operations are supplied by table <a name="pdf-io"><code>io</code></a>.
7572 the operation <a href="#pdf-io.open"><code>io.open</code></a> returns a file descriptor
7579 …a name="pdf-io.stdin"><code>io.stdin</code></a>, <a name="pdf-io.stdout"><code>io.stdout</code></a…
7586 (plus an error message as a second result and
7587 a system-dependent error code as a third result)
7592 <hr><h3><a name="pdf-io.close"><code>io.close ([file])</code></a></h3>
7597 Without a <code>file</code>, closes the default output file.
7603 <hr><h3><a name="pdf-io.flush"><code>io.flush ()</code></a></h3>
7613 <hr><h3><a name="pdf-io.input"><code>io.input ([file])</code></a></h3>
7617 When called with a file name, it opens the named file (in text mode),
7619 When called with a file handle,
7633 <hr><h3><a name="pdf-io.lines"><code>io.lines ([filename])</code></a></h3>
7640 returns a new line from the file.
7661 <hr><h3><a name="pdf-io.open"><code>io.open (filename [, mode])</code></a></h3>
7665 This function opens a file,
7667 It returns a new file handle,
7677 <li><b>"a":</b> append mode;</li>
7680 <li><b>"a+":</b> append update mode, previous data is preserved,
7683 The <code>mode</code> string can also have a '<code>b</code>' at the end,
7692 <hr><h3><a name="pdf-io.output"><code>io.output ([file])</code></a></h3>
7696 Similar to <a href="#pdf-io.input"><code>io.input</code></a>, but operates over the default output …
7702 <hr><h3><a name="pdf-io.popen"><code>io.popen (prog [, mode])</code></a></h3>
7706 Starts program <code>prog</code> in a separated process and returns
7707 a file handle that you can use to read data from this program
7721 <hr><h3><a name="pdf-io.read"><code>io.read (···)</code></a></h3>
7731 <hr><h3><a name="pdf-io.tmpfile"><code>io.tmpfile ()</code></a></h3>
7735 Returns a handle for a temporary file.
7743 <hr><h3><a name="pdf-io.type"><code>io.type (obj)</code></a></h3>
7747 Checks whether <code>obj</code> is a valid file handle.
7749 <code>"closed file"</code> if <code>obj</code> is a closed file handle,
7750 or <b>nil</b> if <code>obj</code> is not a file handle.
7756 <hr><h3><a name="pdf-io.write"><code>io.write (···)</code></a></h3>
7766 <hr><h3><a name="pdf-file:close"><code>file:close ()</code></a></h3>
7779 <hr><h3><a name="pdf-file:flush"><code>file:flush ()</code></a></h3>
7789 <hr><h3><a name="pdf-file:lines"><code>file:lines ()</code></a></h3>
7795 returns a new line from the file.
7802 (Unlike <a href="#pdf-io.lines"><code>io.lines</code></a>, this function does not close the file
7809 <hr><h3><a name="pdf-file:read"><code>file:read (···)</code></a></h3>
7816 the function returns a string (or a number) with the characters read,
7819 it uses a default format that reads the entire next line
7829 reads a number;
7830 this is the only format that returns a number instead of a string.
7833 <li><b>"*a":</b>
7845 reads a string with up to this number of characters,
7857 <hr><h3><a name="pdf-file:seek"><code>file:seek ([whence] [, offset])</code></a></h3>
7863 to the position given by <code>offset</code> plus a base
7874 plus a string describing the error.
7891 <hr><h3><a name="pdf-file:setvbuf"><code>file:setvbuf (mode [, size])</code></a></h3>
7907 (see <a href="#pdf-io.flush"><code>io.flush</code></a>)).
7911 line buffering; output is buffered until a newline is output
7913 (such as a terminal device).
7925 <hr><h3><a name="pdf-file:write"><code>file:write (···)</code></a></h3>
7933 use <a href="#pdf-tostring"><code>tostring</code></a> or <a href="#pdf-string.format"><code>string.…
7941 <h2>5.8 - <a name="5.8">Operating System Facilities</a></h2>
7944 This library is implemented through table <a name="pdf-os"><code>os</code></a>.
7948 <hr><h3><a name="pdf-os.clock"><code>os.clock ()</code></a></h3>
7959 <hr><h3><a name="pdf-os.date"><code>os.date ([format [, time]])</code></a></h3>
7963 Returns a string or a table containing date and time,
7970 (see the <a href="#pdf-os.time"><code>os.time</code></a> function for a description of this value).
7979 then <code>date</code> returns a table with the following fields:
7980 <code>year</code> (four digits), <code>month</code> (1--12), <code>day</code> (1--31),
7981 <code>hour</code> (0--23), <code>min</code> (0--59), <code>sec</code> (0--61),
7984 and <code>isdst</code> (daylight saving flag, a boolean).
7989 then <code>date</code> returns the date as a string,
7995 <code>date</code> returns a reasonable date and time representation that depends on
8003 <hr><h3><a name="pdf-os.difftime"><code>os.difftime (t2, t1)</code></a></h3>
8009 this value is exactly <code>t2</code><em>-</em><code>t1</code>.
8015 <hr><h3><a name="pdf-os.execute"><code>os.execute ([command])</code></a></h3>
8021 It returns a status code, which is system-dependent.
8022 If <code>command</code> is absent, then it returns nonzero if a shell is available
8029 <hr><h3><a name="pdf-os.exit"><code>os.exit ([code])</code></a></h3>
8042 <hr><h3><a name="pdf-os.getenv"><code>os.getenv (varname)</code></a></h3>
8053 <hr><h3><a name="pdf-os.remove"><code>os.remove (filename)</code></a></h3>
8060 plus a string describing the error.
8066 <hr><h3><a name="pdf-os.rename"><code>os.rename (oldname, newname)</code></a></h3>
8072 plus a string describing the error.
8078 <hr><h3><a name="pdf-os.setlocale"><code>os.setlocale (locale [, category])</code></a></h3>
8083 <code>locale</code> is a string specifying a locale;
8094 the current locale is set to an implementation-defined native locale.
8108 <hr><h3><a name="pdf-os.time"><code>os.time ([table])</code></a></h3>
8113 or a time representing the date and time specified by the given table.
8116 (for a description of these fields, see the <a href="#pdf-os.date"><code>os.date</code></a> functio…
8120 The returned value is a number, whose meaning depends on your system.
8131 <hr><h3><a name="pdf-os.tmpname"><code>os.tmpname ()</code></a></h3>
8135 Returns a string with a file name that can
8136 be used for a temporary file.
8143 this function also creates a file with that name,
8153 you may prefer to use <a href="#pdf-io.tmpfile"><code>io.tmpfile</code></a>,
8162 <h2>5.9 - <a name="5.9">The Debug Library</a></h2>
8170 Please resist the temptation to use them as a
8175 (e.g., that variables local to a function
8183 inside the <a name="pdf-debug"><code>debug</code></a> table.
8184 All functions that operate over a thread
8191 <hr><h3><a name="pdf-debug.debug"><code>debug.debug ()</code></a></h3>
8200 A line containing only the word <code>cont</code> finishes this function,
8212 <hr><h3><a name="pdf-debug.getfenv"><code>debug.getfenv (o)</code></a></h3>
8219 <hr><h3><a name="pdf-debug.gethook"><code>debug.gethook ([thread])</code></a></h3>
8226 (as set by the <a href="#pdf-debug.sethook"><code>debug.sethook</code></a> function).
8232 <hr><h3><a name="pdf-debug.getinfo"><code>debug.getinfo ([thread,] function [, what])</code></a></h…
8236 Returns a table with information about a function.
8238 or you can give a number as the value of <code>function</code>,
8244 If <code>function</code> is a number larger than the number of active functions,
8249 …urned table can contain all the fields returned by <a href="#lua_getinfo"><code>lua_getinfo</code>…
8255 adds a field named <code>func</code> with the function itself.
8258 adds a field named <code>activelines</code> with the table of
8264 a table with a name for the current function,
8265 if a reasonable name can be found,
8267 returns a table with all available information
8268 about the <a href="#pdf-print"><code>print</code></a> function.
8274 <hr><h3><a name="pdf-debug.getlocal"><code>debug.getlocal ([thread,] level, local)</code></a></h3>
8284 and raises an error when called with a <code>level</code> out of range.
8285 (You can call <a href="#pdf-debug.getinfo"><code>debug.getinfo</code></a> to check whether the leve…
8297 <hr><h3><a name="pdf-debug.getmetatable"><code>debug.getmetatable (object)</code></a></h3>
8302 or <b>nil</b> if it does not have a metatable.
8308 <hr><h3><a name="pdf-debug.getregistry"><code>debug.getregistry ()</code></a></h3>
8312 Returns the registry table (see <a href="#3.5">§3.5</a>).
8318 <hr><h3><a name="pdf-debug.getupvalue"><code>debug.getupvalue (func, up)</code></a></h3>
8330 <hr><h3><a name="pdf-debug.setfenv"><code>debug.setfenv (object, table)</code></a></h3>
8341 <hr><h3><a name="pdf-debug.sethook"><code>debug.sethook ([thread,] hook, mask [, count])</code></a>…
8345 Sets the given function as a hook.
8352 <li><b><code>"c"</code>:</b> the hook is called every time Lua calls a function;</li>
8353 <li><b><code>"r"</code>:</b> the hook is called every time Lua returns from a function;</li>
8354 <li><b><code>"l"</code>:</b> the hook is called every time Lua enters a new line of code.</li>
8356 With a <code>count</code> different from zero,
8362 <a href="#pdf-debug.sethook"><code>debug.sethook</code></a> turns off the hook.
8366 When the hook is called, its first parameter is a string
8369 when simulating a return from a tail call),
8373 Inside a hook,
8380 and a call to <code>getinfo</code> will return invalid data.
8386 <hr><h3><a name="pdf-debug.setlocal"><code>debug.setlocal ([thread,] level, local, value)</code></a…
8394 and raises an error when called with a <code>level</code> out of range.
8402 <hr><h3><a name="pdf-debug.setmetatable"><code>debug.setmetatable (object, table)</code></a></h3>
8413 <hr><h3><a name="pdf-debug.setupvalue"><code>debug.setupvalue (func, up, value)</code></a></h3>
8427 <hr><h3><a name="pdf-debug.traceback"><code>debug.traceback ([thread,] [message [, level]])</code><…
8431 Returns a string with a traceback of the call stack.
8444 <h1>6 - <a name="6">Lua Stand-alone</a></h1>
8448 to be embedded in a host C program,
8449 it is also frequently used as a stand-alone language.
8450 An interpreter for Lua as a stand-alone language,
8453 The stand-alone interpreter includes
8463 <li><b><code>-e <em>stat</em></code>:</b> executes string <em>stat</em>;</li>
8464 <li><b><code>-l <em>mod</em></code>:</b> "requires" <em>mod</em>;</li>
8465 <li><b><code>-i</code>:</b> enters interactive mode after running <em>script</em>;</li>
8466 <li><b><code>-v</code>:</b> prints version information;</li>
8467 <li><b><code>--</code>:</b> stops handling options;</li>
8468 <li><b><code>-</code>:</b> executes <code>stdin</code> as a file and stops handling options.</li>
8473 <code>lua</code> behaves as <code>lua -v -i</code>
8474 when the standard input (<code>stdin</code>) is a terminal,
8475 and as <code>lua -</code> otherwise.
8480 the interpreter checks for an environment variable <a name="pdf-LUA_INIT"><code>LUA_INIT</code></a>.
8487 All options are handled in order, except <code>-i</code>.
8491 $ lua -e'a=1' -e 'print(a)' script.lua
8493 will first set <code>a</code> to 1, then print the value of <code>a</code> (which is '<code>1</code…
8501 in a global table called <code>arg</code>.
8511 $ lua -la b.lua t1 t2
8513 the interpreter first runs the file <code>a.lua</code>,
8514 then creates a table
8517 arg = { [-2] = "lua", [-1] = "-la",
8531 by issuing a different prompt.
8535 If the global variable <a name="pdf-_PROMPT"><code>_PROMPT</code></a> contains a string,
8537 Similarly, if the global variable <a name="pdf-_PROMPT2"><code>_PROMPT2</code></a> contains a strin…
8545 $ lua -e"_PROMPT='myprompt> '" -i
8549 Note the use of <code>-i</code> to enter interactive mode;
8556 To allow the use of Lua as a
8558 the stand-alone interpreter skips
8559 the first line of a chunk if it starts with <code>#</code>.
8575 is a more portable solution.)
8579 <h1>7 - <a name="7">Incompatibilities with the Previous Version</a></h1>
8582 Here we list the incompatibilities that you may find when moving a program
8591 <h2>7.1 - <a name="7.1">Changes in the Language</a></h2>
8595 The vararg system changed from the pseudo-argument <code>arg</code> with a
8597 (See compile-time option <code>LUA_COMPAT_VARARG</code> in <code>luaconf.h</code>.)
8601 There was a subtle change in the scope of the implicit
8609 (See compile-time option <code>LUA_COMPAT_LSTR</code> in <code>luaconf.h</code>.)
8617 <h2>7.2 - <a name="7.2">Changes in the Libraries</a></h2>
8621 Function <code>string.gfind</code> was renamed <a href="#pdf-string.gmatch"><code>string.gmatch</co…
8622 (See compile-time option <code>LUA_COMPAT_GFIND</code> in <code>luaconf.h</code>.)
8626 When <a href="#pdf-string.gsub"><code>string.gsub</code></a> is called with a function as its
8638 (See compile-time option <code>LUA_COMPAT_GETN</code> in <code>luaconf.h</code>.)
8642 Function <code>loadlib</code> was renamed <a href="#pdf-package.loadlib"><code>package.loadlib</cod…
8643 (See compile-time option <code>LUA_COMPAT_LOADLIB</code> in <code>luaconf.h</code>.)
8647 Function <code>math.mod</code> was renamed <a href="#pdf-math.fmod"><code>math.fmod</code></a>.
8648 (See compile-time option <code>LUA_COMPAT_MOD</code> in <code>luaconf.h</code>.)
8653 You can use a for loop with <code>pairs</code> or <code>ipairs</code> instead.
8657 There were substantial changes in function <a href="#pdf-require"><code>require</code></a> due to
8660 but <code>require</code> gets the path from <a href="#pdf-package.path"><code>package.path</code></…
8665 Function <a href="#pdf-collectgarbage"><code>collectgarbage</code></a> has different arguments.
8675 <h2>7.3 - <a name="7.3">Changes in the API</a></h2>
8681 like a regular C function.
8683 like a Lua function.
8687 Function <code>lua_open</code> was replaced by <a href="#lua_newstate"><code>lua_newstate</code></a…
8688 allow the user to set a memory-allocation function.
8689 You can use <a href="#luaL_newstate"><code>luaL_newstate</code></a> from the standard library to
8690 create a state with a standard allocation function
8697 Use <a href="#lua_objlen"><code>lua_objlen</code></a> instead of <code>luaL_getn</code>
8702 …nction <code>luaL_openlib</code> was replaced by <a href="#luaL_register"><code>luaL_register</cod…
8707 is not a userdata of the expected type.
8716 <h1>8 - <a name="8">The Complete Syntax of Lua</a></h1>
8778 …binop ::= `<b>+</b>´ | `<b>-</b>´ | `<b>*</b>´ | `<b>/</b>´ | `<b>^</b>&ac…
8782 unop ::= `<b>-</b>´ | <b>not</b> | `<b>#</b>´
8799 <!--
8801 -->