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 © 2011–2015 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 <!-- ====================================================================== -->
36 <!-- $Id: manual.of,v 1.104 2013/06/01 00:13:11 roberto Exp $ -->
41 <h1>1 – <a name="1">Introduction</a></h1>
47 It also offers good support for object-oriented programming,
48 functional programming, and data-driven programming.
49 Lua is intended to be used as a powerful, lightweight,
51 Lua is implemented as a library, written in <em>clean C</em>,
56 Being an extension language, Lua has no notion of a "main" program:
57 it only works <em>embedded</em> in a host client,
59 The host program can invoke functions to execute a piece of Lua code,
63 a wide range of different domains,
64 thus creating customized programming languages sharing a syntactical framework.
65 The Lua distribution includes a sample host program called <code>lua</code>,
66 which uses the Lua library to offer a complete, standalone Lua interpreter,
81 For a discussion of the decisions behind the design of Lua,
83 For a detailed introduction to programming in Lua,
88 <h1>2 – <a name="2">Basic Concepts</a></h1>
95 <h2>2.1 – <a name="2.1">Values and Types</a></h2>
98 Lua is a <em>dynamically typed language</em>.
106 All values in Lua are <em>first-class values</em>.
118 it usually represents the absence of a useful value.
120 Both <b>nil</b> and <b>false</b> make a condition false;
122 <em>Number</em> represents real (double-precision floating-point) numbers.
128 such as single-precision floats or long integers;
132 Lua is 8-bit clean:
133 strings can contain any 8-bit value,
140 (see <a href="#3.4.9">§3.4.9</a>).
146 A userdata value is a pointer to a block of raw memory.
154 (see <a href="#2.4">§2.4</a>).
162 and it is used to implement coroutines (see <a href="#2.6">§2.6</a>).
163 Do not confuse Lua threads with operating-system threads.
172 (<em>Not a Number</em>, a special numeric value used to represent
177 Conversely, any key that is not part of a table has
187 providing <code>a.name</code> as syntactic sugar for <code>a["name"]</code>.
189 (see <a href="#3.4.8">§3.4.8</a>).
193 We use the term <em>sequence</em> to denote a table where
196 which is called the length of the sequence (see <a href="#3.4.6">§3.4.6</a>).
203 because functions are first-class values,
205 Thus tables can also carry <em>methods</em> (see <a href="#3.4.10">§3.4.10</a>).
211 The expressions <code>a[i]</code> and <code>a[j]</code>
227 The library function <a href="#pdf-type"><code>type</code></a> returns a string describing the type
228 of a given value (see <a href="#6.1">§6.1</a>).
234 <h2>2.2 – <a name="2.2">Environments and the Global Environment</a></h2>
237 As will be discussed in <a href="#3.2">§3.2</a> and <a href="#3.3.3">§3.3.3</a>,
238 any reference to a global name <code>var</code> is syntactically translated
241 an external local variable called <code>_ENV</code> (see <a href="#3.3.2">§3.3.2</a>),
242 so <code>_ENV</code> itself is never a global name in a chunk.
248 <code>_ENV</code> is a completely regular name.
251 Each reference to a global name uses the <code>_ENV</code> that is
253 following the usual visibility rules of Lua (see <a href="#3.5">§3.5</a>).
261 Lua keeps a distinguished environment called the <em>global environment</em>.
262 This value is kept at a special index in the C registry (see <a href="#4.5">§4.5</a>).
263 In Lua, the variable <a href="#pdf-_G"><code>_G</code></a> is initialized with this same value.
267 When Lua compiles a chunk,
269 with the global environment (see <a href="#pdf-load"><code>load</code></a>).
274 You can use <a href="#pdf-load"><code>load</code></a> (or <a href="#pdf-loadfile"><code>loadfile</c…
275 to load a chunk with a different environment.
286 Moreover, the variable <a href="#pdf-_G"><code>_G</code></a>
294 <h2>2.3 – <a name="2.3">Error Handling</a></h2>
299 calling a function from the Lua library (see <a href="#lua_pcall"><code>lua_pcall</code></a>).
301 the compilation or execution of a Lua chunk,
309 <a href="#pdf-error"><code>error</code></a> function.
311 you can use <a href="#pdf-pcall"><code>pcall</code></a> or <a href="#pdf-xpcall"><code>xpcall</code…
312 to call a given function in <em>protected mode</em>.
319 Lua itself only generates errors where the error object is a string,
325 When you use <a href="#pdf-xpcall"><code>xpcall</code></a> or <a href="#lua_pcall"><code>lua_pcall<…
326 you may give a <em>message handler</em>
329 and returns a new error message.
332 for instance by inspecting the stack and creating a stack traceback.
342 <h2>2.4 – <a name="2.4">Metatables and Metamethods</a></h2>
345 Every value in Lua can have a <em>metatable</em>.
350 of operations over a value by setting specific fields in its metatable.
351 For instance, when a non-numeric value is the operand of an addition,
352 Lua checks for a function in the field "<code>__add</code>" of the value's metatable.
358 The keys in a metatable are derived from the <em>event</em> names;
366 using the <a href="#pdf-getmetatable"><code>getmetatable</code></a> function.
371 using the <a href="#pdf-setmetatable"><code>setmetatable</code></a> function.
383 By default, a value has no metatable,
384 but the string library sets a metatable for the string type (see <a href="#6.4">§6.4</a>).
388 A metatable controls how an object behaves in arithmetic operations,
390 A metatable also can define a function to be called
391 when a userdata or a table is garbage collected.
392 When Lua performs one of these operations over a value,
393 it checks whether this value has a metatable with the corresponding event.
401 The key for each operation is a string with its name prefixed by
408 The semantics of these operations is better explained by a Lua function
414 (<a href="#pdf-rawget"><code>rawget</code></a>, <a href="#pdf-tonumber"><code>tonumber</code></a>, …
415 are described in <a href="#6.1">§6.1</a>.
416 In particular, to retrieve the metamethod of a given object,
427 This means that the access to a metamethod does not invoke other metamethods,
433 For the unary <code>-</code> and <code>#</code> operators,
434 the metamethod is called with a dummy second argument.
450 The function <code>getbinhandler</code> below defines how Lua chooses a handler
451 for a binary operation.
453 If its type does not define a handler for the operation,
467 if o1 and o2 then -- both operands are numeric?
468 return o1 + o2 -- '+' here is the primitive 'add'
469 else -- at least one of the operands is not numeric
472 -- call the handler with both operands
474 else -- no handler available: default behavior
483 the <code>-</code> operation.
505 <code>o1 - floor(o1/o2)*o2</code> as the primitive operation.
517 the unary <code>-</code> operation.
523 if o then -- operand is numeric?
524 return -o -- '-' here is the primitive 'unm'
525 else -- the operand is not numeric.
526 -- Try to get a handler from the operand
529 -- call the handler with the operand
531 else -- no handler available: default behavior
547 return op1 .. op2 -- primitive string concatenation
567 return strlen(op) -- primitive string length
571 return (h(op)) -- call handler with the operand
573 return #op -- primitive table length
574 else -- no handler available: error
580 See <a href="#3.4.6">§3.4.6</a> for a description of the length of a table.
586 The function <code>getequalhandler</code> defines how Lua chooses a metamethod
588 A metamethod is selected only when both values
597 return nil -- different values
608 if op1 == op2 then -- primitive equal?
609 return true -- values are equal
611 -- try metamethod
620 Note that the result is always a boolean.
630 return op1 < op2 -- numeric comparison
632 return op1 < op2 -- lexicographic comparison
643 Note that the result is always a boolean.
653 return op1 <= op2 -- numeric comparison
655 return op1 <= op2 -- lexicographic comparison
671 Note that, in the absence of a "le" metamethod,
672 Lua tries the "lt", assuming that <code>a <= b</code> is
673 equivalent to <code>not (b < a)</code>.
678 the result is always a boolean.
685 (When <code>table</code> is not a table,
695 -- if key is present, return raw value
706 return (h(table, key)) -- call the handler
707 else return h[key] -- or repeat operation on it
724 -- if key is present, do raw assignment
735 h(table, key,value) -- call the handler
736 else h[key] = value -- or repeat operation on it
743 called when Lua calls a value.
749 return func(...) -- primitive call
767 <h2>2.5 – <a name="2.5">Garbage Collection</a></h2>
775 a <em>garbage collector</em> to collect all <em>dead objects</em>
782 Lua implements an incremental mark-and-sweep collector.
783 It uses two numbers to control its garbage-collection cycles:
784 the <em>garbage-collector pause</em> and
785 the <em>garbage-collector step multiplier</em>.
787 (e.g., a value of 100 means an internal value of 1).
791 The garbage-collector pause
792 controls how long the collector waits before starting a new cycle.
795 start a new cycle.
796 A value of 200 means that the collector waits for the total memory in use
797 to double before starting a new cycle.
801 The garbage-collector step multiplier
807 can result in the collector never finishing a cycle.
814 If you set the step multiplier to a very large number
817 the collector behaves like a stop-the-world collector.
820 doing a complete collection every time Lua doubles its
825 You can change these numbers by calling <a href="#lua_gc"><code>lua_gc</code></a> in C
826 or <a href="#pdf-collectgarbage"><code>collectgarbage</code></a> in Lua.
835 A <em>generational collector</em> assumes that most objects die young,
840 from time to time the generational collector performs a full collection.
847 <h3>2.5.1 – <a name="2.5.1">Garbage-Collection Metamethods</a></h3>
850 You can set garbage-collector metamethods for tables
852 for full userdata (see <a href="#2.4">§2.4</a>).
865 and the metatable has a field indexed by the string "<code>__gc</code>".
866 Note that if you set a metatable without a <code>__gc</code> field
874 When a marked object becomes garbage,
876 Instead, Lua puts it in a list.
891 At the end of each garbage-collection cycle,
906 and the object memory is freed in the next garbage-collection cycle.
908 (e.g., a global variable),
909 then there is a permanent resurrection.
916 When you close a state (see <a href="#lua_close"><code>lua_close</code></a>),
926 <h3>2.5.2 – <a name="2.5.2">Weak Tables</a></h3>
929 A <em>weak table</em> is a table whose elements are
931 A weak reference is ignored by the garbage collector.
938 A weak table can have weak keys, weak values, or both.
939 A table with weak keys allows the collection of its keys,
941 A table with both weak keys and weak values allows the collection of
945 The weakness of a table is controlled by the
947 If the <code>__mode</code> field is a string containing the character '<code>k</code>',
954 A table with weak keys and strong values
957 a value is considered reachable only if its key is reachable.
959 if the only reference to a key comes through its value,
964 Any change in the weakness of a table may take effect only
966 In particular, if you change the weakness to a stronger mode,
987 have a special behavior in weak tables.
996 If a weak table is among the resurrected objects in a collection cycle,
1005 <h2>2.6 – <a name="2.6">Coroutines</a></h2>
1010 A coroutine in Lua represents an independent thread of execution.
1012 a coroutine only suspends its execution by explicitly calling
1013 a yield function.
1017 You create a coroutine by calling <a href="#pdf-coroutine.create"><code>coroutine.create</code></a>.
1018 Its sole argument is a function
1020 The <code>create</code> function only creates a new coroutine and
1021 returns a handle to it (an object of type <em>thread</em>);
1026 You execute a coroutine by calling <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a…
1027 When you first call <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a>,
1029 a thread returned by <a href="#pdf-coroutine.create"><code>coroutine.create</code></a>,
1032 Extra arguments passed to <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a> are pas…
1039 A coroutine can terminate its execution in two ways:
1043 In the first case, <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a> returns <b>tru…
1045 In case of errors, <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a> returns <b>fal…
1050 A coroutine yields by calling <a href="#pdf-coroutine.yield"><code>coroutine.yield</code></a>.
1051 When a coroutine yields,
1052 the corresponding <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a> returns immedia…
1055 but in a function directly or indirectly called by the main function).
1056 In the case of a yield, <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a> also retu…
1057 plus any values passed to <a href="#pdf-coroutine.yield"><code>coroutine.yield</code></a>.
1060 with the call to <a href="#pdf-coroutine.yield"><code>coroutine.yield</code></a> returning any extra
1061 arguments passed to <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a>.
1065 Like <a href="#pdf-coroutine.create"><code>coroutine.create</code></a>,
1066 the <a href="#pdf-coroutine.wrap"><code>coroutine.wrap</code></a> function also creates a coroutine,
1068 it returns a function that, when called, resumes the coroutine.
1070 go as extra arguments to <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a>.
1071 …a href="#pdf-coroutine.wrap"><code>coroutine.wrap</code></a> returns all the values returned by <a…
1073 Unlike <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a>,
1074 <a href="#pdf-coroutine.wrap"><code>coroutine.wrap</code></a> does not catch errors;
1083 function foo (a)
1084 print("foo", a)
1085 return coroutine.yield(2*a)
1088 co = coroutine.create(function (a,b)
1089 print("co-body", a, b)
1090 local r = foo(a+1)
1091 print("co-body", r)
1092 local r, s = coroutine.yield(a+b, a-b)
1093 print("co-body", r, s)
1105 co-body 1 10
1108 co-body r
1109 main true 11 -9
1110 co-body x y
1117 see functions <a href="#lua_newthread"><code>lua_newthread</code></a>, <a href="#lua_resume"><code>…
1118 and <a href="#lua_yield"><code>lua_yield</code></a>.
1124 <h1>3 – <a name="3">The Language</a></h1>
1138 {<em>a</em>} means 0 or more <em>a</em>'s, and
1139 [<em>a</em>] means an optional <em>a</em>.
1140 Non-terminals are shown like non-terminal,
1143 The complete syntax of Lua can be found in <a href="#9">§9</a>
1148 <h2>3.1 – <a name="3.1">Lexical Conventions</a></h2>
1151 Lua is a free-form language.
1162 not beginning with a digit.
1179 Lua is a case-sensitive language:
1180 <code>and</code> is a reserved word, but <code>And</code> and <code>AND</code>
1182 As a convention, names starting with an underscore followed by
1183 uppercase letters (such as <a href="#pdf-_VERSION"><code>_VERSION</code></a>)
1191 + - * / % ^ #
1200 and can contain the following C-like escape sequences:
1201 '<code>\a</code>' (bell),
1211 A backslash followed by a real newline
1212 results in a newline in the string.
1214 of white-space characters,
1216 it is particularly useful to break and indent a long literal string
1222 A byte in a literal string can also be specified by its numerical value.
1224 where <em>XX</em> is a sequence of exactly two hexadecimal digits,
1226 where <em>ddd</em> is a sequence of up to three decimal digits.
1227 (Note that if a decimal escape is to be followed by a digit,
1229 Strings in Lua can contain any 8-bit value, including embedded zeros,
1234 Literal strings can also be defined using a long format
1242 A <em>closing long bracket</em> is defined similarly;
1243 for instance, a closing long bracket of level 4 is written as <code>]====]</code>.
1244 A <em>long literal</em> starts with an opening long bracket of any level and
1246 It can contain any text except a closing bracket of the proper level.
1250 Any kind of end-of-line sequence
1253 is converted to a simple newline.
1257 Any byte in a literal string not
1263 non-text data as a quoted literal with
1264 explicit escape sequences for non-text characters.
1269 when the opening long bracket is immediately followed by a newline,
1271 As an example, in a system using ASCII
1272 (in which '<code>a</code>' is coded as 97,
1277 a = 'alo\n123"'
1278 a = "alo\n123\""
1279 a = '\97lo\10\04923"'
1280 a = [[alo
1282 a = [==[
1288 A <em>numerical constant</em> can be written with an optional fractional part
1290 marked by a letter '<code>e</code>' or '<code>E</code>'.
1295 marked by a letter '<code>p</code>' or '<code>P</code>'.
1299 3 3.0 3.1416 314.16e-2 0.31416E1
1300 0xff 0x0.1E 0xA23p-4 0X1.921FB54442D18P+1
1304 A <em>comment</em> starts with a double hyphen (<code>--</code>)
1305 anywhere outside a string.
1306 If the text immediately after <code>--</code> is not an opening long bracket,
1307 the comment is a <em>short comment</em>,
1309 Otherwise, it is a <em>long comment</em>,
1317 <h2>3.2 – <a name="3.2">Variables</a></h2>
1326 A single name can denote a global variable or a local variable
1327 (or a function's formal parameter,
1328 which is a particular kind of local variable):
1333 Name denotes identifiers, as defined in <a href="#3.1">§3.1</a>.
1338 as a local (see <a href="#3.3.7">§3.3.7</a>).
1341 defined inside their scope (see <a href="#3.5">§3.5</a>).
1345 Before the first assignment to a variable, its value is <b>nil</b>.
1349 Square brackets are used to index a table:
1356 a call <code>gettable_event(t,i)</code>.
1357 (See <a href="#2.4">§2.4</a> for a complete description of the
1372 An access to a global variable <code>x</code>
1375 <code>_ENV</code> is never a global name (see <a href="#2.2">§2.2</a>).
1381 <h2>3.3 – <a name="3.3">Statements</a></h2>
1392 <h3>3.3.1 – <a name="3.3.1">Blocks</a></h3>
1395 A block is a list of statements,
1403 start a block with a semicolon
1417 a = b + c
1423 a = b + c(print or io.write)('done')
1425 a = b + c; (print or io.write)('done')
1430 as the start of the arguments to a call.
1432 it is a good practice to always precede with a semicolon
1433 statements that start with a parenthesis:
1440 A block can be explicitly delimited to produce a single statement:
1448 add a <b>return</b> statement in the middle
1449 of another block (see <a href="#3.3.4">§3.3.4</a>).
1455 <h3>3.3.2 – <a name="3.3.2">Chunks</a></h3>
1458 The unit of compilation of Lua is called a <em>chunk</em>.
1460 a chunk is simply a block:
1467 Lua handles a chunk as the body of an anonymous function
1468 with a variable number of arguments
1469 (see <a href="#3.4.10">§3.4.10</a>).
1473 scope of an external local variable called <code>_ENV</code> (see <a href="#2.2">§2.2</a>).
1479 A chunk can be stored in a file or in a string inside the host program.
1480 To execute a chunk,
1481 Lua first precompiles the chunk into instructions for a virtual machine,
1497 <h3>3.3.3 – <a name="3.3.3">Assignment</a></h3>
1502 defines a list of variables on the left side
1503 and a list of expressions on the right side.
1511 Expressions are discussed in <a href="#3.4">§3.4</a>.
1522 If the list of expressions ends with a function call,
1525 (except when the call is enclosed in parentheses; see <a href="#3.4">§3.4</a>).
1535 i, a[i] = i+1, 20
1537 sets <code>a[3]</code> to 20, without affecting <code>a[4]</code>
1538 because the <code>i</code> in <code>a[i]</code> is evaluated (to 3)
1559 (See <a href="#2.4">§2.4</a> for a complete description of the
1566 An assignment to a global variable <code>x = val</code>
1568 <code>_ENV.x = val</code> (see <a href="#2.2">§2.2</a>).
1574 <h3>3.3.4 – <a name="3.3.4">Control Structures</a></h3><p>
1587 Lua also has a <b>for</b> statement, in two flavors (see <a href="#3.3.5">§3.3.5</a>).
1591 The condition expression of a
1607 The <b>goto</b> statement transfers the program control to a label.
1620 A label is visible in the entire block where it is defined,
1622 inside nested blocks where a label with the same name is defined and
1624 A goto may jump to any visible label as long as it does not
1625 enter into the scope of a local variable.
1634 The <b>break</b> statement terminates the execution of a
1642 A <b>break</b> ends the innermost enclosing loop.
1647 from a function or a chunk (which is a function in disguise).
1658 as the last statement of a block.
1659 If it is really necessary to <b>return</b> in the middle of a block,
1668 <h3>3.3.5 – <a name="3.3.5">For Statement</a></h3>
1677 The numeric <b>for</b> loop repeats a block of code while a
1687 More precisely, a <b>for</b> statement like
1722 then a step of 1 is used.
1726 You can use <b>break</b> to exit a <b>for</b> loop.
1741 On each iteration, the iterator function is called to produce a new value,
1749 A <b>for</b> statement like
1774 a <em>state</em>,
1784 You can use <b>break</b> to exit a <b>for</b> loop.
1799 <h3>3.3.6 – <a name="3.3.6">Function Calls as Statements</a></h3><p>
1800 To allow possible side-effects,
1807 Function calls are explained in <a href="#3.4.9">§3.4.9</a>.
1813 <h3>3.3.7 – <a name="3.3.7">Local Declarations</a></h3><p>
1814 Local variables can be declared anywhere inside a block.
1821 of a multiple assignment (see <a href="#3.3.3">§3.3.3</a>).
1826 A chunk is also a block (see <a href="#3.3.2">§3.3.2</a>),
1827 and so local variables can be declared in a chunk outside any explicit block.
1831 The visibility rules for local variables are explained in <a href="#3.5">§3.5</a>.
1839 <h2>3.4 – <a name="3.4">Expressions</a></h2>
1858 Numbers and literal strings are explained in <a href="#3.1">§3.1</a>;
1859 variables are explained in <a href="#3.2">§3.2</a>;
1860 function definitions are explained in <a href="#3.4.10">§3.4.10</a>;
1861 function calls are explained in <a href="#3.4.9">§3.4.9</a>;
1862 table constructors are explained in <a href="#3.4.8">§3.4.8</a>.
1865 directly inside a vararg function;
1866 they are explained in <a href="#3.4.10">§3.4.10</a>.
1870 Binary operators comprise arithmetic operators (see <a href="#3.4.1">§3.4.1</a>),
1871 relational operators (see <a href="#3.4.3">§3.4.3</a>), logical operators (see <a href="#3.4.4…
1872 and the concatenation operator (see <a href="#3.4.5">§3.4.5</a>).
1873 Unary operators comprise the unary minus (see <a href="#3.4.1">§3.4.1</a>),
1874 the unary <b>not</b> (see <a href="#3.4.4">§3.4.4</a>),
1875 and the unary <em>length operator</em> (see <a href="#3.4.6">§3.4.6</a>).
1880 If a function call is used as a statement (see <a href="#3.3.6">§3.3.6</a>),
1884 of a list of expressions,
1890 or adding a single <b>nil</b> if there are no values.
1897 f() -- adjusted to 0 results
1898 g(f(), x) -- f() is adjusted to 1 result
1899 g(x, f()) -- g gets x plus all results from f()
1900 a,b,c = f(), x -- f() is adjusted to 1 result (c gets nil)
1901 a,b = ... -- a gets the first vararg parameter, b gets
1902 -- the second (both a and b can get nil if there
1903 -- is no corresponding vararg parameter)
1905 a,b,c = x, f() -- f() is adjusted to 2 results
1906 a,b,c = f() -- f() is adjusted to 3 results
1907 return f() -- returns all results from f()
1908 return ... -- returns all received vararg parameters
1909 return x,y,f() -- returns x, y, and all results from f()
1910 {f()} -- creates a list with all results from f()
1911 {...} -- creates a list with all vararg parameters
1912 {f(), nil} -- f() is adjusted to 1 result
1918 <code>(f(x,y,z))</code> is always a single value,
1925 <h3>3.4.1 – <a name="3.4.1">Arithmetic Operators</a></h3><p>
1928 <code>-</code> (subtraction), <code>*</code> (multiplication),
1930 and unary <code>-</code> (mathematical negation).
1932 numbers (see <a href="#3.4.2">§3.4.2</a>),
1935 For instance, <code>x^(-0.5)</code> computes the inverse of the square root of <code>x</code>.
1939 a % b == a - math.floor(a/b)*b
1941 That is, it is the remainder of a division that rounds
1948 <h3>3.4.2 – <a name="3.4.2">Coercion</a></h3>
1953 Any arithmetic operation applied to a string tries to convert
1954 this string to a number, following the rules of the Lua lexer.
1955 (The string may have leading and trailing spaces and a sign.)
1956 Conversely, whenever a number is used where a string is expected,
1957 the number is converted to a string, in a reasonable format.
1960 (see <a href="#pdf-string.format"><code>string.format</code></a>).
1966 <h3>3.4.3 – <a name="3.4.3">Relational Operators</a></h3><p>
1983 Every time you create a new object
1984 (a table, userdata, or thread),
1993 by using the "eq" metamethod (see <a href="#2.4">§2.4</a>).
1997 The conversion rules of <a href="#3.4.2">§3.4.2</a>
2001 entries in a table.
2014 metamethod (see <a href="#2.4">§2.4</a>).
2015 A comparison <code>a > b</code> is translated to <code>b < a</code>
2016 and <code>a >= b</code> is translated to <code>b <= a</code>.
2022 <h3>3.4.4 – <a name="3.4.4">Logical Operators</a></h3><p>
2025 Like the control structures (see <a href="#3.3.4">§3.3.4</a>),
2038 Both <b>and</b> and <b>or</b> use short-cut evaluation;
2044 10 or 20 --> 10
2045 10 or error() --> 10
2046 nil or "a" --> "a"
2047 nil and 10 --> nil
2048 false and error() --> false
2049 false and nil --> false
2050 false or nil --> nil
2051 10 and 20 --> 20
2054 <code>--></code> indicates the result of the preceding expression.)
2060 <h3>3.4.5 – <a name="3.4.5">Concatenation</a></h3><p>
2064 strings according to the rules mentioned in <a href="#3.4.2">§3.4.2</a>.
2065 Otherwise, the <code>__concat</code> metamethod is called (see <a href="#2.4">§2.4</a>).
2071 <h3>3.4.6 – <a name="3.4.6">The Length Operator</a></h3>
2075 The length of a string is its number of bytes
2081 A program can modify the behavior of the length operator for
2082 any value but strings through the <code>__len</code> metamethod (see <a href="#2.4">§2.4</a>).
2086 Unless a <code>__len</code> metamethod is given,
2087 the length of a table <code>t</code> is only defined if the
2088 table is a <em>sequence</em>,
2091 for some non-negative integer <em>n</em>.
2093 Note that a table like
2098 is not a sequence, because it has the key <code>4</code>
2102 Note, however, that non-numeric keys do not interfere
2103 with whether a table is a sequence.
2109 <h3>3.4.7 – <a name="3.4.7">Precedence</a></h3><p>
2118 + -
2120 not # - (unary)
2133 <h3>3.4.8 – <a name="3.4.8">Table Constructors</a></h3><p>
2135 Every time a constructor is evaluated, a new table is created.
2136 A constructor can be used to create an empty table
2137 or to create a table and initialize some of its fields.
2150 A field of the form <code>name = exp</code> is equivalent to
2159 a = { [f(1)] = g; "x", "y"; x = 1, f(x), [30] = 23; 45 }
2167 t[1] = "x" -- 1st exp
2168 t[2] = "y" -- 2nd exp
2169 t.x = 1 -- t["x"] = 1
2170 t[3] = f(x) -- 3rd exp
2172 t[4] = 45 -- 4th exp
2173 a = t
2179 and the expression is a function call or a vararg expression,
2181 (see <a href="#3.4.9">§3.4.9</a>).
2186 as a convenience for machine-generated code.
2192 <h3>3.4.9 – <a name="3.4.9">Function Calls</a></h3><p>
2193 A function call in Lua has the following syntax:
2198 In a function call,
2206 (see <a href="#2.4">§2.4</a>).
2216 A call <code>v:name(<em>args</em>)</code>
2230 A call of the form <code>f{<em>fields</em>}</code> is
2232 that is, the argument list is a single new table.
2233 A call of the form <code>f'<em>string</em>'</code>
2236 that is, the argument list is a single literal string.
2240 A call of the form <code>return <em>functioncall</em></code> is called
2241 a <em>tail call</em>.
2244 in a tail call,
2247 a program can execute.
2248 However, a tail call erases any debug information about the
2250 Note that a tail call only happens with a particular syntax,
2257 return (f(x)) -- results adjusted to 1
2259 return x, f(x) -- additional results
2260 f(x); return -- results discarded
2261 return x or f(x) -- results adjusted to 1
2267 <h3>3.4.10 – <a name="3.4.10">Function Definitions</a></h3>
2298 function t.a.b.c.f () <em>body</em> end
2303 t.a.b.c.f = function () <em>body</em> end
2320 (This only makes a difference when the body of the function
2325 A function definition is an executable expression,
2327 When Lua precompiles a chunk,
2342 When a function is called,
2345 unless the function is a <em>vararg function</em>,
2348 A vararg function does not adjust its argument list;
2350 to the function through a <em>vararg expression</em>,
2352 The value of this expression is a list of all actual extra arguments,
2353 similar to a function with multiple results.
2354 If a vararg expression is used inside another expression
2355 or in the middle of a list of expressions,
2357 If the expression is used as the last element of a list of expressions,
2366 function f(a, b) end
2367 function g(a, b, ...) end
2376 f(3) a=3, b=nil
2377 f(3, 4) a=3, b=4
2378 f(3, 4, 5) a=3, b=4
2379 f(r(), 10) a=1, b=10
2380 f(r()) a=1, b=2
2382 g(3) a=3, b=nil, ... --> (nothing)
2383 g(3, 4) a=3, b=4, ... --> (nothing)
2384 g(3, 4, 5, 8) a=3, b=4, ... --> 5 8
2385 g(5, r()) a=5, b=1, ... --> 2 3
2389 Results are returned using the <b>return</b> statement (see <a href="#3.3.4">§3.3.4</a>).
2390 If control reaches the end of a function
2391 without encountering a <b>return</b> statement,
2397 There is a system-dependent limit on the number of values
2398 that a function may return.
2409 function t.a.b.c:f (<em>params</em>) <em>body</em> end
2414 t.a.b.c.f = function (self, <em>params</em>) <em>body</em> end
2422 <h2>3.5 – <a name="3.5">Visibility Rules</a></h2>
2426 Lua is a lexically scoped language.
2427 The scope of a local variable begins at the first statement after
2428 its declaration and lasts until the last non-void statement
2433 x = 10 -- global variable
2434 do -- new block
2435 local x = x -- new 'x', with value 10
2436 print(x) --> 10
2438 do -- another block
2439 local x = x+1 -- another 'x'
2440 print(x) --> 12
2442 print(x) --> 11
2444 print(x) --> 10 (the global one)
2448 Notice that, in a declaration like <code>local x = x</code>,
2457 A local variable used by an inner function is called
2463 Notice that each execution of a <b>local</b> statement
2468 a = {}
2472 a[i] = function () y=y+1; return x+y end
2477 Each of these closures uses a different <code>y</code> variable,
2484 <h1>4 – <a name="4">The Application Program Interface</a></h1>
2492 are declared in the header file <a name="pdf-lua.h"><code>lua.h</code></a>.
2497 any facility in the API may be provided as a macro instead.
2500 (except for the first argument, which is always a Lua state),
2501 and so do not generate any hidden side-effects.
2508 with the macro <a name="pdf-LUA_USE_APICHECK"><code>LUA_USE_APICHECK</code></a> defined.
2512 <h2>4.1 – <a name="4.1">The Stack</a></h2>
2515 Lua uses a <em>virtual stack</em> to pass values to and from C.
2516 Each element in this stack represents a Lua value
2521 Whenever Lua calls C, the called function gets a new stack,
2526 to be returned to the caller (see <a href="#lua_CFunction"><code>lua_CFunction</code></a>).
2531 most query operations in the API do not follow a strict stack discipline.
2534 A positive index represents an absolute stack position
2536 a negative index represents an offset relative to the top of the stack.
2542 index -1 also represents the last element
2544 and index <em>-n</em> represents the first element.
2550 <h2>4.2 – <a name="4.2">Stack Size</a></h2>
2557 You can use the function <a href="#lua_checkstack"><code>lua_checkstack</code></a>
2563 it ensures that the stack has at least <a name="pdf-LUA_MINSTACK"><code>LUA_MINSTACK</code></a> ext…
2570 When you call a Lua function
2571 without a fixed number of results (see <a href="#lua_call"><code>lua_call</code></a>),
2574 So, before pushing anything in the stack after such a call
2575 you should use <a href="#lua_checkstack"><code>lua_checkstack</code></a>.
2581 <h2>4.3 – <a name="4.3">Valid and Acceptable Indices</a></h2>
2589 A <em>valid index</em> is an index that refers to a
2600 any function that accepts valid indices also accepts <em>pseudo-indices</em>,
2603 Pseudo-indices are used to access the registry
2604 and the upvalues of a C function (see <a href="#4.4">§4.4</a>).
2608 Functions that do not need a specific stack position,
2609 but only a value in the stack (e.g., query functions),
2612 including the pseudo-indices,
2624 For instance, a C function can query its third argument
2625 without the need to first check whether there is a third argument,
2626 that is, without the need to check whether 3 is a valid index.
2631 any non-valid index is treated as if it
2632 contains a value of a virtual type <a name="pdf-LUA_TNONE"><code>LUA_TNONE</code></a>,
2633 which behaves like a nil value.
2639 <h2>4.4 – <a name="4.4">C Closures</a></h2>
2642 When a C function is created,
2644 thus creating a <em>C closure</em>
2645 (see <a href="#lua_pushcclosure"><code>lua_pushcclosure</code></a>);
2651 Whenever a C function is called,
2652 its upvalues are located at specific pseudo-indices.
2653 These pseudo-indices are produced by the macro
2654 <a href="#lua_upvalueindex"><code>lua_upvalueindex</code></a>.
2655 The first value associated with a function is at position
2666 <h2>4.5 – <a name="4.5">Registry</a></h2>
2669 Lua provides a <em>registry</em>,
2670 a predefined table that can be used by any C code to
2672 The registry table is always located at pseudo-index
2673 <a name="pdf-LUA_REGISTRYINDEX"><code>LUA_REGISTRYINDEX</code></a>,
2674 which is a valid index.
2679 Typically, you should use as key a string containing your library name,
2680 or a light userdata with the address of a C object in your code,
2695 When you create a new Lua state,
2702 <li><b><a name="pdf-LUA_RIDX_MAINTHREAD"><code>LUA_RIDX_MAINTHREAD</code></a>: </b> At this index t…
2707 <li><b><a name="pdf-LUA_RIDX_GLOBALS"><code>LUA_RIDX_GLOBALS</code></a>: </b> At this index the reg…
2715 <h2>4.6 – <a name="4.6">Error Handling in C</a></h2>
2722 (such as a memory allocation error, type errors, syntax errors,
2725 that is, it does a long jump.
2726 A <em>protected environment</em> uses <code>setjmp</code>
2727 to set a recovery point;
2733 Lua calls a <em>panic function</em> (see <a href="#lua_atpanic"><code>lua_atpanic</code></a>)
2738 (e.g., doing a long jump to your own recovery point outside Lua).
2742 The panic function runs as if it were a message handler (see <a href="#2.3">§2.3</a>);
2746 the panic function should first check the available space (see <a href="#4.2">§4.2</a>).
2751 for instance due to a memory allocation error.
2757 Inside a C function you can throw an error by calling <a href="#lua_error"><code>lua_error</co…
2763 <h2>4.7 – <a name="4.7">Handling Yields in C</a></h2>
2766 Internally, Lua uses the C <code>longjmp</code> facility to yield a coroutine.
2767 Therefore, if a function <code>foo</code> calls an API function
2778 <a href="#lua_yieldk"><code>lua_yieldk</code></a>, <a href="#lua_callk"><code>lua_callk</code></a>,…
2779 All those functions receive a <em>continuation function</em>
2780 (as a parameter called <code>k</code>) to continue execution after a yield.
2785 We have a C function called from Lua which we will call
2790 (This can happen when the callee function is <a href="#lua_yieldk"><code>lua_yieldk</code></a>,
2791 …callee function is either <a href="#lua_callk"><code>lua_callk</code></a> or <a href="#lua_pcallk"…
2802 Instead, Lua calls a <em>continuation function</em>,
2815 after a <a href="#lua_callk"><code>lua_callk</code></a> the function and its arguments are
2824 and its continuation is the result of a call to <a href="#lua_getctx"><code>lua_getctx</code></a>.
2830 <h2>4.8 – <a name="4.8">Functions and Types</a></h2>
2836 <span class="apii">[-o, +p, <em>x</em>]</span>
2845 A field in the form <code>x|y</code> means the function can push (or pop)
2854 '<code>-</code>' means the function never throws any error;
2860 <hr><h3><a name="lua_absindex"><code>lua_absindex</code></a></h3><p>
2861 <span class="apii">[-0, +0, –]</span>
2872 <hr><h3><a name="lua_Alloc"><code>lua_Alloc</code></a></h3>
2879 The type of the memory-allocation function used by Lua states.
2880 The allocator function must provide a
2884 <code>ud</code>, an opaque pointer passed to <a href="#lua_newstate"><code>lua_newstate</code></a>;
2885 <code>ptr</code>, a pointer to the block being allocated/reallocated/freed;
2901 …a href="#pdf-LUA_TSTRING"><code>LUA_TSTRING</code></a>, <a href="#pdf-LUA_TTABLE"><code>LUA_TTABLE…
2902 <a href="#pdf-LUA_TUSERDATA"><code>LUA_TUSERDATA</code></a>, or <a href="#pdf-LUA_TTHREAD"><code>LU…
2903 Lua is creating a new object of that type.
2928 Here is a simple implementation for the allocator function.
2929 It is used in the auxiliary library by <a href="#luaL_newstate"><code>luaL_newstate</code></a>.
2946 This code assumes that <code>realloc</code> does not fail when shrinking a block.
2948 it seems to be a safe assumption.)
2954 <hr><h3><a name="lua_arith"><code>lua_arith</code></a></h3><p>
2955 <span class="apii">[-(2|1), +1, <em>e</em>]</span>
2973 <li><b><a name="pdf-LUA_OPADD"><code>LUA_OPADD</code></a>: </b> performs addition (<code>+</code>)<…
2974 <li><b><a name="pdf-LUA_OPSUB"><code>LUA_OPSUB</code></a>: </b> performs subtraction (<code>-</code…
2975 <li><b><a name="pdf-LUA_OPMUL"><code>LUA_OPMUL</code></a>: </b> performs multiplication (<code>*</c…
2976 <li><b><a name="pdf-LUA_OPDIV"><code>LUA_OPDIV</code></a>: </b> performs division (<code>/</code>)<…
2977 <li><b><a name="pdf-LUA_OPMOD"><code>LUA_OPMOD</code></a>: </b> performs modulo (<code>%</code>)</l…
2978 <li><b><a name="pdf-LUA_OPPOW"><code>LUA_OPPOW</code></a>: </b> performs exponentiation (<code>^</c…
2979 <li><b><a name="pdf-LUA_OPUNM"><code>LUA_OPUNM</code></a>: </b> performs mathematical negation (una…
2986 <hr><h3><a name="lua_atpanic"><code>lua_atpanic</code></a></h3><p>
2987 <span class="apii">[-0, +0, –]</span>
2991 Sets a new panic function and returns the old one (see <a href="#4.6">§4.6</a>).
2997 <hr><h3><a name="lua_call"><code>lua_call</code></a></h3><p>
2998 <span class="apii">[-(nargs+1), +nresults, <em>e</em>]</span>
3002 Calls a function.
3006 To call a function you must use the following protocol:
3011 Finally you call <a href="#lua_call"><code>lua_call</code></a>;
3017 unless <code>nresults</code> is <a name="pdf-LUA_MULTRET"><code>LUA_MULTRET</code></a>.
3027 (with a <code>longjmp</code>).
3035 a = f("how", t.x, 14)
3043 lua_getfield(L, -1, "x"); /* push result of t.x (2nd arg) */
3044 lua_remove(L, -2); /* remove 't' from the stack */
3047 lua_setglobal(L, "a"); /* set global 'a' */
3057 <hr><h3><a name="lua_callk"><code>lua_callk</code></a></h3><p>
3058 <span class="apii">[-(nargs + 1), +nresults, <em>e</em>]</span>
3063 This function behaves exactly like <a href="#lua_call"><code>lua_call</code></a>,
3064 but allows the called function to yield (see <a href="#4.7">§4.7</a>).
3070 <hr><h3><a name="lua_CFunction"><code>lua_CFunction</code></a></h3>
3079 a C function must use the following protocol,
3081 a C function receives its arguments from Lua in its stack
3087 To return values to Lua, a C function just pushes them onto the stack,
3092 Like a Lua function, a C function called by Lua can also return
3097 As an example, the following function receives a variable number
3121 <hr><h3><a name="lua_checkstack"><code>lua_checkstack</code></a></h3><p>
3122 <span class="apii">[-0, +0, –]</span>
3128 because it would cause the stack to be larger than a fixed maximum size
3129 (typically at least a few thousand elements) or
3139 <hr><h3><a name="lua_close"><code>lua_close</code></a></h3><p>
3140 <span class="apii">[-0, +0, –]</span>
3145 (calling the corresponding garbage-collection metamethods, if any)
3149 On the other hand, long-running programs that create multiple states,
3157 <hr><h3><a name="lua_compare"><code>lua_compare</code></a></h3><p>
3158 <span class="apii">[-0, +0, <em>e</em>]</span>
3176 <li><b><a name="pdf-LUA_OPEQ"><code>LUA_OPEQ</code></a>: </b> compares for equality (<code>==</code…
3177 <li><b><a name="pdf-LUA_OPLT"><code>LUA_OPLT</code></a>: </b> compares for less than (<code><</c…
3178 <li><b><a name="pdf-LUA_OPLE"><code>LUA_OPLE</code></a>: </b> compares for less or equal (<code><…
3185 <hr><h3><a name="lua_concat"><code>lua_concat</code></a></h3><p>
3186 <span class="apii">[-n, +1, <em>e</em>]</span>
3196 (see <a href="#3.4.5">§3.4.5</a>).
3202 <hr><h3><a name="lua_copy"><code>lua_copy</code></a></h3><p>
3203 <span class="apii">[-0, +0, –]</span>
3216 <hr><h3><a name="lua_createtable"><code>lua_createtable</code></a></h3><p>
3217 <span class="apii">[-0, +1, <em>e</em>]</span>
3221 Creates a new empty table and pushes it onto the stack.
3222 Parameter <code>narr</code> is a hint for how many elements the table
3223 will have as a sequence;
3224 parameter <code>nrec</code> is a hint for how many other elements
3227 This pre-allocation is useful for performance when you know in advance
3229 Otherwise you can use the function <a href="#lua_newtable"><code>lua_newtable</code></a>.
3235 <hr><h3><a name="lua_dump"><code>lua_dump</code></a></h3><p>
3236 <span class="apii">[-0, +0, <em>e</em>]</span>
3240 Dumps a function as a binary chunk.
3241 Receives a Lua function on the top of the stack
3242 and produces a binary chunk that,
3244 results in a function equivalent to the one dumped.
3246 <a href="#lua_dump"><code>lua_dump</code></a> calls function <code>writer</code> (see <a href="#lua…
3264 <hr><h3><a name="lua_error"><code>lua_error</code></a></h3><p>
3265 <span class="apii">[-1, +0, <em>v</em>]</span>
3269 Generates a Lua error.
3270 The error message (which can actually be a Lua value of any type)
3272 This function does a long jump,
3274 (see <a href="#luaL_error"><code>luaL_error</code></a>).
3280 <hr><h3><a name="lua_gc"><code>lua_gc</code></a></h3><p>
3281 <span class="apii">[-0, +0, <em>e</em>]</span>
3303 performs a full garbage-collection cycle.
3318 (larger values mean more steps) in a non-specified way.
3321 The function returns 1 if the step finished a
3322 garbage-collection cycle.
3327 for the <em>pause</em> of the collector (see <a href="#2.5">§2.5</a>).
3333 the collector (see <a href="#2.5">§2.5</a>).
3338 returns a boolean that tells whether the collector is running
3344 (see <a href="#2.5">§2.5</a>).
3356 see <a href="#pdf-collectgarbage"><code>collectgarbage</code></a>.
3362 <hr><h3><a name="lua_getallocf"><code>lua_getallocf</code></a></h3><p>
3363 <span class="apii">[-0, +0, –]</span>
3367 Returns the memory-allocation function of a given state.
3369 opaque pointer passed to <a href="#lua_newstate"><code>lua_newstate</code></a>.
3375 <hr><h3><a name="lua_getctx"><code>lua_getctx</code></a></h3><p>
3376 <span class="apii">[-0, +0, –]</span>
3380 This function is called by a continuation function (see <a href="#4.7">§4.7</a>)
3381 to retrieve the status of the thread and a context information.
3386 <a href="#lua_getctx"><code>lua_getctx</code></a> always returns <a href="#pdf-LUA_OK"><code>LUA_OK…
3388 When called inside a continuation function,
3389 <a href="#lua_getctx"><code>lua_getctx</code></a> returns <a href="#pdf-LUA_YIELD"><code>LUA_YIELD<…
3396 When the callee is <a href="#lua_pcallk"><code>lua_pcallk</code></a>,
3399 That is, upon an error in the function called by <a href="#lua_pcallk"><code>lua_pcallk</code></a>,
3402 In that case, a call to <a href="#lua_getctx"><code>lua_getctx</code></a> will return the error code
3403 (the value that would be returned by <a href="#lua_pcallk"><code>lua_pcallk</code></a>);
3405 as in the case of a yield.
3411 <hr><h3><a name="lua_getfield"><code>lua_getfield</code></a></h3><p>
3412 <span class="apii">[-0, +1, <em>e</em>]</span>
3418 As in Lua, this function may trigger a metamethod
3419 for the "index" event (see <a href="#2.4">§2.4</a>).
3425 <hr><h3><a name="lua_getglobal"><code>lua_getglobal</code></a></h3><p>
3426 <span class="apii">[-0, +1, <em>e</em>]</span>
3436 <hr><h3><a name="lua_getmetatable"><code>lua_getmetatable</code></a></h3><p>
3437 <span class="apii">[-0, +(0|1), –]</span>
3442 If the value does not have a metatable,
3449 <hr><h3><a name="lua_gettable"><code>lua_gettable</code></a></h3><p>
3450 <span class="apii">[-1, +1, <em>e</em>]</span>
3462 As in Lua, this function may trigger a metamethod
3463 for the "index" event (see <a href="#2.4">§2.4</a>).
3469 <hr><h3><a name="lua_gettop"><code>lua_gettop</code></a></h3><p>
3470 <span class="apii">[-0, +0, –]</span>
3483 <hr><h3><a name="lua_getuservalue"><code>lua_getuservalue</code></a></h3><p>
3484 <span class="apii">[-0, +1, –]</span>
3490 This Lua value must be a table or <b>nil</b>.
3496 <hr><h3><a name="lua_insert"><code>lua_insert</code></a></h3><p>
3497 <span class="apii">[-1, +1, –]</span>
3503 This function cannot be called with a pseudo-index,
3504 because a pseudo-index is not an actual stack position.
3510 <hr><h3><a name="lua_Integer"><code>lua_Integer</code></a></h3>
3518 By default it is a <code>ptrdiff_t</code>,
3526 <hr><h3><a name="lua_isboolean"><code>lua_isboolean</code></a></h3><p>
3527 <span class="apii">[-0, +0, –]</span>
3531 Returns 1 if the value at the given index is a boolean,
3538 <hr><h3><a name="lua_iscfunction"><code>lua_iscfunction</code></a></h3><p>
3539 <span class="apii">[-0, +0, –]</span>
3543 Returns 1 if the value at the given index is a C function,
3550 <hr><h3><a name="lua_isfunction"><code>lua_isfunction</code></a></h3><p>
3551 <span class="apii">[-0, +0, –]</span>
3555 Returns 1 if the value at the given index is a function
3562 <hr><h3><a name="lua_islightuserdata"><code>lua_islightuserdata</code></a></h3><p>
3563 <span class="apii">[-0, +0, –]</span>
3567 Returns 1 if the value at the given index is a light userdata,
3574 <hr><h3><a name="lua_isnil"><code>lua_isnil</code></a></h3><p>
3575 <span class="apii">[-0, +0, –]</span>
3586 <hr><h3><a name="lua_isnone"><code>lua_isnone</code></a></h3><p>
3587 <span class="apii">[-0, +0, –]</span>
3598 <hr><h3><a name="lua_isnoneornil"><code>lua_isnoneornil</code></a></h3><p>
3599 <span class="apii">[-0, +0, –]</span>
3611 <hr><h3><a name="lua_isnumber"><code>lua_isnumber</code></a></h3><p>
3612 <span class="apii">[-0, +0, –]</span>
3616 Returns 1 if the value at the given index is a number
3617 or a string convertible to a number,
3624 <hr><h3><a name="lua_isstring"><code>lua_isstring</code></a></h3><p>
3625 <span class="apii">[-0, +0, –]</span>
3629 Returns 1 if the value at the given index is a string
3630 or a number (which is always convertible to a string),
3637 <hr><h3><a name="lua_istable"><code>lua_istable</code></a></h3><p>
3638 <span class="apii">[-0, +0, –]</span>
3642 Returns 1 if the value at the given index is a table,
3649 <hr><h3><a name="lua_isthread"><code>lua_isthread</code></a></h3><p>
3650 <span class="apii">[-0, +0, –]</span>
3654 Returns 1 if the value at the given index is a thread,
3661 <hr><h3><a name="lua_isuserdata"><code>lua_isuserdata</code></a></h3><p>
3662 <span class="apii">[-0, +0, –]</span>
3666 Returns 1 if the value at the given index is a userdata
3673 <hr><h3><a name="lua_len"><code>lua_len</code></a></h3><p>
3674 <span class="apii">[-0, +1, <em>e</em>]</span>
3679 it is equivalent to the '<code>#</code>' operator in Lua (see <a href="#3.4.6">§3.4.6</a>).
3686 <hr><h3><a name="lua_load"><code>lua_load</code></a></h3><p>
3687 <span class="apii">[-0, +1, –]</span>
3695 Loads a Lua chunk (without running it).
3697 <code>lua_load</code> pushes the compiled chunk as a Lua
3707 <li><b><a href="#pdf-LUA_OK"><code>LUA_OK</code></a>: </b> no errors;</li>
3709 <li><b><a name="pdf-LUA_ERRSYNTAX"><code>LUA_ERRSYNTAX</code></a>: </b>
3712 <li><b><a href="#pdf-LUA_ERRMEM"><code>LUA_ERRMEM</code></a>: </b>
3715 <li><b><a href="#pdf-LUA_ERRGCMM"><code>LUA_ERRGCMM</code></a>: </b>
3716 error while running a <code>__gc</code> metamethod.
3724 The <code>lua_load</code> function uses a user-supplied <code>reader</code> function
3725 to read the chunk (see <a href="#lua_Reader"><code>lua_Reader</code></a>).
3730 The <code>source</code> argument gives a name to the chunk,
3731 which is used for error messages and in debug information (see <a href="#4.9">§4.9</a>).
3737 The string <code>mode</code> works as in function <a href="#pdf-load"><code>load</code></a>,
3739 a <code>NULL</code> value is equivalent to the string "<code>bt</code>".
3751 stored at index <code>LUA_RIDX_GLOBALS</code> in the registry (see <a href="#4.5">§4.5</a>).
3753 this upvalue will be the <code>_ENV</code> variable (see <a href="#2.2">§2.2</a>).
3759 <hr><h3><a name="lua_newstate"><code>lua_newstate</code></a></h3><p>
3760 <span class="apii">[-0, +0, –]</span>
3764 Creates a new thread running in a new, independent state.
3776 <hr><h3><a name="lua_newtable"><code>lua_newtable</code></a></h3><p>
3777 <span class="apii">[-0, +1, <em>e</em>]</span>
3781 Creates a new empty table and pushes it onto the stack.
3788 <hr><h3><a name="lua_newthread"><code>lua_newthread</code></a></h3><p>
3789 <span class="apii">[-0, +1, <em>e</em>]</span>
3793 Creates a new thread, pushes it on the stack,
3794 and returns a pointer to a <a href="#lua_State"><code>lua_State</code></a> that represents this new…
3801 There is no explicit function to close or to destroy a thread.
3809 <hr><h3><a name="lua_newuserdata"><code>lua_newuserdata</code></a></h3><p>
3810 <span class="apii">[-0, +1, <em>e</em>]</span>
3814 This function allocates a new block of memory with the given size,
3815 pushes onto the stack a new full userdata with the block address,
3823 <hr><h3><a name="lua_next"><code>lua_next</code></a></h3><p>
3824 <span class="apii">[-1, +(2|0), <em>e</em>]</span>
3828 Pops a key from the stack,
3829 and pushes a key–value pair from the table at the given index
3832 then <a href="#lua_next"><code>lua_next</code></a> returns 0 (and pushes nothing).
3836 A typical traversal looks like this:
3842 /* uses 'key' (at index -2) and 'value' (at index -1) */
3843 printf("%s - %s\n",
3844 lua_typename(L, lua_type(L, -2)),
3845 lua_typename(L, lua_type(L, -1)));
3852 While traversing a table,
3853 do not call <a href="#lua_tolstring"><code>lua_tolstring</code></a> directly on a key,
3854 unless you know that the key is actually a string.
3855 Recall that <a href="#lua_tolstring"><code>lua_tolstring</code></a> may change
3857 this confuses the next call to <a href="#lua_next"><code>lua_next</code></a>.
3861 See function <a href="#pdf-next"><code>next</code></a> for the caveats of modifying
3868 <hr><h3><a name="lua_Number"><code>lua_Number</code></a></h3>
3881 <hr><h3><a name="lua_pcall"><code>lua_pcall</code></a></h3><p>
3882 <span class="apii">[-(nargs + 1), +(nresults|1), –]</span>
3886 Calls a function in protected mode.
3891 in <a href="#lua_call"><code>lua_call</code></a>.
3893 <a href="#lua_pcall"><code>lua_pcall</code></a> behaves exactly like <a href="#lua_call"><code>lua_…
3895 <a href="#lua_pcall"><code>lua_pcall</code></a> catches it,
3896 pushes a single value on the stack (the error message),
3898 Like <a href="#lua_call"><code>lua_call</code></a>,
3899 <a href="#lua_pcall"><code>lua_pcall</code></a> always removes the function
3907 Otherwise, <code>msgh</code> is the stack index of a
3909 (In the current implementation, this index cannot be a pseudo-index.)
3913 returned on the stack by <a href="#lua_pcall"><code>lua_pcall</code></a>.
3918 information to the error message, such as a stack traceback.
3919 …h information cannot be gathered after the return of <a href="#lua_pcall"><code>lua_pcall</code></…
3924 The <a href="#lua_pcall"><code>lua_pcall</code></a> function returns one of the following codes
3929 <li><b><a name="pdf-LUA_OK"><code>LUA_OK</code></a> (0): </b>
3932 <li><b><a name="pdf-LUA_ERRRUN"><code>LUA_ERRRUN</code></a>: </b>
3933 a runtime error.
3936 <li><b><a name="pdf-LUA_ERRMEM"><code>LUA_ERRMEM</code></a>: </b>
3941 <li><b><a name="pdf-LUA_ERRERR"><code>LUA_ERRERR</code></a>: </b>
3945 <li><b><a name="pdf-LUA_ERRGCMM"><code>LUA_ERRGCMM</code></a>: </b>
3946 error while running a <code>__gc</code> metamethod.
3956 <hr><h3><a name="lua_pcallk"><code>lua_pcallk</code></a></h3><p>
3957 <span class="apii">[-(nargs + 1), +(nresults|1), –]</span>
3966 This function behaves exactly like <a href="#lua_pcall"><code>lua_pcall</code></a>,
3967 but allows the called function to yield (see <a href="#4.7">§4.7</a>).
3973 <hr><h3><a name="lua_pop"><code>lua_pop</code></a></h3><p>
3974 <span class="apii">[-n, +0, –]</span>
3984 <hr><h3><a name="lua_pushboolean"><code>lua_pushboolean</code></a></h3><p>
3985 <span class="apii">[-0, +1, –]</span>
3989 Pushes a boolean value with value <code>b</code> onto the stack.
3995 <hr><h3><a name="lua_pushcclosure"><code>lua_pushcclosure</code></a></h3><p>
3996 <span class="apii">[-n, +1, <em>e</em>]</span>
4000 Pushes a new C closure onto the stack.
4004 When a C function is created,
4006 thus creating a C closure (see <a href="#4.4">§4.4</a>);
4008 To associate values with a C function,
4011 Then <a href="#lua_pushcclosure"><code>lua_pushcclosure</code></a>
4015 <a href="#lua_pushcclosure"><code>lua_pushcclosure</code></a> also pops these values from the stack.
4024 this function creates a <em>light C function</em>,
4025 which is just a pointer to the C function.
4026 In that case, it never throws a memory error.
4032 <hr><h3><a name="lua_pushcfunction"><code>lua_pushcfunction</code></a></h3><p>
4033 <span class="apii">[-0, +1, –]</span>
4037 Pushes a C function onto the stack.
4038 This function receives a pointer to a C function
4039 and pushes onto the stack a Lua value of type <code>function</code> that,
4046 and return its results (see <a href="#lua_CFunction"><code>lua_CFunction</code></a>).
4050 <code>lua_pushcfunction</code> is defined as a macro:
4061 <hr><h3><a name="lua_pushfstring"><code>lua_pushfstring</code></a></h3><p>
4062 <span class="apii">[-0, +1, <em>e</em>]</span>
4066 Pushes onto the stack a formatted string
4067 and returns a pointer to this string.
4075 the result is a Lua string and Lua takes care of memory allocation
4083 '<code>%%</code>' (inserts a '<code>%</code>' in the string),
4084 '<code>%s</code>' (inserts a zero-terminated string, with no size restrictions),
4085 '<code>%f</code>' (inserts a <a href="#lua_Number"><code>lua_Number</code></a>),
4086 '<code>%p</code>' (inserts a pointer as a hexadecimal numeral),
4088 '<code>%c</code>' (inserts an <code>int</code> as a byte).
4096 <hr><h3><a name="lua_pushglobaltable"><code>lua_pushglobaltable</code></a></h3><p>
4097 <span class="apii">[-0, +1, –]</span>
4107 <hr><h3><a name="lua_pushinteger"><code>lua_pushinteger</code></a></h3><p>
4108 <span class="apii">[-0, +1, –]</span>
4112 Pushes a number with value <code>n</code> onto the stack.
4118 <hr><h3><a name="lua_pushlightuserdata"><code>lua_pushlightuserdata</code></a></h3><p>
4119 <span class="apii">[-0, +1, –]</span>
4123 Pushes a light userdata onto the stack.
4128 A <em>light userdata</em> represents a pointer, a <code>void*</code>.
4129 It is a value (like a number):
4132 A light userdata is equal to "any"
4139 <hr><h3><a name="lua_pushliteral"><code>lua_pushliteral</code></a></h3><p>
4140 <span class="apii">[-0, +1, <em>e</em>]</span>
4144 This macro is equivalent to <a href="#lua_pushlstring"><code>lua_pushlstring</code></a>,
4145 but can be used only when <code>s</code> is a literal string.
4152 <hr><h3><a name="lua_pushlstring"><code>lua_pushlstring</code></a></h3><p>
4153 <span class="apii">[-0, +1, <em>e</em>]</span>
4167 Returns a pointer to the internal copy of the string.
4173 <hr><h3><a name="lua_pushnil"><code>lua_pushnil</code></a></h3><p>
4174 <span class="apii">[-0, +1, –]</span>
4178 Pushes a nil value onto the stack.
4184 <hr><h3><a name="lua_pushnumber"><code>lua_pushnumber</code></a></h3><p>
4185 <span class="apii">[-0, +1, –]</span>
4189 Pushes a number with value <code>n</code> onto the stack.
4195 <hr><h3><a name="lua_pushstring"><code>lua_pushstring</code></a></h3><p>
4196 <span class="apii">[-0, +1, <em>e</em>]</span>
4200 Pushes the zero-terminated string pointed to by <code>s</code>
4208 Returns a pointer to the internal copy of the string.
4218 <hr><h3><a name="lua_pushthread"><code>lua_pushthread</code></a></h3><p>
4219 <span class="apii">[-0, +1, –]</span>
4230 <hr><h3><a name="lua_pushunsigned"><code>lua_pushunsigned</code></a></h3><p>
4231 <span class="apii">[-0, +1, –]</span>
4235 Pushes a number with value <code>n</code> onto the stack.
4241 <hr><h3><a name="lua_pushvalue"><code>lua_pushvalue</code></a></h3><p>
4242 <span class="apii">[-0, +1, –]</span>
4246 Pushes a copy of the element at the given index
4253 <hr><h3><a name="lua_pushvfstring"><code>lua_pushvfstring</code></a></h3><p>
4254 <span class="apii">[-0, +1, <em>e</em>]</span>
4260 Equivalent to <a href="#lua_pushfstring"><code>lua_pushfstring</code></a>, except that it receives …
4261 instead of a variable number of arguments.
4267 <hr><h3><a name="lua_rawequal"><code>lua_rawequal</code></a></h3><p>
4268 <span class="apii">[-0, +0, –]</span>
4282 <hr><h3><a name="lua_rawget"><code>lua_rawget</code></a></h3><p>
4283 <span class="apii">[-1, +1, –]</span>
4287 Similar to <a href="#lua_gettable"><code>lua_gettable</code></a>, but does a raw access
4294 <hr><h3><a name="lua_rawgeti"><code>lua_rawgeti</code></a></h3><p>
4295 <span class="apii">[-0, +1, –]</span>
4308 <hr><h3><a name="lua_rawgetp"><code>lua_rawgetp</code></a></h3><p>
4309 <span class="apii">[-0, +1, –]</span>
4315 <code>k</code> is the pointer <code>p</code> represented as a light userdata.
4323 <hr><h3><a name="lua_rawlen"><code>lua_rawlen</code></a></h3><p>
4324 <span class="apii">[-0, +0, –]</span>
4340 <hr><h3><a name="lua_rawset"><code>lua_rawset</code></a></h3><p>
4341 <span class="apii">[-2, +0, <em>e</em>]</span>
4345 Similar to <a href="#lua_settable"><code>lua_settable</code></a>, but does a raw assignment
4352 <hr><h3><a name="lua_rawseti"><code>lua_rawseti</code></a></h3><p>
4353 <span class="apii">[-1, +0, <em>e</em>]</span>
4371 <hr><h3><a name="lua_rawsetp"><code>lua_rawsetp</code></a></h3><p>
4372 <span class="apii">[-1, +0, <em>e</em>]</span>
4378 <code>k</code> is the pointer <code>p</code> represented as a light userdata,
4391 <hr><h3><a name="lua_Reader"><code>lua_Reader</code></a></h3>
4397 The reader function used by <a href="#lua_load"><code>lua_load</code></a>.
4399 <a href="#lua_load"><code>lua_load</code></a> calls the reader,
4401 The reader must return a pointer to a block of memory
4402 with a new piece of the chunk
4413 <hr><h3><a name="lua_register"><code>lua_register</code></a></h3><p>
4414 <span class="apii">[-0, +0, <em>e</em>]</span>
4419 It is defined as a macro:
4429 <hr><h3><a name="lua_remove"><code>lua_remove</code></a></h3><p>
4430 <span class="apii">[-1, +0, –]</span>
4436 This function cannot be called with a pseudo-index,
4437 because a pseudo-index is not an actual stack position.
4443 <hr><h3><a name="lua_replace"><code>lua_replace</code></a></h3><p>
4444 <span class="apii">[-1, +0, –]</span>
4457 <hr><h3><a name="lua_resume"><code>lua_resume</code></a></h3><p>
4458 <span class="apii">[-?, +?, –]</span>
4462 Starts and resumes a coroutine in a given thread.
4466 To start a coroutine,
4468 then you call <a href="#lua_resume"><code>lua_resume</code></a>,
4471 … it returns, the stack contains all values passed to <a href="#lua_yield"><code>lua_yield</code></…
4473 <a href="#lua_resume"><code>lua_resume</code></a> returns
4474 <a href="#pdf-LUA_YIELD"><code>LUA_YIELD</code></a> if the coroutine yields,
4475 <a href="#pdf-LUA_OK"><code>LUA_OK</code></a> if the coroutine finishes its execution
4477 or an error code in case of errors (see <a href="#lua_pcall"><code>lua_pcall</code></a>).
4488 To resume a coroutine,
4489 you remove any results from the last <a href="#lua_yield"><code>lua_yield</code></a>,
4492 and then call <a href="#lua_resume"><code>lua_resume</code></a>.
4504 <hr><h3><a name="lua_setallocf"><code>lua_setallocf</code></a></h3><p>
4505 <span class="apii">[-0, +0, –]</span>
4509 Changes the allocator function of a given state to <code>f</code>
4516 <hr><h3><a name="lua_setfield"><code>lua_setfield</code></a></h3><p>
4517 <span class="apii">[-1, +0, <em>e</em>]</span>
4528 As in Lua, this function may trigger a metamethod
4529 for the "newindex" event (see <a href="#2.4">§2.4</a>).
4535 <hr><h3><a name="lua_setglobal"><code>lua_setglobal</code></a></h3><p>
4536 <span class="apii">[-1, +0, <em>e</em>]</span>
4540 Pops a value from the stack and
4547 <hr><h3><a name="lua_setmetatable"><code>lua_setmetatable</code></a></h3><p>
4548 <span class="apii">[-1, +0, –]</span>
4552 Pops a table from the stack and
4559 <hr><h3><a name="lua_settable"><code>lua_settable</code></a></h3><p>
4560 <span class="apii">[-2, +0, <em>e</em>]</span>
4572 As in Lua, this function may trigger a metamethod
4573 for the "newindex" event (see <a href="#2.4">§2.4</a>).
4579 <hr><h3><a name="lua_settop"><code>lua_settop</code></a></h3><p>
4580 <span class="apii">[-?, +?, –]</span>
4594 <hr><h3><a name="lua_setuservalue"><code>lua_setuservalue</code></a></h3><p>
4595 <span class="apii">[-1, +0, –]</span>
4599 Pops a table or <b>nil</b> from the stack and sets it as
4606 <hr><h3><a name="lua_State"><code>lua_State</code></a></h3>
4610 An opaque structure that points to a thread and indirectly
4611 (through the thread) to the whole state of a Lua interpreter.
4614 All information about a state is accessible through this structure.
4618 A pointer to this structure must be passed as the first argument to
4619 every function in the library, except to <a href="#lua_newstate"><code>lua_newstate</code></a>,
4620 which creates a Lua state from scratch.
4626 <hr><h3><a name="lua_status"><code>lua_status</code></a></h3><p>
4627 <span class="apii">[-0, +0, –]</span>
4635 The status can be 0 (<a href="#pdf-LUA_OK"><code>LUA_OK</code></a>) for a normal thread,
4637 of a <a href="#lua_resume"><code>lua_resume</code></a> with an error,
4638 or <a name="pdf-LUA_YIELD"><code>LUA_YIELD</code></a> if the thread is suspended.
4642 You can only call functions in threads with status <a href="#pdf-LUA_OK"><code>LUA_OK</code></a>.
4643 You can resume threads with status <a href="#pdf-LUA_OK"><code>LUA_OK</code></a>
4644 (to start a new coroutine) or <a href="#pdf-LUA_YIELD"><code>LUA_YIELD</code></a>
4645 (to resume a coroutine).
4651 <hr><h3><a name="lua_toboolean"><code>lua_toboolean</code></a></h3><p>
4652 <span class="apii">[-0, +0, –]</span>
4656 Converts the Lua value at the given index to a C boolean
4659 <a href="#lua_toboolean"><code>lua_toboolean</code></a> returns true for any Lua value
4663 use <a href="#lua_isboolean"><code>lua_isboolean</code></a> to test the value's type.)
4669 <hr><h3><a name="lua_tocfunction"><code>lua_tocfunction</code></a></h3><p>
4670 <span class="apii">[-0, +0, –]</span>
4674 Converts a value at the given index to a C function.
4675 That value must be a C function;
4682 <hr><h3><a name="lua_tointeger"><code>lua_tointeger</code></a></h3><p>
4683 <span class="apii">[-0, +0, –]</span>
4687 Equivalent to <a href="#lua_tointegerx"><code>lua_tointegerx</code></a> with <code>isnum</code> equ…
4693 <hr><h3><a name="lua_tointegerx"><code>lua_tointegerx</code></a></h3><p>
4694 <span class="apii">[-0, +0, –]</span>
4699 to the signed integral type <a href="#lua_Integer"><code>lua_Integer</code></a>.
4700 The Lua value must be a number or a string convertible to a number
4701 (see <a href="#3.4.2">§3.4.2</a>);
4707 it is truncated in some non-specified way.
4712 its referent is assigned a boolean value that
4719 <hr><h3><a name="lua_tolstring"><code>lua_tolstring</code></a></h3><p>
4720 <span class="apii">[-0, +0, <em>e</em>]</span>
4724 Converts the Lua value at the given index to a C string.
4727 The Lua value must be a string or a number;
4729 If the value is a number,
4731 <em>changes the actual value in the stack to a string</em>.
4732 (This change confuses <a href="#lua_next"><code>lua_next</code></a>
4733 when <code>lua_tolstring</code> is applied to keys during a table traversal.)
4737 <code>lua_tolstring</code> returns a fully aligned pointer
4738 to a string inside the Lua state.
4739 This string always has a zero ('<code>\0</code>')
4750 <hr><h3><a name="lua_tonumber"><code>lua_tonumber</code></a></h3><p>
4751 <span class="apii">[-0, +0, –]</span>
4755 Equivalent to <a href="#lua_tonumberx"><code>lua_tonumberx</code></a> with <code>isnum</code> equal…
4761 <hr><h3><a name="lua_tonumberx"><code>lua_tonumberx</code></a></h3><p>
4762 <span class="apii">[-0, +0, –]</span>
4767 to the C type <a href="#lua_Number"><code>lua_Number</code></a> (see <a href="#lua_Number"><co…
4768 The Lua value must be a number or a string convertible to a number
4769 (see <a href="#3.4.2">§3.4.2</a>);
4770 otherwise, <a href="#lua_tonumberx"><code>lua_tonumberx</code></a> returns 0.
4775 its referent is assigned a boolean value that
4782 <hr><h3><a name="lua_topointer"><code>lua_topointer</code></a></h3><p>
4783 <span class="apii">[-0, +0, –]</span>
4787 Converts the value at the given index to a generic
4789 The value can be a userdata, a table, a thread, or a function;
4802 <hr><h3><a name="lua_tostring"><code>lua_tostring</code></a></h3><p>
4803 <span class="apii">[-0, +0, <em>e</em>]</span>
4807 Equivalent to <a href="#lua_tolstring"><code>lua_tolstring</code></a> with <code>len</code> equal t…
4813 <hr><h3><a name="lua_tothread"><code>lua_tothread</code></a></h3><p>
4814 <span class="apii">[-0, +0, –]</span>
4818 Converts the value at the given index to a Lua thread
4820 This value must be a thread;
4827 <hr><h3><a name="lua_tounsigned"><code>lua_tounsigned</code></a></h3><p>
4828 <span class="apii">[-0, +0, –]</span>
4832 Equivalent to <a href="#lua_tounsignedx"><code>lua_tounsignedx</code></a> with <code>isnum</code> e…
4838 <hr><h3><a name="lua_tounsignedx"><code>lua_tounsignedx</code></a></h3><p>
4839 <span class="apii">[-0, +0, –]</span>
4844 to the unsigned integral type <a href="#lua_Unsigned"><code>lua_Unsigned</code></a>.
4845 The Lua value must be a number or a string convertible to a number
4846 (see <a href="#3.4.2">§3.4.2</a>);
4852 it is truncated in some non-specified way.
4860 its referent is assigned a boolean value that
4867 <hr><h3><a name="lua_touserdata"><code>lua_touserdata</code></a></h3><p>
4868 <span class="apii">[-0, +0, –]</span>
4872 If the value at the given index is a full userdata,
4874 If the value is a light userdata,
4882 <hr><h3><a name="lua_type"><code>lua_type</code></a></h3><p>
4883 <span class="apii">[-0, +0, –]</span>
4888 or <code>LUA_TNONE</code> for a non-valid (but acceptable) index.
4889 The types returned by <a href="#lua_type"><code>lua_type</code></a> are coded by the following cons…
4891 <a name="pdf-LUA_TNIL"><code>LUA_TNIL</code></a>,
4892 <a name="pdf-LUA_TNUMBER"><code>LUA_TNUMBER</code></a>,
4893 <a name="pdf-LUA_TBOOLEAN"><code>LUA_TBOOLEAN</code></a>,
4894 <a name="pdf-LUA_TSTRING"><code>LUA_TSTRING</code></a>,
4895 <a name="pdf-LUA_TTABLE"><code>LUA_TTABLE</code></a>,
4896 <a name="pdf-LUA_TFUNCTION"><code>LUA_TFUNCTION</code></a>,
4897 <a name="pdf-LUA_TUSERDATA"><code>LUA_TUSERDATA</code></a>,
4898 <a name="pdf-LUA_TTHREAD"><code>LUA_TTHREAD</code></a>,
4900 <a name="pdf-LUA_TLIGHTUSERDATA"><code>LUA_TLIGHTUSERDATA</code></a>.
4906 <hr><h3><a name="lua_typename"><code>lua_typename</code></a></h3><p>
4907 <span class="apii">[-0, +0, –]</span>
4912 which must be one the values returned by <a href="#lua_type"><code>lua_type</code></a>.
4918 <hr><h3><a name="lua_Unsigned"><code>lua_Unsigned</code></a></h3>
4928 whichever can hold 32-bit values.
4934 <hr><h3><a name="lua_upvalueindex"><code>lua_upvalueindex</code></a></h3><p>
4935 <span class="apii">[-0, +0, –]</span>
4939 Returns the pseudo-index that represents the <code>i</code>-th upvalue of
4940 the running function (see <a href="#4.4">§4.4</a>).
4946 <hr><h3><a name="lua_version"><code>lua_version</code></a></h3><p>
4947 <span class="apii">[-0, +0, <em>v</em>]</span>
4952 When called with a valid <a href="#lua_State"><code>lua_State</code></a>,
4961 <hr><h3><a name="lua_Writer"><code>lua_Writer</code></a></h3>
4968 The type of the writer function used by <a href="#lua_dump"><code>lua_dump</code></a>.
4970 <a href="#lua_dump"><code>lua_dump</code></a> calls the writer,
4973 and the <code>data</code> parameter supplied to <a href="#lua_dump"><code>lua_dump</code></a>.
4979 any other value means an error and stops <a href="#lua_dump"><code>lua_dump</code></a> from
4986 <hr><h3><a name="lua_xmove"><code>lua_xmove</code></a></h3><p>
4987 <span class="apii">[-?, +?, –]</span>
5002 <hr><h3><a name="lua_yield"><code>lua_yield</code></a></h3><p>
5003 <span class="apii">[-?, +?, –]</span>
5007 This function is equivalent to <a href="#lua_yieldk"><code>lua_yieldk</code></a>,
5008 but it has no continuation (see <a href="#4.7">§4.7</a>).
5017 <hr><h3><a name="lua_yieldk"><code>lua_yieldk</code></a></h3><p>
5018 <span class="apii">[-?, +?, –]</span>
5022 Yields a coroutine.
5027 return expression of a C function, as follows:
5032 When a C function calls <a href="#lua_yieldk"><code>lua_yieldk</code></a> in that way,
5034 and the call to <a href="#lua_resume"><code>lua_resume</code></a> that started this coroutine retur…
5036 that are passed as results to <a href="#lua_resume"><code>lua_resume</code></a>.
5042 the execution of the C function that yielded (see <a href="#4.7">§4.7</a>).
5046 replaced by the arguments passed to <a href="#lua_resume"><code>lua_resume</code></a>.
5049 by calling <a href="#lua_getctx"><code>lua_getctx</code></a>.
5057 <h2>4.9 – <a name="4.9">The Debug Interface</a></h2>
5060 Lua has no built-in debugging facilities.
5061 Instead, it offers a special interface
5069 <hr><h3><a name="lua_Debug"><code>lua_Debug</code></a></h3>
5089 A structure used to carry different pieces of
5090 information about a function or an activation record.
5091 <a href="#lua_getstack"><code>lua_getstack</code></a> fills only the private part
5093 To fill the other fields of <a href="#lua_Debug"><code>lua_Debug</code></a> with useful information,
5094 call <a href="#lua_getinfo"><code>lua_getinfo</code></a>.
5098 The fields of <a href="#lua_Debug"><code>lua_Debug</code></a> have the following meaning:
5104 If <code>source</code> starts with a '<code>@</code>',
5105 it means that the function was defined in a file where
5107 If <code>source</code> starts with a '<code>=</code>',
5108 the remainder of its contents describe the source in a user-dependent manner.
5110 the function was defined in a string where
5115 a "printable" version of <code>source</code>, to be used in error messages.
5127 the string <code>"Lua"</code> if the function is a Lua function,
5128 <code>"C"</code> if it is a C function,
5129 <code>"main"</code> if it is the main part of a chunk.
5135 <code>currentline</code> is set to -1.
5139 a reasonable name for the given function.
5140 Because functions in Lua are first-class values,
5141 they do not have a fixed name:
5143 while others can be stored only in a table field.
5145 called to find a suitable name.
5146 If it cannot find a name,
5160 true if this function invocation was called by a tail call.
5174 true if the function is a vararg function
5183 <hr><h3><a name="lua_gethook"><code>lua_gethook</code></a></h3><p>
5184 <span class="apii">[-0, +0, –]</span>
5194 <hr><h3><a name="lua_gethookcount"><code>lua_gethookcount</code></a></h3><p>
5195 <span class="apii">[-0, +0, –]</span>
5205 <hr><h3><a name="lua_gethookmask"><code>lua_gethookmask</code></a></h3><p>
5206 <span class="apii">[-0, +0, –]</span>
5216 <hr><h3><a name="lua_getinfo"><code>lua_getinfo</code></a></h3><p>
5217 <span class="apii">[-(0|1), +(0|1|2), <em>e</em>]</span>
5221 Gets information about a specific function or function invocation.
5225 To get information about a function invocation,
5226 the parameter <code>ar</code> must be a valid activation record that was
5227 filled by a previous call to <a href="#lua_getstack"><code>lua_getstack</code></a> or
5228 given as argument to a hook (see <a href="#lua_Hook"><code>lua_Hook</code></a>).
5232 To get information about a function you push it onto the stack
5236 For instance, to know in which line a function <code>f</code> was defined,
5249 a value to be pushed on the stack:
5277 pushes onto the stack a table whose indices are the
5279 (A <em>valid line</em> is a line with some associated code,
5280 that is, a line where you can put a break point.
5281 Non-valid lines include empty lines and comments.)
5294 <hr><h3><a name="lua_getlocal"><code>lua_getlocal</code></a></h3><p>
5295 <span class="apii">[-0, +(0|1), –]</span>
5299 Gets information about a local variable of
5300 a given activation record or a given function.
5305 the parameter <code>ar</code> must be a valid activation record that was
5306 filled by a previous call to <a href="#lua_getstack"><code>lua_getstack</code></a> or
5307 given as argument to a hook (see <a href="#lua_Hook"><code>lua_Hook</code></a>).
5309 see <a href="#pdf-debug.getlocal"><code>debug.getlocal</code></a> for details about variable indices
5314 <a href="#lua_getlocal"><code>lua_getlocal</code></a> pushes the variable's value onto the stack
5335 <hr><h3><a name="lua_getstack"><code>lua_getstack</code></a></h3><p>
5336 <span class="apii">[-0, +0, –]</span>
5344 This function fills parts of a <a href="#lua_Debug"><code>lua_Debug</code></a> structure with
5346 of the function executing at a given level.
5350 When there are no errors, <a href="#lua_getstack"><code>lua_getstack</code></a> returns 1;
5351 when called with a level greater than the stack depth,
5358 <hr><h3><a name="lua_getupvalue"><code>lua_getupvalue</code></a></h3><p>
5359 <span class="apii">[-0, +(0|1), –]</span>
5363 Gets information about a closure's upvalue.
5367 <a href="#lua_getupvalue"><code>lua_getupvalue</code></a> gets the index <code>n</code> of an upval…
5380 as a name for all upvalues.
5386 <hr><h3><a name="lua_Hook"><code>lua_Hook</code></a></h3>
5394 Whenever a hook is called, its <code>ar</code> argument has its field
5397 <a name="pdf-LUA_HOOKCALL"><code>LUA_HOOKCALL</code></a>, <a name="pdf-LUA_HOOKRET"><code>LUA_HOOKR…
5398 <a name="pdf-LUA_HOOKTAILCALL"><code>LUA_HOOKTAILCALL</code></a>, <a name="pdf-LUA_HOOKLINE"><code>…
5399 and <a name="pdf-LUA_HOOKCOUNT"><code>LUA_HOOKCOUNT</code></a>.
5402 the hook must call <a href="#lua_getinfo"><code>lua_getinfo</code></a>.
5407 the normal value, or <code>LUA_HOOKTAILCALL</code>, for a tail call;
5412 While Lua is running a hook, it disables other calls to hooks.
5413 Therefore, if a hook calls back Lua to execute a function or a chunk,
5419 that is, they cannot call <a href="#lua_yieldk"><code>lua_yieldk</code></a>,
5420 <a href="#lua_pcallk"><code>lua_pcallk</code></a>, or <a href="#lua_callk"><code>lua_callk</code></…
5427 to yield a hook function must finish its execution
5428 calling <a href="#lua_yield"><code>lua_yield</code></a> with <code>nresults</code> equal to zero.
5434 <hr><h3><a name="lua_sethook"><code>lua_sethook</code></a></h3><p>
5435 <span class="apii">[-0, +0, –]</span>
5445 it is formed by a bitwise or of the constants
5446 <a name="pdf-LUA_MASKCALL"><code>LUA_MASKCALL</code></a>,
5447 <a name="pdf-LUA_MASKRET"><code>LUA_MASKRET</code></a>,
5448 <a name="pdf-LUA_MASKLINE"><code>LUA_MASKLINE</code></a>,
5449 and <a name="pdf-LUA_MASKCOUNT"><code>LUA_MASKCOUNT</code></a>.
5456 <li><b>The call hook: </b> is called when the interpreter calls a function.
5461 <li><b>The return hook: </b> is called when the interpreter returns from a function.
5468 start the execution of a new line of code,
5470 (This event only happens while Lua is executing a Lua function.)
5475 (This event only happens while Lua is executing a Lua function.)
5481 A hook is disabled by setting <code>mask</code> to zero.
5487 <hr><h3><a name="lua_setlocal"><code>lua_setlocal</code></a></h3><p>
5488 <span class="apii">[-(0|1), +0, –]</span>
5492 Sets the value of a local variable of a given activation record.
5493 …ters <code>ar</code> and <code>n</code> are as in <a href="#lua_getlocal"><code>lua_getlocal</code…
5494 (see <a href="#lua_getlocal"><code>lua_getlocal</code></a>).
5495 <a href="#lua_setlocal"><code>lua_setlocal</code></a> assigns the value at the top of the stack
5509 <hr><h3><a name="lua_setupvalue"><code>lua_setupvalue</code></a></h3><p>
5510 <span class="apii">[-(0|1), +0, –]</span>
5514 Sets the value of a closure's upvalue.
5518 …ncindex</code> and <code>n</code> are as in the <a href="#lua_getupvalue"><code>lua_getupvalue</co…
5519 (see <a href="#lua_getupvalue"><code>lua_getupvalue</code></a>).
5530 <hr><h3><a name="lua_upvalueid"><code>lua_upvalueid</code></a></h3><p>
5531 <span class="apii">[-0, +0, –]</span>
5537 …ncindex</code> and <code>n</code> are as in the <a href="#lua_getupvalue"><code>lua_getupvalue</co…
5538 (see <a href="#lua_getupvalue"><code>lua_getupvalue</code></a>)
5543 These unique identifiers allow a program to check whether different
5546 (that is, that access a same external local variable)
5553 <hr><h3><a name="lua_upvaluejoin"><code>lua_upvaluejoin</code></a></h3><p>
5554 <span class="apii">[-0, +0, –]</span>
5559 Make the <code>n1</code>-th upvalue of the Lua closure at index <code>funcindex1</code>
5560 refer to the <code>n2</code>-th upvalue of the Lua closure at index <code>funcindex2</code>.
5568 <h1>5 – <a name="5">The Auxiliary Library</a></h1>
5576 the auxiliary library provides higher-level functions for some
5583 have a prefix <code>luaL_</code>.
5597 When a function in the auxiliary library uses less than five slots,
5616 <h2>5.1 – <a name="5.1">Functions and Types</a></h2>
5624 <hr><h3><a name="luaL_addchar"><code>luaL_addchar</code></a></h3><p>
5625 <span class="apii">[-?, +?, <em>e</em>]</span>
5630 (see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>).
5636 <hr><h3><a name="luaL_addlstring"><code>luaL_addlstring</code></a></h3><p>
5637 <span class="apii">[-?, +?, <em>e</em>]</span>
5643 (see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>).
5650 <hr><h3><a name="luaL_addsize"><code>luaL_addsize</code></a></h3><p>
5651 <span class="apii">[-?, +?, <em>e</em>]</span>
5655 Adds to the buffer <code>B</code> (see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>)
5656 a string of length <code>n</code> previously copied to the
5657 buffer area (see <a href="#luaL_prepbuffer"><code>luaL_prepbuffer</code></a>).
5663 <hr><h3><a name="luaL_addstring"><code>luaL_addstring</code></a></h3><p>
5664 <span class="apii">[-?, +?, <em>e</em>]</span>
5668 Adds the zero-terminated string pointed to by <code>s</code>
5670 (see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>).
5677 <hr><h3><a name="luaL_addvalue"><code>luaL_addvalue</code></a></h3><p>
5678 <span class="apii">[-1, +?, <em>e</em>]</span>
5684 (see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>).
5697 <hr><h3><a name="luaL_argcheck"><code>luaL_argcheck</code></a></h3><p>
5698 <span class="apii">[-0, +0, <em>v</em>]</span>
5706 If not, raises an error with a standard message.
5712 <hr><h3><a name="luaL_argerror"><code>luaL_argerror</code></a></h3><p>
5713 <span class="apii">[-0, +0, <em>v</em>]</span>
5717 Raises an error with a standard message
5718 that includes <code>extramsg</code> as a comment.
5730 <hr><h3><a name="luaL_Buffer"><code>luaL_Buffer</code></a></h3>
5734 Type for a <em>string buffer</em>.
5738 A string buffer allows C code to build Lua strings piecemeal.
5743 <li>First declare a variable <code>b</code> of type <a href="#luaL_Buffer"><code>luaL_Buffer</code>…
5745 <li>Then initialize it with a call <code>luaL_buffinit(L, &b)</code>.</li>
5765 <li>First declare a variable <code>b</code> of type <a href="#luaL_Buffer"><code>luaL_Buffer</code>…
5767 <li>Then initialize it and preallocate a space of
5768 size <code>sz</code> with a call <code>luaL_buffinitsize(L, &b, sz)</code>.</li>
5782 a string buffer uses a variable number of stack slots.
5783 So, while using a buffer, you cannot assume that you know where
5788 when you call a buffer operation,
5791 (The only exception to this rule is <a href="#luaL_addvalue"><code>luaL_addvalue</code></a>.)
5792 After calling <a href="#luaL_pushresult"><code>luaL_pushresult</code></a> the stack is back to its
5800 <hr><h3><a name="luaL_buffinit"><code>luaL_buffinit</code></a></h3><p>
5801 <span class="apii">[-0, +0, –]</span>
5805 Initializes a buffer <code>B</code>.
5807 the buffer must be declared as a variable
5808 (see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>).
5814 <hr><h3><a name="luaL_buffinitsize"><code>luaL_buffinitsize</code></a></h3><p>
5815 <span class="apii">[-?, +?, <em>e</em>]</span>
5820 <a href="#luaL_buffinit"><code>luaL_buffinit</code></a>, <a href="#luaL_prepbuffsize"><code>luaL_pr…
5826 <hr><h3><a name="luaL_callmeta"><code>luaL_callmeta</code></a></h3><p>
5827 <span class="apii">[-0, +(0|1), <em>e</em>]</span>
5831 Calls a metamethod.
5835 If the object at index <code>obj</code> has a metatable and this
5836 metatable has a field <code>e</code>,
5847 <hr><h3><a name="luaL_checkany"><code>luaL_checkany</code></a></h3><p>
5848 <span class="apii">[-0, +0, <em>v</em>]</span>
5859 <hr><h3><a name="luaL_checkint"><code>luaL_checkint</code></a></h3><p>
5860 <span class="apii">[-0, +0, <em>v</em>]</span>
5864 Checks whether the function argument <code>arg</code> is a number
5871 <hr><h3><a name="luaL_checkinteger"><code>luaL_checkinteger</code></a></h3><p>
5872 <span class="apii">[-0, +0, <em>v</em>]</span>
5876 Checks whether the function argument <code>arg</code> is a number
5877 and returns this number cast to a <a href="#lua_Integer"><code>lua_Integer</code></a>.
5883 <hr><h3><a name="luaL_checklong"><code>luaL_checklong</code></a></h3><p>
5884 <span class="apii">[-0, +0, <em>v</em>]</span>
5888 Checks whether the function argument <code>arg</code> is a number
5889 and returns this number cast to a <code>long</code>.
5895 <hr><h3><a name="luaL_checklstring"><code>luaL_checklstring</code></a></h3><p>
5896 <span class="apii">[-0, +0, <em>v</em>]</span>
5900 Checks whether the function argument <code>arg</code> is a string
5907 This function uses <a href="#lua_tolstring"><code>lua_tolstring</code></a> to get its result,
5914 <hr><h3><a name="luaL_checknumber"><code>luaL_checknumber</code></a></h3><p>
5915 <span class="apii">[-0, +0, <em>v</em>]</span>
5919 Checks whether the function argument <code>arg</code> is a number
5926 <hr><h3><a name="luaL_checkoption"><code>luaL_checkoption</code></a></h3><p>
5927 <span class="apii">[-0, +0, <em>v</em>]</span>
5934 Checks whether the function argument <code>arg</code> is a string and
5936 (which must be NULL-terminated).
5938 Raises an error if the argument is not a string or
5944 the function uses <code>def</code> as a default value when
5949 This is a useful function for mapping strings to C enums.
5957 <hr><h3><a name="luaL_checkstack"><code>luaL_checkstack</code></a></h3><p>
5958 <span class="apii">[-0, +0, <em>v</em>]</span>
5971 <hr><h3><a name="luaL_checkstring"><code>luaL_checkstring</code></a></h3><p>
5972 <span class="apii">[-0, +0, <em>v</em>]</span>
5976 Checks whether the function argument <code>arg</code> is a string
5981 This function uses <a href="#lua_tolstring"><code>lua_tolstring</code></a> to get its result,
5988 <hr><h3><a name="luaL_checktype"><code>luaL_checktype</code></a></h3><p>
5989 <span class="apii">[-0, +0, <em>v</em>]</span>
5994 See <a href="#lua_type"><code>lua_type</code></a> for the encoding of types for <code>t</code>.
6000 <hr><h3><a name="luaL_checkudata"><code>luaL_checkudata</code></a></h3><p>
6001 <span class="apii">[-0, +0, <em>v</em>]</span>
6005 Checks whether the function argument <code>arg</code> is a userdata
6006 of the type <code>tname</code> (see <a href="#luaL_newmetatable"><code>luaL_newmetatable</code></a>…
6007 returns the userdata address (see <a href="#lua_touserdata"><code>lua_touserdata</code></a>).
6013 <hr><h3><a name="luaL_checkunsigned"><code>luaL_checkunsigned</code></a></h3><p>
6014 <span class="apii">[-0, +0, <em>v</em>]</span>
6018 Checks whether the function argument <code>arg</code> is a number
6019 and returns this number cast to a <a href="#lua_Unsigned"><code>lua_Unsigned</code></a>.
6025 <hr><h3><a name="luaL_checkversion"><code>luaL_checkversion</code></a></h3><p>
6026 <span class="apii">[-0, +0, –]</span>
6041 <hr><h3><a name="luaL_dofile"><code>luaL_dofile</code></a></h3><p>
6042 <span class="apii">[-0, +?, <em>e</em>]</span>
6059 <hr><h3><a name="luaL_dostring"><code>luaL_dostring</code></a></h3><p>
6060 <span class="apii">[-0, +?, –]</span>
6077 <hr><h3><a name="luaL_error"><code>luaL_error</code></a></h3><p>
6078 <span class="apii">[-0, +0, <em>v</em>]</span>
6085 following the same rules of <a href="#lua_pushfstring"><code>lua_pushfstring</code></a>.
6100 <hr><h3><a name="luaL_execresult"><code>luaL_execresult</code></a></h3><p>
6101 <span class="apii">[-0, +3, <em>e</em>]</span>
6106 process-related functions in the standard library
6107 (<a href="#pdf-os.execute"><code>os.execute</code></a> and <a href="#pdf-io.close"><code>io.close</…
6113 <hr><h3><a name="luaL_fileresult"><code>luaL_fileresult</code></a></h3><p>
6114 <span class="apii">[-0, +(1|3), <em>e</em>]</span>
6119 file-related functions in the standard library
6120 …<a href="#pdf-io.open"><code>io.open</code></a>, <a href="#pdf-os.rename"><code>os.rename</code></…
6126 <hr><h3><a name="luaL_getmetafield"><code>luaL_getmetafield</code></a></h3><p>
6127 <span class="apii">[-0, +(0|1), <em>e</em>]</span>
6133 If the object does not have a metatable,
6141 <hr><h3><a name="luaL_getmetatable"><code>luaL_getmetatable</code></a></h3><p>
6142 <span class="apii">[-0, +1, –]</span>
6147 in the registry (see <a href="#luaL_newmetatable"><code>luaL_newmetatable</code></a>).
6153 <hr><h3><a name="luaL_getsubtable"><code>luaL_getsubtable</code></a></h3><p>
6154 <span class="apii">[-0, +1, <em>e</em>]</span>
6160 is a table,
6162 Returns true if it finds a previous table there
6163 and false if it creates a new table.
6169 <hr><h3><a name="luaL_gsub"><code>luaL_gsub</code></a></h3><p>
6170 <span class="apii">[-0, +1, <em>e</em>]</span>
6177 Creates a copy of string <code>s</code> by replacing
6186 <hr><h3><a name="luaL_len"><code>luaL_len</code></a></h3><p>
6187 <span class="apii">[-0, +0, <em>e</em>]</span>
6192 as a number;
6193 it is equivalent to the '<code>#</code>' operator in Lua (see <a href="#3.4.6">§3.4.6</a>).
6194 Raises an error if the result of the operation is not a number.
6201 <hr><h3><a name="luaL_loadbuffer"><code>luaL_loadbuffer</code></a></h3><p>
6202 <span class="apii">[-0, +1, –]</span>
6209 Equivalent to <a href="#luaL_loadbufferx"><code>luaL_loadbufferx</code></a> with <code>mode</code> …
6215 <hr><h3><a name="luaL_loadbufferx"><code>luaL_loadbufferx</code></a></h3><p>
6216 <span class="apii">[-0, +1, –]</span>
6224 Loads a buffer as a Lua chunk.
6225 This function uses <a href="#lua_load"><code>lua_load</code></a> to load the chunk in the
6230 This function returns the same results as <a href="#lua_load"><code>lua_load</code></a>.
6233 The string <code>mode</code> works as in function <a href="#lua_load"><code>lua_load</code></a>.
6239 <hr><h3><a name="luaL_loadfile"><code>luaL_loadfile</code></a></h3><p>
6240 <span class="apii">[-0, +1, <em>e</em>]</span>
6244 Equivalent to <a href="#luaL_loadfilex"><code>luaL_loadfilex</code></a> with <code>mode</code> equa…
6250 <hr><h3><a name="luaL_loadfilex"><code>luaL_loadfilex</code></a></h3><p>
6251 <span class="apii">[-0, +1, <em>e</em>]</span>
6256 Loads a file as a Lua chunk.
6257 This function uses <a href="#lua_load"><code>lua_load</code></a> to load the chunk in the file
6261 The first line in the file is ignored if it starts with a <code>#</code>.
6265 The string <code>mode</code> works as in function <a href="#lua_load"><code>lua_load</code></a>.
6269 This function returns the same results as <a href="#lua_load"><code>lua_load</code></a>,
6270 but it has an extra error code <a name="pdf-LUA_ERRFILE"><code>LUA_ERRFILE</code></a>
6271 if it cannot open/read the file or the file has a wrong mode.
6275 As <a href="#lua_load"><code>lua_load</code></a>, this function only loads the chunk;
6282 <hr><h3><a name="luaL_loadstring"><code>luaL_loadstring</code></a></h3><p>
6283 <span class="apii">[-0, +1, –]</span>
6287 Loads a string as a Lua chunk.
6288 This function uses <a href="#lua_load"><code>lua_load</code></a> to load the chunk in
6289 the zero-terminated string <code>s</code>.
6293 This function returns the same results as <a href="#lua_load"><code>lua_load</code></a>.
6297 Also as <a href="#lua_load"><code>lua_load</code></a>, this function only loads the chunk;
6304 <hr><h3><a name="luaL_newlib"><code>luaL_newlib</code></a></h3><p>
6305 <span class="apii">[-0, +1, <em>e</em>]</span>
6309 Creates a new table and registers there
6320 <hr><h3><a name="luaL_newlibtable"><code>luaL_newlibtable</code></a></h3><p>
6321 <span class="apii">[-0, +1, <em>e</em>]</span>
6325 Creates a new table with a size optimized
6328 It is intended to be used in conjunction with <a href="#luaL_setfuncs"><code>luaL_setfuncs</code></…
6329 (see <a href="#luaL_newlib"><code>luaL_newlib</code></a>).
6333 It is implemented as a macro.
6335 not a pointer to it.
6341 <hr><h3><a name="luaL_newmetatable"><code>luaL_newmetatable</code></a></h3><p>
6342 <span class="apii">[-0, +1, <em>e</em>]</span>
6349 creates a new table to be used as a metatable for userdata,
6362 <hr><h3><a name="luaL_newstate"><code>luaL_newstate</code></a></h3><p>
6363 <span class="apii">[-0, +0, –]</span>
6367 Creates a new Lua state.
6368 It calls <a href="#lua_newstate"><code>lua_newstate</code></a> with an
6370 and then sets a panic function (see <a href="#4.6">§4.6</a>) that prints
6377 or <code>NULL</code> if there is a memory allocation error.
6383 <hr><h3><a name="luaL_openlibs"><code>luaL_openlibs</code></a></h3><p>
6384 <span class="apii">[-0, +0, <em>e</em>]</span>
6394 <hr><h3><a name="luaL_optint"><code>luaL_optint</code></a></h3><p>
6395 <span class="apii">[-0, +0, <em>v</em>]</span>
6399 If the function argument <code>arg</code> is a number,
6409 <hr><h3><a name="luaL_optinteger"><code>luaL_optinteger</code></a></h3><p>
6410 <span class="apii">[-0, +0, <em>v</em>]</span>
6416 If the function argument <code>arg</code> is a number,
6417 returns this number cast to a <a href="#lua_Integer"><code>lua_Integer</code></a>.
6426 <hr><h3><a name="luaL_optlong"><code>luaL_optlong</code></a></h3><p>
6427 <span class="apii">[-0, +0, <em>v</em>]</span>
6431 If the function argument <code>arg</code> is a number,
6432 returns this number cast to a <code>long</code>.
6441 <hr><h3><a name="luaL_optlstring"><code>luaL_optlstring</code></a></h3><p>
6442 <span class="apii">[-0, +0, <em>v</em>]</span>
6449 If the function argument <code>arg</code> is a string,
6464 <hr><h3><a name="luaL_optnumber"><code>luaL_optnumber</code></a></h3><p>
6465 <span class="apii">[-0, +0, <em>v</em>]</span>
6469 If the function argument <code>arg</code> is a number,
6479 <hr><h3><a name="luaL_optstring"><code>luaL_optstring</code></a></h3><p>
6480 <span class="apii">[-0, +0, <em>v</em>]</span>
6486 If the function argument <code>arg</code> is a string,
6496 <hr><h3><a name="luaL_optunsigned"><code>luaL_optunsigned</code></a></h3><p>
6497 <span class="apii">[-0, +0, <em>v</em>]</span>
6503 If the function argument <code>arg</code> is a number,
6504 returns this number cast to a <a href="#lua_Unsigned"><code>lua_Unsigned</code></a>.
6513 <hr><h3><a name="luaL_prepbuffer"><code>luaL_prepbuffer</code></a></h3><p>
6514 <span class="apii">[-?, +?, <em>e</em>]</span>
6518 Equivalent to <a href="#luaL_prepbuffsize"><code>luaL_prepbuffsize</code></a>
6519 with the predefined size <a name="pdf-LUAL_BUFFERSIZE"><code>LUAL_BUFFERSIZE</code></a>.
6525 <hr><h3><a name="luaL_prepbuffsize"><code>luaL_prepbuffsize</code></a></h3><p>
6526 <span class="apii">[-?, +?, <em>e</em>]</span>
6530 Returns an address to a space of size <code>sz</code>
6531 where you can copy a string to be added to buffer <code>B</code>
6532 (see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>).
6534 <a href="#luaL_addsize"><code>luaL_addsize</code></a> with the size of the string to actually add
6541 <hr><h3><a name="luaL_pushresult"><code>luaL_pushresult</code></a></h3><p>
6542 <span class="apii">[-?, +1, <em>e</em>]</span>
6553 <hr><h3><a name="luaL_pushresultsize"><code>luaL_pushresultsize</code></a></h3><p>
6554 <span class="apii">[-?, +1, <em>e</em>]</span>
6558 …nt to the sequence <a href="#luaL_addsize"><code>luaL_addsize</code></a>, <a href="#luaL_pushresul…
6564 <hr><h3><a name="luaL_ref"><code>luaL_ref</code></a></h3><p>
6565 <span class="apii">[-1, +0, <em>e</em>]</span>
6569 Creates and returns a <em>reference</em>,
6575 A reference is a unique integer key.
6577 <a href="#luaL_ref"><code>luaL_ref</code></a> ensures the uniqueness of the key it returns.
6580 Function <a href="#luaL_unref"><code>luaL_unref</code></a> frees a reference and its associated obj…
6585 <a href="#luaL_ref"><code>luaL_ref</code></a> returns the constant <a name="pdf-LUA_REFNIL"><code>L…
6586 The constant <a name="pdf-LUA_NOREF"><code>LUA_NOREF</code></a> is guaranteed to be different
6587 from any reference returned by <a href="#luaL_ref"><code>luaL_ref</code></a>.
6593 <hr><h3><a name="luaL_Reg"><code>luaL_Reg</code></a></h3>
6601 <a href="#luaL_setfuncs"><code>luaL_setfuncs</code></a>.
6602 <code>name</code> is the function name and <code>func</code> is a pointer to
6604 Any array of <a href="#luaL_Reg"><code>luaL_Reg</code></a> must end with an sentinel entry
6611 <hr><h3><a name="luaL_requiref"><code>luaL_requiref</code></a></h3><p>
6612 <span class="apii">[-0, +1, <em>e</em>]</span>
6619 as if that function has been called through <a href="#pdf-require"><code>require</code></a>.
6628 Leaves a copy of that result on the stack.
6634 <hr><h3><a name="luaL_setfuncs"><code>luaL_setfuncs</code></a></h3><p>
6635 <span class="apii">[-nup, +0, <em>e</em>]</span>
6640 (see <a href="#luaL_Reg"><code>luaL_Reg</code></a>) into the table on the top of the stack
6655 <hr><h3><a name="luaL_setmetatable"><code>luaL_setmetatable</code></a></h3><p>
6656 <span class="apii">[-0, +0, –]</span>
6662 in the registry (see <a href="#luaL_newmetatable"><code>luaL_newmetatable</code></a>).
6668 <hr><h3><a name="luaL_testudata"><code>luaL_testudata</code></a></h3><p>
6669 <span class="apii">[-0, +0, <em>e</em>]</span>
6673 This function works like <a href="#luaL_checkudata"><code>luaL_checkudata</code></a>,
6681 <hr><h3><a name="luaL_tolstring"><code>luaL_tolstring</code></a></h3><p>
6682 <span class="apii">[-0, +1, <em>e</em>]</span>
6686 Converts any Lua value at the given index to a C string
6687 in a reasonable format.
6695 If the value has a metatable with a <code>"__tostring"</code> field,
6704 <hr><h3><a name="luaL_traceback"><code>luaL_traceback</code></a></h3><p>
6705 <span class="apii">[-0, +1, <em>e</em>]</span>
6710 Creates and pushes a traceback of the stack <code>L1</code>.
6720 <hr><h3><a name="luaL_typename"><code>luaL_typename</code></a></h3><p>
6721 <span class="apii">[-0, +0, –]</span>
6731 <hr><h3><a name="luaL_unref"><code>luaL_unref</code></a></h3><p>
6732 <span class="apii">[-0, +0, –]</span>
6737 (see <a href="#luaL_ref"><code>luaL_ref</code></a>).
6744 …f <code>ref</code> is <a href="#pdf-LUA_NOREF"><code>LUA_NOREF</code></a> or <a href="#pdf-LUA_REF…
6745 <a href="#luaL_unref"><code>luaL_unref</code></a> does nothing.
6751 <hr><h3><a name="luaL_where"><code>luaL_where</code></a></h3><p>
6752 <span class="apii">[-0, +1, <em>e</em>]</span>
6756 Pushes onto the stack a string identifying the current position
6769 This function is used to build a prefix for error messages.
6777 <h1>6 – <a name="6">Standard Libraries</a></h1>
6783 (e.g., <a href="#pdf-type"><code>type</code></a> and <a href="#pdf-getmetatable"><code>getmetatable…
6787 deserve an implementation in C (e.g., <a href="#pdf-table.sort"><code>table.sort</code></a>).
6797 <li>basic library (<a href="#6.1">§6.1</a>);</li>
6799 <li>coroutine library (<a href="#6.2">§6.2</a>);</li>
6801 <li>package library (<a href="#6.3">§6.3</a>);</li>
6803 <li>string manipulation (<a href="#6.4">§6.4</a>);</li>
6805 <li>table manipulation (<a href="#6.5">§6.5</a>);</li>
6807 <li>mathematical functions (<a href="#6.6">§6.6</a>) (sin, log, etc.);</li>
6809 <li>bitwise operations (<a href="#6.7">§6.7</a>);</li>
6811 <li>input and output (<a href="#6.8">§6.8</a>);</li>
6813 <li>operating system facilities (<a href="#6.9">§6.9</a>);</li>
6815 <li>debug facilities (<a href="#6.10">§6.10</a>).</li>
6819 each library provides all its functions as fields of a global table
6825 the C host program should call the <a href="#luaL_openlibs"><code>luaL_openlibs</code></a> fun…
6829 <a href="#luaL_requiref"><code>luaL_requiref</code></a> to call
6830 <a name="pdf-luaopen_base"><code>luaopen_base</code></a> (for the basic library),
6831 <a name="pdf-luaopen_package"><code>luaopen_package</code></a> (for the package library),
6832 <a name="pdf-luaopen_coroutine"><code>luaopen_coroutine</code></a> (for the coroutine library),
6833 <a name="pdf-luaopen_string"><code>luaopen_string</code></a> (for the string library),
6834 <a name="pdf-luaopen_table"><code>luaopen_table</code></a> (for the table library),
6835 <a name="pdf-luaopen_math"><code>luaopen_math</code></a> (for the mathematical library),
6836 <a name="pdf-luaopen_bit32"><code>luaopen_bit32</code></a> (for the bit library),
6837 <a name="pdf-luaopen_io"><code>luaopen_io</code></a> (for the I/O library),
6838 <a name="pdf-luaopen_os"><code>luaopen_os</code></a> (for the Operating System library),
6839 and <a name="pdf-luaopen_debug"><code>luaopen_debug</code></a> (for the debug library).
6840 These functions are declared in <a name="pdf-lualib.h"><code>lualib.h</code></a>.
6844 <h2>6.1 – <a name="6.1">Basic Functions</a></h2>
6854 <hr><h3><a name="pdf-assert"><code>assert (v [, message])</code></a></h3>
6865 <hr><h3><a name="pdf-collectgarbage"><code>collectgarbage ([opt [, arg]])</code></a></h3>
6869 This function is a generic interface to the garbage collector.
6875 performs a full garbage-collection cycle.
6882 until a call to restart it.
6891 a second value with the total memory in bytes modulo 1024.
6892 The first value has a fractional part,
6900 with a non floating-point type for numbers.)
6904 performs a garbage-collection step.
6906 (larger values mean more steps) in a non-specified way.
6909 Returns <b>true</b> if the step finished a collection cycle.
6914 the collector (see <a href="#2.5">§2.5</a>).
6920 the collector (see <a href="#2.5">§2.5</a>).
6925 returns a boolean that tells whether the collector is running
6931 This is an experimental feature (see <a href="#2.5">§2.5</a>).
6944 <hr><h3><a name="pdf-dofile"><code>dofile ([filename])</code></a></h3>
6945 Opens the named file and executes its contents as a Lua chunk.
6956 <hr><h3><a name="pdf-error"><code>error (message [, level])</code></a></h3>
6964 at the beginning of the message, if the message is a string.
6970 Passing a level 0 avoids the addition of error position information
6977 <hr><h3><a name="pdf-_G"><code>_G</code></a></h3>
6978 A global variable (not a function) that
6979 holds the global environment (see <a href="#2.2">§2.2</a>).
6982 nor vice-versa.
6988 <hr><h3><a name="pdf-getmetatable"><code>getmetatable (object)</code></a></h3>
6992 If <code>object</code> does not have a metatable, returns <b>nil</b>.
6994 if the object's metatable has a <code>"__metatable"</code> field,
7002 <hr><h3><a name="pdf-ipairs"><code>ipairs (t)</code></a></h3>
7006 If <code>t</code> has a metamethod <code>__ipairs</code>,
7026 <hr><h3><a name="pdf-load"><code>load (ld [, source [, mode [, env]]])</code></a></h3>
7030 Loads a chunk.
7034 If <code>ld</code> is a string, the chunk is this string.
7035 If <code>ld</code> is a function,
7037 Each call to <code>ld</code> must return a string that concatenates
7039 A return of an empty string, <b>nil</b>, or no value signals the end of the chunk.
7044 returns the compiled chunk as a function;
7053 (When you load a main chunk,
7055 the <code>_ENV</code> variable (see <a href="#2.2">§2.2</a>).
7056 When you load a binary chunk created from a function (see <a href="#pdf-string.dump"><code>string.d…
7062 and debug information (see <a href="#4.9">§4.9</a>).
7064 it defaults to <code>ld</code>, if <code>ld</code> is a string,
7070 (that is, a precompiled chunk).
7080 <hr><h3><a name="pdf-loadfile"><code>loadfile ([filename [, mode [, env]]])</code></a></h3>
7084 Similar to <a href="#pdf-load"><code>load</code></a>,
7093 <hr><h3><a name="pdf-next"><code>next (table [, index])</code></a></h3>
7097 Allows a program to traverse all fields of a table.
7098 Its first argument is a table and its second argument
7110 you can use <code>next(t)</code> to check whether a table is empty.
7116 (To traverse a table in numeric order,
7117 use a numerical <b>for</b>.)
7123 you assign any value to a non-existent field in the table.
7131 <hr><h3><a name="pdf-pairs"><code>pairs (t)</code></a></h3>
7135 If <code>t</code> has a metamethod <code>__pairs</code>,
7142 returns three values: the <a href="#pdf-next"><code>next</code></a> function, the table <code>t</co…
7152 See function <a href="#pdf-next"><code>next</code></a> for the caveats of modifying
7159 <hr><h3><a name="pdf-pcall"><code>pcall (f [, arg1, ···])</code></a></h3>
7167 and returns a status code.
7168 Its first result is the status code (a boolean),
7178 <hr><h3><a name="pdf-print"><code>print (···)</code></a></h3>
7181 using the <a href="#pdf-tostring"><code>tostring</code></a> function to convert each argument to a …
7183 but only as a quick way to show a value,
7186 use <a href="#pdf-string.format"><code>string.format</code></a> and <a href="#pdf-io.write"><code>i…
7192 <hr><h3><a name="pdf-rawequal"><code>rawequal (v1, v2)</code></a></h3>
7195 Returns a boolean.
7201 <hr><h3><a name="pdf-rawget"><code>rawget (table, index)</code></a></h3>
7204 <code>table</code> must be a table;
7211 <hr><h3><a name="pdf-rawlen"><code>rawlen (v)</code></a></h3>
7213 which must be a table or a string,
7221 <hr><h3><a name="pdf-rawset"><code>rawset (table, index, value)</code></a></h3>
7224 <code>table</code> must be a table,
7236 <hr><h3><a name="pdf-select"><code>select (index, ···)</code></a></h3>
7240 If <code>index</code> is a number,
7242 a negative number indexes from the end (-1 is the last argument).
7250 <hr><h3><a name="pdf-setmetatable"><code>setmetatable (table, metatable)</code></a></h3>
7258 If the original metatable has a <code>"__metatable"</code> field,
7269 <hr><h3><a name="pdf-tonumber"><code>tonumber (e [, base])</code></a></h3>
7274 <code>tonumber</code> tries to convert its argument to a number.
7275 If the argument is already a number or
7276 a string convertible to a number (see <a href="#3.4.2">§3.4.2</a>),
7283 then <code>e</code> should be a string to be interpreted as
7286 In bases above 10, the letter '<code>A</code>' (in either upper or lower case)
7289 If the string <code>e</code> is not a valid numeral in the given base,
7296 <hr><h3><a name="pdf-tostring"><code>tostring (v)</code></a></h3>
7297 Receives a value of any type and
7298 converts it to a string in a reasonable format.
7300 use <a href="#pdf-string.format"><code>string.format</code></a>.)
7304 If the metatable of <code>v</code> has a <code>"__tostring"</code> field,
7313 <hr><h3><a name="pdf-type"><code>type (v)</code></a></h3>
7314 Returns the type of its only argument, coded as a string.
7316 "<code>nil</code>" (a string, not the value <b>nil</b>),
7329 <hr><h3><a name="pdf-_VERSION"><code>_VERSION</code></a></h3>
7330 A global variable (not a function) that
7331 holds a string containing the current interpreter version.
7338 <hr><h3><a name="pdf-xpcall"><code>xpcall (f, msgh [, arg1, ···])</code></a></…
7342 This function is similar to <a href="#pdf-pcall"><code>pcall</code></a>,
7343 except that it sets a new message handler <code>msgh</code>.
7351 <h2>6.2 – <a name="6.2">Coroutine Manipulation</a></h2>
7354 The operations related to coroutines comprise a sub-library of
7355 the basic library and come inside the table <a name="pdf-coroutine"><code>coroutine</code></a>.
7356 See <a href="#2.6">§2.6</a> for a general description of coroutines.
7360 <hr><h3><a name="pdf-coroutine.create"><code>coroutine.create (f)</code></a></h3>
7364 Creates a new coroutine, with body <code>f</code>.
7365 <code>f</code> must be a Lua function.
7373 <hr><h3><a name="pdf-coroutine.resume"><code>coroutine.resume (co [, val1, ···…
7378 The first time you resume a coroutine,
7400 <hr><h3><a name="pdf-coroutine.running"><code>coroutine.running ()</code></a></h3>
7404 Returns the running coroutine plus a boolean,
7411 <hr><h3><a name="pdf-coroutine.status"><code>coroutine.status (co)</code></a></h3>
7415 Returns the status of coroutine <code>co</code>, as a string:
7418 <code>"suspended"</code>, if the coroutine is suspended in a call to <code>yield</code>,
7429 <hr><h3><a name="pdf-coroutine.wrap"><code>coroutine.wrap (f)</code></a></h3>
7433 Creates a new coroutine, with body <code>f</code>.
7434 <code>f</code> must be a Lua function.
7435 Returns a function that resumes the coroutine each time it is called.
7446 <hr><h3><a name="pdf-coroutine.yield"><code>coroutine.yield (···)</code></a></…
7459 <h2>6.3 – <a name="6.3">Modules</a></h2>
7465 <a href="#pdf-require"><code>require</code></a>.
7466 Everything else is exported in a table <a name="pdf-package"><code>package</code></a>.
7470 <hr><h3><a name="pdf-require"><code>require (modname)</code></a></h3>
7475 The function starts by looking into the <a href="#pdf-package.loaded"><code>package.loaded</code></…
7479 Otherwise, it tries to find a <em>loader</em> for the module.
7483 To find a loader,
7484 <code>require</code> is guided by the <a href="#pdf-package.searchers"><code>package.searchers</cod…
7486 we can change how <code>require</code> looks for a module.
7488 for <a href="#pdf-package.searchers"><code>package.searchers</code></a>.
7493 If it has a value,
7494 this value (which should be a function) is the loader.
7495 Otherwise <code>require</code> searches for a Lua loader using the
7496 path stored in <a href="#pdf-package.path"><code>package.path</code></a>.
7497 If that also fails, it searches for a C loader using the
7498 path stored in <a href="#pdf-package.cpath"><code>package.cpath</code></a>.
7500 it tries an <em>all-in-one</em> loader (see <a href="#pdf-package.searchers"><code>package.searcher…
7504 Once a loader is found,
7507 (If the loader came from a file,
7509 If the loader returns any non-nil value,
7511 If the loader does not return a non-nil value and
7527 <hr><h3><a name="pdf-package.config"><code>package.config</code></a></h3>
7531 A string describing some compile-time configurations for packages.
7532 This string is a sequence of lines:
7539 <li>The second line is the character that separates templates in a path.
7543 substitution points in a template.
7546 <li>The fourth line is a string that, in a path in Windows,
7550 <li>The fifth line is a mark to ignore all text before it
7552 Default is '<code>-</code>'.</li>
7559 <hr><h3><a name="pdf-package.cpath"><code>package.cpath</code></a></h3>
7563 The path used by <a href="#pdf-require"><code>require</code></a> to search for a C loader.
7567 Lua initializes the C path <a href="#pdf-package.cpath"><code>package.cpath</code></a> in the …
7568 it initializes the Lua path <a href="#pdf-package.path"><code>package.path</code></a>,
7569 using the environment variable <a name="pdf-LUA_CPATH_5_2"><code>LUA_CPATH_5_2</code></a>
7570 or the environment variable <a name="pdf-LUA_CPATH"><code>LUA_CPATH</code></a>
7571 or a default path defined in <code>luaconf.h</code>.
7577 <hr><h3><a name="pdf-package.loaded"><code>package.loaded</code></a></h3>
7581 A table used by <a href="#pdf-require"><code>require</code></a> to control which
7583 When you require a module <code>modname</code> and
7585 <a href="#pdf-require"><code>require</code></a> simply returns the value stored there.
7589 This variable is only a reference to the real table;
7591 table used by <a href="#pdf-require"><code>require</code></a>.
7597 <hr><h3><a name="pdf-package.loadlib"><code>package.loadlib (libname, funcname)</code></a></h3>
7610 it looks for a function <code>funcname</code> inside the library
7611 and returns this function as a C function.
7612 So, <code>funcname</code> must follow the <a href="#lua_CFunction"><code>lua_CFunction</code></a> p…
7613 (see <a href="#lua_CFunction"><code>lua_CFunction</code></a>).
7617 This is a low-level function.
7619 Unlike <a href="#pdf-require"><code>require</code></a>,
7623 including if necessary a path and an extension.
7638 <hr><h3><a name="pdf-package.path"><code>package.path</code></a></h3>
7642 The path used by <a href="#pdf-require"><code>require</code></a> to search for a Lua loader.
7646 At start-up, Lua initializes this variable with
7647 the value of the environment variable <a name="pdf-LUA_PATH_5_2"><code>LUA_PATH_5_2</code></a> or
7648 the environment variable <a name="pdf-LUA_PATH"><code>LUA_PATH</code></a> or
7649 with a default path defined in <code>luaconf.h</code>,
7658 <hr><h3><a name="pdf-package.preload"><code>package.preload</code></a></h3>
7662 A table to store loaders for specific modules
7663 (see <a href="#pdf-require"><code>require</code></a>).
7667 This variable is only a reference to the real table;
7669 table used by <a href="#pdf-require"><code>require</code></a>.
7675 <hr><h3><a name="pdf-package.searchers"><code>package.searchers</code></a></h3>
7679 A table used by <a href="#pdf-require"><code>require</code></a> to control how to load modules.
7683 Each entry in this table is a <em>searcher function</em>.
7684 When looking for a module,
7685 <a href="#pdf-require"><code>require</code></a> calls each of these searchers in ascending order,
7686 with the module name (the argument given to <a href="#pdf-require"><code>require</code></a>) as its
7690 or a string explaining why it did not find that module
7699 The first searcher simply looks for a loader in the
7700 <a href="#pdf-package.preload"><code>package.preload</code></a> table.
7704 The second searcher looks for a loader as a Lua library,
7705 using the path stored at <a href="#pdf-package.path"><code>package.path</code></a>.
7706 …e search is done as described in function <a href="#pdf-package.searchpath"><code>package.searchpa…
7710 The third searcher looks for a loader as a C library,
7711 using the path given by the variable <a href="#pdf-package.cpath"><code>package.cpath</code></a>.
7713 …e search is done as described in function <a href="#pdf-package.searchpath"><code>package.searchpa…
7723 Once it finds a C library,
7724 this searcher first uses a dynamic link facility to link the
7726 Then it tries to find a C function inside the library to
7729 concatenated with a copy of the module name where each dot
7731 Moreover, if the module name has a hyphen,
7733 For instance, if the module name is <code>a.v1-b.c</code>,
7738 The fourth searcher tries an <em>all-in-one loader</em>.
7739 It searches the C path for a library for
7741 For instance, when requiring <code>a.b.c</code>,
7742 it will search for a C library for <code>a</code>.
7746 With this facility, a package can pack several C submodules
7754 as returned by <a href="#pdf-package.searchpath"><code>package.searchpath</code></a>.
7761 <hr><h3><a name="pdf-package.searchpath"><code>package.searchpath (name, path [, sep [, rep]])</cod…
7769 A path is a string containing a sequence of
7773 in the template with a copy of <code>name</code>
7775 (a dot, by default)
7787 the search for the name <code>foo.a</code>
7789 <code>./foo/a.lua</code>, <code>./foo/a.lc</code>, and
7790 <code>/usr/local/foo/a/init.lua</code>, in that order.
7805 <h2>6.4 – <a name="6.4">String Manipulation</a></h2>
7810 When indexing a string in Lua, the first character is at position 1
7814 Thus, the last character is at position -1, and so on.
7819 <a name="pdf-string"><code>string</code></a>.
7820 It also sets a metatable for strings
7822 Therefore, you can use the string functions in object-oriented style.
7828 The string library assumes one-byte character encodings.
7832 <hr><h3><a name="pdf-string.byte"><code>string.byte (s [, i [, j]])</code></a></h3>
7838 following the same rules of function <a href="#pdf-string.sub"><code>string.sub</code></a>.
7848 <hr><h3><a name="pdf-string.char"><code>string.char (···)</code></a></h3>
7850 Returns a string with length equal to the number of arguments,
7862 <hr><h3><a name="pdf-string.dump"><code>string.dump (function)</code></a></h3>
7866 Returns a string containing a binary representation of the given function,
7867 so that a later <a href="#pdf-load"><code>load</code></a> on this string returns
7868 a copy of the function (but with new upvalues).
7874 <hr><h3><a name="pdf-string.find"><code>string.find (s, pattern [, init [, plain]])</code></a></h3>
7880 If it finds a match, then <code>find</code> returns the indices of <code>s</code>
7883 A third, optional numerical argument <code>init</code> specifies
7886 A value of <b>true</b> as a fourth, optional argument <code>plain</code>
7888 so the function does a plain "find substring" operation,
7895 then in a successful match
7903 <hr><h3><a name="pdf-string.format"><code>string.format (formatstring, ···)</c…
7907 Returns a formatted version of its variable number of arguments
7908 following the description given in its first argument (which must be a string).
7914 The <code>q</code> option formats a string between double quotes,
7920 string.format('%q', 'a string with "quotes" and \n new line')
7925 "a string with \"quotes\" and \
7931 <code>A</code> and <code>a</code> (when available),
7933 <code>G</code>, and <code>g</code> all expect a number as argument.
7936 also expect a number,
7941 Option <code>q</code> expects a string;
7942 option <code>s</code> expects a string without embedded zeros.
7943 If the argument to option <code>s</code> is not a string,
7944 it is converted to one following the same rules of <a href="#pdf-tostring"><code>tostring</code></a…
7950 <hr><h3><a name="pdf-string.gmatch"><code>string.gmatch (s, pattern)</code></a></h3>
7965 for w in string.gmatch(s, "%a+") do
7970 given string into a table:
7981 For this function, a caret '<code>^</code>' at the start of a pattern does not
7988 <hr><h3><a name="pdf-string.gsub"><code>string.gsub (s, pattern, repl [, n])</code></a></h3>
7989 Returns a copy of <code>s</code>
7992 replaced by a replacement string specified by <code>repl</code>,
7993 which can be a string, a table, or a function.
8000 If <code>repl</code> is a string, then its value is used for replacement.
8004 stands for the value of the <em>d</em>-th captured substring.
8006 The sequence <code>%%</code> stands for a single <code>%</code>.
8010 If <code>repl</code> is a table, then the table is queried for every match,
8015 If <code>repl</code> is a function, then this function is called every time a
8023 then it behaves as if the whole pattern was inside a capture.
8028 is a string or a number,
8040 --> x="hello hello world world"
8043 --> x="hello hello world"
8046 --> x="world hello Lua from"
8049 --> x="home = /home/roberto, user = roberto"
8051 x = string.gsub("4+5 = $return 4+5$", "%$(.-)%$", function (s)
8054 --> x="4+5 = 9"
8057 x = string.gsub("$name-$version.tar.gz", "%$(%w+)", t)
8058 --> x="lua-5.2.tar.gz"
8064 <hr><h3><a name="pdf-string.len"><code>string.len (s)</code></a></h3>
8065 Receives a string and returns its length.
8068 so <code>"a\000bc\000"</code> has length 5.
8074 <hr><h3><a name="pdf-string.lower"><code>string.lower (s)</code></a></h3>
8075 Receives a string and returns a copy of this string with all
8084 <hr><h3><a name="pdf-string.match"><code>string.match (s, pattern [, init])</code></a></h3>
8092 A third, optional numerical argument <code>init</code> specifies
8100 <hr><h3><a name="pdf-string.rep"><code>string.rep (s, n [, sep])</code></a></h3>
8101 Returns a string that is the concatenation of <code>n</code> copies of
8110 <hr><h3><a name="pdf-string.reverse"><code>string.reverse (s)</code></a></h3>
8111 Returns a string that is the string <code>s</code> reversed.
8117 <hr><h3><a name="pdf-string.sub"><code>string.sub (s, i [, j])</code></a></h3>
8121 If <code>j</code> is absent, then it is assumed to be equal to -1
8124 the call <code>string.sub(s,1,j)</code> returns a prefix of <code>s</code>
8126 and <code>string.sub(s, -i)</code> returns a suffix of <code>s</code>
8144 <hr><h3><a name="pdf-string.upper"><code>string.upper (s)</code></a></h3>
8145 Receives a string and returns a copy of this string with all
8148 The definition of what a lowercase letter is depends on the current locale.
8152 <h3>6.4.1 – <a name="6.4.1">Patterns</a></h3>
8156 A <em>character class</em> is used to represent a set of characters.
8157 The following combinations are allowed in describing a character class:
8163 <code>^$()%.[]*+-?</code>)
8167 <li><b><code>.</code>: </b> (a dot) represents all characters.</li>
8169 <li><b><code>%a</code>: </b> represents all letters.</li>
8189 <li><b><code>%<em>x</em></code>: </b> (where <em>x</em> is any non-alphanumeric character)
8193 can be preceded by a '<code>%</code>'
8194 when used to represent itself in a pattern.
8200 A range of characters can be specified by
8202 in ascending order, with a '<code>-</code>',
8208 <code>[0-7]</code> represents the octal digits,
8209 and <code>[0-7%l%-]</code> represents the octal digits plus
8210 the lowercase letters plus the '<code>-</code>' character.
8215 Therefore, patterns like <code>[%a-z]</code> or <code>[a-%%]</code>
8225 For all classes represented by single letters (<code>%a</code>, <code>%c</code>, etc.),
8227 For instance, <code>%S</code> represents all non-space characters.
8233 In particular, the class <code>[a-z]</code> may not be equivalent to <code>%l</code>.
8240 A <em>pattern item</em> can be
8245 a single character class,
8250 a single character class followed by '<code>*</code>',
8256 a single character class followed by '<code>+</code>',
8262 a single character class followed by '<code>-</code>',
8269 a single character class followed by '<code>?</code>',
8270 which matches 0 or 1 occurrence of a character in the class;
8275 such item matches a substring equal to the <em>n</em>-th captured string
8284 counting <em>+1</em> for an <em>x</em> and <em>-1</em> for a <em>y</em>,
8291 <code>%f[<em>set</em>]</code>, a <em>frontier pattern</em>;
8306 A <em>pattern</em> is a sequence of pattern items.
8307 A caret '<code>^</code>' at the beginning of a pattern anchors the match at the
8309 A '<code>$</code>' at the end of a pattern anchors the match at the
8319 A pattern can contain sub-patterns enclosed in parentheses;
8321 When a match succeeds, the substrings of the subject string
8324 For instance, in the pattern <code>"(a*(.)%w(%s*))"</code>,
8325 the part of the string matching <code>"a*(.)%w(%s*)"</code> is
8332 As a special case, the empty capture <code>()</code> captures
8333 the current string position (a number).
8347 <h2>6.5 – <a name="6.5">Table Manipulation</a></h2>
8351 It provides all its functions inside the table <a name="pdf-table"><code>table</code></a>.
8355 Remember that, whenever an operation needs the length of a table,
8356 the table should be a proper sequence
8357 or have a <code>__len</code> metamethod (see <a href="#3.4.6">§3.4.6</a>).
8358 All functions ignore non-numeric keys
8368 <hr><h3><a name="pdf-table.concat"><code>table.concat (list [, sep [, i [, j]]])</code></a></h3>
8372 Given a list where all elements are strings or numbers,
8383 <hr><h3><a name="pdf-table.insert"><code>table.insert (list, [pos,] value)</code></a></h3>
8391 so that a call <code>table.insert(t,x)</code> inserts <code>x</code> at the end
8398 <hr><h3><a name="pdf-table.pack"><code>table.pack (···)</code></a></h3>
8402 Returns a new table with all parameters stored into keys 1, 2, etc.
8403 and with a field "<code>n</code>" with the total number of parameters.
8404 Note that the resulting table may not be a sequence.
8410 <hr><h3><a name="pdf-table.remove"><code>table.remove (list [, pos])</code></a></h3>
8427 so that a call <code>table.remove(t)</code> removes the last element
8434 <hr><h3><a name="pdf-table.sort"><code>table.sort (list [, comp])</code></a></h3>
8438 Sorts list elements in a given order, <em>in-place</em>,
8441 then it must be a function that receives two list elements
8458 <hr><h3><a name="pdf-table.unpack"><code>table.unpack (list [, i [, j]])</code></a></h3>
8476 <h2>6.6 – <a name="6.6">Mathematical Functions</a></h2>
8480 It provides all its functions inside the table <a name="pdf-math"><code>math</code></a>.
8484 <hr><h3><a name="pdf-math.abs"><code>math.abs (x)</code></a></h3>
8494 <hr><h3><a name="pdf-math.acos"><code>math.acos (x)</code></a></h3>
8504 <hr><h3><a name="pdf-math.asin"><code>math.asin (x)</code></a></h3>
8514 <hr><h3><a name="pdf-math.atan"><code>math.atan (x)</code></a></h3>
8524 <hr><h3><a name="pdf-math.atan2"><code>math.atan2 (y, x)</code></a></h3>
8537 <hr><h3><a name="pdf-math.ceil"><code>math.ceil (x)</code></a></h3>
8547 <hr><h3><a name="pdf-math.cos"><code>math.cos (x)</code></a></h3>
8557 <hr><h3><a name="pdf-math.cosh"><code>math.cosh (x)</code></a></h3>
8567 <hr><h3><a name="pdf-math.deg"><code>math.deg (x)</code></a></h3>
8577 <hr><h3><a name="pdf-math.exp"><code>math.exp (x)</code></a></h3>
8587 <hr><h3><a name="pdf-math.floor"><code>math.floor (x)</code></a></h3>
8597 <hr><h3><a name="pdf-math.fmod"><code>math.fmod (x, y)</code></a></h3>
8608 <hr><h3><a name="pdf-math.frexp"><code>math.frexp (x)</code></a></h3>
8621 <hr><h3><a name="pdf-math.huge"><code>math.huge</code></a></h3>
8626 a value larger than or equal to any other numerical value.
8632 <hr><h3><a name="pdf-math.ldexp"><code>math.ldexp (m, e)</code></a></h3>
8642 <hr><h3><a name="pdf-math.log"><code>math.log (x [, base])</code></a></h3>
8654 <hr><h3><a name="pdf-math.max"><code>math.max (x, ···)</code></a></h3>
8664 <hr><h3><a name="pdf-math.min"><code>math.min (x, ···)</code></a></h3>
8674 <hr><h3><a name="pdf-math.modf"><code>math.modf (x)</code></a></h3>
8685 <hr><h3><a name="pdf-math.pi"><code>math.pi</code></a></h3>
8695 <hr><h3><a name="pdf-math.pow"><code>math.pow (x, y)</code></a></h3>
8706 <hr><h3><a name="pdf-math.rad"><code>math.rad (x)</code></a></h3>
8716 <hr><h3><a name="pdf-math.random"><code>math.random ([m [, n]])</code></a></h3>
8721 pseudo-random generator function <code>rand</code> provided by Standard C.
8727 returns a uniform pseudo-random real number
8731 a uniform pseudo-random integer in the range <em>[1, m]</em>.
8733 <code>math.random</code> returns a uniform pseudo-random
8740 <hr><h3><a name="pdf-math.randomseed"><code>math.randomseed (x)</code></a></h3>
8745 for the pseudo-random generator:
8752 <hr><h3><a name="pdf-math.sin"><code>math.sin (x)</code></a></h3>
8762 <hr><h3><a name="pdf-math.sinh"><code>math.sinh (x)</code></a></h3>
8772 <hr><h3><a name="pdf-math.sqrt"><code>math.sqrt (x)</code></a></h3>
8783 <hr><h3><a name="pdf-math.tan"><code>math.tan (x)</code></a></h3>
8793 <hr><h3><a name="pdf-math.tanh"><code>math.tanh (x)</code></a></h3>
8805 <h2>6.7 – <a name="6.7">Bitwise Operations</a></h2>
8809 It provides all its functions inside the table <a name="pdf-bit32"><code>bit32</code></a>.
8815 <em>(-2<sup>51</sup>,+2<sup>51</sup>)</em>;
8819 so that its final value falls in the range <em>[0,2<sup>32</sup> - 1]</em>.
8820 Similarly, all results are in the range <em>[0,2<sup>32</sup> - 1]</em>.
8822 which is different from <code>-1</code>.
8826 <hr><h3><a name="pdf-bit32.arshift"><code>bit32.arshift (x, disp)</code></a></h3>
8848 <hr><h3><a name="pdf-bit32.band"><code>bit32.band (···)</code></a></h3>
8858 <hr><h3><a name="pdf-bit32.bnot"><code>bit32.bnot (x)</code></a></h3>
8867 assert(bit32.bnot(x) == (-1 - x) % 2^32)
8873 <hr><h3><a name="pdf-bit32.bor"><code>bit32.bor (···)</code></a></h3>
8883 <hr><h3><a name="pdf-bit32.btest"><code>bit32.btest (···)</code></a></h3>
8887 Returns a boolean signaling
8894 <hr><h3><a name="pdf-bit32.bxor"><code>bit32.bxor (···)</code></a></h3>
8904 <hr><h3><a name="pdf-bit32.extract"><code>bit32.extract (n, field [, width])</code></a></h3>
8909 <code>field</code> to <code>field + width - 1</code> from <code>n</code>.
8921 <hr><h3><a name="pdf-bit32.replace"><code>bit32.replace (n, v, field [, width])</code></a></h3>
8925 Returns a copy of <code>n</code> with
8926 the bits <code>field</code> to <code>field + width - 1</code>
8928 See <a href="#pdf-bit32.extract"><code>bit32.extract</code></a> for details about <code>field</code…
8934 <hr><h3><a name="pdf-bit32.lrotate"><code>bit32.lrotate (x, disp)</code></a></h3>
8956 <hr><h3><a name="pdf-bit32.lshift"><code>bit32.lshift (x, disp)</code></a></h3>
8980 <hr><h3><a name="pdf-bit32.rrotate"><code>bit32.rrotate (x, disp)</code></a></h3>
9002 <hr><h3><a name="pdf-bit32.rshift"><code>bit32.rshift (x, disp)</code></a></h3>
9032 <h2>6.8 – <a name="6.8">Input and Output Facilities</a></h2>
9037 that is, there are operations to set a default input file and a
9045 all operations are supplied by table <a name="pdf-io"><code>io</code></a>.
9047 the operation <a href="#pdf-io.open"><code>io.open</code></a> returns a file descriptor
9054 …a name="pdf-io.stdin"><code>io.stdin</code></a>, <a name="pdf-io.stdout"><code>io.stdout</code></a…
9061 (plus an error message as a second result and
9062 a system-dependent error code as a third result)
9064 On non-Posix systems,
9072 <hr><h3><a name="pdf-io.close"><code>io.close ([file])</code></a></h3>
9077 Without a <code>file</code>, closes the default output file.
9083 <hr><h3><a name="pdf-io.flush"><code>io.flush ()</code></a></h3>
9093 <hr><h3><a name="pdf-io.input"><code>io.input ([file])</code></a></h3>
9097 When called with a file name, it opens the named file (in text mode),
9099 When called with a file handle,
9113 <hr><h3><a name="pdf-io.lines"><code>io.lines ([filename ···])</code></a></h3>
9139 <hr><h3><a name="pdf-io.open"><code>io.open (filename [, mode])</code></a></h3>
9143 This function opens a file,
9145 It returns a new file handle,
9155 <li><b>"<code>a</code>": </b> append mode;</li>
9158 <li><b>"<code>a+</code>": </b> append update mode, previous data is preserved,
9161 The <code>mode</code> string can also have a '<code>b</code>' at the end,
9168 <hr><h3><a name="pdf-io.output"><code>io.output ([file])</code></a></h3>
9172 Similar to <a href="#pdf-io.input"><code>io.input</code></a>, but operates over the default output …
9178 <hr><h3><a name="pdf-io.popen"><code>io.popen (prog [, mode])</code></a></h3>
9187 Starts program <code>prog</code> in a separated process and returns
9188 a file handle that you can use to read data from this program
9197 <hr><h3><a name="pdf-io.read"><code>io.read (···)</code></a></h3>
9207 <hr><h3><a name="pdf-io.tmpfile"><code>io.tmpfile ()</code></a></h3>
9211 Returns a handle for a temporary file.
9219 <hr><h3><a name="pdf-io.type"><code>io.type (obj)</code></a></h3>
9223 Checks whether <code>obj</code> is a valid file handle.
9225 <code>"closed file"</code> if <code>obj</code> is a closed file handle,
9226 or <b>nil</b> if <code>obj</code> is not a file handle.
9232 <hr><h3><a name="pdf-io.write"><code>io.write (···)</code></a></h3>
9242 <hr><h3><a name="pdf-file:close"><code>file:close ()</code></a></h3>
9253 When closing a file handle created with <a href="#pdf-io.popen"><code>io.popen</code></a>,
9254 <a href="#pdf-file:close"><code>file:close</code></a> returns the same values
9255 returned by <a href="#pdf-os.execute"><code>os.execute</code></a>.
9261 <hr><h3><a name="pdf-file:flush"><code>file:flush ()</code></a></h3>
9271 <hr><h3><a name="pdf-file:lines"><code>file:lines (···)</code></a></h3>
9279 uses "*l" as a default.
9287 Unlike <a href="#pdf-io.lines"><code>io.lines</code></a>, this function does not close the file
9299 <hr><h3><a name="pdf-file:read"><code>file:read (···)</code></a></h3>
9306 the function returns a string (or a number) with the characters read,
9309 it uses a default format that reads the next line
9319 reads a number;
9320 this is the only format that returns a number instead of a string.
9323 <li><b>"<code>*a</code>": </b>
9340 reads a string with up to this number of bytes,
9352 <hr><h3><a name="pdf-file:seek"><code>file:seek ([whence [, offset]])</code></a></h3>
9358 to the position given by <code>offset</code> plus a base
9369 plus a string describing the error.
9386 <hr><h3><a name="pdf-file:setvbuf"><code>file:setvbuf (mode [, size])</code></a></h3>
9402 you explicitly <code>flush</code> the file (see <a href="#pdf-io.flush"><code>io.flush</code></a>).
9406 line buffering; output is buffered until a newline is output
9408 (such as a terminal device).
9420 <hr><h3><a name="pdf-file:write"><code>file:write (···)</code></a></h3>
9430 Otherwise it returns <b>nil</b> plus a string describing the error.
9438 <h2>6.9 – <a name="6.9">Operating System Facilities</a></h2>
9441 This library is implemented through table <a name="pdf-os"><code>os</code></a>.
9445 <hr><h3><a name="pdf-os.clock"><code>os.clock ()</code></a></h3>
9456 <hr><h3><a name="pdf-os.date"><code>os.date ([format [, time]])</code></a></h3>
9460 Returns a string or a table containing date and time,
9467 (see the <a href="#pdf-os.time"><code>os.time</code></a> function for a description of this value).
9476 then <code>date</code> returns a table with the following fields:
9481 and <code>isdst</code> (daylight saving flag, a boolean).
9488 then <code>date</code> returns the date as a string,
9494 <code>date</code> returns a reasonable date and time representation that depends on
9500 On non-Posix systems,
9508 <hr><h3><a name="pdf-os.difftime"><code>os.difftime (t2, t1)</code></a></h3>
9514 this value is exactly <code>t2</code><em>-</em><code>t1</code>.
9520 <hr><h3><a name="pdf-os.execute"><code>os.execute ([command])</code></a></h3>
9530 the function returns a string and a number,
9541 the command was terminated by a signal;
9548 When called without a <code>command</code>,
9549 <code>os.execute</code> returns a boolean that is true if a shell is available.
9555 <hr><h3><a name="pdf-os.exit"><code>os.exit ([code [, close])</code></a></h3>
9564 if <code>code</code> is a number,
9577 <hr><h3><a name="pdf-os.getenv"><code>os.getenv (varname)</code></a></h3>
9588 <hr><h3><a name="pdf-os.remove"><code>os.remove (filename)</code></a></h3>
9595 plus a string describing the error and the error code.
9601 <hr><h3><a name="pdf-os.rename"><code>os.rename (oldname, newname)</code></a></h3>
9607 plus a string describing the error and the error code.
9613 <hr><h3><a name="pdf-os.setlocale"><code>os.setlocale (locale [, category])</code></a></h3>
9618 <code>locale</code> is a system-dependent string specifying a locale;
9629 the current locale is set to an implementation-defined native locale.
9648 <hr><h3><a name="pdf-os.time"><code>os.time ([table])</code></a></h3>
9653 or a time representing the date and time specified by the given table.
9660 For a description of these fields, see the <a href="#pdf-os.date"><code>os.date</code></a> function.
9664 The returned value is a number, whose meaning depends on your system.
9670 <a href="#pdf-os.date"><code>os.date</code></a> and <a href="#pdf-os.difftime"><code>os.difftime</c…
9676 <hr><h3><a name="pdf-os.tmpname"><code>os.tmpname ()</code></a></h3>
9680 Returns a string with a file name that can
9681 be used for a temporary file.
9688 this function also creates a file with that name,
9698 you may prefer to use <a href="#pdf-io.tmpfile"><code>io.tmpfile</code></a>,
9707 <h2>6.10 – <a name="6.10">The Debug Library</a></h2>
9711 the functionality of the debug interface (<a href="#4.9">§4.9</a>) to Lua programs.
9715 (e.g., that variables local to a function
9725 inside the <a name="pdf-debug"><code>debug</code></a> table.
9726 All functions that operate over a thread
9733 <hr><h3><a name="pdf-debug.debug"><code>debug.debug ()</code></a></h3>
9742 A line containing only the word <code>cont</code> finishes this function,
9754 <hr><h3><a name="pdf-debug.gethook"><code>debug.gethook ([thread])</code></a></h3>
9761 (as set by the <a href="#pdf-debug.sethook"><code>debug.sethook</code></a> function).
9767 <hr><h3><a name="pdf-debug.getinfo"><code>debug.getinfo ([thread,] f [, what])</code></a></h3>
9771 Returns a table with information about a function.
9773 or you can give a number as the value of <code>f</code>,
9780 If <code>f</code> is a number larger than the number of active functions,
9785 …urned table can contain all the fields returned by <a href="#lua_getinfo"><code>lua_getinfo</code>…
9791 adds a field named <code>func</code> with the function itself.
9794 adds a field named <code>activelines</code> with the table of
9800 a table with a name for the current function,
9801 if a reasonable name can be found,
9803 returns a table with all available information
9804 about the <a href="#pdf-print"><code>print</code></a> function.
9810 <hr><h3><a name="pdf-debug.getlocal"><code>debug.getlocal ([thread,] f, local)</code></a></h3>
9824 -1 is the first vararg parameter.
9826 and raises an error when called with a level out of range.
9827 (You can call <a href="#pdf-debug.getinfo"><code>debug.getinfo</code></a> to check whether the leve…
9837 The parameter <code>f</code> may also be a function.
9844 <hr><h3><a name="pdf-debug.getmetatable"><code>debug.getmetatable (value)</code></a></h3>
9849 or <b>nil</b> if it does not have a metatable.
9855 <hr><h3><a name="pdf-debug.getregistry"><code>debug.getregistry ()</code></a></h3>
9859 Returns the registry table (see <a href="#4.5">§4.5</a>).
9865 <hr><h3><a name="pdf-debug.getupvalue"><code>debug.getupvalue (f, up)</code></a></h3>
9877 <hr><h3><a name="pdf-debug.getuservalue"><code>debug.getuservalue (u)</code></a></h3>
9882 If <code>u</code> is not a userdata,
9889 <hr><h3><a name="pdf-debug.sethook"><code>debug.sethook ([thread,] hook, mask [, count])</code></a>…
9893 Sets the given function as a hook.
9900 <li><b>'<code>c</code>': </b> the hook is called every time Lua calls a function;</li>
9901 <li><b>'<code>r</code>': </b> the hook is called every time Lua returns from a function;</li>
9902 <li><b>'<code>l</code>': </b> the hook is called every time Lua enters a new line of code.</li>
9905 with a <code>count</code> different from zero,
9911 <a href="#pdf-debug.sethook"><code>debug.sethook</code></a> turns off the hook.
9915 When the hook is called, its first parameter is a string
9922 Inside a hook,
9932 <hr><h3><a name="pdf-debug.setlocal"><code>debug.setlocal ([thread,] level, local, value)</code></a…
9940 and raises an error when called with a <code>level</code> out of range.
9946 See <a href="#pdf-debug.getlocal"><code>debug.getlocal</code></a> for more information about
9953 <hr><h3><a name="pdf-debug.setmetatable"><code>debug.setmetatable (value, table)</code></a></h3>
9965 <hr><h3><a name="pdf-debug.setupvalue"><code>debug.setupvalue (f, up, value)</code></a></h3>
9979 <hr><h3><a name="pdf-debug.setuservalue"><code>debug.setuservalue (udata, value)</code></a></h3>
9985 <code>value</code> must be a table or <b>nil</b>;
9986 <code>udata</code> must be a full userdata.
9996 <hr><h3><a name="pdf-debug.traceback"><code>debug.traceback ([thread,] [message [, level]])</code><…
10000 If <code>message</code> is present but is neither a string nor <b>nil</b>,
10003 it returns a string with a traceback of the call stack.
10014 <hr><h3><a name="pdf-debug.upvalueid"><code>debug.upvalueid (f, n)</code></a></h3>
10018 Returns an unique identifier (as a light userdata)
10024 These unique identifiers allow a program to check whether different
10027 (that is, that access a same external local variable)
10034 <hr><h3><a name="pdf-debug.upvaluejoin"><code>debug.upvaluejoin (f1, n1, f2, n2)</code></a></h3>
10038 Make the <code>n1</code>-th upvalue of the Lua closure <code>f1</code>
10039 refer to the <code>n2</code>-th upvalue of the Lua closure <code>f2</code>.
10047 <h1>7 – <a name="7">Lua Standalone</a></h1>
10051 to be embedded in a host C program,
10052 it is also frequently used as a standalone language.
10053 An interpreter for Lua as a standalone language,
10066 <li><b><code>-e <em>stat</em></code>: </b> executes string <em>stat</em>;</li>
10067 <li><b><code>-l <em>mod</em></code>: </b> "requires" <em>mod</em>;</li>
10068 <li><b><code>-i</code>: </b> enters interactive mode after running <em>script</em>;</li>
10069 <li><b><code>-v</code>: </b> prints version information;</li>
10070 <li><b><code>-E</code>: </b> ignores environment variables;</li>
10071 <li><b><code>--</code>: </b> stops handling options;</li>
10072 <li><b><code>-</code>: </b> executes <code>stdin</code> as a file and stops handling options.</li>
10077 <code>lua</code> behaves as <code>lua -v -i</code>
10078 when the standard input (<code>stdin</code>) is a terminal,
10079 and as <code>lua -</code> otherwise.
10083 When called without option <code>-E</code>,
10084 … interpreter checks for an environment variable <a name="pdf-LUA_INIT_5_2"><code>LUA_INIT_5_2</cod…
10085 (or <a name="pdf-LUA_INIT"><code>LUA_INIT</code></a> if it is not defined)
10093 When called with option <code>-E</code>,
10098 <a href="#pdf-package.path"><code>package.path</code></a> and <a href="#pdf-package.cpath"><code>pa…
10103 All options are handled in order, except <code>-i</code> and <code>-E</code>.
10107 $ lua -e'a=1' -e 'print(a)' script.lua
10109 will first set <code>a</code> to 1, then print the value of <code>a</code>,
10117 in a global table called <code>arg</code>.
10127 $ lua -la b.lua t1 t2
10129 the interpreter first runs the file <code>a.lua</code>,
10130 then creates a table
10133 arg = { [-2] = "lua", [-1] = "-la",
10147 by issuing a different prompt.
10153 If the error object is a string,
10154 the interpreter adds a stack traceback to it.
10155 Otherwise, if the error object has a metamethod <code>__tostring</code>,
10164 (see <a href="#lua_close"><code>lua_close</code></a>).
10166 calling <a href="#pdf-os.exit"><code>os.exit</code></a> to terminate.
10170 To allow the use of Lua as a
10173 the first line of a chunk if it starts with <code>#</code>.
10189 is a more portable solution.)
10193 <h1>8 – <a name="8">Incompatibilities with the Previous Version</a></h1>
10196 Here we list the incompatibilities that you may find when moving a program
10208 <h2>8.1 – <a name="8.1">Changes in the Language</a></h2>
10214 To set the environment of a Lua function,
10215 use the variable <code>_ENV</code> or the function <a href="#pdf-load"><code>load</code></a>.
10220 Use an upvalue with a shared table if you need to keep
10222 (You may use <a href="#luaL_setfuncs"><code>luaL_setfuncs</code></a> to open a C library
10223 with all functions sharing a common upvalue.)
10227 To manipulate the "environment" of a userdata
10230 <a href="#lua_getuservalue"><code>lua_getuservalue</code></a> and <a href="#lua_setuservalue"><code…
10234 Lua identifiers cannot use locale-dependent letters.
10238 Doing a step or a full collection in the garbage collector
10248 Instead, tail calls generate a special new event,
10250 there will not be a corresponding return event.
10255 Now, a function definition may not create a new value;
10265 <h2>8.2 – <a name="8.2">Changes in the Libraries</a></h2>
10270 It is easy to set up a module with regular Lua code.
10281 Use <a href="#pdf-math.log"><code>math.log</code></a> with 10 as its second argument, instead.
10303 and therefore must be called as <a href="#pdf-table.unpack"><code>table.unpack</code></a>.
10308 as now patterns may contain '<code>\0</code>' as a regular character.
10318 (<a href="#pdf-load"><code>load</code></a> and <a href="#pdf-loadfile"><code>loadfile</code></a>)
10337 <h2>8.3 – <a name="8.3">Changes in the API</a></h2>
10343 (see <a href="#4.5">§4.5</a>).
10355 Use <a href="#luaL_setfuncs"><code>luaL_setfuncs</code></a> so that your module does not create glo…
10361 may not be zero when creating a new block,
10363 (see <a href="#lua_Alloc"><code>lua_Alloc</code></a>).
10371 not that they were created (see <a href="#2.5.1">§2.5.1</a>).
10374 if the metatable does not have a <code>__gc</code> field when set,
10386 You can simply push the function with <a href="#lua_pushcfunction"><code>lua_pushcfunction</code></…
10387 and call it with <a href="#lua_pcall"><code>lua_pcall</code></a>.
10392 Use the new <a href="#lua_compare"><code>lua_compare</code></a> with appropriate options instead.
10396 Function <code>lua_objlen</code> was renamed <a href="#lua_rawlen"><code>lua_rawlen</code></a>.
10400 Function <a href="#lua_load"><code>lua_load</code></a> has an extra parameter, <code>mode</code>.
10405 Function <a href="#lua_resume"><code>lua_resume</code></a> has an extra parameter, <code>from</code…
10414 <h1>9 – <a name="9">The Complete Syntax of Lua</a></h1>
10482 …binop ::= ‘<b>+</b>’ | ‘<b>-</b>’ | ‘<b>*</b>’ | ‘<b>/</…
10486 unop ::= ‘<b>-</b>’ | <b>not</b> | ‘<b>#</b>’
10503 <!--
10505 -->