manual.html revision 326344 
1280405Srpaulo<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
2326344Simp<HTML>
3326344Simp<HEAD>
4326344Simp<TITLE>Lua 5.3 Reference Manual</TITLE>
5326344Simp<LINK REL="stylesheet" TYPE="text/css" HREF="lua.css">
6326344Simp<LINK REL="stylesheet" TYPE="text/css" HREF="manual.css">
7280405Srpaulo<META HTTP-EQUIV="content-type" CONTENT="text/html; charset=iso-8859-1">
8326344Simp</HEAD>
9280405Srpaulo
10326344Simp<BODY>
11280405Srpaulo
12326344Simp<H1>
13326344Simp<A HREF="http://www.lua.org/"><IMG SRC="logo.gif" ALT="Lua"></A>
14280405SrpauloLua 5.3 Reference Manual
15326344Simp</H1>
16280405Srpaulo
17326344Simp<P>
18280405Srpauloby Roberto Ierusalimschy, Luiz Henrique de Figueiredo, Waldemar Celes
19326344Simp
20326344Simp<P>
21326344Simp<SMALL>
22326344SimpCopyright &copy; 2015&ndash;2017 Lua.org, PUC-Rio.
23280405SrpauloFreely available under the terms of the
24280405Srpaulo<a href="http://www.lua.org/license.html">Lua license</a>.
25326344Simp</SMALL>
26280405Srpaulo
27326344Simp<DIV CLASS="menubar">
28326344Simp<A HREF="contents.html#contents">contents</A>
29280405Srpaulo&middot;
30326344Simp<A HREF="contents.html#index">index</A>
31326344Simp&middot;
32326344Simp<A HREF="http://www.lua.org/manual/">other versions</A>
33326344Simp</DIV>
34280405Srpaulo
35280405Srpaulo<!-- ====================================================================== -->
36280405Srpaulo<p>
37280405Srpaulo
38326344Simp<!-- $Id: manual.of,v 1.167 2017/01/09 15:18:11 roberto Exp $ -->
39280405Srpaulo
40280405Srpaulo
41280405Srpaulo
42280405Srpaulo
43280405Srpaulo<h1>1 &ndash; <a name="1">Introduction</a></h1>
44280405Srpaulo
45280405Srpaulo<p>
46326344SimpLua is a powerful, efficient, lightweight, embeddable scripting language.
47326344SimpIt supports procedural programming,
48326344Simpobject-oriented programming, functional programming,
49326344Simpdata-driven programming, and data description.
50326344Simp
51326344Simp
52326344Simp<p>
53326344SimpLua combines simple procedural syntax with powerful data description
54326344Simpconstructs based on associative arrays and extensible semantics.
55326344SimpLua is dynamically typed,
56326344Simpruns by interpreting bytecode with a register-based
57326344Simpvirtual machine,
58326344Simpand has automatic memory management with
59326344Simpincremental garbage collection,
60326344Simpmaking it ideal for configuration, scripting,
61326344Simpand rapid prototyping.
62326344Simp
63326344Simp
64326344Simp<p>
65280405SrpauloLua is implemented as a library, written in <em>clean C</em>,
66280405Srpaulothe common subset of Standard&nbsp;C and C++.
67326344SimpThe Lua distribution includes a host program called <code>lua</code>,
68326344Simpwhich uses the Lua library to offer a complete,
69326344Simpstandalone Lua interpreter,
70326344Simpfor interactive or batch use.
71326344SimpLua is intended to be used both as a powerful, lightweight,
72326344Simpembeddable scripting language for any program that needs one,
73326344Simpand as a powerful but lightweight and efficient stand-alone language.
74280405Srpaulo
75280405Srpaulo
76280405Srpaulo<p>
77280405SrpauloAs an extension language, Lua has no notion of a "main" program:
78326344Simpit works <em>embedded</em> in a host client,
79280405Srpaulocalled the <em>embedding program</em> or simply the <em>host</em>.
80326344Simp(Frequently, this host is the stand-alone <code>lua</code> program.)
81280405SrpauloThe host program can invoke functions to execute a piece of Lua code,
82280405Srpaulocan write and read Lua variables,
83280405Srpauloand can register C&nbsp;functions to be called by Lua code.
84280405SrpauloThrough the use of C&nbsp;functions, Lua can be augmented to cope with
85280405Srpauloa wide range of different domains,
86280405Srpaulothus creating customized programming languages sharing a syntactical framework.
87280405Srpaulo
88280405Srpaulo
89280405Srpaulo<p>
90280405SrpauloLua is free software,
91280405Srpauloand is provided as usual with no guarantees,
92280405Srpauloas stated in its license.
93280405SrpauloThe implementation described in this manual is available
94280405Srpauloat Lua's official web site, <code>www.lua.org</code>.
95280405Srpaulo
96280405Srpaulo
97280405Srpaulo<p>
98280405SrpauloLike any other reference manual,
99280405Srpaulothis document is dry in places.
100280405SrpauloFor a discussion of the decisions behind the design of Lua,
101280405Srpaulosee the technical papers available at Lua's web site.
102280405SrpauloFor a detailed introduction to programming in Lua,
103280405Srpaulosee Roberto's book, <em>Programming in Lua</em>.
104280405Srpaulo
105280405Srpaulo
106280405Srpaulo
107280405Srpaulo<h1>2 &ndash; <a name="2">Basic Concepts</a></h1>
108280405Srpaulo
109280405Srpaulo<p>
110280405SrpauloThis section describes the basic concepts of the language.
111280405Srpaulo
112280405Srpaulo
113280405Srpaulo
114280405Srpaulo<h2>2.1 &ndash; <a name="2.1">Values and Types</a></h2>
115280405Srpaulo
116280405Srpaulo<p>
117280405SrpauloLua is a <em>dynamically typed language</em>.
118280405SrpauloThis means that
119280405Srpaulovariables do not have types; only values do.
120280405SrpauloThere are no type definitions in the language.
121280405SrpauloAll values carry their own type.
122280405Srpaulo
123280405Srpaulo
124280405Srpaulo<p>
125280405SrpauloAll values in Lua are <em>first-class values</em>.
126280405SrpauloThis means that all values can be stored in variables,
127280405Srpaulopassed as arguments to other functions, and returned as results.
128280405Srpaulo
129280405Srpaulo
130280405Srpaulo<p>
131280405SrpauloThere are eight basic types in Lua:
132280405Srpaulo<em>nil</em>, <em>boolean</em>, <em>number</em>,
133280405Srpaulo<em>string</em>, <em>function</em>, <em>userdata</em>,
134280405Srpaulo<em>thread</em>, and <em>table</em>.
135326344SimpThe type <em>nil</em> has one single value, <b>nil</b>,
136280405Srpaulowhose main property is to be different from any other value;
137280405Srpauloit usually represents the absence of a useful value.
138326344SimpThe type <em>boolean</em> has two values, <b>false</b> and <b>true</b>.
139280405SrpauloBoth <b>nil</b> and <b>false</b> make a condition false;
140280405Srpauloany other value makes it true.
141326344SimpThe type <em>number</em> represents both
142280405Srpaulointeger numbers and real (floating-point) numbers.
143326344SimpThe type <em>string</em> represents immutable sequences of bytes.
144280405Srpaulo
145280405SrpauloLua is 8-bit clean:
146280405Srpaulostrings can contain any 8-bit value,
147280405Srpauloincluding embedded zeros ('<code>\0</code>').
148280405SrpauloLua is also encoding-agnostic;
149280405Srpauloit makes no assumptions about the contents of a string.
150280405Srpaulo
151280405Srpaulo
152280405Srpaulo<p>
153280405SrpauloThe type <em>number</em> uses two internal representations,
154326344Simpor two subtypes,
155280405Srpauloone called <em>integer</em> and the other called <em>float</em>.
156280405SrpauloLua has explicit rules about when each representation is used,
157280405Srpaulobut it also converts between them automatically as needed (see <a href="#3.4.3">&sect;3.4.3</a>).
158280405SrpauloTherefore,
159280405Srpaulothe programmer may choose to mostly ignore the difference
160280405Srpaulobetween integers and floats
161280405Srpauloor to assume complete control over the representation of each number.
162280405SrpauloStandard Lua uses 64-bit integers and double-precision (64-bit) floats,
163280405Srpaulobut you can also compile Lua so that it
164280405Srpaulouses 32-bit integers and/or single-precision (32-bit) floats.
165326344SimpThe option with 32 bits for both integers and floats
166280405Srpaulois particularly attractive
167280405Srpaulofor small machines and embedded systems.
168280405Srpaulo(See macro <code>LUA_32BITS</code> in file <code>luaconf.h</code>.)
169280405Srpaulo
170280405Srpaulo
171280405Srpaulo<p>
172280405SrpauloLua can call (and manipulate) functions written in Lua and
173280405Srpaulofunctions written in C (see <a href="#3.4.10">&sect;3.4.10</a>).
174280405SrpauloBoth are represented by the type <em>function</em>.
175280405Srpaulo
176280405Srpaulo
177280405Srpaulo<p>
178280405SrpauloThe type <em>userdata</em> is provided to allow arbitrary C&nbsp;data to
179280405Srpaulobe stored in Lua variables.
180280405SrpauloA userdata value represents a block of raw memory.
181280405SrpauloThere are two kinds of userdata:
182280405Srpaulo<em>full userdata</em>,
183280405Srpaulowhich is an object with a block of memory managed by Lua,
184280405Srpauloand <em>light userdata</em>,
185280405Srpaulowhich is simply a C&nbsp;pointer value.
186280405SrpauloUserdata has no predefined operations in Lua,
187280405Srpauloexcept assignment and identity test.
188280405SrpauloBy using <em>metatables</em>,
189280405Srpaulothe programmer can define operations for full userdata values
190280405Srpaulo(see <a href="#2.4">&sect;2.4</a>).
191280405SrpauloUserdata values cannot be created or modified in Lua,
192280405Srpauloonly through the C&nbsp;API.
193280405SrpauloThis guarantees the integrity of data owned by the host program.
194280405Srpaulo
195280405Srpaulo
196280405Srpaulo<p>
197280405SrpauloThe type <em>thread</em> represents independent threads of execution
198280405Srpauloand it is used to implement coroutines (see <a href="#2.6">&sect;2.6</a>).
199280405SrpauloLua threads are not related to operating-system threads.
200280405SrpauloLua supports coroutines on all systems,
201280405Srpauloeven those that do not support threads natively.
202280405Srpaulo
203280405Srpaulo
204280405Srpaulo<p>
205280405SrpauloThe type <em>table</em> implements associative arrays,
206280405Srpaulothat is, arrays that can be indexed not only with numbers,
207280405Srpaulobut with any Lua value except <b>nil</b> and NaN.
208326344Simp(<em>Not a Number</em> is a special value used to represent
209326344Simpundefined or unrepresentable numerical results, such as <code>0/0</code>.)
210280405SrpauloTables can be <em>heterogeneous</em>;
211280405Srpaulothat is, they can contain values of all types (except <b>nil</b>).
212280405SrpauloAny key with value <b>nil</b> is not considered part of the table.
213280405SrpauloConversely, any key that is not part of a table has
214280405Srpauloan associated value <b>nil</b>.
215280405Srpaulo
216280405Srpaulo
217280405Srpaulo<p>
218280405SrpauloTables are the sole data-structuring mechanism in Lua;
219326344Simpthey can be used to represent ordinary arrays, lists,
220280405Srpaulosymbol tables, sets, records, graphs, trees, etc.
221280405SrpauloTo represent records, Lua uses the field name as an index.
222280405SrpauloThe language supports this representation by
223280405Srpauloproviding <code>a.name</code> as syntactic sugar for <code>a["name"]</code>.
224280405SrpauloThere are several convenient ways to create tables in Lua
225280405Srpaulo(see <a href="#3.4.9">&sect;3.4.9</a>).
226280405Srpaulo
227280405Srpaulo
228280405Srpaulo<p>
229280405SrpauloLike indices,
230280405Srpaulothe values of table fields can be of any type.
231280405SrpauloIn particular,
232280405Srpaulobecause functions are first-class values,
233280405Srpaulotable fields can contain functions.
234280405SrpauloThus tables can also carry <em>methods</em> (see <a href="#3.4.11">&sect;3.4.11</a>).
235280405Srpaulo
236280405Srpaulo
237280405Srpaulo<p>
238280405SrpauloThe indexing of tables follows
239280405Srpaulothe definition of raw equality in the language.
240280405SrpauloThe expressions <code>a[i]</code> and <code>a[j]</code>
241280405Srpaulodenote the same table element
242280405Srpauloif and only if <code>i</code> and <code>j</code> are raw equal
243280405Srpaulo(that is, equal without metamethods).
244280405SrpauloIn particular, floats with integral values
245280405Srpauloare equal to their respective integers
246280405Srpaulo(e.g., <code>1.0 == 1</code>).
247280405SrpauloTo avoid ambiguities,
248280405Srpauloany float with integral value used as a key
249280405Srpaulois converted to its respective integer.
250280405SrpauloFor instance, if you write <code>a[2.0] = true</code>,
251280405Srpaulothe actual key inserted into the table will be the
252280405Srpaulointeger <code>2</code>.
253280405Srpaulo(On the other hand,
254280405Srpaulo2 and "<code>2</code>" are different Lua values and therefore
255280405Srpaulodenote different table entries.)
256280405Srpaulo
257280405Srpaulo
258280405Srpaulo<p>
259280405SrpauloTables, functions, threads, and (full) userdata values are <em>objects</em>:
260280405Srpaulovariables do not actually <em>contain</em> these values,
261280405Srpauloonly <em>references</em> to them.
262280405SrpauloAssignment, parameter passing, and function returns
263280405Srpauloalways manipulate references to such values;
264280405Srpaulothese operations do not imply any kind of copy.
265280405Srpaulo
266280405Srpaulo
267280405Srpaulo<p>
268280405SrpauloThe library function <a href="#pdf-type"><code>type</code></a> returns a string describing the type
269280405Srpauloof a given value (see <a href="#6.1">&sect;6.1</a>).
270280405Srpaulo
271280405Srpaulo
272280405Srpaulo
273280405Srpaulo
274280405Srpaulo
275280405Srpaulo<h2>2.2 &ndash; <a name="2.2">Environments and the Global Environment</a></h2>
276280405Srpaulo
277280405Srpaulo<p>
278280405SrpauloAs will be discussed in <a href="#3.2">&sect;3.2</a> and <a href="#3.3.3">&sect;3.3.3</a>,
279280405Srpauloany reference to a free name
280280405Srpaulo(that is, a name not bound to any declaration) <code>var</code>
281280405Srpaulois syntactically translated to <code>_ENV.var</code>.
282280405SrpauloMoreover, every chunk is compiled in the scope of
283280405Srpauloan external local variable named <code>_ENV</code> (see <a href="#3.3.2">&sect;3.3.2</a>),
284280405Srpauloso <code>_ENV</code> itself is never a free name in a chunk.
285280405Srpaulo
286280405Srpaulo
287280405Srpaulo<p>
288280405SrpauloDespite the existence of this external <code>_ENV</code> variable and
289280405Srpaulothe translation of free names,
290280405Srpaulo<code>_ENV</code> is a completely regular name.
291280405SrpauloIn particular,
292280405Srpauloyou can define new variables and parameters with that name.
293280405SrpauloEach reference to a free name uses the <code>_ENV</code> that is
294280405Srpaulovisible at that point in the program,
295280405Srpaulofollowing the usual visibility rules of Lua (see <a href="#3.5">&sect;3.5</a>).
296280405Srpaulo
297280405Srpaulo
298280405Srpaulo<p>
299280405SrpauloAny table used as the value of <code>_ENV</code> is called an <em>environment</em>.
300280405Srpaulo
301280405Srpaulo
302280405Srpaulo<p>
303280405SrpauloLua keeps a distinguished environment called the <em>global environment</em>.
304280405SrpauloThis value is kept at a special index in the C registry (see <a href="#4.5">&sect;4.5</a>).
305280405SrpauloIn Lua, the global variable <a href="#pdf-_G"><code>_G</code></a> is initialized with this same value.
306280405Srpaulo(<a href="#pdf-_G"><code>_G</code></a> is never used internally.)
307280405Srpaulo
308280405Srpaulo
309280405Srpaulo<p>
310280405SrpauloWhen Lua loads a chunk,
311280405Srpaulothe default value for its <code>_ENV</code> upvalue
312280405Srpaulois the global environment (see <a href="#pdf-load"><code>load</code></a>).
313280405SrpauloTherefore, by default,
314280405Srpaulofree names in Lua code refer to entries in the global environment
315280405Srpaulo(and, therefore, they are also called <em>global variables</em>).
316280405SrpauloMoreover, all standard libraries are loaded in the global environment
317280405Srpauloand some functions there operate on that environment.
318280405SrpauloYou can use <a href="#pdf-load"><code>load</code></a> (or <a href="#pdf-loadfile"><code>loadfile</code></a>)
319280405Srpauloto load a chunk with a different environment.
320280405Srpaulo(In C, you have to load the chunk and then change the value
321280405Srpauloof its first upvalue.)
322280405Srpaulo
323280405Srpaulo
324280405Srpaulo
325280405Srpaulo
326280405Srpaulo
327280405Srpaulo<h2>2.3 &ndash; <a name="2.3">Error Handling</a></h2>
328280405Srpaulo
329280405Srpaulo<p>
330280405SrpauloBecause Lua is an embedded extension language,
331280405Srpauloall Lua actions start from C&nbsp;code in the host program
332280405Srpaulocalling a function from the Lua library.
333280405Srpaulo(When you use Lua standalone,
334280405Srpaulothe <code>lua</code> application is the host program.)
335280405SrpauloWhenever an error occurs during
336280405Srpaulothe compilation or execution of a Lua chunk,
337280405Srpaulocontrol returns to the host,
338280405Srpaulowhich can take appropriate measures
339280405Srpaulo(such as printing an error message).
340280405Srpaulo
341280405Srpaulo
342280405Srpaulo<p>
343280405SrpauloLua code can explicitly generate an error by calling the
344280405Srpaulo<a href="#pdf-error"><code>error</code></a> function.
345280405SrpauloIf you need to catch errors in Lua,
346280405Srpauloyou can use <a href="#pdf-pcall"><code>pcall</code></a> or <a href="#pdf-xpcall"><code>xpcall</code></a>
347280405Srpauloto call a given function in <em>protected mode</em>.
348280405Srpaulo
349280405Srpaulo
350280405Srpaulo<p>
351280405SrpauloWhenever there is an error,
352280405Srpauloan <em>error object</em> (also called an <em>error message</em>)
353280405Srpaulois propagated with information about the error.
354280405SrpauloLua itself only generates errors whose error object is a string,
355280405Srpaulobut programs may generate errors with
356280405Srpauloany value as the error object.
357280405SrpauloIt is up to the Lua program or its host to handle such error objects.
358280405Srpaulo
359280405Srpaulo
360280405Srpaulo<p>
361280405SrpauloWhen you use <a href="#pdf-xpcall"><code>xpcall</code></a> or <a href="#lua_pcall"><code>lua_pcall</code></a>,
362280405Srpauloyou may give a <em>message handler</em>
363280405Srpauloto be called in case of errors.
364326344SimpThis function is called with the original error object
365326344Simpand returns a new error object.
366280405SrpauloIt is called before the error unwinds the stack,
367280405Srpauloso that it can gather more information about the error,
368280405Srpaulofor instance by inspecting the stack and creating a stack traceback.
369280405SrpauloThis message handler is still protected by the protected call;
370280405Srpauloso, an error inside the message handler
371280405Srpaulowill call the message handler again.
372280405SrpauloIf this loop goes on for too long,
373280405SrpauloLua breaks it and returns an appropriate message.
374326344Simp(The message handler is called only for regular runtime errors.
375326344SimpIt is not called for memory-allocation errors
376326344Simpnor for errors while running finalizers.)
377280405Srpaulo
378280405Srpaulo
379280405Srpaulo
380280405Srpaulo
381280405Srpaulo
382280405Srpaulo<h2>2.4 &ndash; <a name="2.4">Metatables and Metamethods</a></h2>
383280405Srpaulo
384280405Srpaulo<p>
385280405SrpauloEvery value in Lua can have a <em>metatable</em>.
386280405SrpauloThis <em>metatable</em> is an ordinary Lua table
387280405Srpaulothat defines the behavior of the original value
388280405Srpaulounder certain special operations.
389280405SrpauloYou can change several aspects of the behavior
390280405Srpauloof operations over a value by setting specific fields in its metatable.
391280405SrpauloFor instance, when a non-numeric value is the operand of an addition,
392280405SrpauloLua checks for a function in the field "<code>__add</code>" of the value's metatable.
393280405SrpauloIf it finds one,
394280405SrpauloLua calls this function to perform the addition.
395280405Srpaulo
396280405Srpaulo
397280405Srpaulo<p>
398326344SimpThe key for each event in a metatable is a string
399326344Simpwith the event name prefixed by two underscores;
400280405Srpaulothe corresponding values are called <em>metamethods</em>.
401326344SimpIn the previous example, the key is "<code>__add</code>"
402280405Srpauloand the metamethod is the function that performs the addition.
403280405Srpaulo
404280405Srpaulo
405280405Srpaulo<p>
406280405SrpauloYou can query the metatable of any value
407280405Srpaulousing the <a href="#pdf-getmetatable"><code>getmetatable</code></a> function.
408326344SimpLua queries metamethods in metatables using a raw access (see <a href="#pdf-rawget"><code>rawget</code></a>).
409326344SimpSo, to retrieve the metamethod for event <code>ev</code> in object <code>o</code>,
410326344SimpLua does the equivalent to the following code:
411280405Srpaulo
412326344Simp<pre>
413326344Simp     rawget(getmetatable(<em>o</em>) or {}, "__<em>ev</em>")
414326344Simp</pre>
415280405Srpaulo
416280405Srpaulo<p>
417280405SrpauloYou can replace the metatable of tables
418280405Srpaulousing the <a href="#pdf-setmetatable"><code>setmetatable</code></a> function.
419326344SimpYou cannot change the metatable of other types from Lua code
420280405Srpaulo(except by using the debug library (<a href="#6.10">&sect;6.10</a>));
421326344Simpyou should use the C&nbsp;API for that.
422280405Srpaulo
423280405Srpaulo
424280405Srpaulo<p>
425280405SrpauloTables and full userdata have individual metatables
426280405Srpaulo(although multiple tables and userdata can share their metatables).
427280405SrpauloValues of all other types share one single metatable per type;
428280405Srpaulothat is, there is one single metatable for all numbers,
429280405Srpauloone for all strings, etc.
430280405SrpauloBy default, a value has no metatable,
431280405Srpaulobut the string library sets a metatable for the string type (see <a href="#6.4">&sect;6.4</a>).
432280405Srpaulo
433280405Srpaulo
434280405Srpaulo<p>
435280405SrpauloA metatable controls how an object behaves in
436280405Srpauloarithmetic operations, bitwise operations,
437280405Srpauloorder comparisons, concatenation, length operation, calls, and indexing.
438280405SrpauloA metatable also can define a function to be called
439280405Srpaulowhen a userdata or a table is garbage collected (<a href="#2.5">&sect;2.5</a>).
440280405Srpaulo
441280405Srpaulo
442280405Srpaulo<p>
443326344SimpFor the unary operators (negation, length, and bitwise NOT),
444280405Srpaulothe metamethod is computed and called with a dummy second operand,
445280405Srpauloequal to the first one.
446280405SrpauloThis extra operand is only to simplify Lua's internals
447280405Srpaulo(by making these operators behave like a binary operation)
448280405Srpauloand may be removed in future versions.
449280405Srpaulo(For most uses this extra operand is irrelevant.)
450280405Srpaulo
451280405Srpaulo
452326344Simp<p>
453326344SimpA detailed list of events controlled by metatables is given next.
454326344SimpEach operation is identified by its corresponding key.
455280405Srpaulo
456326344Simp
457326344Simp
458280405Srpaulo<ul>
459280405Srpaulo
460326344Simp<li><b><code>__add</code>: </b>
461326344Simpthe addition (<code>+</code>) operation.
462280405SrpauloIf any operand for an addition is not a number
463280405Srpaulo(nor a string coercible to a number),
464280405SrpauloLua will try to call a metamethod.
465280405SrpauloFirst, Lua will check the first operand (even if it is valid).
466326344SimpIf that operand does not define a metamethod for <code>__add</code>,
467280405Srpaulothen Lua will check the second operand.
468280405SrpauloIf Lua can find a metamethod,
469280405Srpauloit calls the metamethod with the two operands as arguments,
470280405Srpauloand the result of the call
471280405Srpaulo(adjusted to one value)
472280405Srpaulois the result of the operation.
473280405SrpauloOtherwise,
474280405Srpauloit raises an error.
475280405Srpaulo</li>
476280405Srpaulo
477326344Simp<li><b><code>__sub</code>: </b>
478326344Simpthe subtraction (<code>-</code>) operation.
479326344SimpBehavior similar to the addition operation.
480280405Srpaulo</li>
481280405Srpaulo
482326344Simp<li><b><code>__mul</code>: </b>
483326344Simpthe multiplication (<code>*</code>) operation.
484326344SimpBehavior similar to the addition operation.
485280405Srpaulo</li>
486280405Srpaulo
487326344Simp<li><b><code>__div</code>: </b>
488326344Simpthe division (<code>/</code>) operation.
489326344SimpBehavior similar to the addition operation.
490280405Srpaulo</li>
491280405Srpaulo
492326344Simp<li><b><code>__mod</code>: </b>
493326344Simpthe modulo (<code>%</code>) operation.
494326344SimpBehavior similar to the addition operation.
495280405Srpaulo</li>
496280405Srpaulo
497326344Simp<li><b><code>__pow</code>: </b>
498326344Simpthe exponentiation (<code>^</code>) operation.
499326344SimpBehavior similar to the addition operation.
500280405Srpaulo</li>
501280405Srpaulo
502326344Simp<li><b><code>__unm</code>: </b>
503326344Simpthe negation (unary <code>-</code>) operation.
504326344SimpBehavior similar to the addition operation.
505280405Srpaulo</li>
506280405Srpaulo
507326344Simp<li><b><code>__idiv</code>: </b>
508326344Simpthe floor division (<code>//</code>) operation.
509326344SimpBehavior similar to the addition operation.
510280405Srpaulo</li>
511280405Srpaulo
512326344Simp<li><b><code>__band</code>: </b>
513326344Simpthe bitwise AND (<code>&amp;</code>) operation.
514326344SimpBehavior similar to the addition operation,
515280405Srpauloexcept that Lua will try a metamethod
516326344Simpif any operand is neither an integer
517280405Srpaulonor a value coercible to an integer (see <a href="#3.4.3">&sect;3.4.3</a>).
518280405Srpaulo</li>
519280405Srpaulo
520326344Simp<li><b><code>__bor</code>: </b>
521326344Simpthe bitwise OR (<code>|</code>) operation.
522326344SimpBehavior similar to the bitwise AND operation.
523280405Srpaulo</li>
524280405Srpaulo
525326344Simp<li><b><code>__bxor</code>: </b>
526326344Simpthe bitwise exclusive OR (binary <code>~</code>) operation.
527326344SimpBehavior similar to the bitwise AND operation.
528280405Srpaulo</li>
529280405Srpaulo
530326344Simp<li><b><code>__bnot</code>: </b>
531326344Simpthe bitwise NOT (unary <code>~</code>) operation.
532326344SimpBehavior similar to the bitwise AND operation.
533280405Srpaulo</li>
534280405Srpaulo
535326344Simp<li><b><code>__shl</code>: </b>
536326344Simpthe bitwise left shift (<code>&lt;&lt;</code>) operation.
537326344SimpBehavior similar to the bitwise AND operation.
538280405Srpaulo</li>
539280405Srpaulo
540326344Simp<li><b><code>__shr</code>: </b>
541326344Simpthe bitwise right shift (<code>&gt;&gt;</code>) operation.
542326344SimpBehavior similar to the bitwise AND operation.
543280405Srpaulo</li>
544280405Srpaulo
545326344Simp<li><b><code>__concat</code>: </b>
546326344Simpthe concatenation (<code>..</code>) operation.
547326344SimpBehavior similar to the addition operation,
548280405Srpauloexcept that Lua will try a metamethod
549326344Simpif any operand is neither a string nor a number
550280405Srpaulo(which is always coercible to a string).
551280405Srpaulo</li>
552280405Srpaulo
553326344Simp<li><b><code>__len</code>: </b>
554326344Simpthe length (<code>#</code>) operation.
555280405SrpauloIf the object is not a string,
556280405SrpauloLua will try its metamethod.
557280405SrpauloIf there is a metamethod,
558280405SrpauloLua calls it with the object as argument,
559280405Srpauloand the result of the call
560280405Srpaulo(always adjusted to one value)
561280405Srpaulois the result of the operation.
562280405SrpauloIf there is no metamethod but the object is a table,
563280405Srpaulothen Lua uses the table length operation (see <a href="#3.4.7">&sect;3.4.7</a>).
564280405SrpauloOtherwise, Lua raises an error.
565280405Srpaulo</li>
566280405Srpaulo
567326344Simp<li><b><code>__eq</code>: </b>
568326344Simpthe equal (<code>==</code>) operation.
569326344SimpBehavior similar to the addition operation,
570280405Srpauloexcept that Lua will try a metamethod only when the values
571280405Srpaulobeing compared are either both tables or both full userdata
572280405Srpauloand they are not primitively equal.
573280405SrpauloThe result of the call is always converted to a boolean.
574280405Srpaulo</li>
575280405Srpaulo
576326344Simp<li><b><code>__lt</code>: </b>
577326344Simpthe less than (<code>&lt;</code>) operation.
578326344SimpBehavior similar to the addition operation,
579280405Srpauloexcept that Lua will try a metamethod only when the values
580280405Srpaulobeing compared are neither both numbers nor both strings.
581280405SrpauloThe result of the call is always converted to a boolean.
582280405Srpaulo</li>
583280405Srpaulo
584326344Simp<li><b><code>__le</code>: </b>
585326344Simpthe less equal (<code>&lt;=</code>) operation.
586280405SrpauloUnlike other operations,
587326344Simpthe less-equal operation can use two different events.
588326344SimpFirst, Lua looks for the <code>__le</code> metamethod in both operands,
589326344Simplike in the less than operation.
590280405SrpauloIf it cannot find such a metamethod,
591326344Simpthen it will try the <code>__lt</code> metamethod,
592280405Srpauloassuming that <code>a &lt;= b</code> is equivalent to <code>not (b &lt; a)</code>.
593280405SrpauloAs with the other comparison operators,
594280405Srpaulothe result is always a boolean.
595326344Simp(This use of the <code>__lt</code> event can be removed in future versions;
596326344Simpit is also slower than a real <code>__le</code> metamethod.)
597280405Srpaulo</li>
598280405Srpaulo
599326344Simp<li><b><code>__index</code>: </b>
600280405SrpauloThe indexing access <code>table[key]</code>.
601280405SrpauloThis event happens when <code>table</code> is not a table or
602280405Srpaulowhen <code>key</code> is not present in <code>table</code>.
603280405SrpauloThe metamethod is looked up in <code>table</code>.
604280405Srpaulo
605280405Srpaulo
606280405Srpaulo<p>
607280405SrpauloDespite the name,
608280405Srpaulothe metamethod for this event can be either a function or a table.
609280405SrpauloIf it is a function,
610326344Simpit is called with <code>table</code> and <code>key</code> as arguments,
611326344Simpand the result of the call
612326344Simp(adjusted to one value)
613326344Simpis the result of the operation.
614280405SrpauloIf it is a table,
615280405Srpaulothe final result is the result of indexing this table with <code>key</code>.
616280405Srpaulo(This indexing is regular, not raw,
617280405Srpauloand therefore can trigger another metamethod.)
618280405Srpaulo</li>
619280405Srpaulo
620326344Simp<li><b><code>__newindex</code>: </b>
621280405SrpauloThe indexing assignment <code>table[key] = value</code>.
622280405SrpauloLike the index event,
623280405Srpaulothis event happens when <code>table</code> is not a table or
624280405Srpaulowhen <code>key</code> is not present in <code>table</code>.
625280405SrpauloThe metamethod is looked up in <code>table</code>.
626280405Srpaulo
627280405Srpaulo
628280405Srpaulo<p>
629280405SrpauloLike with indexing,
630280405Srpaulothe metamethod for this event can be either a function or a table.
631280405SrpauloIf it is a function,
632280405Srpauloit is called with <code>table</code>, <code>key</code>, and <code>value</code> as arguments.
633280405SrpauloIf it is a table,
634280405SrpauloLua does an indexing assignment to this table with the same key and value.
635280405Srpaulo(This assignment is regular, not raw,
636280405Srpauloand therefore can trigger another metamethod.)
637280405Srpaulo
638280405Srpaulo
639280405Srpaulo<p>
640326344SimpWhenever there is a <code>__newindex</code> metamethod,
641280405SrpauloLua does not perform the primitive assignment.
642280405Srpaulo(If necessary,
643280405Srpaulothe metamethod itself can call <a href="#pdf-rawset"><code>rawset</code></a>
644280405Srpauloto do the assignment.)
645280405Srpaulo</li>
646280405Srpaulo
647326344Simp<li><b><code>__call</code>: </b>
648280405SrpauloThe call operation <code>func(args)</code>.
649280405SrpauloThis event happens when Lua tries to call a non-function value
650280405Srpaulo(that is, <code>func</code> is not a function).
651280405SrpauloThe metamethod is looked up in <code>func</code>.
652280405SrpauloIf present,
653280405Srpaulothe metamethod is called with <code>func</code> as its first argument,
654280405Srpaulofollowed by the arguments of the original call (<code>args</code>).
655326344SimpAll results of the call
656326344Simpare the result of the operation.
657326344Simp(This is the only metamethod that allows multiple results.)
658280405Srpaulo</li>
659280405Srpaulo
660280405Srpaulo</ul>
661280405Srpaulo
662326344Simp<p>
663326344SimpIt is a good practice to add all needed metamethods to a table
664326344Simpbefore setting it as a metatable of some object.
665326344SimpIn particular, the <code>__gc</code> metamethod works only when this order
666326344Simpis followed (see <a href="#2.5.1">&sect;2.5.1</a>).
667280405Srpaulo
668280405Srpaulo
669326344Simp<p>
670326344SimpBecause metatables are regular tables,
671326344Simpthey can contain arbitrary fields,
672326344Simpnot only the event names defined above.
673326344SimpSome functions in the standard library
674326344Simp(e.g., <a href="#pdf-tostring"><code>tostring</code></a>)
675326344Simpuse other fields in metatables for their own purposes.
676280405Srpaulo
677326344Simp
678326344Simp
679326344Simp
680326344Simp
681280405Srpaulo<h2>2.5 &ndash; <a name="2.5">Garbage Collection</a></h2>
682280405Srpaulo
683280405Srpaulo<p>
684280405SrpauloLua performs automatic memory management.
685280405SrpauloThis means that
686280405Srpauloyou do not have to worry about allocating memory for new objects
687280405Srpauloor freeing it when the objects are no longer needed.
688280405SrpauloLua manages memory automatically by running
689280405Srpauloa <em>garbage collector</em> to collect all <em>dead objects</em>
690280405Srpaulo(that is, objects that are no longer accessible from Lua).
691280405SrpauloAll memory used by Lua is subject to automatic management:
692280405Srpaulostrings, tables, userdata, functions, threads, internal structures, etc.
693280405Srpaulo
694280405Srpaulo
695280405Srpaulo<p>
696280405SrpauloLua implements an incremental mark-and-sweep collector.
697280405SrpauloIt uses two numbers to control its garbage-collection cycles:
698280405Srpaulothe <em>garbage-collector pause</em> and
699280405Srpaulothe <em>garbage-collector step multiplier</em>.
700280405SrpauloBoth use percentage points as units
701280405Srpaulo(e.g., a value of 100 means an internal value of 1).
702280405Srpaulo
703280405Srpaulo
704280405Srpaulo<p>
705280405SrpauloThe garbage-collector pause
706280405Srpaulocontrols how long the collector waits before starting a new cycle.
707280405SrpauloLarger values make the collector less aggressive.
708280405SrpauloValues smaller than 100 mean the collector will not wait to
709280405Srpaulostart a new cycle.
710280405SrpauloA value of 200 means that the collector waits for the total memory in use
711280405Srpauloto double before starting a new cycle.
712280405Srpaulo
713280405Srpaulo
714280405Srpaulo<p>
715280405SrpauloThe garbage-collector step multiplier
716280405Srpaulocontrols the relative speed of the collector relative to
717280405Srpaulomemory allocation.
718280405SrpauloLarger values make the collector more aggressive but also increase
719280405Srpaulothe size of each incremental step.
720280405SrpauloYou should not use values smaller than 100,
721280405Srpaulobecause they make the collector too slow and
722280405Srpaulocan result in the collector never finishing a cycle.
723280405SrpauloThe default is 200,
724280405Srpaulowhich means that the collector runs at "twice"
725280405Srpaulothe speed of memory allocation.
726280405Srpaulo
727280405Srpaulo
728280405Srpaulo<p>
729280405SrpauloIf you set the step multiplier to a very large number
730280405Srpaulo(larger than 10% of the maximum number of
731280405Srpaulobytes that the program may use),
732280405Srpaulothe collector behaves like a stop-the-world collector.
733280405SrpauloIf you then set the pause to 200,
734280405Srpaulothe collector behaves as in old Lua versions,
735280405Srpaulodoing a complete collection every time Lua doubles its
736280405Srpaulomemory usage.
737280405Srpaulo
738280405Srpaulo
739280405Srpaulo<p>
740280405SrpauloYou can change these numbers by calling <a href="#lua_gc"><code>lua_gc</code></a> in C
741280405Srpauloor <a href="#pdf-collectgarbage"><code>collectgarbage</code></a> in Lua.
742280405SrpauloYou can also use these functions to control
743280405Srpaulothe collector directly (e.g., stop and restart it).
744280405Srpaulo
745280405Srpaulo
746280405Srpaulo
747280405Srpaulo<h3>2.5.1 &ndash; <a name="2.5.1">Garbage-Collection Metamethods</a></h3>
748280405Srpaulo
749280405Srpaulo<p>
750280405SrpauloYou can set garbage-collector metamethods for tables
751280405Srpauloand, using the C&nbsp;API,
752280405Srpaulofor full userdata (see <a href="#2.4">&sect;2.4</a>).
753280405SrpauloThese metamethods are also called <em>finalizers</em>.
754280405SrpauloFinalizers allow you to coordinate Lua's garbage collection
755280405Srpaulowith external resource management
756280405Srpaulo(such as closing files, network or database connections,
757280405Srpauloor freeing your own memory).
758280405Srpaulo
759280405Srpaulo
760280405Srpaulo<p>
761280405SrpauloFor an object (table or userdata) to be finalized when collected,
762280405Srpauloyou must <em>mark</em> it for finalization.
763280405Srpaulo
764280405SrpauloYou mark an object for finalization when you set its metatable
765280405Srpauloand the metatable has a field indexed by the string "<code>__gc</code>".
766280405SrpauloNote that if you set a metatable without a <code>__gc</code> field
767280405Srpauloand later create that field in the metatable,
768280405Srpaulothe object will not be marked for finalization.
769280405Srpaulo
770280405Srpaulo
771280405Srpaulo<p>
772280405SrpauloWhen a marked object becomes garbage,
773280405Srpauloit is not collected immediately by the garbage collector.
774280405SrpauloInstead, Lua puts it in a list.
775280405SrpauloAfter the collection,
776280405SrpauloLua goes through that list.
777280405SrpauloFor each object in the list,
778280405Srpauloit checks the object's <code>__gc</code> metamethod:
779280405SrpauloIf it is a function,
780280405SrpauloLua calls it with the object as its single argument;
781280405Srpauloif the metamethod is not a function,
782280405SrpauloLua simply ignores it.
783280405Srpaulo
784280405Srpaulo
785280405Srpaulo<p>
786280405SrpauloAt the end of each garbage-collection cycle,
787280405Srpaulothe finalizers for objects are called in
788280405Srpaulothe reverse order that the objects were marked for finalization,
789280405Srpauloamong those collected in that cycle;
790280405Srpaulothat is, the first finalizer to be called is the one associated
791280405Srpaulowith the object marked last in the program.
792280405SrpauloThe execution of each finalizer may occur at any point during
793280405Srpaulothe execution of the regular code.
794280405Srpaulo
795280405Srpaulo
796280405Srpaulo<p>
797280405SrpauloBecause the object being collected must still be used by the finalizer,
798280405Srpaulothat object (and other objects accessible only through it)
799280405Srpaulomust be <em>resurrected</em> by Lua.
800280405SrpauloUsually, this resurrection is transient,
801280405Srpauloand the object memory is freed in the next garbage-collection cycle.
802280405SrpauloHowever, if the finalizer stores the object in some global place
803280405Srpaulo(e.g., a global variable),
804280405Srpaulothen the resurrection is permanent.
805280405SrpauloMoreover, if the finalizer marks a finalizing object for finalization again,
806280405Srpauloits finalizer will be called again in the next cycle where the
807280405Srpauloobject is unreachable.
808280405SrpauloIn any case,
809326344Simpthe object memory is freed only in a GC cycle where
810280405Srpaulothe object is unreachable and not marked for finalization.
811280405Srpaulo
812280405Srpaulo
813280405Srpaulo<p>
814280405SrpauloWhen you close a state (see <a href="#lua_close"><code>lua_close</code></a>),
815280405SrpauloLua calls the finalizers of all objects marked for finalization,
816280405Srpaulofollowing the reverse order that they were marked.
817280405SrpauloIf any finalizer marks objects for collection during that phase,
818280405Srpaulothese marks have no effect.
819280405Srpaulo
820280405Srpaulo
821280405Srpaulo
822280405Srpaulo
823280405Srpaulo
824280405Srpaulo<h3>2.5.2 &ndash; <a name="2.5.2">Weak Tables</a></h3>
825280405Srpaulo
826280405Srpaulo<p>
827280405SrpauloA <em>weak table</em> is a table whose elements are
828280405Srpaulo<em>weak references</em>.
829280405SrpauloA weak reference is ignored by the garbage collector.
830280405SrpauloIn other words,
831280405Srpauloif the only references to an object are weak references,
832280405Srpaulothen the garbage collector will collect that object.
833280405Srpaulo
834280405Srpaulo
835280405Srpaulo<p>
836280405SrpauloA weak table can have weak keys, weak values, or both.
837326344SimpA table with weak values allows the collection of its values,
838326344Simpbut prevents the collection of its keys.
839280405SrpauloA table with both weak keys and weak values allows the collection of
840280405Srpauloboth keys and values.
841280405SrpauloIn any case, if either the key or the value is collected,
842280405Srpaulothe whole pair is removed from the table.
843280405SrpauloThe weakness of a table is controlled by the
844280405Srpaulo<code>__mode</code> field of its metatable.
845280405SrpauloIf the <code>__mode</code> field is a string containing the character&nbsp;'<code>k</code>',
846280405Srpaulothe keys in the table are weak.
847280405SrpauloIf <code>__mode</code> contains '<code>v</code>',
848280405Srpaulothe values in the table are weak.
849280405Srpaulo
850280405Srpaulo
851280405Srpaulo<p>
852280405SrpauloA table with weak keys and strong values
853280405Srpaulois also called an <em>ephemeron table</em>.
854280405SrpauloIn an ephemeron table,
855280405Srpauloa value is considered reachable only if its key is reachable.
856280405SrpauloIn particular,
857280405Srpauloif the only reference to a key comes through its value,
858280405Srpaulothe pair is removed.
859280405Srpaulo
860280405Srpaulo
861280405Srpaulo<p>
862280405SrpauloAny change in the weakness of a table may take effect only
863280405Srpauloat the next collect cycle.
864280405SrpauloIn particular, if you change the weakness to a stronger mode,
865280405SrpauloLua may still collect some items from that table
866280405Srpaulobefore the change takes effect.
867280405Srpaulo
868280405Srpaulo
869280405Srpaulo<p>
870280405SrpauloOnly objects that have an explicit construction
871280405Srpauloare removed from weak tables.
872326344SimpValues, such as numbers and light C&nbsp;functions,
873280405Srpauloare not subject to garbage collection,
874280405Srpauloand therefore are not removed from weak tables
875280405Srpaulo(unless their associated values are collected).
876280405SrpauloAlthough strings are subject to garbage collection,
877280405Srpaulothey do not have an explicit construction,
878280405Srpauloand therefore are not removed from weak tables.
879280405Srpaulo
880280405Srpaulo
881280405Srpaulo<p>
882280405SrpauloResurrected objects
883280405Srpaulo(that is, objects being finalized
884280405Srpauloand objects accessible only through objects being finalized)
885280405Srpaulohave a special behavior in weak tables.
886280405SrpauloThey are removed from weak values before running their finalizers,
887280405Srpaulobut are removed from weak keys only in the next collection
888280405Srpauloafter running their finalizers, when such objects are actually freed.
889280405SrpauloThis behavior allows the finalizer to access properties
890280405Srpauloassociated with the object through weak tables.
891280405Srpaulo
892280405Srpaulo
893280405Srpaulo<p>
894280405SrpauloIf a weak table is among the resurrected objects in a collection cycle,
895280405Srpauloit may not be properly cleared until the next cycle.
896280405Srpaulo
897280405Srpaulo
898280405Srpaulo
899280405Srpaulo
900280405Srpaulo
901280405Srpaulo
902280405Srpaulo
903280405Srpaulo<h2>2.6 &ndash; <a name="2.6">Coroutines</a></h2>
904280405Srpaulo
905280405Srpaulo<p>
906280405SrpauloLua supports coroutines,
907280405Srpauloalso called <em>collaborative multithreading</em>.
908280405SrpauloA coroutine in Lua represents an independent thread of execution.
909280405SrpauloUnlike threads in multithread systems, however,
910280405Srpauloa coroutine only suspends its execution by explicitly calling
911280405Srpauloa yield function.
912280405Srpaulo
913280405Srpaulo
914280405Srpaulo<p>
915280405SrpauloYou create a coroutine by calling <a href="#pdf-coroutine.create"><code>coroutine.create</code></a>.
916280405SrpauloIts sole argument is a function
917280405Srpaulothat is the main function of the coroutine.
918280405SrpauloThe <code>create</code> function only creates a new coroutine and
919280405Srpauloreturns a handle to it (an object of type <em>thread</em>);
920280405Srpauloit does not start the coroutine.
921280405Srpaulo
922280405Srpaulo
923280405Srpaulo<p>
924280405SrpauloYou execute a coroutine by calling <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a>.
925280405SrpauloWhen you first call <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a>,
926280405Srpaulopassing as its first argument
927280405Srpauloa thread returned by <a href="#pdf-coroutine.create"><code>coroutine.create</code></a>,
928326344Simpthe coroutine starts its execution by
929326344Simpcalling its main function.
930280405SrpauloExtra arguments passed to <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a> are passed
931326344Simpas arguments to that function.
932280405SrpauloAfter the coroutine starts running,
933280405Srpauloit runs until it terminates or <em>yields</em>.
934280405Srpaulo
935280405Srpaulo
936280405Srpaulo<p>
937280405SrpauloA coroutine can terminate its execution in two ways:
938280405Srpaulonormally, when its main function returns
939280405Srpaulo(explicitly or implicitly, after the last instruction);
940280405Srpauloand abnormally, if there is an unprotected error.
941280405SrpauloIn case of normal termination,
942280405Srpaulo<a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a> returns <b>true</b>,
943280405Srpauloplus any values returned by the coroutine main function.
944280405SrpauloIn case of errors, <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a> returns <b>false</b>
945326344Simpplus an error object.
946280405Srpaulo
947280405Srpaulo
948280405Srpaulo<p>
949280405SrpauloA coroutine yields by calling <a href="#pdf-coroutine.yield"><code>coroutine.yield</code></a>.
950280405SrpauloWhen a coroutine yields,
951280405Srpaulothe corresponding <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a> returns immediately,
952280405Srpauloeven if the yield happens inside nested function calls
953280405Srpaulo(that is, not in the main function,
954280405Srpaulobut in a function directly or indirectly called by the main function).
955280405SrpauloIn the case of a yield, <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a> also returns <b>true</b>,
956280405Srpauloplus any values passed to <a href="#pdf-coroutine.yield"><code>coroutine.yield</code></a>.
957280405SrpauloThe next time you resume the same coroutine,
958280405Srpauloit continues its execution from the point where it yielded,
959280405Srpaulowith the call to <a href="#pdf-coroutine.yield"><code>coroutine.yield</code></a> returning any extra
960280405Srpauloarguments passed to <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a>.
961280405Srpaulo
962280405Srpaulo
963280405Srpaulo<p>
964280405SrpauloLike <a href="#pdf-coroutine.create"><code>coroutine.create</code></a>,
965280405Srpaulothe <a href="#pdf-coroutine.wrap"><code>coroutine.wrap</code></a> function also creates a coroutine,
966280405Srpaulobut instead of returning the coroutine itself,
967280405Srpauloit returns a function that, when called, resumes the coroutine.
968280405SrpauloAny arguments passed to this function
969280405Srpaulogo as extra arguments to <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a>.
970280405Srpaulo<a href="#pdf-coroutine.wrap"><code>coroutine.wrap</code></a> returns all the values returned by <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a>,
971280405Srpauloexcept the first one (the boolean error code).
972280405SrpauloUnlike <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a>,
973280405Srpaulo<a href="#pdf-coroutine.wrap"><code>coroutine.wrap</code></a> does not catch errors;
974280405Srpauloany error is propagated to the caller.
975280405Srpaulo
976280405Srpaulo
977280405Srpaulo<p>
978280405SrpauloAs an example of how coroutines work,
979280405Srpauloconsider the following code:
980280405Srpaulo
981280405Srpaulo<pre>
982280405Srpaulo     function foo (a)
983280405Srpaulo       print("foo", a)
984280405Srpaulo       return coroutine.yield(2*a)
985280405Srpaulo     end
986280405Srpaulo     
987280405Srpaulo     co = coroutine.create(function (a,b)
988280405Srpaulo           print("co-body", a, b)
989280405Srpaulo           local r = foo(a+1)
990280405Srpaulo           print("co-body", r)
991280405Srpaulo           local r, s = coroutine.yield(a+b, a-b)
992280405Srpaulo           print("co-body", r, s)
993280405Srpaulo           return b, "end"
994280405Srpaulo     end)
995280405Srpaulo     
996280405Srpaulo     print("main", coroutine.resume(co, 1, 10))
997280405Srpaulo     print("main", coroutine.resume(co, "r"))
998280405Srpaulo     print("main", coroutine.resume(co, "x", "y"))
999280405Srpaulo     print("main", coroutine.resume(co, "x", "y"))
1000280405Srpaulo</pre><p>
1001280405SrpauloWhen you run it, it produces the following output:
1002280405Srpaulo
1003280405Srpaulo<pre>
1004280405Srpaulo     co-body 1       10
1005280405Srpaulo     foo     2
1006280405Srpaulo     main    true    4
1007280405Srpaulo     co-body r
1008280405Srpaulo     main    true    11      -9
1009280405Srpaulo     co-body x       y
1010280405Srpaulo     main    true    10      end
1011280405Srpaulo     main    false   cannot resume dead coroutine
1012280405Srpaulo</pre>
1013280405Srpaulo
1014280405Srpaulo<p>
1015280405SrpauloYou can also create and manipulate coroutines through the C API:
1016280405Srpaulosee functions <a href="#lua_newthread"><code>lua_newthread</code></a>, <a href="#lua_resume"><code>lua_resume</code></a>,
1017280405Srpauloand <a href="#lua_yield"><code>lua_yield</code></a>.
1018280405Srpaulo
1019280405Srpaulo
1020280405Srpaulo
1021280405Srpaulo
1022280405Srpaulo
1023280405Srpaulo<h1>3 &ndash; <a name="3">The Language</a></h1>
1024280405Srpaulo
1025280405Srpaulo<p>
1026280405SrpauloThis section describes the lexis, the syntax, and the semantics of Lua.
1027280405SrpauloIn other words,
1028280405Srpaulothis section describes
1029280405Srpaulowhich tokens are valid,
1030280405Srpaulohow they can be combined,
1031280405Srpauloand what their combinations mean.
1032280405Srpaulo
1033280405Srpaulo
1034280405Srpaulo<p>
1035280405SrpauloLanguage constructs will be explained using the usual extended BNF notation,
1036280405Srpauloin which
1037280405Srpaulo{<em>a</em>}&nbsp;means&nbsp;0 or more <em>a</em>'s, and
1038280405Srpaulo[<em>a</em>]&nbsp;means an optional <em>a</em>.
1039280405SrpauloNon-terminals are shown like non-terminal,
1040280405Srpaulokeywords are shown like <b>kword</b>,
1041280405Srpauloand other terminal symbols are shown like &lsquo;<b>=</b>&rsquo;.
1042280405SrpauloThe complete syntax of Lua can be found in <a href="#9">&sect;9</a>
1043280405Srpauloat the end of this manual.
1044280405Srpaulo
1045280405Srpaulo
1046280405Srpaulo
1047280405Srpaulo<h2>3.1 &ndash; <a name="3.1">Lexical Conventions</a></h2>
1048280405Srpaulo
1049280405Srpaulo<p>
1050280405SrpauloLua is a free-form language.
1051280405SrpauloIt ignores spaces (including new lines) and comments
1052280405Srpaulobetween lexical elements (tokens),
1053280405Srpauloexcept as delimiters between names and keywords.
1054280405Srpaulo
1055280405Srpaulo
1056280405Srpaulo<p>
1057280405Srpaulo<em>Names</em>
1058280405Srpaulo(also called <em>identifiers</em>)
1059280405Srpauloin Lua can be any string of letters,
1060280405Srpaulodigits, and underscores,
1061326344Simpnot beginning with a digit and
1062326344Simpnot being a reserved word.
1063280405SrpauloIdentifiers are used to name variables, table fields, and labels.
1064280405Srpaulo
1065280405Srpaulo
1066280405Srpaulo<p>
1067280405SrpauloThe following <em>keywords</em> are reserved
1068280405Srpauloand cannot be used as names:
1069280405Srpaulo
1070280405Srpaulo
1071280405Srpaulo<pre>
1072280405Srpaulo     and       break     do        else      elseif    end
1073280405Srpaulo     false     for       function  goto      if        in
1074280405Srpaulo     local     nil       not       or        repeat    return
1075280405Srpaulo     then      true      until     while
1076280405Srpaulo</pre>
1077280405Srpaulo
1078280405Srpaulo<p>
1079280405SrpauloLua is a case-sensitive language:
1080280405Srpaulo<code>and</code> is a reserved word, but <code>And</code> and <code>AND</code>
1081280405Srpauloare two different, valid names.
1082280405SrpauloAs a convention,
1083326344Simpprograms should avoid creating
1084280405Srpaulonames that start with an underscore followed by
1085280405Srpauloone or more uppercase letters (such as <a href="#pdf-_VERSION"><code>_VERSION</code></a>).
1086280405Srpaulo
1087280405Srpaulo
1088280405Srpaulo<p>
1089280405SrpauloThe following strings denote other tokens:
1090280405Srpaulo
1091280405Srpaulo<pre>
1092280405Srpaulo     +     -     *     /     %     ^     #
1093280405Srpaulo     &amp;     ~     |     &lt;&lt;    &gt;&gt;    //
1094280405Srpaulo     ==    ~=    &lt;=    &gt;=    &lt;     &gt;     =
1095280405Srpaulo     (     )     {     }     [     ]     ::
1096280405Srpaulo     ;     :     ,     .     ..    ...
1097280405Srpaulo</pre>
1098280405Srpaulo
1099280405Srpaulo<p>
1100326344SimpA <em>short literal string</em>
1101280405Srpaulocan be delimited by matching single or double quotes,
1102280405Srpauloand can contain the following C-like escape sequences:
1103280405Srpaulo'<code>\a</code>' (bell),
1104280405Srpaulo'<code>\b</code>' (backspace),
1105280405Srpaulo'<code>\f</code>' (form feed),
1106280405Srpaulo'<code>\n</code>' (newline),
1107280405Srpaulo'<code>\r</code>' (carriage return),
1108280405Srpaulo'<code>\t</code>' (horizontal tab),
1109280405Srpaulo'<code>\v</code>' (vertical tab),
1110280405Srpaulo'<code>\\</code>' (backslash),
1111280405Srpaulo'<code>\"</code>' (quotation mark [double quote]),
1112280405Srpauloand '<code>\'</code>' (apostrophe [single quote]).
1113326344SimpA backslash followed by a line break
1114280405Srpauloresults in a newline in the string.
1115280405SrpauloThe escape sequence '<code>\z</code>' skips the following span
1116280405Srpauloof white-space characters,
1117280405Srpauloincluding line breaks;
1118280405Srpauloit is particularly useful to break and indent a long literal string
1119280405Srpaulointo multiple lines without adding the newlines and spaces
1120280405Srpaulointo the string contents.
1121326344SimpA short literal string cannot contain unescaped line breaks
1122326344Simpnor escapes not forming a valid escape sequence.
1123280405Srpaulo
1124280405Srpaulo
1125280405Srpaulo<p>
1126326344SimpWe can specify any byte in a short literal string by its numeric value
1127326344Simp(including embedded zeros).
1128280405SrpauloThis can be done
1129280405Srpaulowith the escape sequence <code>\x<em>XX</em></code>,
1130280405Srpaulowhere <em>XX</em> is a sequence of exactly two hexadecimal digits,
1131280405Srpauloor with the escape sequence <code>\<em>ddd</em></code>,
1132280405Srpaulowhere <em>ddd</em> is a sequence of up to three decimal digits.
1133280405Srpaulo(Note that if a decimal escape sequence is to be followed by a digit,
1134280405Srpauloit must be expressed using exactly three digits.)
1135280405Srpaulo
1136280405Srpaulo
1137280405Srpaulo<p>
1138280405SrpauloThe UTF-8 encoding of a Unicode character
1139280405Srpaulocan be inserted in a literal string with
1140280405Srpaulothe escape sequence <code>\u{<em>XXX</em>}</code>
1141280405Srpaulo(note the mandatory enclosing brackets),
1142280405Srpaulowhere <em>XXX</em> is a sequence of one or more hexadecimal digits
1143280405Srpaulorepresenting the character code point.
1144280405Srpaulo
1145280405Srpaulo
1146280405Srpaulo<p>
1147280405SrpauloLiteral strings can also be defined using a long format
1148280405Srpauloenclosed by <em>long brackets</em>.
1149280405SrpauloWe define an <em>opening long bracket of level <em>n</em></em> as an opening
1150280405Srpaulosquare bracket followed by <em>n</em> equal signs followed by another
1151280405Srpauloopening square bracket.
1152280405SrpauloSo, an opening long bracket of level&nbsp;0 is written as <code>[[</code>, 
1153280405Srpauloan opening long bracket of level&nbsp;1 is written as <code>[=[</code>, 
1154280405Srpauloand so on.
1155280405SrpauloA <em>closing long bracket</em> is defined similarly;
1156280405Srpaulofor instance,
1157280405Srpauloa closing long bracket of level&nbsp;4 is written as  <code>]====]</code>.
1158280405SrpauloA <em>long literal</em> starts with an opening long bracket of any level and
1159280405Srpauloends at the first closing long bracket of the same level.
1160280405SrpauloIt can contain any text except a closing bracket of the same level.
1161280405SrpauloLiterals in this bracketed form can run for several lines,
1162280405Srpaulodo not interpret any escape sequences,
1163280405Srpauloand ignore long brackets of any other level.
1164280405SrpauloAny kind of end-of-line sequence
1165280405Srpaulo(carriage return, newline, carriage return followed by newline,
1166280405Srpauloor newline followed by carriage return)
1167280405Srpaulois converted to a simple newline.
1168280405Srpaulo
1169280405Srpaulo
1170280405Srpaulo<p>
1171280405SrpauloFor convenience,
1172280405Srpaulowhen the opening long bracket is immediately followed by a newline,
1173280405Srpaulothe newline is not included in the string.
1174280405SrpauloAs an example, in a system using ASCII
1175280405Srpaulo(in which '<code>a</code>' is coded as&nbsp;97,
1176280405Srpaulonewline is coded as&nbsp;10, and '<code>1</code>' is coded as&nbsp;49),
1177280405Srpaulothe five literal strings below denote the same string:
1178280405Srpaulo
1179280405Srpaulo<pre>
1180280405Srpaulo     a = 'alo\n123"'
1181280405Srpaulo     a = "alo\n123\""
1182280405Srpaulo     a = '\97lo\10\04923"'
1183280405Srpaulo     a = [[alo
1184280405Srpaulo     123"]]
1185280405Srpaulo     a = [==[
1186280405Srpaulo     alo
1187280405Srpaulo     123"]==]
1188280405Srpaulo</pre>
1189280405Srpaulo
1190280405Srpaulo<p>
1191326344SimpAny byte in a literal string not
1192326344Simpexplicitly affected by the previous rules represents itself.
1193326344SimpHowever, Lua opens files for parsing in text mode,
1194326344Simpand the system file functions may have problems with
1195326344Simpsome control characters.
1196326344SimpSo, it is safer to represent
1197326344Simpnon-text data as a quoted literal with
1198326344Simpexplicit escape sequences for the non-text characters.
1199326344Simp
1200326344Simp
1201326344Simp<p>
1202326344SimpA <em>numeric constant</em> (or <em>numeral</em>)
1203280405Srpaulocan be written with an optional fractional part
1204280405Srpauloand an optional decimal exponent,
1205280405Srpaulomarked by a letter '<code>e</code>' or '<code>E</code>'.
1206280405SrpauloLua also accepts hexadecimal constants,
1207280405Srpaulowhich start with <code>0x</code> or <code>0X</code>.
1208280405SrpauloHexadecimal constants also accept an optional fractional part
1209280405Srpauloplus an optional binary exponent,
1210280405Srpaulomarked by a letter '<code>p</code>' or '<code>P</code>'.
1211326344SimpA numeric constant with a radix point or an exponent
1212280405Srpaulodenotes a float;
1213326344Simpotherwise,
1214326344Simpif its value fits in an integer,
1215326344Simpit denotes an integer.
1216280405SrpauloExamples of valid integer constants are
1217280405Srpaulo
1218280405Srpaulo<pre>
1219280405Srpaulo     3   345   0xff   0xBEBADA
1220280405Srpaulo</pre><p>
1221280405SrpauloExamples of valid float constants are
1222280405Srpaulo
1223280405Srpaulo<pre>
1224280405Srpaulo     3.0     3.1416     314.16e-2     0.31416E1     34e1
1225280405Srpaulo     0x0.1E  0xA23p-4   0X1.921FB54442D18P+1
1226280405Srpaulo</pre>
1227280405Srpaulo
1228280405Srpaulo<p>
1229280405SrpauloA <em>comment</em> starts with a double hyphen (<code>--</code>)
1230280405Srpauloanywhere outside a string.
1231280405SrpauloIf the text immediately after <code>--</code> is not an opening long bracket,
1232280405Srpaulothe comment is a <em>short comment</em>,
1233280405Srpaulowhich runs until the end of the line.
1234280405SrpauloOtherwise, it is a <em>long comment</em>,
1235280405Srpaulowhich runs until the corresponding closing long bracket.
1236280405SrpauloLong comments are frequently used to disable code temporarily.
1237280405Srpaulo
1238280405Srpaulo
1239280405Srpaulo
1240280405Srpaulo
1241280405Srpaulo
1242280405Srpaulo<h2>3.2 &ndash; <a name="3.2">Variables</a></h2>
1243280405Srpaulo
1244280405Srpaulo<p>
1245280405SrpauloVariables are places that store values.
1246280405SrpauloThere are three kinds of variables in Lua:
1247280405Srpauloglobal variables, local variables, and table fields.
1248280405Srpaulo
1249280405Srpaulo
1250280405Srpaulo<p>
1251280405SrpauloA single name can denote a global variable or a local variable
1252280405Srpaulo(or a function's formal parameter,
1253280405Srpaulowhich is a particular kind of local variable):
1254280405Srpaulo
1255280405Srpaulo<pre>
1256280405Srpaulo	var ::= Name
1257280405Srpaulo</pre><p>
1258280405SrpauloName denotes identifiers, as defined in <a href="#3.1">&sect;3.1</a>.
1259280405Srpaulo
1260280405Srpaulo
1261280405Srpaulo<p>
1262280405SrpauloAny variable name is assumed to be global unless explicitly declared
1263280405Srpauloas a local (see <a href="#3.3.7">&sect;3.3.7</a>).
1264280405SrpauloLocal variables are <em>lexically scoped</em>:
1265280405Srpaulolocal variables can be freely accessed by functions
1266280405Srpaulodefined inside their scope (see <a href="#3.5">&sect;3.5</a>).
1267280405Srpaulo
1268280405Srpaulo
1269280405Srpaulo<p>
1270280405SrpauloBefore the first assignment to a variable, its value is <b>nil</b>.
1271280405Srpaulo
1272280405Srpaulo
1273280405Srpaulo<p>
1274280405SrpauloSquare brackets are used to index a table:
1275280405Srpaulo
1276280405Srpaulo<pre>
1277280405Srpaulo	var ::= prefixexp &lsquo;<b>[</b>&rsquo; exp &lsquo;<b>]</b>&rsquo;
1278280405Srpaulo</pre><p>
1279280405SrpauloThe meaning of accesses to table fields can be changed via metatables.
1280280405SrpauloAn access to an indexed variable <code>t[i]</code> is equivalent to
1281280405Srpauloa call <code>gettable_event(t,i)</code>.
1282280405Srpaulo(See <a href="#2.4">&sect;2.4</a> for a complete description of the
1283280405Srpaulo<code>gettable_event</code> function.
1284280405SrpauloThis function is not defined or callable in Lua.
1285280405SrpauloWe use it here only for explanatory purposes.)
1286280405Srpaulo
1287280405Srpaulo
1288280405Srpaulo<p>
1289280405SrpauloThe syntax <code>var.Name</code> is just syntactic sugar for
1290280405Srpaulo<code>var["Name"]</code>:
1291280405Srpaulo
1292280405Srpaulo<pre>
1293280405Srpaulo	var ::= prefixexp &lsquo;<b>.</b>&rsquo; Name
1294280405Srpaulo</pre>
1295280405Srpaulo
1296280405Srpaulo<p>
1297280405SrpauloAn access to a global variable <code>x</code>
1298280405Srpaulois equivalent to <code>_ENV.x</code>.
1299280405SrpauloDue to the way that chunks are compiled,
1300280405Srpaulo<code>_ENV</code> is never a global name (see <a href="#2.2">&sect;2.2</a>).
1301280405Srpaulo
1302280405Srpaulo
1303280405Srpaulo
1304280405Srpaulo
1305280405Srpaulo
1306280405Srpaulo<h2>3.3 &ndash; <a name="3.3">Statements</a></h2>
1307280405Srpaulo
1308280405Srpaulo<p>
1309280405SrpauloLua supports an almost conventional set of statements,
1310280405Srpaulosimilar to those in Pascal or C.
1311280405SrpauloThis set includes
1312280405Srpauloassignments, control structures, function calls,
1313280405Srpauloand variable declarations.
1314280405Srpaulo
1315280405Srpaulo
1316280405Srpaulo
1317280405Srpaulo<h3>3.3.1 &ndash; <a name="3.3.1">Blocks</a></h3>
1318280405Srpaulo
1319280405Srpaulo<p>
1320280405SrpauloA block is a list of statements,
1321280405Srpaulowhich are executed sequentially:
1322280405Srpaulo
1323280405Srpaulo<pre>
1324280405Srpaulo	block ::= {stat}
1325280405Srpaulo</pre><p>
1326280405SrpauloLua has <em>empty statements</em>
1327280405Srpaulothat allow you to separate statements with semicolons,
1328280405Srpaulostart a block with a semicolon
1329280405Srpauloor write two semicolons in sequence:
1330280405Srpaulo
1331280405Srpaulo<pre>
1332280405Srpaulo	stat ::= &lsquo;<b>;</b>&rsquo;
1333280405Srpaulo</pre>
1334280405Srpaulo
1335280405Srpaulo<p>
1336280405SrpauloFunction calls and assignments
1337280405Srpaulocan start with an open parenthesis.
1338280405SrpauloThis possibility leads to an ambiguity in Lua's grammar.
1339280405SrpauloConsider the following fragment:
1340280405Srpaulo
1341280405Srpaulo<pre>
1342280405Srpaulo     a = b + c
1343280405Srpaulo     (print or io.write)('done')
1344280405Srpaulo</pre><p>
1345280405SrpauloThe grammar could see it in two ways:
1346280405Srpaulo
1347280405Srpaulo<pre>
1348280405Srpaulo     a = b + c(print or io.write)('done')
1349280405Srpaulo     
1350280405Srpaulo     a = b + c; (print or io.write)('done')
1351280405Srpaulo</pre><p>
1352280405SrpauloThe current parser always sees such constructions
1353280405Srpauloin the first way,
1354280405Srpaulointerpreting the open parenthesis
1355280405Srpauloas the start of the arguments to a call.
1356280405SrpauloTo avoid this ambiguity,
1357280405Srpauloit is a good practice to always precede with a semicolon
1358280405Srpaulostatements that start with a parenthesis:
1359280405Srpaulo
1360280405Srpaulo<pre>
1361280405Srpaulo     ;(print or io.write)('done')
1362280405Srpaulo</pre>
1363280405Srpaulo
1364280405Srpaulo<p>
1365280405SrpauloA block can be explicitly delimited to produce a single statement:
1366280405Srpaulo
1367280405Srpaulo<pre>
1368280405Srpaulo	stat ::= <b>do</b> block <b>end</b>
1369280405Srpaulo</pre><p>
1370280405SrpauloExplicit blocks are useful
1371280405Srpauloto control the scope of variable declarations.
1372280405SrpauloExplicit blocks are also sometimes used to
1373280405Srpauloadd a <b>return</b> statement in the middle
1374280405Srpauloof another block (see <a href="#3.3.4">&sect;3.3.4</a>).
1375280405Srpaulo
1376280405Srpaulo
1377280405Srpaulo
1378280405Srpaulo
1379280405Srpaulo
1380280405Srpaulo<h3>3.3.2 &ndash; <a name="3.3.2">Chunks</a></h3>
1381280405Srpaulo
1382280405Srpaulo<p>
1383280405SrpauloThe unit of compilation of Lua is called a <em>chunk</em>.
1384280405SrpauloSyntactically,
1385280405Srpauloa chunk is simply a block:
1386280405Srpaulo
1387280405Srpaulo<pre>
1388280405Srpaulo	chunk ::= block
1389280405Srpaulo</pre>
1390280405Srpaulo
1391280405Srpaulo<p>
1392280405SrpauloLua handles a chunk as the body of an anonymous function
1393280405Srpaulowith a variable number of arguments
1394280405Srpaulo(see <a href="#3.4.11">&sect;3.4.11</a>).
1395280405SrpauloAs such, chunks can define local variables,
1396280405Srpauloreceive arguments, and return values.
1397280405SrpauloMoreover, such anonymous function is compiled as in the
1398280405Srpauloscope of an external local variable called <code>_ENV</code> (see <a href="#2.2">&sect;2.2</a>).
1399280405SrpauloThe resulting function always has <code>_ENV</code> as its only upvalue,
1400280405Srpauloeven if it does not use that variable.
1401280405Srpaulo
1402280405Srpaulo
1403280405Srpaulo<p>
1404280405SrpauloA chunk can be stored in a file or in a string inside the host program.
1405280405SrpauloTo execute a chunk,
1406280405SrpauloLua first <em>loads</em> it,
1407280405Srpauloprecompiling the chunk's code into instructions for a virtual machine,
1408280405Srpauloand then Lua executes the compiled code
1409280405Srpaulowith an interpreter for the virtual machine.
1410280405Srpaulo
1411280405Srpaulo
1412280405Srpaulo<p>
1413280405SrpauloChunks can also be precompiled into binary form;
1414280405Srpaulosee program <code>luac</code> and function <a href="#pdf-string.dump"><code>string.dump</code></a> for details.
1415280405SrpauloPrograms in source and compiled forms are interchangeable;
1416280405SrpauloLua automatically detects the file type and acts accordingly (see <a href="#pdf-load"><code>load</code></a>).
1417280405Srpaulo
1418280405Srpaulo
1419280405Srpaulo
1420280405Srpaulo
1421280405Srpaulo
1422280405Srpaulo<h3>3.3.3 &ndash; <a name="3.3.3">Assignment</a></h3>
1423280405Srpaulo
1424280405Srpaulo<p>
1425280405SrpauloLua allows multiple assignments.
1426280405SrpauloTherefore, the syntax for assignment
1427280405Srpaulodefines a list of variables on the left side
1428280405Srpauloand a list of expressions on the right side.
1429280405SrpauloThe elements in both lists are separated by commas:
1430280405Srpaulo
1431280405Srpaulo<pre>
1432280405Srpaulo	stat ::= varlist &lsquo;<b>=</b>&rsquo; explist
1433280405Srpaulo	varlist ::= var {&lsquo;<b>,</b>&rsquo; var}
1434280405Srpaulo	explist ::= exp {&lsquo;<b>,</b>&rsquo; exp}
1435280405Srpaulo</pre><p>
1436280405SrpauloExpressions are discussed in <a href="#3.4">&sect;3.4</a>.
1437280405Srpaulo
1438280405Srpaulo
1439280405Srpaulo<p>
1440280405SrpauloBefore the assignment,
1441280405Srpaulothe list of values is <em>adjusted</em> to the length of
1442280405Srpaulothe list of variables.
1443280405SrpauloIf there are more values than needed,
1444280405Srpaulothe excess values are thrown away.
1445280405SrpauloIf there are fewer values than needed,
1446280405Srpaulothe list is extended with as many  <b>nil</b>'s as needed.
1447280405SrpauloIf the list of expressions ends with a function call,
1448280405Srpaulothen all values returned by that call enter the list of values,
1449280405Srpaulobefore the adjustment
1450280405Srpaulo(except when the call is enclosed in parentheses; see <a href="#3.4">&sect;3.4</a>).
1451280405Srpaulo
1452280405Srpaulo
1453280405Srpaulo<p>
1454280405SrpauloThe assignment statement first evaluates all its expressions
1455280405Srpauloand only then the assignments are performed.
1456280405SrpauloThus the code
1457280405Srpaulo
1458280405Srpaulo<pre>
1459280405Srpaulo     i = 3
1460280405Srpaulo     i, a[i] = i+1, 20
1461280405Srpaulo</pre><p>
1462280405Srpaulosets <code>a[3]</code> to 20, without affecting <code>a[4]</code>
1463280405Srpaulobecause the <code>i</code> in <code>a[i]</code> is evaluated (to 3)
1464280405Srpaulobefore it is assigned&nbsp;4.
1465280405SrpauloSimilarly, the line
1466280405Srpaulo
1467280405Srpaulo<pre>
1468280405Srpaulo     x, y = y, x
1469280405Srpaulo</pre><p>
1470280405Srpauloexchanges the values of <code>x</code> and <code>y</code>,
1471280405Srpauloand
1472280405Srpaulo
1473280405Srpaulo<pre>
1474280405Srpaulo     x, y, z = y, z, x
1475280405Srpaulo</pre><p>
1476280405Srpaulocyclically permutes the values of <code>x</code>, <code>y</code>, and <code>z</code>.
1477280405Srpaulo
1478280405Srpaulo
1479280405Srpaulo<p>
1480280405SrpauloThe meaning of assignments to global variables
1481280405Srpauloand table fields can be changed via metatables.
1482280405SrpauloAn assignment to an indexed variable <code>t[i] = val</code> is equivalent to
1483280405Srpaulo<code>settable_event(t,i,val)</code>.
1484280405Srpaulo(See <a href="#2.4">&sect;2.4</a> for a complete description of the
1485280405Srpaulo<code>settable_event</code> function.
1486280405SrpauloThis function is not defined or callable in Lua.
1487280405SrpauloWe use it here only for explanatory purposes.)
1488280405Srpaulo
1489280405Srpaulo
1490280405Srpaulo<p>
1491280405SrpauloAn assignment to a global name <code>x = val</code>
1492280405Srpaulois equivalent to the assignment
1493280405Srpaulo<code>_ENV.x = val</code> (see <a href="#2.2">&sect;2.2</a>).
1494280405Srpaulo
1495280405Srpaulo
1496280405Srpaulo
1497280405Srpaulo
1498280405Srpaulo
1499280405Srpaulo<h3>3.3.4 &ndash; <a name="3.3.4">Control Structures</a></h3><p>
1500280405SrpauloThe control structures
1501280405Srpaulo<b>if</b>, <b>while</b>, and <b>repeat</b> have the usual meaning and
1502280405Srpaulofamiliar syntax:
1503280405Srpaulo
1504280405Srpaulo
1505280405Srpaulo
1506280405Srpaulo
1507280405Srpaulo<pre>
1508280405Srpaulo	stat ::= <b>while</b> exp <b>do</b> block <b>end</b>
1509280405Srpaulo	stat ::= <b>repeat</b> block <b>until</b> exp
1510280405Srpaulo	stat ::= <b>if</b> exp <b>then</b> block {<b>elseif</b> exp <b>then</b> block} [<b>else</b> block] <b>end</b>
1511280405Srpaulo</pre><p>
1512280405SrpauloLua also has a <b>for</b> statement, in two flavors (see <a href="#3.3.5">&sect;3.3.5</a>).
1513280405Srpaulo
1514280405Srpaulo
1515280405Srpaulo<p>
1516280405SrpauloThe condition expression of a
1517280405Srpaulocontrol structure can return any value.
1518280405SrpauloBoth <b>false</b> and <b>nil</b> are considered false.
1519280405SrpauloAll values different from <b>nil</b> and <b>false</b> are considered true
1520280405Srpaulo(in particular, the number 0 and the empty string are also true).
1521280405Srpaulo
1522280405Srpaulo
1523280405Srpaulo<p>
1524280405SrpauloIn the <b>repeat</b>&ndash;<b>until</b> loop,
1525280405Srpaulothe inner block does not end at the <b>until</b> keyword,
1526280405Srpaulobut only after the condition.
1527280405SrpauloSo, the condition can refer to local variables
1528280405Srpaulodeclared inside the loop block.
1529280405Srpaulo
1530280405Srpaulo
1531280405Srpaulo<p>
1532280405SrpauloThe <b>goto</b> statement transfers the program control to a label.
1533280405SrpauloFor syntactical reasons,
1534280405Srpaulolabels in Lua are considered statements too:
1535280405Srpaulo
1536280405Srpaulo
1537280405Srpaulo
1538280405Srpaulo<pre>
1539280405Srpaulo	stat ::= <b>goto</b> Name
1540280405Srpaulo	stat ::= label
1541280405Srpaulo	label ::= &lsquo;<b>::</b>&rsquo; Name &lsquo;<b>::</b>&rsquo;
1542280405Srpaulo</pre>
1543280405Srpaulo
1544280405Srpaulo<p>
1545280405SrpauloA label is visible in the entire block where it is defined,
1546280405Srpauloexcept
1547280405Srpauloinside nested blocks where a label with the same name is defined and
1548280405Srpauloinside nested functions.
1549280405SrpauloA goto may jump to any visible label as long as it does not
1550280405Srpauloenter into the scope of a local variable.
1551280405Srpaulo
1552280405Srpaulo
1553280405Srpaulo<p>
1554280405SrpauloLabels and empty statements are called <em>void statements</em>,
1555280405Srpauloas they perform no actions.
1556280405Srpaulo
1557280405Srpaulo
1558280405Srpaulo<p>
1559280405SrpauloThe <b>break</b> statement terminates the execution of a
1560280405Srpaulo<b>while</b>, <b>repeat</b>, or <b>for</b> loop,
1561280405Srpauloskipping to the next statement after the loop:
1562280405Srpaulo
1563280405Srpaulo
1564280405Srpaulo<pre>
1565280405Srpaulo	stat ::= <b>break</b>
1566280405Srpaulo</pre><p>
1567280405SrpauloA <b>break</b> ends the innermost enclosing loop.
1568280405Srpaulo
1569280405Srpaulo
1570280405Srpaulo<p>
1571280405SrpauloThe <b>return</b> statement is used to return values
1572280405Srpaulofrom a function or a chunk
1573280405Srpaulo(which is an anonymous function).
1574280405Srpaulo
1575280405SrpauloFunctions can return more than one value,
1576280405Srpauloso the syntax for the <b>return</b> statement is
1577280405Srpaulo
1578280405Srpaulo<pre>
1579280405Srpaulo	stat ::= <b>return</b> [explist] [&lsquo;<b>;</b>&rsquo;]
1580280405Srpaulo</pre>
1581280405Srpaulo
1582280405Srpaulo<p>
1583280405SrpauloThe <b>return</b> statement can only be written
1584280405Srpauloas the last statement of a block.
1585280405SrpauloIf it is really necessary to <b>return</b> in the middle of a block,
1586280405Srpaulothen an explicit inner block can be used,
1587280405Srpauloas in the idiom <code>do return end</code>,
1588280405Srpaulobecause now <b>return</b> is the last statement in its (inner) block.
1589280405Srpaulo
1590280405Srpaulo
1591280405Srpaulo
1592280405Srpaulo
1593280405Srpaulo
1594280405Srpaulo<h3>3.3.5 &ndash; <a name="3.3.5">For Statement</a></h3>
1595280405Srpaulo
1596280405Srpaulo<p>
1597280405Srpaulo
1598280405SrpauloThe <b>for</b> statement has two forms:
1599326344Simpone numerical and one generic.
1600280405Srpaulo
1601280405Srpaulo
1602280405Srpaulo<p>
1603326344SimpThe numerical <b>for</b> loop repeats a block of code while a
1604280405Srpaulocontrol variable runs through an arithmetic progression.
1605280405SrpauloIt has the following syntax:
1606280405Srpaulo
1607280405Srpaulo<pre>
1608280405Srpaulo	stat ::= <b>for</b> Name &lsquo;<b>=</b>&rsquo; exp &lsquo;<b>,</b>&rsquo; exp [&lsquo;<b>,</b>&rsquo; exp] <b>do</b> block <b>end</b>
1609280405Srpaulo</pre><p>
1610280405SrpauloThe <em>block</em> is repeated for <em>name</em> starting at the value of
1611280405Srpaulothe first <em>exp</em>, until it passes the second <em>exp</em> by steps of the
1612280405Srpaulothird <em>exp</em>.
1613280405SrpauloMore precisely, a <b>for</b> statement like
1614280405Srpaulo
1615280405Srpaulo<pre>
1616280405Srpaulo     for v = <em>e1</em>, <em>e2</em>, <em>e3</em> do <em>block</em> end
1617280405Srpaulo</pre><p>
1618280405Srpaulois equivalent to the code:
1619280405Srpaulo
1620280405Srpaulo<pre>
1621280405Srpaulo     do
1622280405Srpaulo       local <em>var</em>, <em>limit</em>, <em>step</em> = tonumber(<em>e1</em>), tonumber(<em>e2</em>), tonumber(<em>e3</em>)
1623280405Srpaulo       if not (<em>var</em> and <em>limit</em> and <em>step</em>) then error() end
1624280405Srpaulo       <em>var</em> = <em>var</em> - <em>step</em>
1625280405Srpaulo       while true do
1626280405Srpaulo         <em>var</em> = <em>var</em> + <em>step</em>
1627280405Srpaulo         if (<em>step</em> &gt;= 0 and <em>var</em> &gt; <em>limit</em>) or (<em>step</em> &lt; 0 and <em>var</em> &lt; <em>limit</em>) then
1628280405Srpaulo           break
1629280405Srpaulo         end
1630280405Srpaulo         local v = <em>var</em>
1631280405Srpaulo         <em>block</em>
1632280405Srpaulo       end
1633280405Srpaulo     end
1634280405Srpaulo</pre>
1635280405Srpaulo
1636280405Srpaulo<p>
1637280405SrpauloNote the following:
1638280405Srpaulo
1639280405Srpaulo<ul>
1640280405Srpaulo
1641280405Srpaulo<li>
1642280405SrpauloAll three control expressions are evaluated only once,
1643280405Srpaulobefore the loop starts.
1644280405SrpauloThey must all result in numbers.
1645280405Srpaulo</li>
1646280405Srpaulo
1647280405Srpaulo<li>
1648280405Srpaulo<code><em>var</em></code>, <code><em>limit</em></code>, and <code><em>step</em></code> are invisible variables.
1649280405SrpauloThe names shown here are for explanatory purposes only.
1650280405Srpaulo</li>
1651280405Srpaulo
1652280405Srpaulo<li>
1653280405SrpauloIf the third expression (the step) is absent,
1654280405Srpaulothen a step of&nbsp;1 is used.
1655280405Srpaulo</li>
1656280405Srpaulo
1657280405Srpaulo<li>
1658280405SrpauloYou can use <b>break</b> and <b>goto</b> to exit a <b>for</b> loop.
1659280405Srpaulo</li>
1660280405Srpaulo
1661280405Srpaulo<li>
1662280405SrpauloThe loop variable <code>v</code> is local to the loop body.
1663280405SrpauloIf you need its value after the loop,
1664280405Srpauloassign it to another variable before exiting the loop.
1665280405Srpaulo</li>
1666280405Srpaulo
1667280405Srpaulo</ul>
1668280405Srpaulo
1669280405Srpaulo<p>
1670280405SrpauloThe generic <b>for</b> statement works over functions,
1671280405Srpaulocalled <em>iterators</em>.
1672280405SrpauloOn each iteration, the iterator function is called to produce a new value,
1673280405Srpaulostopping when this new value is <b>nil</b>.
1674280405SrpauloThe generic <b>for</b> loop has the following syntax:
1675280405Srpaulo
1676280405Srpaulo<pre>
1677280405Srpaulo	stat ::= <b>for</b> namelist <b>in</b> explist <b>do</b> block <b>end</b>
1678280405Srpaulo	namelist ::= Name {&lsquo;<b>,</b>&rsquo; Name}
1679280405Srpaulo</pre><p>
1680280405SrpauloA <b>for</b> statement like
1681280405Srpaulo
1682280405Srpaulo<pre>
1683280405Srpaulo     for <em>var_1</em>, &middot;&middot;&middot;, <em>var_n</em> in <em>explist</em> do <em>block</em> end
1684280405Srpaulo</pre><p>
1685280405Srpaulois equivalent to the code:
1686280405Srpaulo
1687280405Srpaulo<pre>
1688280405Srpaulo     do
1689280405Srpaulo       local <em>f</em>, <em>s</em>, <em>var</em> = <em>explist</em>
1690280405Srpaulo       while true do
1691280405Srpaulo         local <em>var_1</em>, &middot;&middot;&middot;, <em>var_n</em> = <em>f</em>(<em>s</em>, <em>var</em>)
1692280405Srpaulo         if <em>var_1</em> == nil then break end
1693280405Srpaulo         <em>var</em> = <em>var_1</em>
1694280405Srpaulo         <em>block</em>
1695280405Srpaulo       end
1696280405Srpaulo     end
1697280405Srpaulo</pre><p>
1698280405SrpauloNote the following:
1699280405Srpaulo
1700280405Srpaulo<ul>
1701280405Srpaulo
1702280405Srpaulo<li>
1703280405Srpaulo<code><em>explist</em></code> is evaluated only once.
1704280405SrpauloIts results are an <em>iterator</em> function,
1705280405Srpauloa <em>state</em>,
1706280405Srpauloand an initial value for the first <em>iterator variable</em>.
1707280405Srpaulo</li>
1708280405Srpaulo
1709280405Srpaulo<li>
1710280405Srpaulo<code><em>f</em></code>, <code><em>s</em></code>, and <code><em>var</em></code> are invisible variables.
1711280405SrpauloThe names are here for explanatory purposes only.
1712280405Srpaulo</li>
1713280405Srpaulo
1714280405Srpaulo<li>
1715280405SrpauloYou can use <b>break</b> to exit a <b>for</b> loop.
1716280405Srpaulo</li>
1717280405Srpaulo
1718280405Srpaulo<li>
1719280405SrpauloThe loop variables <code><em>var_i</em></code> are local to the loop;
1720280405Srpauloyou cannot use their values after the <b>for</b> ends.
1721280405SrpauloIf you need these values,
1722280405Srpaulothen assign them to other variables before breaking or exiting the loop.
1723280405Srpaulo</li>
1724280405Srpaulo
1725280405Srpaulo</ul>
1726280405Srpaulo
1727280405Srpaulo
1728280405Srpaulo
1729280405Srpaulo
1730280405Srpaulo<h3>3.3.6 &ndash; <a name="3.3.6">Function Calls as Statements</a></h3><p>
1731280405SrpauloTo allow possible side-effects,
1732280405Srpaulofunction calls can be executed as statements:
1733280405Srpaulo
1734280405Srpaulo<pre>
1735280405Srpaulo	stat ::= functioncall
1736280405Srpaulo</pre><p>
1737280405SrpauloIn this case, all returned values are thrown away.
1738280405SrpauloFunction calls are explained in <a href="#3.4.10">&sect;3.4.10</a>.
1739280405Srpaulo
1740280405Srpaulo
1741280405Srpaulo
1742280405Srpaulo
1743280405Srpaulo
1744280405Srpaulo<h3>3.3.7 &ndash; <a name="3.3.7">Local Declarations</a></h3><p>
1745280405SrpauloLocal variables can be declared anywhere inside a block.
1746280405SrpauloThe declaration can include an initial assignment:
1747280405Srpaulo
1748280405Srpaulo<pre>
1749280405Srpaulo	stat ::= <b>local</b> namelist [&lsquo;<b>=</b>&rsquo; explist]
1750280405Srpaulo</pre><p>
1751280405SrpauloIf present, an initial assignment has the same semantics
1752280405Srpauloof a multiple assignment (see <a href="#3.3.3">&sect;3.3.3</a>).
1753280405SrpauloOtherwise, all variables are initialized with <b>nil</b>.
1754280405Srpaulo
1755280405Srpaulo
1756280405Srpaulo<p>
1757280405SrpauloA chunk is also a block (see <a href="#3.3.2">&sect;3.3.2</a>),
1758280405Srpauloand so local variables can be declared in a chunk outside any explicit block.
1759280405Srpaulo
1760280405Srpaulo
1761280405Srpaulo<p>
1762280405SrpauloThe visibility rules for local variables are explained in <a href="#3.5">&sect;3.5</a>.
1763280405Srpaulo
1764280405Srpaulo
1765280405Srpaulo
1766280405Srpaulo
1767280405Srpaulo
1768280405Srpaulo
1769280405Srpaulo
1770280405Srpaulo<h2>3.4 &ndash; <a name="3.4">Expressions</a></h2>
1771280405Srpaulo
1772280405Srpaulo<p>
1773280405SrpauloThe basic expressions in Lua are the following:
1774280405Srpaulo
1775280405Srpaulo<pre>
1776280405Srpaulo	exp ::= prefixexp
1777280405Srpaulo	exp ::= <b>nil</b> | <b>false</b> | <b>true</b>
1778280405Srpaulo	exp ::= Numeral
1779280405Srpaulo	exp ::= LiteralString
1780280405Srpaulo	exp ::= functiondef
1781280405Srpaulo	exp ::= tableconstructor
1782280405Srpaulo	exp ::= &lsquo;<b>...</b>&rsquo;
1783280405Srpaulo	exp ::= exp binop exp
1784280405Srpaulo	exp ::= unop exp
1785280405Srpaulo	prefixexp ::= var | functioncall | &lsquo;<b>(</b>&rsquo; exp &lsquo;<b>)</b>&rsquo;
1786280405Srpaulo</pre>
1787280405Srpaulo
1788280405Srpaulo<p>
1789280405SrpauloNumerals and literal strings are explained in <a href="#3.1">&sect;3.1</a>;
1790280405Srpaulovariables are explained in <a href="#3.2">&sect;3.2</a>;
1791280405Srpaulofunction definitions are explained in <a href="#3.4.11">&sect;3.4.11</a>;
1792280405Srpaulofunction calls are explained in <a href="#3.4.10">&sect;3.4.10</a>;
1793280405Srpaulotable constructors are explained in <a href="#3.4.9">&sect;3.4.9</a>.
1794280405SrpauloVararg expressions,
1795280405Srpaulodenoted by three dots ('<code>...</code>'), can only be used when
1796280405Srpaulodirectly inside a vararg function;
1797280405Srpaulothey are explained in <a href="#3.4.11">&sect;3.4.11</a>.
1798280405Srpaulo
1799280405Srpaulo
1800280405Srpaulo<p>
1801280405SrpauloBinary operators comprise arithmetic operators (see <a href="#3.4.1">&sect;3.4.1</a>),
1802280405Srpaulobitwise operators (see <a href="#3.4.2">&sect;3.4.2</a>),
1803280405Srpaulorelational operators (see <a href="#3.4.4">&sect;3.4.4</a>), logical operators (see <a href="#3.4.5">&sect;3.4.5</a>),
1804280405Srpauloand the concatenation operator (see <a href="#3.4.6">&sect;3.4.6</a>).
1805280405SrpauloUnary operators comprise the unary minus (see <a href="#3.4.1">&sect;3.4.1</a>),
1806326344Simpthe unary bitwise NOT (see <a href="#3.4.2">&sect;3.4.2</a>),
1807280405Srpaulothe unary logical <b>not</b> (see <a href="#3.4.5">&sect;3.4.5</a>),
1808280405Srpauloand the unary <em>length operator</em> (see <a href="#3.4.7">&sect;3.4.7</a>).
1809280405Srpaulo
1810280405Srpaulo
1811280405Srpaulo<p>
1812280405SrpauloBoth function calls and vararg expressions can result in multiple values.
1813280405SrpauloIf a function call is used as a statement (see <a href="#3.3.6">&sect;3.3.6</a>),
1814280405Srpaulothen its return list is adjusted to zero elements,
1815280405Srpaulothus discarding all returned values.
1816280405SrpauloIf an expression is used as the last (or the only) element
1817280405Srpauloof a list of expressions,
1818280405Srpaulothen no adjustment is made
1819280405Srpaulo(unless the expression is enclosed in parentheses).
1820280405SrpauloIn all other contexts,
1821280405SrpauloLua adjusts the result list to one element,
1822280405Srpauloeither discarding all values except the first one
1823280405Srpauloor adding a single <b>nil</b> if there are no values.
1824280405Srpaulo
1825280405Srpaulo
1826280405Srpaulo<p>
1827280405SrpauloHere are some examples:
1828280405Srpaulo
1829280405Srpaulo<pre>
1830280405Srpaulo     f()                -- adjusted to 0 results
1831280405Srpaulo     g(f(), x)          -- f() is adjusted to 1 result
1832280405Srpaulo     g(x, f())          -- g gets x plus all results from f()
1833280405Srpaulo     a,b,c = f(), x     -- f() is adjusted to 1 result (c gets nil)
1834280405Srpaulo     a,b = ...          -- a gets the first vararg parameter, b gets
1835280405Srpaulo                        -- the second (both a and b can get nil if there
1836280405Srpaulo                        -- is no corresponding vararg parameter)
1837280405Srpaulo     
1838280405Srpaulo     a,b,c = x, f()     -- f() is adjusted to 2 results
1839280405Srpaulo     a,b,c = f()        -- f() is adjusted to 3 results
1840280405Srpaulo     return f()         -- returns all results from f()
1841280405Srpaulo     return ...         -- returns all received vararg parameters
1842280405Srpaulo     return x,y,f()     -- returns x, y, and all results from f()
1843280405Srpaulo     {f()}              -- creates a list with all results from f()
1844280405Srpaulo     {...}              -- creates a list with all vararg parameters
1845280405Srpaulo     {f(), nil}         -- f() is adjusted to 1 result
1846280405Srpaulo</pre>
1847280405Srpaulo
1848280405Srpaulo<p>
1849280405SrpauloAny expression enclosed in parentheses always results in only one value.
1850280405SrpauloThus,
1851280405Srpaulo<code>(f(x,y,z))</code> is always a single value,
1852280405Srpauloeven if <code>f</code> returns several values.
1853280405Srpaulo(The value of <code>(f(x,y,z))</code> is the first value returned by <code>f</code>
1854280405Srpauloor <b>nil</b> if <code>f</code> does not return any values.)
1855280405Srpaulo
1856280405Srpaulo
1857280405Srpaulo
1858280405Srpaulo<h3>3.4.1 &ndash; <a name="3.4.1">Arithmetic Operators</a></h3><p>
1859280405SrpauloLua supports the following arithmetic operators:
1860280405Srpaulo
1861280405Srpaulo<ul>
1862280405Srpaulo<li><b><code>+</code>: </b>addition</li>
1863280405Srpaulo<li><b><code>-</code>: </b>subtraction</li>
1864280405Srpaulo<li><b><code>*</code>: </b>multiplication</li>
1865280405Srpaulo<li><b><code>/</code>: </b>float division</li>
1866280405Srpaulo<li><b><code>//</code>: </b>floor division</li>
1867280405Srpaulo<li><b><code>%</code>: </b>modulo</li>
1868280405Srpaulo<li><b><code>^</code>: </b>exponentiation</li>
1869280405Srpaulo<li><b><code>-</code>: </b>unary minus</li>
1870280405Srpaulo</ul>
1871280405Srpaulo
1872280405Srpaulo<p>
1873280405SrpauloWith the exception of exponentiation and float division,
1874280405Srpaulothe arithmetic operators work as follows:
1875280405SrpauloIf both operands are integers,
1876280405Srpaulothe operation is performed over integers and the result is an integer.
1877280405SrpauloOtherwise, if both operands are numbers
1878280405Srpauloor strings that can be converted to
1879280405Srpaulonumbers (see <a href="#3.4.3">&sect;3.4.3</a>),
1880280405Srpaulothen they are converted to floats,
1881280405Srpaulothe operation is performed following the usual rules
1882280405Srpaulofor floating-point arithmetic
1883280405Srpaulo(usually the IEEE 754 standard),
1884280405Srpauloand the result is a float.
1885280405Srpaulo
1886280405Srpaulo
1887280405Srpaulo<p>
1888280405SrpauloExponentiation and float division (<code>/</code>)
1889280405Srpauloalways convert their operands to floats
1890280405Srpauloand the result is always a float.
1891280405SrpauloExponentiation uses the ISO&nbsp;C function <code>pow</code>,
1892280405Srpauloso that it works for non-integer exponents too.
1893280405Srpaulo
1894280405Srpaulo
1895280405Srpaulo<p>
1896326344SimpFloor division (<code>//</code>) is a division
1897326344Simpthat rounds the quotient towards minus infinity,
1898280405Srpaulothat is, the floor of the division of its operands.
1899280405Srpaulo
1900280405Srpaulo
1901280405Srpaulo<p>
1902280405SrpauloModulo is defined as the remainder of a division
1903326344Simpthat rounds the quotient towards minus infinity (floor division).
1904280405Srpaulo
1905280405Srpaulo
1906280405Srpaulo<p>
1907280405SrpauloIn case of overflows in integer arithmetic,
1908280405Srpauloall operations <em>wrap around</em>,
1909280405Srpauloaccording to the usual rules of two-complement arithmetic.
1910280405Srpaulo(In other words,
1911280405Srpaulothey return the unique representable integer
1912280405Srpaulothat is equal modulo <em>2<sup>64</sup></em> to the mathematical result.)
1913280405Srpaulo
1914280405Srpaulo
1915280405Srpaulo
1916280405Srpaulo<h3>3.4.2 &ndash; <a name="3.4.2">Bitwise Operators</a></h3><p>
1917280405SrpauloLua supports the following bitwise operators:
1918280405Srpaulo
1919280405Srpaulo<ul>
1920326344Simp<li><b><code>&amp;</code>: </b>bitwise AND</li>
1921326344Simp<li><b><code>&#124;</code>: </b>bitwise OR</li>
1922326344Simp<li><b><code>~</code>: </b>bitwise exclusive OR</li>
1923280405Srpaulo<li><b><code>&gt;&gt;</code>: </b>right shift</li>
1924280405Srpaulo<li><b><code>&lt;&lt;</code>: </b>left shift</li>
1925326344Simp<li><b><code>~</code>: </b>unary bitwise NOT</li>
1926280405Srpaulo</ul>
1927280405Srpaulo
1928280405Srpaulo<p>
1929280405SrpauloAll bitwise operations convert its operands to integers
1930280405Srpaulo(see <a href="#3.4.3">&sect;3.4.3</a>),
1931280405Srpaulooperate on all bits of those integers,
1932280405Srpauloand result in an integer.
1933280405Srpaulo
1934280405Srpaulo
1935280405Srpaulo<p>
1936280405SrpauloBoth right and left shifts fill the vacant bits with zeros.
1937280405SrpauloNegative displacements shift to the other direction;
1938280405Srpaulodisplacements with absolute values equal to or higher than
1939280405Srpaulothe number of bits in an integer
1940280405Srpauloresult in zero (as all bits are shifted out).
1941280405Srpaulo
1942280405Srpaulo
1943280405Srpaulo
1944280405Srpaulo
1945280405Srpaulo
1946280405Srpaulo<h3>3.4.3 &ndash; <a name="3.4.3">Coercions and Conversions</a></h3><p>
1947280405SrpauloLua provides some automatic conversions between some
1948280405Srpaulotypes and representations at run time.
1949280405SrpauloBitwise operators always convert float operands to integers.
1950280405SrpauloExponentiation and float division
1951280405Srpauloalways convert integer operands to floats.
1952280405SrpauloAll other arithmetic operations applied to mixed numbers
1953280405Srpaulo(integers and floats) convert the integer operand to a float;
1954280405Srpaulothis is called the <em>usual rule</em>.
1955280405SrpauloThe C API also converts both integers to floats and
1956280405Srpaulofloats to integers, as needed.
1957280405SrpauloMoreover, string concatenation accepts numbers as arguments,
1958326344Simpbesides strings.
1959280405Srpaulo
1960280405Srpaulo
1961280405Srpaulo<p>
1962280405SrpauloLua also converts strings to numbers,
1963280405Srpaulowhenever a number is expected.
1964280405Srpaulo
1965280405Srpaulo
1966280405Srpaulo<p>
1967280405SrpauloIn a conversion from integer to float,
1968280405Srpauloif the integer value has an exact representation as a float,
1969280405Srpaulothat is the result.
1970280405SrpauloOtherwise,
1971280405Srpaulothe conversion gets the nearest higher or
1972280405Srpaulothe nearest lower representable value.
1973280405SrpauloThis kind of conversion never fails.
1974280405Srpaulo
1975280405Srpaulo
1976280405Srpaulo<p>
1977280405SrpauloThe conversion from float to integer
1978280405Srpaulochecks whether the float has an exact representation as an integer
1979280405Srpaulo(that is, the float has an integral value and
1980280405Srpauloit is in the range of integer representation).
1981280405SrpauloIf it does, that representation is the result.
1982280405SrpauloOtherwise, the conversion fails.
1983280405Srpaulo
1984280405Srpaulo
1985280405Srpaulo<p>
1986280405SrpauloThe conversion from strings to numbers goes as follows:
1987280405SrpauloFirst, the string is converted to an integer or a float,
1988280405Srpaulofollowing its syntax and the rules of the Lua lexer.
1989280405Srpaulo(The string may have also leading and trailing spaces and a sign.)
1990326344SimpThen, the resulting number (float or integer)
1991326344Simpis converted to the type (float or integer) required by the context
1992326344Simp(e.g., the operation that forced the conversion).
1993280405Srpaulo
1994280405Srpaulo
1995280405Srpaulo<p>
1996326344SimpAll conversions from strings to numbers
1997326344Simpaccept both a dot and the current locale mark
1998326344Simpas the radix character.
1999326344Simp(The Lua lexer, however, accepts only a dot.)
2000326344Simp
2001326344Simp
2002326344Simp<p>
2003280405SrpauloThe conversion from numbers to strings uses a
2004280405Srpaulonon-specified human-readable format.
2005280405SrpauloFor complete control over how numbers are converted to strings,
2006280405Srpaulouse the <code>format</code> function from the string library
2007280405Srpaulo(see <a href="#pdf-string.format"><code>string.format</code></a>).
2008280405Srpaulo
2009280405Srpaulo
2010280405Srpaulo
2011280405Srpaulo
2012280405Srpaulo
2013280405Srpaulo<h3>3.4.4 &ndash; <a name="3.4.4">Relational Operators</a></h3><p>
2014280405SrpauloLua supports the following relational operators:
2015280405Srpaulo
2016280405Srpaulo<ul>
2017280405Srpaulo<li><b><code>==</code>: </b>equality</li>
2018280405Srpaulo<li><b><code>~=</code>: </b>inequality</li>
2019280405Srpaulo<li><b><code>&lt;</code>: </b>less than</li>
2020280405Srpaulo<li><b><code>&gt;</code>: </b>greater than</li>
2021280405Srpaulo<li><b><code>&lt;=</code>: </b>less or equal</li>
2022280405Srpaulo<li><b><code>&gt;=</code>: </b>greater or equal</li>
2023280405Srpaulo</ul><p>
2024280405SrpauloThese operators always result in <b>false</b> or <b>true</b>.
2025280405Srpaulo
2026280405Srpaulo
2027280405Srpaulo<p>
2028280405SrpauloEquality (<code>==</code>) first compares the type of its operands.
2029280405SrpauloIf the types are different, then the result is <b>false</b>.
2030280405SrpauloOtherwise, the values of the operands are compared.
2031280405SrpauloStrings are compared in the obvious way.
2032326344SimpNumbers are equal if they denote the same mathematical value.
2033280405Srpaulo
2034280405Srpaulo
2035280405Srpaulo<p>
2036280405SrpauloTables, userdata, and threads
2037280405Srpauloare compared by reference:
2038280405Srpaulotwo objects are considered equal only if they are the same object.
2039280405SrpauloEvery time you create a new object
2040280405Srpaulo(a table, userdata, or thread),
2041280405Srpaulothis new object is different from any previously existing object.
2042280405SrpauloClosures with the same reference are always equal.
2043280405SrpauloClosures with any detectable difference
2044280405Srpaulo(different behavior, different definition) are always different.
2045280405Srpaulo
2046280405Srpaulo
2047280405Srpaulo<p>
2048280405SrpauloYou can change the way that Lua compares tables and userdata
2049280405Srpauloby using the "eq" metamethod (see <a href="#2.4">&sect;2.4</a>).
2050280405Srpaulo
2051280405Srpaulo
2052280405Srpaulo<p>
2053280405SrpauloEquality comparisons do not convert strings to numbers
2054280405Srpauloor vice versa.
2055280405SrpauloThus, <code>"0"==0</code> evaluates to <b>false</b>,
2056280405Srpauloand <code>t[0]</code> and <code>t["0"]</code> denote different
2057280405Srpauloentries in a table.
2058280405Srpaulo
2059280405Srpaulo
2060280405Srpaulo<p>
2061280405SrpauloThe operator <code>~=</code> is exactly the negation of equality (<code>==</code>).
2062280405Srpaulo
2063280405Srpaulo
2064280405Srpaulo<p>
2065280405SrpauloThe order operators work as follows.
2066280405SrpauloIf both arguments are numbers,
2067326344Simpthen they are compared according to their mathematical values
2068326344Simp(regardless of their subtypes).
2069280405SrpauloOtherwise, if both arguments are strings,
2070280405Srpaulothen their values are compared according to the current locale.
2071280405SrpauloOtherwise, Lua tries to call the "lt" or the "le"
2072280405Srpaulometamethod (see <a href="#2.4">&sect;2.4</a>).
2073280405SrpauloA comparison <code>a &gt; b</code> is translated to <code>b &lt; a</code>
2074280405Srpauloand <code>a &gt;= b</code> is translated to <code>b &lt;= a</code>.
2075280405Srpaulo
2076280405Srpaulo
2077326344Simp<p>
2078326344SimpFollowing the IEEE 754 standard,
2079326344SimpNaN is considered neither smaller than,
2080326344Simpnor equal to, nor greater than any value (including itself).
2081280405Srpaulo
2082280405Srpaulo
2083280405Srpaulo
2084326344Simp
2085326344Simp
2086280405Srpaulo<h3>3.4.5 &ndash; <a name="3.4.5">Logical Operators</a></h3><p>
2087280405SrpauloThe logical operators in Lua are
2088280405Srpaulo<b>and</b>, <b>or</b>, and <b>not</b>.
2089280405SrpauloLike the control structures (see <a href="#3.3.4">&sect;3.3.4</a>),
2090280405Srpauloall logical operators consider both <b>false</b> and <b>nil</b> as false
2091280405Srpauloand anything else as true.
2092280405Srpaulo
2093280405Srpaulo
2094280405Srpaulo<p>
2095280405SrpauloThe negation operator <b>not</b> always returns <b>false</b> or <b>true</b>.
2096280405SrpauloThe conjunction operator <b>and</b> returns its first argument
2097280405Srpauloif this value is <b>false</b> or <b>nil</b>;
2098280405Srpaulootherwise, <b>and</b> returns its second argument.
2099280405SrpauloThe disjunction operator <b>or</b> returns its first argument
2100280405Srpauloif this value is different from <b>nil</b> and <b>false</b>;
2101280405Srpaulootherwise, <b>or</b> returns its second argument.
2102280405SrpauloBoth <b>and</b> and <b>or</b> use short-circuit evaluation;
2103280405Srpaulothat is,
2104280405Srpaulothe second operand is evaluated only if necessary.
2105280405SrpauloHere are some examples:
2106280405Srpaulo
2107280405Srpaulo<pre>
2108280405Srpaulo     10 or 20            --&gt; 10
2109280405Srpaulo     10 or error()       --&gt; 10
2110280405Srpaulo     nil or "a"          --&gt; "a"
2111280405Srpaulo     nil and 10          --&gt; nil
2112280405Srpaulo     false and error()   --&gt; false
2113280405Srpaulo     false and nil       --&gt; false
2114280405Srpaulo     false or nil        --&gt; nil
2115280405Srpaulo     10 and 20           --&gt; 20
2116280405Srpaulo</pre><p>
2117280405Srpaulo(In this manual,
2118280405Srpaulo<code>--&gt;</code> indicates the result of the preceding expression.)
2119280405Srpaulo
2120280405Srpaulo
2121280405Srpaulo
2122280405Srpaulo
2123280405Srpaulo
2124280405Srpaulo<h3>3.4.6 &ndash; <a name="3.4.6">Concatenation</a></h3><p>
2125280405SrpauloThe string concatenation operator in Lua is
2126280405Srpaulodenoted by two dots ('<code>..</code>').
2127280405SrpauloIf both operands are strings or numbers, then they are converted to
2128280405Srpaulostrings according to the rules described in <a href="#3.4.3">&sect;3.4.3</a>.
2129280405SrpauloOtherwise, the <code>__concat</code> metamethod is called (see <a href="#2.4">&sect;2.4</a>).
2130280405Srpaulo
2131280405Srpaulo
2132280405Srpaulo
2133280405Srpaulo
2134280405Srpaulo
2135280405Srpaulo<h3>3.4.7 &ndash; <a name="3.4.7">The Length Operator</a></h3>
2136280405Srpaulo
2137280405Srpaulo<p>
2138280405SrpauloThe length operator is denoted by the unary prefix operator <code>#</code>.
2139326344Simp
2140326344Simp
2141326344Simp<p>
2142280405SrpauloThe length of a string is its number of bytes
2143280405Srpaulo(that is, the usual meaning of string length when each
2144280405Srpaulocharacter is one byte).
2145280405Srpaulo
2146280405Srpaulo
2147280405Srpaulo<p>
2148326344SimpThe length operator applied on a table
2149326344Simpreturns a border in that table.
2150326344SimpA <em>border</em> in a table <code>t</code> is any natural number
2151326344Simpthat satisfies the following condition:
2152280405Srpaulo
2153326344Simp<pre>
2154326344Simp     (border == 0 or t[border] ~= nil) and t[border + 1] == nil
2155326344Simp</pre><p>
2156326344SimpIn words,
2157326344Simpa border is any (natural) index in a table
2158326344Simpwhere a non-nil value is followed by a nil value
2159326344Simp(or zero, when index 1 is nil).
2160280405Srpaulo
2161326344Simp
2162280405Srpaulo<p>
2163326344SimpA table with exactly one border is called a <em>sequence</em>.
2164326344SimpFor instance, the table <code>{10, 20, 30, 40, 50}</code> is a sequence,
2165326344Simpas it has only one border (5).
2166326344SimpThe table <code>{10, 20, 30, nil, 50}</code> has two borders (3 and 5),
2167326344Simpand therefore it is not a sequence.
2168326344SimpThe table <code>{nil, 20, 30, nil, nil, 60, nil}</code>
2169326344Simphas three borders (0, 3, and 6),
2170326344Simpso it is not a sequence, too.
2171326344SimpThe table <code>{}</code> is a sequence with border 0.
2172326344SimpNote that non-natural keys do not interfere
2173280405Srpaulowith whether a table is a sequence.
2174280405Srpaulo
2175280405Srpaulo
2176326344Simp<p>
2177326344SimpWhen <code>t</code> is a sequence,
2178326344Simp<code>#t</code> returns its only border,
2179326344Simpwhich corresponds to the intuitive notion of the length of the sequence.
2180326344SimpWhen <code>t</code> is not a sequence,
2181326344Simp<code>#t</code> can return any of its borders.
2182326344Simp(The exact one depends on details of
2183326344Simpthe internal representation of the table,
2184326344Simpwhich in turn can depend on how the table was populated and
2185326344Simpthe memory addresses of its non-numeric keys.)
2186280405Srpaulo
2187280405Srpaulo
2188326344Simp<p>
2189326344SimpThe computation of the length of a table
2190326344Simphas a guaranteed worst time of <em>O(log n)</em>,
2191326344Simpwhere <em>n</em> is the largest natural key in the table.
2192280405Srpaulo
2193326344Simp
2194326344Simp<p>
2195326344SimpA program can modify the behavior of the length operator for
2196326344Simpany value but strings through the <code>__len</code> metamethod (see <a href="#2.4">&sect;2.4</a>).
2197326344Simp
2198326344Simp
2199326344Simp
2200326344Simp
2201326344Simp
2202280405Srpaulo<h3>3.4.8 &ndash; <a name="3.4.8">Precedence</a></h3><p>
2203280405SrpauloOperator precedence in Lua follows the table below,
2204280405Srpaulofrom lower to higher priority:
2205280405Srpaulo
2206280405Srpaulo<pre>
2207280405Srpaulo     or
2208280405Srpaulo     and
2209280405Srpaulo     &lt;     &gt;     &lt;=    &gt;=    ~=    ==
2210280405Srpaulo     |
2211280405Srpaulo     ~
2212280405Srpaulo     &amp;
2213280405Srpaulo     &lt;&lt;    &gt;&gt;
2214280405Srpaulo     ..
2215280405Srpaulo     +     -
2216280405Srpaulo     *     /     //    %
2217280405Srpaulo     unary operators (not   #     -     ~)
2218280405Srpaulo     ^
2219280405Srpaulo</pre><p>
2220280405SrpauloAs usual,
2221280405Srpauloyou can use parentheses to change the precedences of an expression.
2222280405SrpauloThe concatenation ('<code>..</code>') and exponentiation ('<code>^</code>')
2223280405Srpaulooperators are right associative.
2224280405SrpauloAll other binary operators are left associative.
2225280405Srpaulo
2226280405Srpaulo
2227280405Srpaulo
2228280405Srpaulo
2229280405Srpaulo
2230280405Srpaulo<h3>3.4.9 &ndash; <a name="3.4.9">Table Constructors</a></h3><p>
2231280405SrpauloTable constructors are expressions that create tables.
2232280405SrpauloEvery time a constructor is evaluated, a new table is created.
2233280405SrpauloA constructor can be used to create an empty table
2234280405Srpauloor to create a table and initialize some of its fields.
2235280405SrpauloThe general syntax for constructors is
2236280405Srpaulo
2237280405Srpaulo<pre>
2238280405Srpaulo	tableconstructor ::= &lsquo;<b>{</b>&rsquo; [fieldlist] &lsquo;<b>}</b>&rsquo;
2239280405Srpaulo	fieldlist ::= field {fieldsep field} [fieldsep]
2240280405Srpaulo	field ::= &lsquo;<b>[</b>&rsquo; exp &lsquo;<b>]</b>&rsquo; &lsquo;<b>=</b>&rsquo; exp | Name &lsquo;<b>=</b>&rsquo; exp | exp
2241280405Srpaulo	fieldsep ::= &lsquo;<b>,</b>&rsquo; | &lsquo;<b>;</b>&rsquo;
2242280405Srpaulo</pre>
2243280405Srpaulo
2244280405Srpaulo<p>
2245280405SrpauloEach field of the form <code>[exp1] = exp2</code> adds to the new table an entry
2246280405Srpaulowith key <code>exp1</code> and value <code>exp2</code>.
2247280405SrpauloA field of the form <code>name = exp</code> is equivalent to
2248280405Srpaulo<code>["name"] = exp</code>.
2249280405SrpauloFinally, fields of the form <code>exp</code> are equivalent to
2250280405Srpaulo<code>[i] = exp</code>, where <code>i</code> are consecutive integers
2251280405Srpaulostarting with 1.
2252280405SrpauloFields in the other formats do not affect this counting.
2253280405SrpauloFor example,
2254280405Srpaulo
2255280405Srpaulo<pre>
2256280405Srpaulo     a = { [f(1)] = g; "x", "y"; x = 1, f(x), [30] = 23; 45 }
2257280405Srpaulo</pre><p>
2258280405Srpaulois equivalent to
2259280405Srpaulo
2260280405Srpaulo<pre>
2261280405Srpaulo     do
2262280405Srpaulo       local t = {}
2263280405Srpaulo       t[f(1)] = g
2264280405Srpaulo       t[1] = "x"         -- 1st exp
2265280405Srpaulo       t[2] = "y"         -- 2nd exp
2266280405Srpaulo       t.x = 1            -- t["x"] = 1
2267280405Srpaulo       t[3] = f(x)        -- 3rd exp
2268280405Srpaulo       t[30] = 23
2269280405Srpaulo       t[4] = 45          -- 4th exp
2270280405Srpaulo       a = t
2271280405Srpaulo     end
2272280405Srpaulo</pre>
2273280405Srpaulo
2274280405Srpaulo<p>
2275280405SrpauloThe order of the assignments in a constructor is undefined.
2276280405Srpaulo(This order would be relevant only when there are repeated keys.)
2277280405Srpaulo
2278280405Srpaulo
2279280405Srpaulo<p>
2280280405SrpauloIf the last field in the list has the form <code>exp</code>
2281280405Srpauloand the expression is a function call or a vararg expression,
2282280405Srpaulothen all values returned by this expression enter the list consecutively
2283280405Srpaulo(see <a href="#3.4.10">&sect;3.4.10</a>).
2284280405Srpaulo
2285280405Srpaulo
2286280405Srpaulo<p>
2287280405SrpauloThe field list can have an optional trailing separator,
2288280405Srpauloas a convenience for machine-generated code.
2289280405Srpaulo
2290280405Srpaulo
2291280405Srpaulo
2292280405Srpaulo
2293280405Srpaulo
2294280405Srpaulo<h3>3.4.10 &ndash; <a name="3.4.10">Function Calls</a></h3><p>
2295280405SrpauloA function call in Lua has the following syntax:
2296280405Srpaulo
2297280405Srpaulo<pre>
2298280405Srpaulo	functioncall ::= prefixexp args
2299280405Srpaulo</pre><p>
2300280405SrpauloIn a function call,
2301280405Srpaulofirst prefixexp and args are evaluated.
2302280405SrpauloIf the value of prefixexp has type <em>function</em>,
2303280405Srpaulothen this function is called
2304280405Srpaulowith the given arguments.
2305280405SrpauloOtherwise, the prefixexp "call" metamethod is called,
2306280405Srpaulohaving as first parameter the value of prefixexp,
2307280405Srpaulofollowed by the original call arguments
2308280405Srpaulo(see <a href="#2.4">&sect;2.4</a>).
2309280405Srpaulo
2310280405Srpaulo
2311280405Srpaulo<p>
2312280405SrpauloThe form
2313280405Srpaulo
2314280405Srpaulo<pre>
2315280405Srpaulo	functioncall ::= prefixexp &lsquo;<b>:</b>&rsquo; Name args
2316280405Srpaulo</pre><p>
2317280405Srpaulocan be used to call "methods".
2318280405SrpauloA call <code>v:name(<em>args</em>)</code>
2319280405Srpaulois syntactic sugar for <code>v.name(v,<em>args</em>)</code>,
2320280405Srpauloexcept that <code>v</code> is evaluated only once.
2321280405Srpaulo
2322280405Srpaulo
2323280405Srpaulo<p>
2324280405SrpauloArguments have the following syntax:
2325280405Srpaulo
2326280405Srpaulo<pre>
2327280405Srpaulo	args ::= &lsquo;<b>(</b>&rsquo; [explist] &lsquo;<b>)</b>&rsquo;
2328280405Srpaulo	args ::= tableconstructor
2329280405Srpaulo	args ::= LiteralString
2330280405Srpaulo</pre><p>
2331280405SrpauloAll argument expressions are evaluated before the call.
2332280405SrpauloA call of the form <code>f{<em>fields</em>}</code> is
2333280405Srpaulosyntactic sugar for <code>f({<em>fields</em>})</code>;
2334280405Srpaulothat is, the argument list is a single new table.
2335280405SrpauloA call of the form <code>f'<em>string</em>'</code>
2336280405Srpaulo(or <code>f"<em>string</em>"</code> or <code>f[[<em>string</em>]]</code>)
2337280405Srpaulois syntactic sugar for <code>f('<em>string</em>')</code>;
2338280405Srpaulothat is, the argument list is a single literal string.
2339280405Srpaulo
2340280405Srpaulo
2341280405Srpaulo<p>
2342280405SrpauloA call of the form <code>return <em>functioncall</em></code> is called
2343280405Srpauloa <em>tail call</em>.
2344280405SrpauloLua implements <em>proper tail calls</em>
2345280405Srpaulo(or <em>proper tail recursion</em>):
2346280405Srpauloin a tail call,
2347280405Srpaulothe called function reuses the stack entry of the calling function.
2348280405SrpauloTherefore, there is no limit on the number of nested tail calls that
2349280405Srpauloa program can execute.
2350280405SrpauloHowever, a tail call erases any debug information about the
2351280405Srpaulocalling function.
2352280405SrpauloNote that a tail call only happens with a particular syntax,
2353280405Srpaulowhere the <b>return</b> has one single function call as argument;
2354280405Srpaulothis syntax makes the calling function return exactly
2355280405Srpaulothe returns of the called function.
2356280405SrpauloSo, none of the following examples are tail calls:
2357280405Srpaulo
2358280405Srpaulo<pre>
2359280405Srpaulo     return (f(x))        -- results adjusted to 1
2360280405Srpaulo     return 2 * f(x)
2361280405Srpaulo     return x, f(x)       -- additional results
2362280405Srpaulo     f(x); return         -- results discarded
2363280405Srpaulo     return x or f(x)     -- results adjusted to 1
2364280405Srpaulo</pre>
2365280405Srpaulo
2366280405Srpaulo
2367280405Srpaulo
2368280405Srpaulo
2369280405Srpaulo<h3>3.4.11 &ndash; <a name="3.4.11">Function Definitions</a></h3>
2370280405Srpaulo
2371280405Srpaulo<p>
2372280405SrpauloThe syntax for function definition is
2373280405Srpaulo
2374280405Srpaulo<pre>
2375280405Srpaulo	functiondef ::= <b>function</b> funcbody
2376280405Srpaulo	funcbody ::= &lsquo;<b>(</b>&rsquo; [parlist] &lsquo;<b>)</b>&rsquo; block <b>end</b>
2377280405Srpaulo</pre>
2378280405Srpaulo
2379280405Srpaulo<p>
2380280405SrpauloThe following syntactic sugar simplifies function definitions:
2381280405Srpaulo
2382280405Srpaulo<pre>
2383280405Srpaulo	stat ::= <b>function</b> funcname funcbody
2384280405Srpaulo	stat ::= <b>local</b> <b>function</b> Name funcbody
2385280405Srpaulo	funcname ::= Name {&lsquo;<b>.</b>&rsquo; Name} [&lsquo;<b>:</b>&rsquo; Name]
2386280405Srpaulo</pre><p>
2387280405SrpauloThe statement
2388280405Srpaulo
2389280405Srpaulo<pre>
2390280405Srpaulo     function f () <em>body</em> end
2391280405Srpaulo</pre><p>
2392280405Srpaulotranslates to
2393280405Srpaulo
2394280405Srpaulo<pre>
2395280405Srpaulo     f = function () <em>body</em> end
2396280405Srpaulo</pre><p>
2397280405SrpauloThe statement
2398280405Srpaulo
2399280405Srpaulo<pre>
2400280405Srpaulo     function t.a.b.c.f () <em>body</em> end
2401280405Srpaulo</pre><p>
2402280405Srpaulotranslates to
2403280405Srpaulo
2404280405Srpaulo<pre>
2405280405Srpaulo     t.a.b.c.f = function () <em>body</em> end
2406280405Srpaulo</pre><p>
2407280405SrpauloThe statement
2408280405Srpaulo
2409280405Srpaulo<pre>
2410280405Srpaulo     local function f () <em>body</em> end
2411280405Srpaulo</pre><p>
2412280405Srpaulotranslates to
2413280405Srpaulo
2414280405Srpaulo<pre>
2415280405Srpaulo     local f; f = function () <em>body</em> end
2416280405Srpaulo</pre><p>
2417280405Srpaulonot to
2418280405Srpaulo
2419280405Srpaulo<pre>
2420280405Srpaulo     local f = function () <em>body</em> end
2421280405Srpaulo</pre><p>
2422280405Srpaulo(This only makes a difference when the body of the function
2423280405Srpaulocontains references to <code>f</code>.)
2424280405Srpaulo
2425280405Srpaulo
2426280405Srpaulo<p>
2427280405SrpauloA function definition is an executable expression,
2428280405Srpaulowhose value has type <em>function</em>.
2429280405SrpauloWhen Lua precompiles a chunk,
2430280405Srpauloall its function bodies are precompiled too.
2431280405SrpauloThen, whenever Lua executes the function definition,
2432280405Srpaulothe function is <em>instantiated</em> (or <em>closed</em>).
2433280405SrpauloThis function instance (or <em>closure</em>)
2434280405Srpaulois the final value of the expression.
2435280405Srpaulo
2436280405Srpaulo
2437280405Srpaulo<p>
2438280405SrpauloParameters act as local variables that are
2439280405Srpauloinitialized with the argument values:
2440280405Srpaulo
2441280405Srpaulo<pre>
2442280405Srpaulo	parlist ::= namelist [&lsquo;<b>,</b>&rsquo; &lsquo;<b>...</b>&rsquo;] | &lsquo;<b>...</b>&rsquo;
2443280405Srpaulo</pre><p>
2444280405SrpauloWhen a function is called,
2445280405Srpaulothe list of arguments is adjusted to
2446280405Srpaulothe length of the list of parameters,
2447280405Srpaulounless the function is a <em>vararg function</em>,
2448280405Srpaulowhich is indicated by three dots ('<code>...</code>')
2449280405Srpauloat the end of its parameter list.
2450280405SrpauloA vararg function does not adjust its argument list;
2451280405Srpauloinstead, it collects all extra arguments and supplies them
2452280405Srpauloto the function through a <em>vararg expression</em>,
2453280405Srpaulowhich is also written as three dots.
2454280405SrpauloThe value of this expression is a list of all actual extra arguments,
2455280405Srpaulosimilar to a function with multiple results.
2456280405SrpauloIf a vararg expression is used inside another expression
2457280405Srpauloor in the middle of a list of expressions,
2458280405Srpaulothen its return list is adjusted to one element.
2459280405SrpauloIf the expression is used as the last element of a list of expressions,
2460280405Srpaulothen no adjustment is made
2461280405Srpaulo(unless that last expression is enclosed in parentheses).
2462280405Srpaulo
2463280405Srpaulo
2464280405Srpaulo<p>
2465280405SrpauloAs an example, consider the following definitions:
2466280405Srpaulo
2467280405Srpaulo<pre>
2468280405Srpaulo     function f(a, b) end
2469280405Srpaulo     function g(a, b, ...) end
2470280405Srpaulo     function r() return 1,2,3 end
2471280405Srpaulo</pre><p>
2472280405SrpauloThen, we have the following mapping from arguments to parameters and
2473280405Srpauloto the vararg expression:
2474280405Srpaulo
2475280405Srpaulo<pre>
2476280405Srpaulo     CALL            PARAMETERS
2477280405Srpaulo     
2478280405Srpaulo     f(3)             a=3, b=nil
2479280405Srpaulo     f(3, 4)          a=3, b=4
2480280405Srpaulo     f(3, 4, 5)       a=3, b=4
2481280405Srpaulo     f(r(), 10)       a=1, b=10
2482280405Srpaulo     f(r())           a=1, b=2
2483280405Srpaulo     
2484280405Srpaulo     g(3)             a=3, b=nil, ... --&gt;  (nothing)
2485280405Srpaulo     g(3, 4)          a=3, b=4,   ... --&gt;  (nothing)
2486280405Srpaulo     g(3, 4, 5, 8)    a=3, b=4,   ... --&gt;  5  8
2487280405Srpaulo     g(5, r())        a=5, b=1,   ... --&gt;  2  3
2488280405Srpaulo</pre>
2489280405Srpaulo
2490280405Srpaulo<p>
2491280405SrpauloResults are returned using the <b>return</b> statement (see <a href="#3.3.4">&sect;3.3.4</a>).
2492280405SrpauloIf control reaches the end of a function
2493280405Srpaulowithout encountering a <b>return</b> statement,
2494280405Srpaulothen the function returns with no results.
2495280405Srpaulo
2496280405Srpaulo
2497280405Srpaulo<p>
2498280405Srpaulo
2499280405SrpauloThere is a system-dependent limit on the number of values
2500280405Srpaulothat a function may return.
2501280405SrpauloThis limit is guaranteed to be larger than 1000.
2502280405Srpaulo
2503280405Srpaulo
2504280405Srpaulo<p>
2505280405SrpauloThe <em>colon</em> syntax
2506280405Srpaulois used for defining <em>methods</em>,
2507280405Srpaulothat is, functions that have an implicit extra parameter <code>self</code>.
2508280405SrpauloThus, the statement
2509280405Srpaulo
2510280405Srpaulo<pre>
2511280405Srpaulo     function t.a.b.c:f (<em>params</em>) <em>body</em> end
2512280405Srpaulo</pre><p>
2513280405Srpaulois syntactic sugar for
2514280405Srpaulo
2515280405Srpaulo<pre>
2516280405Srpaulo     t.a.b.c.f = function (self, <em>params</em>) <em>body</em> end
2517280405Srpaulo</pre>
2518280405Srpaulo
2519280405Srpaulo
2520280405Srpaulo
2521280405Srpaulo
2522280405Srpaulo
2523280405Srpaulo
2524280405Srpaulo<h2>3.5 &ndash; <a name="3.5">Visibility Rules</a></h2>
2525280405Srpaulo
2526280405Srpaulo<p>
2527280405Srpaulo
2528280405SrpauloLua is a lexically scoped language.
2529280405SrpauloThe scope of a local variable begins at the first statement after
2530280405Srpauloits declaration and lasts until the last non-void statement
2531280405Srpauloof the innermost block that includes the declaration.
2532280405SrpauloConsider the following example:
2533280405Srpaulo
2534280405Srpaulo<pre>
2535280405Srpaulo     x = 10                -- global variable
2536280405Srpaulo     do                    -- new block
2537280405Srpaulo       local x = x         -- new 'x', with value 10
2538280405Srpaulo       print(x)            --&gt; 10
2539280405Srpaulo       x = x+1
2540280405Srpaulo       do                  -- another block
2541280405Srpaulo         local x = x+1     -- another 'x'
2542280405Srpaulo         print(x)          --&gt; 12
2543280405Srpaulo       end
2544280405Srpaulo       print(x)            --&gt; 11
2545280405Srpaulo     end
2546280405Srpaulo     print(x)              --&gt; 10  (the global one)
2547280405Srpaulo</pre>
2548280405Srpaulo
2549280405Srpaulo<p>
2550280405SrpauloNotice that, in a declaration like <code>local x = x</code>,
2551280405Srpaulothe new <code>x</code> being declared is not in scope yet,
2552280405Srpauloand so the second <code>x</code> refers to the outside variable.
2553280405Srpaulo
2554280405Srpaulo
2555280405Srpaulo<p>
2556280405SrpauloBecause of the lexical scoping rules,
2557280405Srpaulolocal variables can be freely accessed by functions
2558280405Srpaulodefined inside their scope.
2559280405SrpauloA local variable used by an inner function is called
2560280405Srpauloan <em>upvalue</em>, or <em>external local variable</em>,
2561280405Srpauloinside the inner function.
2562280405Srpaulo
2563280405Srpaulo
2564280405Srpaulo<p>
2565280405SrpauloNotice that each execution of a <b>local</b> statement
2566280405Srpaulodefines new local variables.
2567280405SrpauloConsider the following example:
2568280405Srpaulo
2569280405Srpaulo<pre>
2570280405Srpaulo     a = {}
2571280405Srpaulo     local x = 20
2572280405Srpaulo     for i=1,10 do
2573280405Srpaulo       local y = 0
2574280405Srpaulo       a[i] = function () y=y+1; return x+y end
2575280405Srpaulo     end
2576280405Srpaulo</pre><p>
2577280405SrpauloThe loop creates ten closures
2578280405Srpaulo(that is, ten instances of the anonymous function).
2579280405SrpauloEach of these closures uses a different <code>y</code> variable,
2580280405Srpaulowhile all of them share the same <code>x</code>.
2581280405Srpaulo
2582280405Srpaulo
2583280405Srpaulo
2584280405Srpaulo
2585280405Srpaulo
2586280405Srpaulo<h1>4 &ndash; <a name="4">The Application Program Interface</a></h1>
2587280405Srpaulo
2588280405Srpaulo<p>
2589280405Srpaulo
2590280405SrpauloThis section describes the C&nbsp;API for Lua, that is,
2591280405Srpaulothe set of C&nbsp;functions available to the host program to communicate
2592280405Srpaulowith Lua.
2593280405SrpauloAll API functions and related types and constants
2594280405Srpauloare declared in the header file <a name="pdf-lua.h"><code>lua.h</code></a>.
2595280405Srpaulo
2596280405Srpaulo
2597280405Srpaulo<p>
2598280405SrpauloEven when we use the term "function",
2599280405Srpauloany facility in the API may be provided as a macro instead.
2600280405SrpauloExcept where stated otherwise,
2601280405Srpauloall such macros use each of their arguments exactly once
2602280405Srpaulo(except for the first argument, which is always a Lua state),
2603280405Srpauloand so do not generate any hidden side-effects.
2604280405Srpaulo
2605280405Srpaulo
2606280405Srpaulo<p>
2607280405SrpauloAs in most C&nbsp;libraries,
2608280405Srpaulothe Lua API functions do not check their arguments for validity or consistency.
2609280405SrpauloHowever, you can change this behavior by compiling Lua
2610280405Srpaulowith the macro <a name="pdf-LUA_USE_APICHECK"><code>LUA_USE_APICHECK</code></a> defined.
2611280405Srpaulo
2612280405Srpaulo
2613326344Simp<p>
2614326344SimpThe Lua library is fully reentrant:
2615326344Simpit has no global variables.
2616326344SimpIt keeps all information it needs in a dynamic structure,
2617326344Simpcalled the <em>Lua state</em>.
2618280405Srpaulo
2619326344Simp
2620326344Simp<p>
2621326344SimpEach Lua state has one or more threads,
2622326344Simpwhich correspond to independent, cooperative lines of execution.
2623326344SimpThe type <a href="#lua_State"><code>lua_State</code></a> (despite its name) refers to a thread.
2624326344Simp(Indirectly, through the thread, it also refers to the
2625326344SimpLua state associated to the thread.)
2626326344Simp
2627326344Simp
2628326344Simp<p>
2629326344SimpA pointer to a thread must be passed as the first argument to
2630326344Simpevery function in the library, except to <a href="#lua_newstate"><code>lua_newstate</code></a>,
2631326344Simpwhich creates a Lua state from scratch and returns a pointer
2632326344Simpto the <em>main thread</em> in the new state.
2633326344Simp
2634326344Simp
2635326344Simp
2636280405Srpaulo<h2>4.1 &ndash; <a name="4.1">The Stack</a></h2>
2637280405Srpaulo
2638280405Srpaulo<p>
2639280405SrpauloLua uses a <em>virtual stack</em> to pass values to and from C.
2640280405SrpauloEach element in this stack represents a Lua value
2641280405Srpaulo(<b>nil</b>, number, string, etc.).
2642326344SimpFunctions in the API can access this stack through the
2643326344SimpLua state parameter that they receive.
2644280405Srpaulo
2645280405Srpaulo
2646280405Srpaulo<p>
2647280405SrpauloWhenever Lua calls C, the called function gets a new stack,
2648280405Srpaulowhich is independent of previous stacks and of stacks of
2649280405SrpauloC&nbsp;functions that are still active.
2650280405SrpauloThis stack initially contains any arguments to the C&nbsp;function
2651326344Simpand it is where the C&nbsp;function can store temporary
2652326344SimpLua values and must push its results
2653280405Srpauloto be returned to the caller (see <a href="#lua_CFunction"><code>lua_CFunction</code></a>).
2654280405Srpaulo
2655280405Srpaulo
2656280405Srpaulo<p>
2657280405SrpauloFor convenience,
2658280405Srpaulomost query operations in the API do not follow a strict stack discipline.
2659280405SrpauloInstead, they can refer to any element in the stack
2660280405Srpauloby using an <em>index</em>:
2661280405SrpauloA positive index represents an absolute stack position
2662280405Srpaulo(starting at&nbsp;1);
2663280405Srpauloa negative index represents an offset relative to the top of the stack.
2664280405SrpauloMore specifically, if the stack has <em>n</em> elements,
2665280405Srpaulothen index&nbsp;1 represents the first element
2666280405Srpaulo(that is, the element that was pushed onto the stack first)
2667280405Srpauloand
2668280405Srpauloindex&nbsp;<em>n</em> represents the last element;
2669280405Srpauloindex&nbsp;-1 also represents the last element
2670280405Srpaulo(that is, the element at the&nbsp;top)
2671280405Srpauloand index <em>-n</em> represents the first element.
2672280405Srpaulo
2673280405Srpaulo
2674280405Srpaulo
2675280405Srpaulo
2676280405Srpaulo
2677280405Srpaulo<h2>4.2 &ndash; <a name="4.2">Stack Size</a></h2>
2678280405Srpaulo
2679280405Srpaulo<p>
2680280405SrpauloWhen you interact with the Lua API,
2681280405Srpauloyou are responsible for ensuring consistency.
2682280405SrpauloIn particular,
2683280405Srpaulo<em>you are responsible for controlling stack overflow</em>.
2684280405SrpauloYou can use the function <a href="#lua_checkstack"><code>lua_checkstack</code></a>
2685280405Srpauloto ensure that the stack has enough space for pushing new elements.
2686280405Srpaulo
2687280405Srpaulo
2688280405Srpaulo<p>
2689280405SrpauloWhenever Lua calls C,
2690280405Srpauloit ensures that the stack has space for
2691280405Srpauloat least <a name="pdf-LUA_MINSTACK"><code>LUA_MINSTACK</code></a> extra slots.
2692280405Srpaulo<code>LUA_MINSTACK</code> is defined as 20,
2693280405Srpauloso that usually you do not have to worry about stack space
2694280405Srpaulounless your code has loops pushing elements onto the stack.
2695280405Srpaulo
2696280405Srpaulo
2697280405Srpaulo<p>
2698280405SrpauloWhen you call a Lua function
2699280405Srpaulowithout a fixed number of results (see <a href="#lua_call"><code>lua_call</code></a>),
2700280405SrpauloLua ensures that the stack has enough space for all results,
2701280405Srpaulobut it does not ensure any extra space.
2702280405SrpauloSo, before pushing anything in the stack after such a call
2703280405Srpauloyou should use <a href="#lua_checkstack"><code>lua_checkstack</code></a>.
2704280405Srpaulo
2705280405Srpaulo
2706280405Srpaulo
2707280405Srpaulo
2708280405Srpaulo
2709280405Srpaulo<h2>4.3 &ndash; <a name="4.3">Valid and Acceptable Indices</a></h2>
2710280405Srpaulo
2711280405Srpaulo<p>
2712280405SrpauloAny function in the API that receives stack indices
2713280405Srpauloworks only with <em>valid indices</em> or <em>acceptable indices</em>.
2714280405Srpaulo
2715280405Srpaulo
2716280405Srpaulo<p>
2717280405SrpauloA <em>valid index</em> is an index that refers to a
2718326344Simpposition that stores a modifiable Lua value.
2719326344SimpIt comprises stack indices between&nbsp;1 and the stack top
2720326344Simp(<code>1 &le; abs(index) &le; top</code>)
2721280405Srpaulo
2722326344Simpplus <em>pseudo-indices</em>,
2723326344Simpwhich represent some positions that are accessible to C&nbsp;code
2724326344Simpbut that are not in the stack.
2725326344SimpPseudo-indices are used to access the registry (see <a href="#4.5">&sect;4.5</a>)
2726280405Srpauloand the upvalues of a C&nbsp;function (see <a href="#4.4">&sect;4.4</a>).
2727280405Srpaulo
2728280405Srpaulo
2729280405Srpaulo<p>
2730326344SimpFunctions that do not need a specific mutable position,
2731326344Simpbut only a value (e.g., query functions),
2732280405Srpaulocan be called with acceptable indices.
2733280405SrpauloAn <em>acceptable index</em> can be any valid index,
2734280405Srpaulobut it also can be any positive index after the stack top
2735280405Srpaulowithin the space allocated for the stack,
2736280405Srpaulothat is, indices up to the stack size.
2737280405Srpaulo(Note that 0 is never an acceptable index.)
2738280405SrpauloExcept when noted otherwise,
2739280405Srpaulofunctions in the API work with acceptable indices.
2740280405Srpaulo
2741280405Srpaulo
2742280405Srpaulo<p>
2743280405SrpauloAcceptable indices serve to avoid extra tests
2744280405Srpauloagainst the stack top when querying the stack.
2745280405SrpauloFor instance, a C&nbsp;function can query its third argument
2746280405Srpaulowithout the need to first check whether there is a third argument,
2747280405Srpaulothat is, without the need to check whether 3 is a valid index.
2748280405Srpaulo
2749280405Srpaulo
2750280405Srpaulo<p>
2751280405SrpauloFor functions that can be called with acceptable indices,
2752280405Srpauloany non-valid index is treated as if it
2753280405Srpaulocontains a value of a virtual type <a name="pdf-LUA_TNONE"><code>LUA_TNONE</code></a>,
2754280405Srpaulowhich behaves like a nil value.
2755280405Srpaulo
2756280405Srpaulo
2757280405Srpaulo
2758280405Srpaulo
2759280405Srpaulo
2760280405Srpaulo<h2>4.4 &ndash; <a name="4.4">C Closures</a></h2>
2761280405Srpaulo
2762280405Srpaulo<p>
2763280405SrpauloWhen a C&nbsp;function is created,
2764280405Srpauloit is possible to associate some values with it,
2765280405Srpaulothus creating a <em>C&nbsp;closure</em>
2766280405Srpaulo(see <a href="#lua_pushcclosure"><code>lua_pushcclosure</code></a>);
2767280405Srpaulothese values are called <em>upvalues</em> and are
2768280405Srpauloaccessible to the function whenever it is called.
2769280405Srpaulo
2770280405Srpaulo
2771280405Srpaulo<p>
2772280405SrpauloWhenever a C&nbsp;function is called,
2773280405Srpauloits upvalues are located at specific pseudo-indices.
2774280405SrpauloThese pseudo-indices are produced by the macro
2775280405Srpaulo<a href="#lua_upvalueindex"><code>lua_upvalueindex</code></a>.
2776326344SimpThe first upvalue associated with a function is at index
2777280405Srpaulo<code>lua_upvalueindex(1)</code>, and so on.
2778280405SrpauloAny access to <code>lua_upvalueindex(<em>n</em>)</code>,
2779280405Srpaulowhere <em>n</em> is greater than the number of upvalues of the
2780326344Simpcurrent function
2781326344Simp(but not greater than 256,
2782326344Simpwhich is one plus the maximum number of upvalues in a closure),
2783280405Srpauloproduces an acceptable but invalid index.
2784280405Srpaulo
2785280405Srpaulo
2786280405Srpaulo
2787280405Srpaulo
2788280405Srpaulo
2789280405Srpaulo<h2>4.5 &ndash; <a name="4.5">Registry</a></h2>
2790280405Srpaulo
2791280405Srpaulo<p>
2792280405SrpauloLua provides a <em>registry</em>,
2793280405Srpauloa predefined table that can be used by any C&nbsp;code to
2794280405Srpaulostore whatever Lua values it needs to store.
2795280405SrpauloThe registry table is always located at pseudo-index
2796326344Simp<a name="pdf-LUA_REGISTRYINDEX"><code>LUA_REGISTRYINDEX</code></a>.
2797280405SrpauloAny C&nbsp;library can store data into this table,
2798280405Srpaulobut it must take care to choose keys
2799280405Srpaulothat are different from those used
2800280405Srpauloby other libraries, to avoid collisions.
2801280405SrpauloTypically, you should use as key a string containing your library name,
2802280405Srpauloor a light userdata with the address of a C&nbsp;object in your code,
2803280405Srpauloor any Lua object created by your code.
2804280405SrpauloAs with variable names,
2805280405Srpaulostring keys starting with an underscore followed by
2806280405Srpaulouppercase letters are reserved for Lua.
2807280405Srpaulo
2808280405Srpaulo
2809280405Srpaulo<p>
2810280405SrpauloThe integer keys in the registry are used
2811280405Srpauloby the reference mechanism (see <a href="#luaL_ref"><code>luaL_ref</code></a>)
2812280405Srpauloand by some predefined values.
2813280405SrpauloTherefore, integer keys must not be used for other purposes.
2814280405Srpaulo
2815280405Srpaulo
2816280405Srpaulo<p>
2817280405SrpauloWhen you create a new Lua state,
2818280405Srpauloits registry comes with some predefined values.
2819280405SrpauloThese predefined values are indexed with integer keys
2820280405Srpaulodefined as constants in <code>lua.h</code>.
2821280405SrpauloThe following constants are defined:
2822280405Srpaulo
2823280405Srpaulo<ul>
2824280405Srpaulo<li><b><a name="pdf-LUA_RIDX_MAINTHREAD"><code>LUA_RIDX_MAINTHREAD</code></a>: </b> At this index the registry has
2825280405Srpaulothe main thread of the state.
2826280405Srpaulo(The main thread is the one created together with the state.)
2827280405Srpaulo</li>
2828280405Srpaulo
2829280405Srpaulo<li><b><a name="pdf-LUA_RIDX_GLOBALS"><code>LUA_RIDX_GLOBALS</code></a>: </b> At this index the registry has
2830280405Srpaulothe global environment.
2831280405Srpaulo</li>
2832280405Srpaulo</ul>
2833280405Srpaulo
2834280405Srpaulo
2835280405Srpaulo
2836280405Srpaulo
2837280405Srpaulo<h2>4.6 &ndash; <a name="4.6">Error Handling in C</a></h2>
2838280405Srpaulo
2839280405Srpaulo<p>
2840280405SrpauloInternally, Lua uses the C <code>longjmp</code> facility to handle errors.
2841280405Srpaulo(Lua will use exceptions if you compile it as C++;
2842280405Srpaulosearch for <code>LUAI_THROW</code> in the source code for details.)
2843280405SrpauloWhen Lua faces any error
2844326344Simp(such as a memory allocation error or a type error)
2845280405Srpauloit <em>raises</em> an error;
2846280405Srpaulothat is, it does a long jump.
2847280405SrpauloA <em>protected environment</em> uses <code>setjmp</code>
2848280405Srpauloto set a recovery point;
2849280405Srpauloany error jumps to the most recent active recovery point.
2850280405Srpaulo
2851280405Srpaulo
2852280405Srpaulo<p>
2853326344SimpInside a C&nbsp;function you can raise an error by calling <a href="#lua_error"><code>lua_error</code></a>.
2854326344Simp
2855326344Simp
2856326344Simp<p>
2857326344SimpMost functions in the API can raise an error,
2858326344Simpfor instance due to a memory allocation error.
2859326344SimpThe documentation for each function indicates whether
2860326344Simpit can raise errors.
2861326344Simp
2862326344Simp
2863326344Simp<p>
2864280405SrpauloIf an error happens outside any protected environment,
2865280405SrpauloLua calls a <em>panic function</em> (see <a href="#lua_atpanic"><code>lua_atpanic</code></a>)
2866280405Srpauloand then calls <code>abort</code>,
2867280405Srpaulothus exiting the host application.
2868280405SrpauloYour panic function can avoid this exit by
2869280405Srpaulonever returning
2870280405Srpaulo(e.g., doing a long jump to your own recovery point outside Lua).
2871280405Srpaulo
2872280405Srpaulo
2873280405Srpaulo<p>
2874326344SimpThe panic function,
2875326344Simpas its name implies,
2876326344Simpis a mechanism of last resort.
2877326344SimpPrograms should avoid it.
2878326344SimpAs a general rule,
2879326344Simpwhen a C&nbsp;function is called by Lua with a Lua state,
2880326344Simpit can do whatever it wants on that Lua state,
2881326344Simpas it should be already protected.
2882326344SimpHowever,
2883326344Simpwhen C code operates on other Lua states
2884326344Simp(e.g., a Lua parameter to the function,
2885326344Simpa Lua state stored in the registry, or
2886326344Simpthe result of <a href="#lua_newthread"><code>lua_newthread</code></a>),
2887326344Simpit should use them only in API calls that cannot raise errors.
2888326344Simp
2889326344Simp
2890326344Simp<p>
2891280405SrpauloThe panic function runs as if it were a message handler (see <a href="#2.3">&sect;2.3</a>);
2892326344Simpin particular, the error object is at the top of the stack.
2893280405SrpauloHowever, there is no guarantee about stack space.
2894280405SrpauloTo push anything on the stack,
2895280405Srpaulothe panic function must first check the available space (see <a href="#4.2">&sect;4.2</a>).
2896280405Srpaulo
2897280405Srpaulo
2898280405Srpaulo
2899280405Srpaulo
2900280405Srpaulo
2901280405Srpaulo<h2>4.7 &ndash; <a name="4.7">Handling Yields in C</a></h2>
2902280405Srpaulo
2903280405Srpaulo<p>
2904280405SrpauloInternally, Lua uses the C <code>longjmp</code> facility to yield a coroutine.
2905326344SimpTherefore, if a C&nbsp;function <code>foo</code> calls an API function
2906280405Srpauloand this API function yields
2907280405Srpaulo(directly or indirectly by calling another function that yields),
2908280405SrpauloLua cannot return to <code>foo</code> any more,
2909280405Srpaulobecause the <code>longjmp</code> removes its frame from the C stack.
2910280405Srpaulo
2911280405Srpaulo
2912280405Srpaulo<p>
2913280405SrpauloTo avoid this kind of problem,
2914280405SrpauloLua raises an error whenever it tries to yield across an API call,
2915280405Srpauloexcept for three functions:
2916280405Srpaulo<a href="#lua_yieldk"><code>lua_yieldk</code></a>, <a href="#lua_callk"><code>lua_callk</code></a>, and <a href="#lua_pcallk"><code>lua_pcallk</code></a>.
2917280405SrpauloAll those functions receive a <em>continuation function</em>
2918280405Srpaulo(as a parameter named <code>k</code>) to continue execution after a yield.
2919280405Srpaulo
2920280405Srpaulo
2921280405Srpaulo<p>
2922280405SrpauloWe need to set some terminology to explain continuations.
2923326344SimpWe have a C&nbsp;function called from Lua which we will call
2924280405Srpaulothe <em>original function</em>.
2925280405SrpauloThis original function then calls one of those three functions in the C API,
2926280405Srpaulowhich we will call the <em>callee function</em>,
2927280405Srpaulothat then yields the current thread.
2928280405Srpaulo(This can happen when the callee function is <a href="#lua_yieldk"><code>lua_yieldk</code></a>,
2929280405Srpauloor when the callee function is either <a href="#lua_callk"><code>lua_callk</code></a> or <a href="#lua_pcallk"><code>lua_pcallk</code></a>
2930280405Srpauloand the function called by them yields.)
2931280405Srpaulo
2932280405Srpaulo
2933280405Srpaulo<p>
2934280405SrpauloSuppose the running thread yields while executing the callee function.
2935280405SrpauloAfter the thread resumes,
2936280405Srpauloit eventually will finish running the callee function.
2937280405SrpauloHowever,
2938280405Srpaulothe callee function cannot return to the original function,
2939280405Srpaulobecause its frame in the C stack was destroyed by the yield.
2940280405SrpauloInstead, Lua calls a <em>continuation function</em>,
2941280405Srpaulowhich was given as an argument to the callee function.
2942280405SrpauloAs the name implies,
2943280405Srpaulothe continuation function should continue the task
2944280405Srpauloof the original function.
2945280405Srpaulo
2946280405Srpaulo
2947280405Srpaulo<p>
2948280405SrpauloAs an illustration, consider the following function:
2949280405Srpaulo
2950280405Srpaulo<pre>
2951280405Srpaulo     int original_function (lua_State *L) {
2952280405Srpaulo       ...     /* code 1 */
2953280405Srpaulo       status = lua_pcall(L, n, m, h);  /* calls Lua */
2954280405Srpaulo       ...     /* code 2 */
2955280405Srpaulo     }
2956280405Srpaulo</pre><p>
2957280405SrpauloNow we want to allow
2958280405Srpaulothe Lua code being run by <a href="#lua_pcall"><code>lua_pcall</code></a> to yield.
2959280405SrpauloFirst, we can rewrite our function like here:
2960280405Srpaulo
2961280405Srpaulo<pre>
2962280405Srpaulo     int k (lua_State *L, int status, lua_KContext ctx) {
2963280405Srpaulo       ...  /* code 2 */
2964280405Srpaulo     }
2965280405Srpaulo     
2966280405Srpaulo     int original_function (lua_State *L) {
2967280405Srpaulo       ...     /* code 1 */
2968280405Srpaulo       return k(L, lua_pcall(L, n, m, h), ctx);
2969280405Srpaulo     }
2970280405Srpaulo</pre><p>
2971280405SrpauloIn the above code,
2972280405Srpaulothe new function <code>k</code> is a
2973280405Srpaulo<em>continuation function</em> (with type <a href="#lua_KFunction"><code>lua_KFunction</code></a>),
2974280405Srpaulowhich should do all the work that the original function
2975280405Srpaulowas doing after calling <a href="#lua_pcall"><code>lua_pcall</code></a>.
2976280405SrpauloNow, we must inform Lua that it must call <code>k</code> if the Lua code
2977280405Srpaulobeing executed by <a href="#lua_pcall"><code>lua_pcall</code></a> gets interrupted in some way
2978280405Srpaulo(errors or yielding),
2979280405Srpauloso we rewrite the code as here,
2980280405Srpauloreplacing <a href="#lua_pcall"><code>lua_pcall</code></a> by <a href="#lua_pcallk"><code>lua_pcallk</code></a>:
2981280405Srpaulo
2982280405Srpaulo<pre>
2983280405Srpaulo     int original_function (lua_State *L) {
2984280405Srpaulo       ...     /* code 1 */
2985280405Srpaulo       return k(L, lua_pcallk(L, n, m, h, ctx2, k), ctx1);
2986280405Srpaulo     }
2987280405Srpaulo</pre><p>
2988280405SrpauloNote the external, explicit call to the continuation:
2989280405SrpauloLua will call the continuation only if needed, that is,
2990280405Srpauloin case of errors or resuming after a yield.
2991280405SrpauloIf the called function returns normally without ever yielding,
2992280405Srpaulo<a href="#lua_pcallk"><code>lua_pcallk</code></a> (and <a href="#lua_callk"><code>lua_callk</code></a>) will also return normally.
2993280405Srpaulo(Of course, instead of calling the continuation in that case,
2994280405Srpauloyou can do the equivalent work directly inside the original function.)
2995280405Srpaulo
2996280405Srpaulo
2997280405Srpaulo<p>
2998280405SrpauloBesides the Lua state,
2999280405Srpaulothe continuation function has two other parameters:
3000280405Srpaulothe final status of the call plus the context value (<code>ctx</code>) that
3001280405Srpaulowas passed originally to <a href="#lua_pcallk"><code>lua_pcallk</code></a>.
3002280405Srpaulo(Lua does not use this context value;
3003280405Srpauloit only passes this value from the original function to the
3004280405Srpaulocontinuation function.)
3005280405SrpauloFor <a href="#lua_pcallk"><code>lua_pcallk</code></a>,
3006280405Srpaulothe status is the same value that would be returned by <a href="#lua_pcallk"><code>lua_pcallk</code></a>,
3007280405Srpauloexcept that it is <a href="#pdf-LUA_YIELD"><code>LUA_YIELD</code></a> when being executed after a yield
3008280405Srpaulo(instead of <a href="#pdf-LUA_OK"><code>LUA_OK</code></a>).
3009280405SrpauloFor <a href="#lua_yieldk"><code>lua_yieldk</code></a> and <a href="#lua_callk"><code>lua_callk</code></a>,
3010280405Srpaulothe status is always <a href="#pdf-LUA_YIELD"><code>LUA_YIELD</code></a> when Lua calls the continuation.
3011280405Srpaulo(For these two functions,
3012280405SrpauloLua will not call the continuation in case of errors,
3013280405Srpaulobecause they do not handle errors.)
3014280405SrpauloSimilarly, when using <a href="#lua_callk"><code>lua_callk</code></a>,
3015280405Srpauloyou should call the continuation function
3016280405Srpaulowith <a href="#pdf-LUA_OK"><code>LUA_OK</code></a> as the status.
3017280405Srpaulo(For <a href="#lua_yieldk"><code>lua_yieldk</code></a>, there is not much point in calling
3018280405Srpaulodirectly the continuation function,
3019280405Srpaulobecause <a href="#lua_yieldk"><code>lua_yieldk</code></a> usually does not return.)
3020280405Srpaulo
3021280405Srpaulo
3022280405Srpaulo<p>
3023280405SrpauloLua treats the continuation function as if it were the original function.
3024280405SrpauloThe continuation function receives the same Lua stack
3025280405Srpaulofrom the original function,
3026280405Srpauloin the same state it would be if the callee function had returned.
3027280405Srpaulo(For instance,
3028280405Srpauloafter a <a href="#lua_callk"><code>lua_callk</code></a> the function and its arguments are
3029280405Srpauloremoved from the stack and replaced by the results from the call.)
3030280405SrpauloIt also has the same upvalues.
3031280405SrpauloWhatever it returns is handled by Lua as if it were the return
3032280405Srpauloof the original function.
3033280405Srpaulo
3034280405Srpaulo
3035280405Srpaulo
3036280405Srpaulo
3037280405Srpaulo
3038280405Srpaulo<h2>4.8 &ndash; <a name="4.8">Functions and Types</a></h2>
3039280405Srpaulo
3040280405Srpaulo<p>
3041280405SrpauloHere we list all functions and types from the C&nbsp;API in
3042280405Srpauloalphabetical order.
3043280405SrpauloEach function has an indicator like this:
3044280405Srpaulo<span class="apii">[-o, +p, <em>x</em>]</span>
3045280405Srpaulo
3046280405Srpaulo
3047280405Srpaulo<p>
3048280405SrpauloThe first field, <code>o</code>,
3049280405Srpaulois how many elements the function pops from the stack.
3050280405SrpauloThe second field, <code>p</code>,
3051280405Srpaulois how many elements the function pushes onto the stack.
3052280405Srpaulo(Any function always pushes its results after popping its arguments.)
3053280405SrpauloA field in the form <code>x|y</code> means the function can push (or pop)
3054280405Srpaulo<code>x</code> or <code>y</code> elements,
3055280405Srpaulodepending on the situation;
3056280405Srpauloan interrogation mark '<code>?</code>' means that
3057280405Srpaulowe cannot know how many elements the function pops/pushes
3058280405Srpauloby looking only at its arguments
3059280405Srpaulo(e.g., they may depend on what is on the stack).
3060280405SrpauloThe third field, <code>x</code>,
3061280405Srpaulotells whether the function may raise errors:
3062280405Srpaulo'<code>-</code>' means the function never raises any error;
3063326344Simp'<code>m</code>' means the function may raise out-of-memory errors
3064326344Simpand errors running a <code>__gc</code> metamethod;
3065326344Simp'<code>e</code>' means the function may raise any errors
3066326344Simp(it can run arbitrary Lua code,
3067326344Simpeither directly or through metamethods);
3068280405Srpaulo'<code>v</code>' means the function may raise an error on purpose.
3069280405Srpaulo
3070280405Srpaulo
3071280405Srpaulo
3072280405Srpaulo<hr><h3><a name="lua_absindex"><code>lua_absindex</code></a></h3><p>
3073280405Srpaulo<span class="apii">[-0, +0, &ndash;]</span>
3074280405Srpaulo<pre>int lua_absindex (lua_State *L, int idx);</pre>
3075280405Srpaulo
3076280405Srpaulo<p>
3077326344SimpConverts the acceptable index <code>idx</code>
3078326344Simpinto an equivalent absolute index
3079280405Srpaulo(that is, one that does not depend on the stack top).
3080280405Srpaulo
3081280405Srpaulo
3082280405Srpaulo
3083280405Srpaulo
3084280405Srpaulo
3085280405Srpaulo<hr><h3><a name="lua_Alloc"><code>lua_Alloc</code></a></h3>
3086280405Srpaulo<pre>typedef void * (*lua_Alloc) (void *ud,
3087280405Srpaulo                             void *ptr,
3088280405Srpaulo                             size_t osize,
3089280405Srpaulo                             size_t nsize);</pre>
3090280405Srpaulo
3091280405Srpaulo<p>
3092280405SrpauloThe type of the memory-allocation function used by Lua states.
3093280405SrpauloThe allocator function must provide a
3094280405Srpaulofunctionality similar to <code>realloc</code>,
3095280405Srpaulobut not exactly the same.
3096280405SrpauloIts arguments are
3097280405Srpaulo<code>ud</code>, an opaque pointer passed to <a href="#lua_newstate"><code>lua_newstate</code></a>;
3098280405Srpaulo<code>ptr</code>, a pointer to the block being allocated/reallocated/freed;
3099280405Srpaulo<code>osize</code>, the original size of the block or some code about what
3100280405Srpaulois being allocated;
3101280405Srpauloand <code>nsize</code>, the new size of the block.
3102280405Srpaulo
3103280405Srpaulo
3104280405Srpaulo<p>
3105280405SrpauloWhen <code>ptr</code> is not <code>NULL</code>,
3106280405Srpaulo<code>osize</code> is the size of the block pointed by <code>ptr</code>,
3107280405Srpaulothat is, the size given when it was allocated or reallocated.
3108280405Srpaulo
3109280405Srpaulo
3110280405Srpaulo<p>
3111280405SrpauloWhen <code>ptr</code> is <code>NULL</code>,
3112280405Srpaulo<code>osize</code> encodes the kind of object that Lua is allocating.
3113280405Srpaulo<code>osize</code> is any of
3114280405Srpaulo<a href="#pdf-LUA_TSTRING"><code>LUA_TSTRING</code></a>, <a href="#pdf-LUA_TTABLE"><code>LUA_TTABLE</code></a>, <a href="#pdf-LUA_TFUNCTION"><code>LUA_TFUNCTION</code></a>,
3115280405Srpaulo<a href="#pdf-LUA_TUSERDATA"><code>LUA_TUSERDATA</code></a>, or <a href="#pdf-LUA_TTHREAD"><code>LUA_TTHREAD</code></a> when (and only when)
3116280405SrpauloLua is creating a new object of that type.
3117280405SrpauloWhen <code>osize</code> is some other value,
3118280405SrpauloLua is allocating memory for something else.
3119280405Srpaulo
3120280405Srpaulo
3121280405Srpaulo<p>
3122280405SrpauloLua assumes the following behavior from the allocator function:
3123280405Srpaulo
3124280405Srpaulo
3125280405Srpaulo<p>
3126280405SrpauloWhen <code>nsize</code> is zero,
3127280405Srpaulothe allocator must behave like <code>free</code>
3128280405Srpauloand return <code>NULL</code>.
3129280405Srpaulo
3130280405Srpaulo
3131280405Srpaulo<p>
3132280405SrpauloWhen <code>nsize</code> is not zero,
3133280405Srpaulothe allocator must behave like <code>realloc</code>.
3134280405SrpauloThe allocator returns <code>NULL</code>
3135280405Srpauloif and only if it cannot fulfill the request.
3136280405SrpauloLua assumes that the allocator never fails when
3137280405Srpaulo<code>osize &gt;= nsize</code>.
3138280405Srpaulo
3139280405Srpaulo
3140280405Srpaulo<p>
3141280405SrpauloHere is a simple implementation for the allocator function.
3142280405SrpauloIt is used in the auxiliary library by <a href="#luaL_newstate"><code>luaL_newstate</code></a>.
3143280405Srpaulo
3144280405Srpaulo<pre>
3145280405Srpaulo     static void *l_alloc (void *ud, void *ptr, size_t osize,
3146280405Srpaulo                                                size_t nsize) {
3147280405Srpaulo       (void)ud;  (void)osize;  /* not used */
3148280405Srpaulo       if (nsize == 0) {
3149280405Srpaulo         free(ptr);
3150280405Srpaulo         return NULL;
3151280405Srpaulo       }
3152280405Srpaulo       else
3153280405Srpaulo         return realloc(ptr, nsize);
3154280405Srpaulo     }
3155280405Srpaulo</pre><p>
3156280405SrpauloNote that Standard&nbsp;C ensures
3157280405Srpaulothat <code>free(NULL)</code> has no effect and that
3158280405Srpaulo<code>realloc(NULL,size)</code> is equivalent to <code>malloc(size)</code>.
3159280405SrpauloThis code assumes that <code>realloc</code> does not fail when shrinking a block.
3160280405Srpaulo(Although Standard&nbsp;C does not ensure this behavior,
3161280405Srpauloit seems to be a safe assumption.)
3162280405Srpaulo
3163280405Srpaulo
3164280405Srpaulo
3165280405Srpaulo
3166280405Srpaulo
3167280405Srpaulo<hr><h3><a name="lua_arith"><code>lua_arith</code></a></h3><p>
3168280405Srpaulo<span class="apii">[-(2|1), +1, <em>e</em>]</span>
3169280405Srpaulo<pre>void lua_arith (lua_State *L, int op);</pre>
3170280405Srpaulo
3171280405Srpaulo<p>
3172280405SrpauloPerforms an arithmetic or bitwise operation over the two values
3173280405Srpaulo(or one, in the case of negations)
3174280405Srpauloat the top of the stack,
3175280405Srpaulowith the value at the top being the second operand,
3176280405Srpaulopops these values, and pushes the result of the operation.
3177280405SrpauloThe function follows the semantics of the corresponding Lua operator
3178280405Srpaulo(that is, it may call metamethods).
3179280405Srpaulo
3180280405Srpaulo
3181280405Srpaulo<p>
3182280405SrpauloThe value of <code>op</code> must be one of the following constants:
3183280405Srpaulo
3184280405Srpaulo<ul>
3185280405Srpaulo
3186280405Srpaulo<li><b><a name="pdf-LUA_OPADD"><code>LUA_OPADD</code></a>: </b> performs addition (<code>+</code>)</li>
3187280405Srpaulo<li><b><a name="pdf-LUA_OPSUB"><code>LUA_OPSUB</code></a>: </b> performs subtraction (<code>-</code>)</li>
3188280405Srpaulo<li><b><a name="pdf-LUA_OPMUL"><code>LUA_OPMUL</code></a>: </b> performs multiplication (<code>*</code>)</li>
3189280405Srpaulo<li><b><a name="pdf-LUA_OPDIV"><code>LUA_OPDIV</code></a>: </b> performs float division (<code>/</code>)</li>
3190280405Srpaulo<li><b><a name="pdf-LUA_OPIDIV"><code>LUA_OPIDIV</code></a>: </b> performs floor division (<code>//</code>)</li>
3191280405Srpaulo<li><b><a name="pdf-LUA_OPMOD"><code>LUA_OPMOD</code></a>: </b> performs modulo (<code>%</code>)</li>
3192280405Srpaulo<li><b><a name="pdf-LUA_OPPOW"><code>LUA_OPPOW</code></a>: </b> performs exponentiation (<code>^</code>)</li>
3193280405Srpaulo<li><b><a name="pdf-LUA_OPUNM"><code>LUA_OPUNM</code></a>: </b> performs mathematical negation (unary <code>-</code>)</li>
3194326344Simp<li><b><a name="pdf-LUA_OPBNOT"><code>LUA_OPBNOT</code></a>: </b> performs bitwise NOT (<code>~</code>)</li>
3195326344Simp<li><b><a name="pdf-LUA_OPBAND"><code>LUA_OPBAND</code></a>: </b> performs bitwise AND (<code>&amp;</code>)</li>
3196326344Simp<li><b><a name="pdf-LUA_OPBOR"><code>LUA_OPBOR</code></a>: </b> performs bitwise OR (<code>|</code>)</li>
3197326344Simp<li><b><a name="pdf-LUA_OPBXOR"><code>LUA_OPBXOR</code></a>: </b> performs bitwise exclusive OR (<code>~</code>)</li>
3198280405Srpaulo<li><b><a name="pdf-LUA_OPSHL"><code>LUA_OPSHL</code></a>: </b> performs left shift (<code>&lt;&lt;</code>)</li>
3199280405Srpaulo<li><b><a name="pdf-LUA_OPSHR"><code>LUA_OPSHR</code></a>: </b> performs right shift (<code>&gt;&gt;</code>)</li>
3200280405Srpaulo
3201280405Srpaulo</ul>
3202280405Srpaulo
3203280405Srpaulo
3204280405Srpaulo
3205280405Srpaulo
3206280405Srpaulo<hr><h3><a name="lua_atpanic"><code>lua_atpanic</code></a></h3><p>
3207280405Srpaulo<span class="apii">[-0, +0, &ndash;]</span>
3208280405Srpaulo<pre>lua_CFunction lua_atpanic (lua_State *L, lua_CFunction panicf);</pre>
3209280405Srpaulo
3210280405Srpaulo<p>
3211280405SrpauloSets a new panic function and returns the old one (see <a href="#4.6">&sect;4.6</a>).
3212280405Srpaulo
3213280405Srpaulo
3214280405Srpaulo
3215280405Srpaulo
3216280405Srpaulo
3217280405Srpaulo<hr><h3><a name="lua_call"><code>lua_call</code></a></h3><p>
3218280405Srpaulo<span class="apii">[-(nargs+1), +nresults, <em>e</em>]</span>
3219280405Srpaulo<pre>void lua_call (lua_State *L, int nargs, int nresults);</pre>
3220280405Srpaulo
3221280405Srpaulo<p>
3222280405SrpauloCalls a function.
3223280405Srpaulo
3224280405Srpaulo
3225280405Srpaulo<p>
3226280405SrpauloTo call a function you must use the following protocol:
3227280405Srpaulofirst, the function to be called is pushed onto the stack;
3228280405Srpaulothen, the arguments to the function are pushed
3229280405Srpauloin direct order;
3230280405Srpaulothat is, the first argument is pushed first.
3231280405SrpauloFinally you call <a href="#lua_call"><code>lua_call</code></a>;
3232280405Srpaulo<code>nargs</code> is the number of arguments that you pushed onto the stack.
3233280405SrpauloAll arguments and the function value are popped from the stack
3234280405Srpaulowhen the function is called.
3235280405SrpauloThe function results are pushed onto the stack when the function returns.
3236280405SrpauloThe number of results is adjusted to <code>nresults</code>,
3237280405Srpaulounless <code>nresults</code> is <a name="pdf-LUA_MULTRET"><code>LUA_MULTRET</code></a>.
3238326344SimpIn this case, all results from the function are pushed;
3239326344SimpLua takes care that the returned values fit into the stack space,
3240326344Simpbut it does not ensure any extra space in the stack.
3241280405SrpauloThe function results are pushed onto the stack in direct order
3242280405Srpaulo(the first result is pushed first),
3243280405Srpauloso that after the call the last result is on the top of the stack.
3244280405Srpaulo
3245280405Srpaulo
3246280405Srpaulo<p>
3247280405SrpauloAny error inside the called function is propagated upwards
3248280405Srpaulo(with a <code>longjmp</code>).
3249280405Srpaulo
3250280405Srpaulo
3251280405Srpaulo<p>
3252280405SrpauloThe following example shows how the host program can do the
3253280405Srpauloequivalent to this Lua code:
3254280405Srpaulo
3255280405Srpaulo<pre>
3256280405Srpaulo     a = f("how", t.x, 14)
3257280405Srpaulo</pre><p>
3258280405SrpauloHere it is in&nbsp;C:
3259280405Srpaulo
3260280405Srpaulo<pre>
3261280405Srpaulo     lua_getglobal(L, "f");                  /* function to be called */
3262280405Srpaulo     lua_pushliteral(L, "how");                       /* 1st argument */
3263280405Srpaulo     lua_getglobal(L, "t");                    /* table to be indexed */
3264280405Srpaulo     lua_getfield(L, -1, "x");        /* push result of t.x (2nd arg) */
3265280405Srpaulo     lua_remove(L, -2);                  /* remove 't' from the stack */
3266280405Srpaulo     lua_pushinteger(L, 14);                          /* 3rd argument */
3267280405Srpaulo     lua_call(L, 3, 1);     /* call 'f' with 3 arguments and 1 result */
3268280405Srpaulo     lua_setglobal(L, "a");                         /* set global 'a' */
3269280405Srpaulo</pre><p>
3270280405SrpauloNote that the code above is <em>balanced</em>:
3271280405Srpauloat its end, the stack is back to its original configuration.
3272280405SrpauloThis is considered good programming practice.
3273280405Srpaulo
3274280405Srpaulo
3275280405Srpaulo
3276280405Srpaulo
3277280405Srpaulo
3278280405Srpaulo<hr><h3><a name="lua_callk"><code>lua_callk</code></a></h3><p>
3279280405Srpaulo<span class="apii">[-(nargs + 1), +nresults, <em>e</em>]</span>
3280280405Srpaulo<pre>void lua_callk (lua_State *L,
3281280405Srpaulo                int nargs,
3282280405Srpaulo                int nresults,
3283280405Srpaulo                lua_KContext ctx,
3284280405Srpaulo                lua_KFunction k);</pre>
3285280405Srpaulo
3286280405Srpaulo<p>
3287280405SrpauloThis function behaves exactly like <a href="#lua_call"><code>lua_call</code></a>,
3288280405Srpaulobut allows the called function to yield (see <a href="#4.7">&sect;4.7</a>).
3289280405Srpaulo
3290280405Srpaulo
3291280405Srpaulo
3292280405Srpaulo
3293280405Srpaulo
3294280405Srpaulo<hr><h3><a name="lua_CFunction"><code>lua_CFunction</code></a></h3>
3295280405Srpaulo<pre>typedef int (*lua_CFunction) (lua_State *L);</pre>
3296280405Srpaulo
3297280405Srpaulo<p>
3298280405SrpauloType for C&nbsp;functions.
3299280405Srpaulo
3300280405Srpaulo
3301280405Srpaulo<p>
3302280405SrpauloIn order to communicate properly with Lua,
3303280405Srpauloa C&nbsp;function must use the following protocol,
3304280405Srpaulowhich defines the way parameters and results are passed:
3305280405Srpauloa C&nbsp;function receives its arguments from Lua in its stack
3306280405Srpauloin direct order (the first argument is pushed first).
3307280405SrpauloSo, when the function starts,
3308280405Srpaulo<code>lua_gettop(L)</code> returns the number of arguments received by the function.
3309280405SrpauloThe first argument (if any) is at index 1
3310280405Srpauloand its last argument is at index <code>lua_gettop(L)</code>.
3311280405SrpauloTo return values to Lua, a C&nbsp;function just pushes them onto the stack,
3312280405Srpauloin direct order (the first result is pushed first),
3313280405Srpauloand returns the number of results.
3314280405SrpauloAny other value in the stack below the results will be properly
3315280405Srpaulodiscarded by Lua.
3316280405SrpauloLike a Lua function, a C&nbsp;function called by Lua can also return
3317280405Srpaulomany results.
3318280405Srpaulo
3319280405Srpaulo
3320280405Srpaulo<p>
3321280405SrpauloAs an example, the following function receives a variable number
3322326344Simpof numeric arguments and returns their average and their sum:
3323280405Srpaulo
3324280405Srpaulo<pre>
3325280405Srpaulo     static int foo (lua_State *L) {
3326280405Srpaulo       int n = lua_gettop(L);    /* number of arguments */
3327280405Srpaulo       lua_Number sum = 0.0;
3328280405Srpaulo       int i;
3329280405Srpaulo       for (i = 1; i &lt;= n; i++) {
3330280405Srpaulo         if (!lua_isnumber(L, i)) {
3331280405Srpaulo           lua_pushliteral(L, "incorrect argument");
3332280405Srpaulo           lua_error(L);
3333280405Srpaulo         }
3334280405Srpaulo         sum += lua_tonumber(L, i);
3335280405Srpaulo       }
3336280405Srpaulo       lua_pushnumber(L, sum/n);        /* first result */
3337280405Srpaulo       lua_pushnumber(L, sum);         /* second result */
3338280405Srpaulo       return 2;                   /* number of results */
3339280405Srpaulo     }
3340280405Srpaulo</pre>
3341280405Srpaulo
3342280405Srpaulo
3343280405Srpaulo
3344280405Srpaulo
3345280405Srpaulo<hr><h3><a name="lua_checkstack"><code>lua_checkstack</code></a></h3><p>
3346280405Srpaulo<span class="apii">[-0, +0, &ndash;]</span>
3347280405Srpaulo<pre>int lua_checkstack (lua_State *L, int n);</pre>
3348280405Srpaulo
3349280405Srpaulo<p>
3350326344SimpEnsures that the stack has space for at least <code>n</code> extra slots
3351326344Simp(that is, that you can safely push up to <code>n</code> values into it).
3352280405SrpauloIt returns false if it cannot fulfill the request,
3353280405Srpauloeither because it would cause the stack
3354280405Srpauloto be larger than a fixed maximum size
3355280405Srpaulo(typically at least several thousand elements) or
3356280405Srpaulobecause it cannot allocate memory for the extra space.
3357280405SrpauloThis function never shrinks the stack;
3358326344Simpif the stack already has space for the extra slots,
3359280405Srpauloit is left unchanged.
3360280405Srpaulo
3361280405Srpaulo
3362280405Srpaulo
3363280405Srpaulo
3364280405Srpaulo
3365280405Srpaulo<hr><h3><a name="lua_close"><code>lua_close</code></a></h3><p>
3366280405Srpaulo<span class="apii">[-0, +0, &ndash;]</span>
3367280405Srpaulo<pre>void lua_close (lua_State *L);</pre>
3368280405Srpaulo
3369280405Srpaulo<p>
3370280405SrpauloDestroys all objects in the given Lua state
3371280405Srpaulo(calling the corresponding garbage-collection metamethods, if any)
3372280405Srpauloand frees all dynamic memory used by this state.
3373280405SrpauloOn several platforms, you may not need to call this function,
3374280405Srpaulobecause all resources are naturally released when the host program ends.
3375280405SrpauloOn the other hand, long-running programs that create multiple states,
3376280405Srpaulosuch as daemons or web servers,
3377280405Srpaulowill probably need to close states as soon as they are not needed.
3378280405Srpaulo
3379280405Srpaulo
3380280405Srpaulo
3381280405Srpaulo
3382280405Srpaulo
3383280405Srpaulo<hr><h3><a name="lua_compare"><code>lua_compare</code></a></h3><p>
3384280405Srpaulo<span class="apii">[-0, +0, <em>e</em>]</span>
3385280405Srpaulo<pre>int lua_compare (lua_State *L, int index1, int index2, int op);</pre>
3386280405Srpaulo
3387280405Srpaulo<p>
3388280405SrpauloCompares two Lua values.
3389280405SrpauloReturns 1 if the value at index <code>index1</code> satisfies <code>op</code>
3390280405Srpaulowhen compared with the value at index <code>index2</code>,
3391280405Srpaulofollowing the semantics of the corresponding Lua operator
3392280405Srpaulo(that is, it may call metamethods).
3393280405SrpauloOtherwise returns&nbsp;0.
3394280405SrpauloAlso returns&nbsp;0 if any of the indices is not valid.
3395280405Srpaulo
3396280405Srpaulo
3397280405Srpaulo<p>
3398280405SrpauloThe value of <code>op</code> must be one of the following constants:
3399280405Srpaulo
3400280405Srpaulo<ul>
3401280405Srpaulo
3402280405Srpaulo<li><b><a name="pdf-LUA_OPEQ"><code>LUA_OPEQ</code></a>: </b> compares for equality (<code>==</code>)</li>
3403280405Srpaulo<li><b><a name="pdf-LUA_OPLT"><code>LUA_OPLT</code></a>: </b> compares for less than (<code>&lt;</code>)</li>
3404280405Srpaulo<li><b><a name="pdf-LUA_OPLE"><code>LUA_OPLE</code></a>: </b> compares for less or equal (<code>&lt;=</code>)</li>
3405280405Srpaulo
3406280405Srpaulo</ul>
3407280405Srpaulo
3408280405Srpaulo
3409280405Srpaulo
3410280405Srpaulo
3411280405Srpaulo<hr><h3><a name="lua_concat"><code>lua_concat</code></a></h3><p>
3412280405Srpaulo<span class="apii">[-n, +1, <em>e</em>]</span>
3413280405Srpaulo<pre>void lua_concat (lua_State *L, int n);</pre>
3414280405Srpaulo
3415280405Srpaulo<p>
3416280405SrpauloConcatenates the <code>n</code> values at the top of the stack,
3417280405Srpaulopops them, and leaves the result at the top.
3418280405SrpauloIf <code>n</code>&nbsp;is&nbsp;1, the result is the single value on the stack
3419280405Srpaulo(that is, the function does nothing);
3420280405Srpauloif <code>n</code> is 0, the result is the empty string.
3421280405SrpauloConcatenation is performed following the usual semantics of Lua
3422280405Srpaulo(see <a href="#3.4.6">&sect;3.4.6</a>).
3423280405Srpaulo
3424280405Srpaulo
3425280405Srpaulo
3426280405Srpaulo
3427280405Srpaulo
3428280405Srpaulo<hr><h3><a name="lua_copy"><code>lua_copy</code></a></h3><p>
3429280405Srpaulo<span class="apii">[-0, +0, &ndash;]</span>
3430280405Srpaulo<pre>void lua_copy (lua_State *L, int fromidx, int toidx);</pre>
3431280405Srpaulo
3432280405Srpaulo<p>
3433280405SrpauloCopies the element at index <code>fromidx</code>
3434280405Srpaulointo the valid index <code>toidx</code>,
3435280405Srpauloreplacing the value at that position.
3436280405SrpauloValues at other positions are not affected.
3437280405Srpaulo
3438280405Srpaulo
3439280405Srpaulo
3440280405Srpaulo
3441280405Srpaulo
3442280405Srpaulo<hr><h3><a name="lua_createtable"><code>lua_createtable</code></a></h3><p>
3443326344Simp<span class="apii">[-0, +1, <em>m</em>]</span>
3444280405Srpaulo<pre>void lua_createtable (lua_State *L, int narr, int nrec);</pre>
3445280405Srpaulo
3446280405Srpaulo<p>
3447280405SrpauloCreates a new empty table and pushes it onto the stack.
3448280405SrpauloParameter <code>narr</code> is a hint for how many elements the table
3449280405Srpaulowill have as a sequence;
3450280405Srpauloparameter <code>nrec</code> is a hint for how many other elements
3451280405Srpaulothe table will have.
3452280405SrpauloLua may use these hints to preallocate memory for the new table.
3453326344SimpThis preallocation is useful for performance when you know in advance
3454280405Srpaulohow many elements the table will have.
3455280405SrpauloOtherwise you can use the function <a href="#lua_newtable"><code>lua_newtable</code></a>.
3456280405Srpaulo
3457280405Srpaulo
3458280405Srpaulo
3459280405Srpaulo
3460280405Srpaulo
3461280405Srpaulo<hr><h3><a name="lua_dump"><code>lua_dump</code></a></h3><p>
3462326344Simp<span class="apii">[-0, +0, &ndash;]</span>
3463280405Srpaulo<pre>int lua_dump (lua_State *L,
3464280405Srpaulo                        lua_Writer writer,
3465280405Srpaulo                        void *data,
3466280405Srpaulo                        int strip);</pre>
3467280405Srpaulo
3468280405Srpaulo<p>
3469280405SrpauloDumps a function as a binary chunk.
3470280405SrpauloReceives a Lua function on the top of the stack
3471280405Srpauloand produces a binary chunk that,
3472280405Srpauloif loaded again,
3473280405Srpauloresults in a function equivalent to the one dumped.
3474280405SrpauloAs it produces parts of the chunk,
3475280405Srpaulo<a href="#lua_dump"><code>lua_dump</code></a> calls function <code>writer</code> (see <a href="#lua_Writer"><code>lua_Writer</code></a>)
3476280405Srpaulowith the given <code>data</code>
3477280405Srpauloto write them.
3478280405Srpaulo
3479280405Srpaulo
3480280405Srpaulo<p>
3481280405SrpauloIf <code>strip</code> is true,
3482326344Simpthe binary representation may not include all debug information
3483326344Simpabout the function,
3484326344Simpto save space.
3485280405Srpaulo
3486280405Srpaulo
3487280405Srpaulo<p>
3488280405SrpauloThe value returned is the error code returned by the last
3489280405Srpaulocall to the writer;
3490280405Srpaulo0&nbsp;means no errors.
3491280405Srpaulo
3492280405Srpaulo
3493280405Srpaulo<p>
3494280405SrpauloThis function does not pop the Lua function from the stack.
3495280405Srpaulo
3496280405Srpaulo
3497280405Srpaulo
3498280405Srpaulo
3499280405Srpaulo
3500280405Srpaulo<hr><h3><a name="lua_error"><code>lua_error</code></a></h3><p>
3501280405Srpaulo<span class="apii">[-1, +0, <em>v</em>]</span>
3502280405Srpaulo<pre>int lua_error (lua_State *L);</pre>
3503280405Srpaulo
3504280405Srpaulo<p>
3505280405SrpauloGenerates a Lua error,
3506280405Srpaulousing the value at the top of the stack as the error object.
3507280405SrpauloThis function does a long jump,
3508280405Srpauloand therefore never returns
3509280405Srpaulo(see <a href="#luaL_error"><code>luaL_error</code></a>).
3510280405Srpaulo
3511280405Srpaulo
3512280405Srpaulo
3513280405Srpaulo
3514280405Srpaulo
3515280405Srpaulo<hr><h3><a name="lua_gc"><code>lua_gc</code></a></h3><p>
3516326344Simp<span class="apii">[-0, +0, <em>m</em>]</span>
3517280405Srpaulo<pre>int lua_gc (lua_State *L, int what, int data);</pre>
3518280405Srpaulo
3519280405Srpaulo<p>
3520280405SrpauloControls the garbage collector.
3521280405Srpaulo
3522280405Srpaulo
3523280405Srpaulo<p>
3524280405SrpauloThis function performs several tasks,
3525280405Srpauloaccording to the value of the parameter <code>what</code>:
3526280405Srpaulo
3527280405Srpaulo<ul>
3528280405Srpaulo
3529280405Srpaulo<li><b><code>LUA_GCSTOP</code>: </b>
3530280405Srpaulostops the garbage collector.
3531280405Srpaulo</li>
3532280405Srpaulo
3533280405Srpaulo<li><b><code>LUA_GCRESTART</code>: </b>
3534280405Srpaulorestarts the garbage collector.
3535280405Srpaulo</li>
3536280405Srpaulo
3537280405Srpaulo<li><b><code>LUA_GCCOLLECT</code>: </b>
3538280405Srpauloperforms a full garbage-collection cycle.
3539280405Srpaulo</li>
3540280405Srpaulo
3541280405Srpaulo<li><b><code>LUA_GCCOUNT</code>: </b>
3542280405Srpauloreturns the current amount of memory (in Kbytes) in use by Lua.
3543280405Srpaulo</li>
3544280405Srpaulo
3545280405Srpaulo<li><b><code>LUA_GCCOUNTB</code>: </b>
3546280405Srpauloreturns the remainder of dividing the current amount of bytes of
3547280405Srpaulomemory in use by Lua by 1024.
3548280405Srpaulo</li>
3549280405Srpaulo
3550280405Srpaulo<li><b><code>LUA_GCSTEP</code>: </b>
3551280405Srpauloperforms an incremental step of garbage collection.
3552280405Srpaulo</li>
3553280405Srpaulo
3554280405Srpaulo<li><b><code>LUA_GCSETPAUSE</code>: </b>
3555280405Srpaulosets <code>data</code> as the new value
3556280405Srpaulofor the <em>pause</em> of the collector (see <a href="#2.5">&sect;2.5</a>)
3557280405Srpauloand returns the previous value of the pause.
3558280405Srpaulo</li>
3559280405Srpaulo
3560280405Srpaulo<li><b><code>LUA_GCSETSTEPMUL</code>: </b>
3561280405Srpaulosets <code>data</code> as the new value for the <em>step multiplier</em> of
3562280405Srpaulothe collector (see <a href="#2.5">&sect;2.5</a>)
3563280405Srpauloand returns the previous value of the step multiplier.
3564280405Srpaulo</li>
3565280405Srpaulo
3566280405Srpaulo<li><b><code>LUA_GCISRUNNING</code>: </b>
3567280405Srpauloreturns a boolean that tells whether the collector is running
3568280405Srpaulo(i.e., not stopped).
3569280405Srpaulo</li>
3570280405Srpaulo
3571280405Srpaulo</ul>
3572280405Srpaulo
3573280405Srpaulo<p>
3574280405SrpauloFor more details about these options,
3575280405Srpaulosee <a href="#pdf-collectgarbage"><code>collectgarbage</code></a>.
3576280405Srpaulo
3577280405Srpaulo
3578280405Srpaulo
3579280405Srpaulo
3580280405Srpaulo
3581280405Srpaulo<hr><h3><a name="lua_getallocf"><code>lua_getallocf</code></a></h3><p>
3582280405Srpaulo<span class="apii">[-0, +0, &ndash;]</span>
3583280405Srpaulo<pre>lua_Alloc lua_getallocf (lua_State *L, void **ud);</pre>
3584280405Srpaulo
3585280405Srpaulo<p>
3586280405SrpauloReturns the memory-allocation function of a given state.
3587280405SrpauloIf <code>ud</code> is not <code>NULL</code>, Lua stores in <code>*ud</code> the
3588280405Srpauloopaque pointer given when the memory-allocator function was set.
3589280405Srpaulo
3590280405Srpaulo
3591280405Srpaulo
3592280405Srpaulo
3593280405Srpaulo
3594280405Srpaulo<hr><h3><a name="lua_getfield"><code>lua_getfield</code></a></h3><p>
3595280405Srpaulo<span class="apii">[-0, +1, <em>e</em>]</span>
3596280405Srpaulo<pre>int lua_getfield (lua_State *L, int index, const char *k);</pre>
3597280405Srpaulo
3598280405Srpaulo<p>
3599280405SrpauloPushes onto the stack the value <code>t[k]</code>,
3600280405Srpaulowhere <code>t</code> is the value at the given index.
3601280405SrpauloAs in Lua, this function may trigger a metamethod
3602280405Srpaulofor the "index" event (see <a href="#2.4">&sect;2.4</a>).
3603280405Srpaulo
3604280405Srpaulo
3605280405Srpaulo<p>
3606280405SrpauloReturns the type of the pushed value.
3607280405Srpaulo
3608280405Srpaulo
3609280405Srpaulo
3610280405Srpaulo
3611280405Srpaulo
3612280405Srpaulo<hr><h3><a name="lua_getextraspace"><code>lua_getextraspace</code></a></h3><p>
3613280405Srpaulo<span class="apii">[-0, +0, &ndash;]</span>
3614280405Srpaulo<pre>void *lua_getextraspace (lua_State *L);</pre>
3615280405Srpaulo
3616280405Srpaulo<p>
3617280405SrpauloReturns a pointer to a raw memory area associated with the
3618280405Srpaulogiven Lua state.
3619280405SrpauloThe application can use this area for any purpose;
3620280405SrpauloLua does not use it for anything.
3621280405Srpaulo
3622280405Srpaulo
3623280405Srpaulo<p>
3624280405SrpauloEach new thread has this area initialized with a copy
3625280405Srpauloof the area of the main thread.
3626280405Srpaulo
3627280405Srpaulo
3628280405Srpaulo<p>
3629280405SrpauloBy default, this area has the size of a pointer to void,
3630280405Srpaulobut you can recompile Lua with a different size for this area.
3631280405Srpaulo(See <code>LUA_EXTRASPACE</code> in <code>luaconf.h</code>.)
3632280405Srpaulo
3633280405Srpaulo
3634280405Srpaulo
3635280405Srpaulo
3636280405Srpaulo
3637280405Srpaulo<hr><h3><a name="lua_getglobal"><code>lua_getglobal</code></a></h3><p>
3638280405Srpaulo<span class="apii">[-0, +1, <em>e</em>]</span>
3639280405Srpaulo<pre>int lua_getglobal (lua_State *L, const char *name);</pre>
3640280405Srpaulo
3641280405Srpaulo<p>
3642280405SrpauloPushes onto the stack the value of the global <code>name</code>.
3643280405SrpauloReturns the type of that value.
3644280405Srpaulo
3645280405Srpaulo
3646280405Srpaulo
3647280405Srpaulo
3648280405Srpaulo
3649280405Srpaulo<hr><h3><a name="lua_geti"><code>lua_geti</code></a></h3><p>
3650280405Srpaulo<span class="apii">[-0, +1, <em>e</em>]</span>
3651280405Srpaulo<pre>int lua_geti (lua_State *L, int index, lua_Integer i);</pre>
3652280405Srpaulo
3653280405Srpaulo<p>
3654280405SrpauloPushes onto the stack the value <code>t[i]</code>,
3655280405Srpaulowhere <code>t</code> is the value at the given index.
3656280405SrpauloAs in Lua, this function may trigger a metamethod
3657280405Srpaulofor the "index" event (see <a href="#2.4">&sect;2.4</a>).
3658280405Srpaulo
3659280405Srpaulo
3660280405Srpaulo<p>
3661280405SrpauloReturns the type of the pushed value.
3662280405Srpaulo
3663280405Srpaulo
3664280405Srpaulo
3665280405Srpaulo
3666280405Srpaulo
3667280405Srpaulo<hr><h3><a name="lua_getmetatable"><code>lua_getmetatable</code></a></h3><p>
3668280405Srpaulo<span class="apii">[-0, +(0|1), &ndash;]</span>
3669280405Srpaulo<pre>int lua_getmetatable (lua_State *L, int index);</pre>
3670280405Srpaulo
3671280405Srpaulo<p>
3672280405SrpauloIf the value at the given index has a metatable,
3673280405Srpaulothe function pushes that metatable onto the stack and returns&nbsp;1.
3674280405SrpauloOtherwise,
3675280405Srpaulothe function returns&nbsp;0 and pushes nothing on the stack.
3676280405Srpaulo
3677280405Srpaulo
3678280405Srpaulo
3679280405Srpaulo
3680280405Srpaulo
3681280405Srpaulo<hr><h3><a name="lua_gettable"><code>lua_gettable</code></a></h3><p>
3682280405Srpaulo<span class="apii">[-1, +1, <em>e</em>]</span>
3683280405Srpaulo<pre>int lua_gettable (lua_State *L, int index);</pre>
3684280405Srpaulo
3685280405Srpaulo<p>
3686280405SrpauloPushes onto the stack the value <code>t[k]</code>,
3687280405Srpaulowhere <code>t</code> is the value at the given index
3688280405Srpauloand <code>k</code> is the value at the top of the stack.
3689280405Srpaulo
3690280405Srpaulo
3691280405Srpaulo<p>
3692280405SrpauloThis function pops the key from the stack,
3693280405Srpaulopushing the resulting value in its place.
3694280405SrpauloAs in Lua, this function may trigger a metamethod
3695280405Srpaulofor the "index" event (see <a href="#2.4">&sect;2.4</a>).
3696280405Srpaulo
3697280405Srpaulo
3698280405Srpaulo<p>
3699280405SrpauloReturns the type of the pushed value.
3700280405Srpaulo
3701280405Srpaulo
3702280405Srpaulo
3703280405Srpaulo
3704280405Srpaulo
3705280405Srpaulo<hr><h3><a name="lua_gettop"><code>lua_gettop</code></a></h3><p>
3706280405Srpaulo<span class="apii">[-0, +0, &ndash;]</span>
3707280405Srpaulo<pre>int lua_gettop (lua_State *L);</pre>
3708280405Srpaulo
3709280405Srpaulo<p>
3710280405SrpauloReturns the index of the top element in the stack.
3711280405SrpauloBecause indices start at&nbsp;1,
3712280405Srpaulothis result is equal to the number of elements in the stack;
3713280405Srpauloin particular, 0&nbsp;means an empty stack.
3714280405Srpaulo
3715280405Srpaulo
3716280405Srpaulo
3717280405Srpaulo
3718280405Srpaulo
3719280405Srpaulo<hr><h3><a name="lua_getuservalue"><code>lua_getuservalue</code></a></h3><p>
3720280405Srpaulo<span class="apii">[-0, +1, &ndash;]</span>
3721280405Srpaulo<pre>int lua_getuservalue (lua_State *L, int index);</pre>
3722280405Srpaulo
3723280405Srpaulo<p>
3724326344SimpPushes onto the stack the Lua value associated with the full userdata
3725280405Srpauloat the given index.
3726280405Srpaulo
3727280405Srpaulo
3728280405Srpaulo<p>
3729280405SrpauloReturns the type of the pushed value.
3730280405Srpaulo
3731280405Srpaulo
3732280405Srpaulo
3733280405Srpaulo
3734280405Srpaulo
3735280405Srpaulo<hr><h3><a name="lua_insert"><code>lua_insert</code></a></h3><p>
3736280405Srpaulo<span class="apii">[-1, +1, &ndash;]</span>
3737280405Srpaulo<pre>void lua_insert (lua_State *L, int index);</pre>
3738280405Srpaulo
3739280405Srpaulo<p>
3740280405SrpauloMoves the top element into the given valid index,
3741280405Srpauloshifting up the elements above this index to open space.
3742280405SrpauloThis function cannot be called with a pseudo-index,
3743280405Srpaulobecause a pseudo-index is not an actual stack position.
3744280405Srpaulo
3745280405Srpaulo
3746280405Srpaulo
3747280405Srpaulo
3748280405Srpaulo
3749280405Srpaulo<hr><h3><a name="lua_Integer"><code>lua_Integer</code></a></h3>
3750280405Srpaulo<pre>typedef ... lua_Integer;</pre>
3751280405Srpaulo
3752280405Srpaulo<p>
3753280405SrpauloThe type of integers in Lua.
3754280405Srpaulo
3755280405Srpaulo
3756280405Srpaulo<p>
3757280405SrpauloBy default this type is <code>long long</code>,
3758280405Srpaulo(usually a 64-bit two-complement integer),
3759280405Srpaulobut that can be changed to <code>long</code> or <code>int</code>
3760280405Srpaulo(usually a 32-bit two-complement integer).
3761326344Simp(See <code>LUA_INT_TYPE</code> in <code>luaconf.h</code>.)
3762280405Srpaulo
3763280405Srpaulo
3764280405Srpaulo<p>
3765280405SrpauloLua also defines the constants
3766280405Srpaulo<a name="pdf-LUA_MININTEGER"><code>LUA_MININTEGER</code></a> and <a name="pdf-LUA_MAXINTEGER"><code>LUA_MAXINTEGER</code></a>,
3767280405Srpaulowith the minimum and the maximum values that fit in this type.
3768280405Srpaulo
3769280405Srpaulo
3770280405Srpaulo
3771280405Srpaulo
3772280405Srpaulo
3773280405Srpaulo<hr><h3><a name="lua_isboolean"><code>lua_isboolean</code></a></h3><p>
3774280405Srpaulo<span class="apii">[-0, +0, &ndash;]</span>
3775280405Srpaulo<pre>int lua_isboolean (lua_State *L, int index);</pre>
3776280405Srpaulo
3777280405Srpaulo<p>
3778280405SrpauloReturns 1 if the value at the given index is a boolean,
3779280405Srpauloand 0&nbsp;otherwise.
3780280405Srpaulo
3781280405Srpaulo
3782280405Srpaulo
3783280405Srpaulo
3784280405Srpaulo
3785280405Srpaulo<hr><h3><a name="lua_iscfunction"><code>lua_iscfunction</code></a></h3><p>
3786280405Srpaulo<span class="apii">[-0, +0, &ndash;]</span>
3787280405Srpaulo<pre>int lua_iscfunction (lua_State *L, int index);</pre>
3788280405Srpaulo
3789280405Srpaulo<p>
3790280405SrpauloReturns 1 if the value at the given index is a C&nbsp;function,
3791280405Srpauloand 0&nbsp;otherwise.
3792280405Srpaulo
3793280405Srpaulo
3794280405Srpaulo
3795280405Srpaulo
3796280405Srpaulo
3797280405Srpaulo<hr><h3><a name="lua_isfunction"><code>lua_isfunction</code></a></h3><p>
3798280405Srpaulo<span class="apii">[-0, +0, &ndash;]</span>
3799280405Srpaulo<pre>int lua_isfunction (lua_State *L, int index);</pre>
3800280405Srpaulo
3801280405Srpaulo<p>
3802280405SrpauloReturns 1 if the value at the given index is a function
3803280405Srpaulo(either C or Lua), and 0&nbsp;otherwise.
3804280405Srpaulo
3805280405Srpaulo
3806280405Srpaulo
3807280405Srpaulo
3808280405Srpaulo
3809280405Srpaulo<hr><h3><a name="lua_isinteger"><code>lua_isinteger</code></a></h3><p>
3810280405Srpaulo<span class="apii">[-0, +0, &ndash;]</span>
3811280405Srpaulo<pre>int lua_isinteger (lua_State *L, int index);</pre>
3812280405Srpaulo
3813280405Srpaulo<p>
3814280405SrpauloReturns 1 if the value at the given index is an integer
3815280405Srpaulo(that is, the value is a number and is represented as an integer),
3816280405Srpauloand 0&nbsp;otherwise.
3817280405Srpaulo
3818280405Srpaulo
3819280405Srpaulo
3820280405Srpaulo
3821280405Srpaulo
3822280405Srpaulo<hr><h3><a name="lua_islightuserdata"><code>lua_islightuserdata</code></a></h3><p>
3823280405Srpaulo<span class="apii">[-0, +0, &ndash;]</span>
3824280405Srpaulo<pre>int lua_islightuserdata (lua_State *L, int index);</pre>
3825280405Srpaulo
3826280405Srpaulo<p>
3827280405SrpauloReturns 1 if the value at the given index is a light userdata,
3828280405Srpauloand 0&nbsp;otherwise.
3829280405Srpaulo
3830280405Srpaulo
3831280405Srpaulo
3832280405Srpaulo
3833280405Srpaulo
3834280405Srpaulo<hr><h3><a name="lua_isnil"><code>lua_isnil</code></a></h3><p>
3835280405Srpaulo<span class="apii">[-0, +0, &ndash;]</span>
3836280405Srpaulo<pre>int lua_isnil (lua_State *L, int index);</pre>
3837280405Srpaulo
3838280405Srpaulo<p>
3839280405SrpauloReturns 1 if the value at the given index is <b>nil</b>,
3840280405Srpauloand 0&nbsp;otherwise.
3841280405Srpaulo
3842280405Srpaulo
3843280405Srpaulo
3844280405Srpaulo
3845280405Srpaulo
3846280405Srpaulo<hr><h3><a name="lua_isnone"><code>lua_isnone</code></a></h3><p>
3847280405Srpaulo<span class="apii">[-0, +0, &ndash;]</span>
3848280405Srpaulo<pre>int lua_isnone (lua_State *L, int index);</pre>
3849280405Srpaulo
3850280405Srpaulo<p>
3851280405SrpauloReturns 1 if the given index is not valid,
3852280405Srpauloand 0&nbsp;otherwise.
3853280405Srpaulo
3854280405Srpaulo
3855280405Srpaulo
3856280405Srpaulo
3857280405Srpaulo
3858280405Srpaulo<hr><h3><a name="lua_isnoneornil"><code>lua_isnoneornil</code></a></h3><p>
3859280405Srpaulo<span class="apii">[-0, +0, &ndash;]</span>
3860280405Srpaulo<pre>int lua_isnoneornil (lua_State *L, int index);</pre>
3861280405Srpaulo
3862280405Srpaulo<p>
3863280405SrpauloReturns 1 if the given index is not valid
3864280405Srpauloor if the value at this index is <b>nil</b>,
3865280405Srpauloand 0&nbsp;otherwise.
3866280405Srpaulo
3867280405Srpaulo
3868280405Srpaulo
3869280405Srpaulo
3870280405Srpaulo
3871280405Srpaulo<hr><h3><a name="lua_isnumber"><code>lua_isnumber</code></a></h3><p>
3872280405Srpaulo<span class="apii">[-0, +0, &ndash;]</span>
3873280405Srpaulo<pre>int lua_isnumber (lua_State *L, int index);</pre>
3874280405Srpaulo
3875280405Srpaulo<p>
3876280405SrpauloReturns 1 if the value at the given index is a number
3877280405Srpauloor a string convertible to a number,
3878280405Srpauloand 0&nbsp;otherwise.
3879280405Srpaulo
3880280405Srpaulo
3881280405Srpaulo
3882280405Srpaulo
3883280405Srpaulo
3884280405Srpaulo<hr><h3><a name="lua_isstring"><code>lua_isstring</code></a></h3><p>
3885280405Srpaulo<span class="apii">[-0, +0, &ndash;]</span>
3886280405Srpaulo<pre>int lua_isstring (lua_State *L, int index);</pre>
3887280405Srpaulo
3888280405Srpaulo<p>
3889280405SrpauloReturns 1 if the value at the given index is a string
3890280405Srpauloor a number (which is always convertible to a string),
3891280405Srpauloand 0&nbsp;otherwise.
3892280405Srpaulo
3893280405Srpaulo
3894280405Srpaulo
3895280405Srpaulo
3896280405Srpaulo
3897280405Srpaulo<hr><h3><a name="lua_istable"><code>lua_istable</code></a></h3><p>
3898280405Srpaulo<span class="apii">[-0, +0, &ndash;]</span>
3899280405Srpaulo<pre>int lua_istable (lua_State *L, int index);</pre>
3900280405Srpaulo
3901280405Srpaulo<p>
3902280405SrpauloReturns 1 if the value at the given index is a table,
3903280405Srpauloand 0&nbsp;otherwise.
3904280405Srpaulo
3905280405Srpaulo
3906280405Srpaulo
3907280405Srpaulo
3908280405Srpaulo
3909280405Srpaulo<hr><h3><a name="lua_isthread"><code>lua_isthread</code></a></h3><p>
3910280405Srpaulo<span class="apii">[-0, +0, &ndash;]</span>
3911280405Srpaulo<pre>int lua_isthread (lua_State *L, int index);</pre>
3912280405Srpaulo
3913280405Srpaulo<p>
3914280405SrpauloReturns 1 if the value at the given index is a thread,
3915280405Srpauloand 0&nbsp;otherwise.
3916280405Srpaulo
3917280405Srpaulo
3918280405Srpaulo
3919280405Srpaulo
3920280405Srpaulo
3921280405Srpaulo<hr><h3><a name="lua_isuserdata"><code>lua_isuserdata</code></a></h3><p>
3922280405Srpaulo<span class="apii">[-0, +0, &ndash;]</span>
3923280405Srpaulo<pre>int lua_isuserdata (lua_State *L, int index);</pre>
3924280405Srpaulo
3925280405Srpaulo<p>
3926280405SrpauloReturns 1 if the value at the given index is a userdata
3927280405Srpaulo(either full or light), and 0&nbsp;otherwise.
3928280405Srpaulo
3929280405Srpaulo
3930280405Srpaulo
3931280405Srpaulo
3932280405Srpaulo
3933280405Srpaulo<hr><h3><a name="lua_isyieldable"><code>lua_isyieldable</code></a></h3><p>
3934280405Srpaulo<span class="apii">[-0, +0, &ndash;]</span>
3935280405Srpaulo<pre>int lua_isyieldable (lua_State *L);</pre>
3936280405Srpaulo
3937280405Srpaulo<p>
3938280405SrpauloReturns 1 if the given coroutine can yield,
3939280405Srpauloand 0&nbsp;otherwise.
3940280405Srpaulo
3941280405Srpaulo
3942280405Srpaulo
3943280405Srpaulo
3944280405Srpaulo
3945280405Srpaulo<hr><h3><a name="lua_KContext"><code>lua_KContext</code></a></h3>
3946280405Srpaulo<pre>typedef ... lua_KContext;</pre>
3947280405Srpaulo
3948280405Srpaulo<p>
3949280405SrpauloThe type for continuation-function contexts.
3950326344SimpIt must be a numeric type.
3951280405SrpauloThis type is defined as <code>intptr_t</code>
3952280405Srpaulowhen <code>intptr_t</code> is available,
3953280405Srpauloso that it can store pointers too.
3954280405SrpauloOtherwise, it is defined as <code>ptrdiff_t</code>.
3955280405Srpaulo
3956280405Srpaulo
3957280405Srpaulo
3958280405Srpaulo
3959280405Srpaulo
3960280405Srpaulo<hr><h3><a name="lua_KFunction"><code>lua_KFunction</code></a></h3>
3961280405Srpaulo<pre>typedef int (*lua_KFunction) (lua_State *L, int status, lua_KContext ctx);</pre>
3962280405Srpaulo
3963280405Srpaulo<p>
3964280405SrpauloType for continuation functions (see <a href="#4.7">&sect;4.7</a>).
3965280405Srpaulo
3966280405Srpaulo
3967280405Srpaulo
3968280405Srpaulo
3969280405Srpaulo
3970280405Srpaulo<hr><h3><a name="lua_len"><code>lua_len</code></a></h3><p>
3971280405Srpaulo<span class="apii">[-0, +1, <em>e</em>]</span>
3972280405Srpaulo<pre>void lua_len (lua_State *L, int index);</pre>
3973280405Srpaulo
3974280405Srpaulo<p>
3975280405SrpauloReturns the length of the value at the given index.
3976280405SrpauloIt is equivalent to the '<code>#</code>' operator in Lua (see <a href="#3.4.7">&sect;3.4.7</a>) and
3977280405Srpaulomay trigger a metamethod for the "length" event (see <a href="#2.4">&sect;2.4</a>).
3978280405SrpauloThe result is pushed on the stack.
3979280405Srpaulo
3980280405Srpaulo
3981280405Srpaulo
3982280405Srpaulo
3983280405Srpaulo
3984280405Srpaulo<hr><h3><a name="lua_load"><code>lua_load</code></a></h3><p>
3985280405Srpaulo<span class="apii">[-0, +1, &ndash;]</span>
3986280405Srpaulo<pre>int lua_load (lua_State *L,
3987280405Srpaulo              lua_Reader reader,
3988280405Srpaulo              void *data,
3989280405Srpaulo              const char *chunkname,
3990280405Srpaulo              const char *mode);</pre>
3991280405Srpaulo
3992280405Srpaulo<p>
3993280405SrpauloLoads a Lua chunk without running it.
3994280405SrpauloIf there are no errors,
3995280405Srpaulo<code>lua_load</code> pushes the compiled chunk as a Lua
3996280405Srpaulofunction on top of the stack.
3997280405SrpauloOtherwise, it pushes an error message.
3998280405Srpaulo
3999280405Srpaulo
4000280405Srpaulo<p>
4001280405SrpauloThe return values of <code>lua_load</code> are:
4002280405Srpaulo
4003280405Srpaulo<ul>
4004280405Srpaulo
4005280405Srpaulo<li><b><a href="#pdf-LUA_OK"><code>LUA_OK</code></a>: </b> no errors;</li>
4006280405Srpaulo
4007280405Srpaulo<li><b><a name="pdf-LUA_ERRSYNTAX"><code>LUA_ERRSYNTAX</code></a>: </b>
4008280405Srpaulosyntax error during precompilation;</li>
4009280405Srpaulo
4010280405Srpaulo<li><b><a href="#pdf-LUA_ERRMEM"><code>LUA_ERRMEM</code></a>: </b>
4011326344Simpmemory allocation (out-of-memory) error;</li>
4012280405Srpaulo
4013280405Srpaulo<li><b><a href="#pdf-LUA_ERRGCMM"><code>LUA_ERRGCMM</code></a>: </b>
4014280405Srpauloerror while running a <code>__gc</code> metamethod.
4015280405Srpaulo(This error has no relation with the chunk being loaded.
4016280405SrpauloIt is generated by the garbage collector.)
4017280405Srpaulo</li>
4018280405Srpaulo
4019280405Srpaulo</ul>
4020280405Srpaulo
4021280405Srpaulo<p>
4022280405SrpauloThe <code>lua_load</code> function uses a user-supplied <code>reader</code> function
4023280405Srpauloto read the chunk (see <a href="#lua_Reader"><code>lua_Reader</code></a>).
4024280405SrpauloThe <code>data</code> argument is an opaque value passed to the reader function.
4025280405Srpaulo
4026280405Srpaulo
4027280405Srpaulo<p>
4028280405SrpauloThe <code>chunkname</code> argument gives a name to the chunk,
4029280405Srpaulowhich is used for error messages and in debug information (see <a href="#4.9">&sect;4.9</a>).
4030280405Srpaulo
4031280405Srpaulo
4032280405Srpaulo<p>
4033280405Srpaulo<code>lua_load</code> automatically detects whether the chunk is text or binary
4034280405Srpauloand loads it accordingly (see program <code>luac</code>).
4035280405SrpauloThe string <code>mode</code> works as in function <a href="#pdf-load"><code>load</code></a>,
4036280405Srpaulowith the addition that
4037280405Srpauloa <code>NULL</code> value is equivalent to the string "<code>bt</code>".
4038280405Srpaulo
4039280405Srpaulo
4040280405Srpaulo<p>
4041280405Srpaulo<code>lua_load</code> uses the stack internally,
4042280405Srpauloso the reader function must always leave the stack
4043280405Srpaulounmodified when returning.
4044280405Srpaulo
4045280405Srpaulo
4046280405Srpaulo<p>
4047280405SrpauloIf the resulting function has upvalues,
4048280405Srpauloits first upvalue is set to the value of the global environment
4049280405Srpaulostored at index <code>LUA_RIDX_GLOBALS</code> in the registry (see <a href="#4.5">&sect;4.5</a>).
4050280405SrpauloWhen loading main chunks,
4051280405Srpaulothis upvalue will be the <code>_ENV</code> variable (see <a href="#2.2">&sect;2.2</a>).
4052280405SrpauloOther upvalues are initialized with <b>nil</b>.
4053280405Srpaulo
4054280405Srpaulo
4055280405Srpaulo
4056280405Srpaulo
4057280405Srpaulo
4058280405Srpaulo<hr><h3><a name="lua_newstate"><code>lua_newstate</code></a></h3><p>
4059280405Srpaulo<span class="apii">[-0, +0, &ndash;]</span>
4060280405Srpaulo<pre>lua_State *lua_newstate (lua_Alloc f, void *ud);</pre>
4061280405Srpaulo
4062280405Srpaulo<p>
4063280405SrpauloCreates a new thread running in a new, independent state.
4064280405SrpauloReturns <code>NULL</code> if it cannot create the thread or the state
4065280405Srpaulo(due to lack of memory).
4066280405SrpauloThe argument <code>f</code> is the allocator function;
4067326344SimpLua does all memory allocation for this state
4068326344Simpthrough this function (see <a href="#lua_Alloc"><code>lua_Alloc</code></a>).
4069280405SrpauloThe second argument, <code>ud</code>, is an opaque pointer that Lua
4070280405Srpaulopasses to the allocator in every call.
4071280405Srpaulo
4072280405Srpaulo
4073280405Srpaulo
4074280405Srpaulo
4075280405Srpaulo
4076280405Srpaulo<hr><h3><a name="lua_newtable"><code>lua_newtable</code></a></h3><p>
4077326344Simp<span class="apii">[-0, +1, <em>m</em>]</span>
4078280405Srpaulo<pre>void lua_newtable (lua_State *L);</pre>
4079280405Srpaulo
4080280405Srpaulo<p>
4081280405SrpauloCreates a new empty table and pushes it onto the stack.
4082280405SrpauloIt is equivalent to <code>lua_createtable(L, 0, 0)</code>.
4083280405Srpaulo
4084280405Srpaulo
4085280405Srpaulo
4086280405Srpaulo
4087280405Srpaulo
4088280405Srpaulo<hr><h3><a name="lua_newthread"><code>lua_newthread</code></a></h3><p>
4089326344Simp<span class="apii">[-0, +1, <em>m</em>]</span>
4090280405Srpaulo<pre>lua_State *lua_newthread (lua_State *L);</pre>
4091280405Srpaulo
4092280405Srpaulo<p>
4093280405SrpauloCreates a new thread, pushes it on the stack,
4094280405Srpauloand returns a pointer to a <a href="#lua_State"><code>lua_State</code></a> that represents this new thread.
4095280405SrpauloThe new thread returned by this function shares with the original thread
4096280405Srpauloits global environment,
4097280405Srpaulobut has an independent execution stack.
4098280405Srpaulo
4099280405Srpaulo
4100280405Srpaulo<p>
4101280405SrpauloThere is no explicit function to close or to destroy a thread.
4102280405SrpauloThreads are subject to garbage collection,
4103280405Srpaulolike any Lua object.
4104280405Srpaulo
4105280405Srpaulo
4106280405Srpaulo
4107280405Srpaulo
4108280405Srpaulo
4109280405Srpaulo<hr><h3><a name="lua_newuserdata"><code>lua_newuserdata</code></a></h3><p>
4110326344Simp<span class="apii">[-0, +1, <em>m</em>]</span>
4111280405Srpaulo<pre>void *lua_newuserdata (lua_State *L, size_t size);</pre>
4112280405Srpaulo
4113280405Srpaulo<p>
4114280405SrpauloThis function allocates a new block of memory with the given size,
4115280405Srpaulopushes onto the stack a new full userdata with the block address,
4116280405Srpauloand returns this address.
4117280405SrpauloThe host program can freely use this memory.
4118280405Srpaulo
4119280405Srpaulo
4120280405Srpaulo
4121280405Srpaulo
4122280405Srpaulo
4123280405Srpaulo<hr><h3><a name="lua_next"><code>lua_next</code></a></h3><p>
4124280405Srpaulo<span class="apii">[-1, +(2|0), <em>e</em>]</span>
4125280405Srpaulo<pre>int lua_next (lua_State *L, int index);</pre>
4126280405Srpaulo
4127280405Srpaulo<p>
4128280405SrpauloPops a key from the stack,
4129280405Srpauloand pushes a key&ndash;value pair from the table at the given index
4130280405Srpaulo(the "next" pair after the given key).
4131280405SrpauloIf there are no more elements in the table,
4132280405Srpaulothen <a href="#lua_next"><code>lua_next</code></a> returns 0 (and pushes nothing).
4133280405Srpaulo
4134280405Srpaulo
4135280405Srpaulo<p>
4136280405SrpauloA typical traversal looks like this:
4137280405Srpaulo
4138280405Srpaulo<pre>
4139280405Srpaulo     /* table is in the stack at index 't' */
4140280405Srpaulo     lua_pushnil(L);  /* first key */
4141280405Srpaulo     while (lua_next(L, t) != 0) {
4142280405Srpaulo       /* uses 'key' (at index -2) and 'value' (at index -1) */
4143280405Srpaulo       printf("%s - %s\n",
4144280405Srpaulo              lua_typename(L, lua_type(L, -2)),
4145280405Srpaulo              lua_typename(L, lua_type(L, -1)));
4146280405Srpaulo       /* removes 'value'; keeps 'key' for next iteration */
4147280405Srpaulo       lua_pop(L, 1);
4148280405Srpaulo     }
4149280405Srpaulo</pre>
4150280405Srpaulo
4151280405Srpaulo<p>
4152280405SrpauloWhile traversing a table,
4153280405Srpaulodo not call <a href="#lua_tolstring"><code>lua_tolstring</code></a> directly on a key,
4154280405Srpaulounless you know that the key is actually a string.
4155280405SrpauloRecall that <a href="#lua_tolstring"><code>lua_tolstring</code></a> may change
4156280405Srpaulothe value at the given index;
4157280405Srpaulothis confuses the next call to <a href="#lua_next"><code>lua_next</code></a>.
4158280405Srpaulo
4159280405Srpaulo
4160280405Srpaulo<p>
4161280405SrpauloSee function <a href="#pdf-next"><code>next</code></a> for the caveats of modifying
4162280405Srpaulothe table during its traversal.
4163280405Srpaulo
4164280405Srpaulo
4165280405Srpaulo
4166280405Srpaulo
4167280405Srpaulo
4168280405Srpaulo<hr><h3><a name="lua_Number"><code>lua_Number</code></a></h3>
4169326344Simp<pre>typedef ... lua_Number;</pre>
4170280405Srpaulo
4171280405Srpaulo<p>
4172280405SrpauloThe type of floats in Lua.
4173280405Srpaulo
4174280405Srpaulo
4175280405Srpaulo<p>
4176280405SrpauloBy default this type is double,
4177326344Simpbut that can be changed to a single float or a long double.
4178326344Simp(See <code>LUA_FLOAT_TYPE</code> in <code>luaconf.h</code>.)
4179280405Srpaulo
4180280405Srpaulo
4181280405Srpaulo
4182280405Srpaulo
4183280405Srpaulo
4184280405Srpaulo<hr><h3><a name="lua_numbertointeger"><code>lua_numbertointeger</code></a></h3>
4185280405Srpaulo<pre>int lua_numbertointeger (lua_Number n, lua_Integer *p);</pre>
4186280405Srpaulo
4187280405Srpaulo<p>
4188280405SrpauloConverts a Lua float to a Lua integer.
4189280405SrpauloThis macro assumes that <code>n</code> has an integral value.
4190280405SrpauloIf that value is within the range of Lua integers,
4191280405Srpauloit is converted to an integer and assigned to <code>*p</code>.
4192280405SrpauloThe macro results in a boolean indicating whether the
4193280405Srpauloconversion was successful.
4194280405Srpaulo(Note that this range test can be tricky to do
4195280405Srpaulocorrectly without this macro,
4196280405Srpaulodue to roundings.)
4197280405Srpaulo
4198280405Srpaulo
4199280405Srpaulo<p>
4200280405SrpauloThis macro may evaluate its arguments more than once.
4201280405Srpaulo
4202280405Srpaulo
4203280405Srpaulo
4204280405Srpaulo
4205280405Srpaulo
4206280405Srpaulo<hr><h3><a name="lua_pcall"><code>lua_pcall</code></a></h3><p>
4207280405Srpaulo<span class="apii">[-(nargs + 1), +(nresults|1), &ndash;]</span>
4208280405Srpaulo<pre>int lua_pcall (lua_State *L, int nargs, int nresults, int msgh);</pre>
4209280405Srpaulo
4210280405Srpaulo<p>
4211280405SrpauloCalls a function in protected mode.
4212280405Srpaulo
4213280405Srpaulo
4214280405Srpaulo<p>
4215280405SrpauloBoth <code>nargs</code> and <code>nresults</code> have the same meaning as
4216280405Srpauloin <a href="#lua_call"><code>lua_call</code></a>.
4217280405SrpauloIf there are no errors during the call,
4218280405Srpaulo<a href="#lua_pcall"><code>lua_pcall</code></a> behaves exactly like <a href="#lua_call"><code>lua_call</code></a>.
4219280405SrpauloHowever, if there is any error,
4220280405Srpaulo<a href="#lua_pcall"><code>lua_pcall</code></a> catches it,
4221326344Simppushes a single value on the stack (the error object),
4222280405Srpauloand returns an error code.
4223280405SrpauloLike <a href="#lua_call"><code>lua_call</code></a>,
4224280405Srpaulo<a href="#lua_pcall"><code>lua_pcall</code></a> always removes the function
4225280405Srpauloand its arguments from the stack.
4226280405Srpaulo
4227280405Srpaulo
4228280405Srpaulo<p>
4229280405SrpauloIf <code>msgh</code> is 0,
4230326344Simpthen the error object returned on the stack
4231326344Simpis exactly the original error object.
4232280405SrpauloOtherwise, <code>msgh</code> is the stack index of a
4233280405Srpaulo<em>message handler</em>.
4234326344Simp(This index cannot be a pseudo-index.)
4235280405SrpauloIn case of runtime errors,
4236326344Simpthis function will be called with the error object
4237326344Simpand its return value will be the object
4238280405Srpauloreturned on the stack by <a href="#lua_pcall"><code>lua_pcall</code></a>.
4239280405Srpaulo
4240280405Srpaulo
4241280405Srpaulo<p>
4242280405SrpauloTypically, the message handler is used to add more debug
4243326344Simpinformation to the error object, such as a stack traceback.
4244280405SrpauloSuch information cannot be gathered after the return of <a href="#lua_pcall"><code>lua_pcall</code></a>,
4245280405Srpaulosince by then the stack has unwound.
4246280405Srpaulo
4247280405Srpaulo
4248280405Srpaulo<p>
4249280405SrpauloThe <a href="#lua_pcall"><code>lua_pcall</code></a> function returns one of the following constants
4250280405Srpaulo(defined in <code>lua.h</code>):
4251280405Srpaulo
4252280405Srpaulo<ul>
4253280405Srpaulo
4254280405Srpaulo<li><b><a name="pdf-LUA_OK"><code>LUA_OK</code></a> (0): </b>
4255280405Srpaulosuccess.</li>
4256280405Srpaulo
4257280405Srpaulo<li><b><a name="pdf-LUA_ERRRUN"><code>LUA_ERRRUN</code></a>: </b>
4258280405Srpauloa runtime error.
4259280405Srpaulo</li>
4260280405Srpaulo
4261280405Srpaulo<li><b><a name="pdf-LUA_ERRMEM"><code>LUA_ERRMEM</code></a>: </b>
4262280405Srpaulomemory allocation error.
4263280405SrpauloFor such errors, Lua does not call the message handler.
4264280405Srpaulo</li>
4265280405Srpaulo
4266280405Srpaulo<li><b><a name="pdf-LUA_ERRERR"><code>LUA_ERRERR</code></a>: </b>
4267280405Srpauloerror while running the message handler.
4268280405Srpaulo</li>
4269280405Srpaulo
4270280405Srpaulo<li><b><a name="pdf-LUA_ERRGCMM"><code>LUA_ERRGCMM</code></a>: </b>
4271280405Srpauloerror while running a <code>__gc</code> metamethod.
4272326344SimpFor such errors, Lua does not call the message handler
4273326344Simp(as this kind of error typically has no relation
4274326344Simpwith the function being called).
4275280405Srpaulo</li>
4276280405Srpaulo
4277280405Srpaulo</ul>
4278280405Srpaulo
4279280405Srpaulo
4280280405Srpaulo
4281280405Srpaulo
4282280405Srpaulo<hr><h3><a name="lua_pcallk"><code>lua_pcallk</code></a></h3><p>
4283280405Srpaulo<span class="apii">[-(nargs + 1), +(nresults|1), &ndash;]</span>
4284280405Srpaulo<pre>int lua_pcallk (lua_State *L,
4285280405Srpaulo                int nargs,
4286280405Srpaulo                int nresults,
4287280405Srpaulo                int msgh,
4288280405Srpaulo                lua_KContext ctx,
4289280405Srpaulo                lua_KFunction k);</pre>
4290280405Srpaulo
4291280405Srpaulo<p>
4292280405SrpauloThis function behaves exactly like <a href="#lua_pcall"><code>lua_pcall</code></a>,
4293280405Srpaulobut allows the called function to yield (see <a href="#4.7">&sect;4.7</a>).
4294280405Srpaulo
4295280405Srpaulo
4296280405Srpaulo
4297280405Srpaulo
4298280405Srpaulo
4299280405Srpaulo<hr><h3><a name="lua_pop"><code>lua_pop</code></a></h3><p>
4300280405Srpaulo<span class="apii">[-n, +0, &ndash;]</span>
4301280405Srpaulo<pre>void lua_pop (lua_State *L, int n);</pre>
4302280405Srpaulo
4303280405Srpaulo<p>
4304280405SrpauloPops <code>n</code> elements from the stack.
4305280405Srpaulo
4306280405Srpaulo
4307280405Srpaulo
4308280405Srpaulo
4309280405Srpaulo
4310280405Srpaulo<hr><h3><a name="lua_pushboolean"><code>lua_pushboolean</code></a></h3><p>
4311280405Srpaulo<span class="apii">[-0, +1, &ndash;]</span>
4312280405Srpaulo<pre>void lua_pushboolean (lua_State *L, int b);</pre>
4313280405Srpaulo
4314280405Srpaulo<p>
4315280405SrpauloPushes a boolean value with value <code>b</code> onto the stack.
4316280405Srpaulo
4317280405Srpaulo
4318280405Srpaulo
4319280405Srpaulo
4320280405Srpaulo
4321280405Srpaulo<hr><h3><a name="lua_pushcclosure"><code>lua_pushcclosure</code></a></h3><p>
4322326344Simp<span class="apii">[-n, +1, <em>m</em>]</span>
4323280405Srpaulo<pre>void lua_pushcclosure (lua_State *L, lua_CFunction fn, int n);</pre>
4324280405Srpaulo
4325280405Srpaulo<p>
4326280405SrpauloPushes a new C&nbsp;closure onto the stack.
4327280405Srpaulo
4328280405Srpaulo
4329280405Srpaulo<p>
4330280405SrpauloWhen a C&nbsp;function is created,
4331280405Srpauloit is possible to associate some values with it,
4332280405Srpaulothus creating a C&nbsp;closure (see <a href="#4.4">&sect;4.4</a>);
4333280405Srpaulothese values are then accessible to the function whenever it is called.
4334280405SrpauloTo associate values with a C&nbsp;function,
4335280405Srpaulofirst these values must be pushed onto the stack
4336280405Srpaulo(when there are multiple values, the first value is pushed first).
4337280405SrpauloThen <a href="#lua_pushcclosure"><code>lua_pushcclosure</code></a>
4338280405Srpaulois called to create and push the C&nbsp;function onto the stack,
4339280405Srpaulowith the argument <code>n</code> telling how many values will be
4340280405Srpauloassociated with the function.
4341280405Srpaulo<a href="#lua_pushcclosure"><code>lua_pushcclosure</code></a> also pops these values from the stack.
4342280405Srpaulo
4343280405Srpaulo
4344280405Srpaulo<p>
4345280405SrpauloThe maximum value for <code>n</code> is 255.
4346280405Srpaulo
4347280405Srpaulo
4348280405Srpaulo<p>
4349280405SrpauloWhen <code>n</code> is zero,
4350326344Simpthis function creates a <em>light C&nbsp;function</em>,
4351280405Srpaulowhich is just a pointer to the C&nbsp;function.
4352280405SrpauloIn that case, it never raises a memory error.
4353280405Srpaulo
4354280405Srpaulo
4355280405Srpaulo
4356280405Srpaulo
4357280405Srpaulo
4358280405Srpaulo<hr><h3><a name="lua_pushcfunction"><code>lua_pushcfunction</code></a></h3><p>
4359280405Srpaulo<span class="apii">[-0, +1, &ndash;]</span>
4360280405Srpaulo<pre>void lua_pushcfunction (lua_State *L, lua_CFunction f);</pre>
4361280405Srpaulo
4362280405Srpaulo<p>
4363280405SrpauloPushes a C&nbsp;function onto the stack.
4364326344SimpThis function receives a pointer to a C&nbsp;function
4365280405Srpauloand pushes onto the stack a Lua value of type <code>function</code> that,
4366280405Srpaulowhen called, invokes the corresponding C&nbsp;function.
4367280405Srpaulo
4368280405Srpaulo
4369280405Srpaulo<p>
4370326344SimpAny function to be callable by Lua must
4371280405Srpaulofollow the correct protocol to receive its parameters
4372280405Srpauloand return its results (see <a href="#lua_CFunction"><code>lua_CFunction</code></a>).
4373280405Srpaulo
4374280405Srpaulo
4375280405Srpaulo
4376280405Srpaulo
4377280405Srpaulo
4378280405Srpaulo<hr><h3><a name="lua_pushfstring"><code>lua_pushfstring</code></a></h3><p>
4379280405Srpaulo<span class="apii">[-0, +1, <em>e</em>]</span>
4380280405Srpaulo<pre>const char *lua_pushfstring (lua_State *L, const char *fmt, ...);</pre>
4381280405Srpaulo
4382280405Srpaulo<p>
4383280405SrpauloPushes onto the stack a formatted string
4384280405Srpauloand returns a pointer to this string.
4385280405SrpauloIt is similar to the ISO&nbsp;C function <code>sprintf</code>,
4386280405Srpaulobut has some important differences:
4387280405Srpaulo
4388280405Srpaulo<ul>
4389280405Srpaulo
4390280405Srpaulo<li>
4391280405SrpauloYou do not have to allocate space for the result:
4392280405Srpaulothe result is a Lua string and Lua takes care of memory allocation
4393280405Srpaulo(and deallocation, through garbage collection).
4394280405Srpaulo</li>
4395280405Srpaulo
4396280405Srpaulo<li>
4397280405SrpauloThe conversion specifiers are quite restricted.
4398280405SrpauloThere are no flags, widths, or precisions.
4399280405SrpauloThe conversion specifiers can only be
4400280405Srpaulo'<code>%%</code>' (inserts the character '<code>%</code>'),
4401280405Srpaulo'<code>%s</code>' (inserts a zero-terminated string, with no size restrictions),
4402280405Srpaulo'<code>%f</code>' (inserts a <a href="#lua_Number"><code>lua_Number</code></a>),
4403326344Simp'<code>%I</code>' (inserts a <a href="#lua_Integer"><code>lua_Integer</code></a>),
4404280405Srpaulo'<code>%p</code>' (inserts a pointer as a hexadecimal numeral),
4405280405Srpaulo'<code>%d</code>' (inserts an <code>int</code>),
4406280405Srpaulo'<code>%c</code>' (inserts an <code>int</code> as a one-byte character), and
4407280405Srpaulo'<code>%U</code>' (inserts a <code>long int</code> as a UTF-8 byte sequence).
4408280405Srpaulo</li>
4409280405Srpaulo
4410280405Srpaulo</ul>
4411280405Srpaulo
4412326344Simp<p>
4413326344SimpUnlike other push functions,
4414326344Simpthis function checks for the stack space it needs,
4415326344Simpincluding the slot for its result.
4416280405Srpaulo
4417280405Srpaulo
4418280405Srpaulo
4419326344Simp
4420326344Simp
4421280405Srpaulo<hr><h3><a name="lua_pushglobaltable"><code>lua_pushglobaltable</code></a></h3><p>
4422280405Srpaulo<span class="apii">[-0, +1, &ndash;]</span>
4423280405Srpaulo<pre>void lua_pushglobaltable (lua_State *L);</pre>
4424280405Srpaulo
4425280405Srpaulo<p>
4426280405SrpauloPushes the global environment onto the stack.
4427280405Srpaulo
4428280405Srpaulo
4429280405Srpaulo
4430280405Srpaulo
4431280405Srpaulo
4432280405Srpaulo<hr><h3><a name="lua_pushinteger"><code>lua_pushinteger</code></a></h3><p>
4433280405Srpaulo<span class="apii">[-0, +1, &ndash;]</span>
4434280405Srpaulo<pre>void lua_pushinteger (lua_State *L, lua_Integer n);</pre>
4435280405Srpaulo
4436280405Srpaulo<p>
4437280405SrpauloPushes an integer with value <code>n</code> onto the stack.
4438280405Srpaulo
4439280405Srpaulo
4440280405Srpaulo
4441280405Srpaulo
4442280405Srpaulo
4443280405Srpaulo<hr><h3><a name="lua_pushlightuserdata"><code>lua_pushlightuserdata</code></a></h3><p>
4444280405Srpaulo<span class="apii">[-0, +1, &ndash;]</span>
4445280405Srpaulo<pre>void lua_pushlightuserdata (lua_State *L, void *p);</pre>
4446280405Srpaulo
4447280405Srpaulo<p>
4448280405SrpauloPushes a light userdata onto the stack.
4449280405Srpaulo
4450280405Srpaulo
4451280405Srpaulo<p>
4452280405SrpauloUserdata represent C&nbsp;values in Lua.
4453280405SrpauloA <em>light userdata</em> represents a pointer, a <code>void*</code>.
4454280405SrpauloIt is a value (like a number):
4455280405Srpauloyou do not create it, it has no individual metatable,
4456280405Srpauloand it is not collected (as it was never created).
4457280405SrpauloA light userdata is equal to "any"
4458280405Srpaulolight userdata with the same C&nbsp;address.
4459280405Srpaulo
4460280405Srpaulo
4461280405Srpaulo
4462280405Srpaulo
4463280405Srpaulo
4464280405Srpaulo<hr><h3><a name="lua_pushliteral"><code>lua_pushliteral</code></a></h3><p>
4465326344Simp<span class="apii">[-0, +1, <em>m</em>]</span>
4466280405Srpaulo<pre>const char *lua_pushliteral (lua_State *L, const char *s);</pre>
4467280405Srpaulo
4468280405Srpaulo<p>
4469326344SimpThis macro is equivalent to <a href="#lua_pushstring"><code>lua_pushstring</code></a>,
4470326344Simpbut should be used only when <code>s</code> is a literal string.
4471280405Srpaulo
4472280405Srpaulo
4473280405Srpaulo
4474280405Srpaulo
4475280405Srpaulo
4476280405Srpaulo<hr><h3><a name="lua_pushlstring"><code>lua_pushlstring</code></a></h3><p>
4477326344Simp<span class="apii">[-0, +1, <em>m</em>]</span>
4478280405Srpaulo<pre>const char *lua_pushlstring (lua_State *L, const char *s, size_t len);</pre>
4479280405Srpaulo
4480280405Srpaulo<p>
4481280405SrpauloPushes the string pointed to by <code>s</code> with size <code>len</code>
4482280405Srpauloonto the stack.
4483280405SrpauloLua makes (or reuses) an internal copy of the given string,
4484280405Srpauloso the memory at <code>s</code> can be freed or reused immediately after
4485280405Srpaulothe function returns.
4486280405SrpauloThe string can contain any binary data,
4487280405Srpauloincluding embedded zeros.
4488280405Srpaulo
4489280405Srpaulo
4490280405Srpaulo<p>
4491280405SrpauloReturns a pointer to the internal copy of the string.
4492280405Srpaulo
4493280405Srpaulo
4494280405Srpaulo
4495280405Srpaulo
4496280405Srpaulo
4497280405Srpaulo<hr><h3><a name="lua_pushnil"><code>lua_pushnil</code></a></h3><p>
4498280405Srpaulo<span class="apii">[-0, +1, &ndash;]</span>
4499280405Srpaulo<pre>void lua_pushnil (lua_State *L);</pre>
4500280405Srpaulo
4501280405Srpaulo<p>
4502280405SrpauloPushes a nil value onto the stack.
4503280405Srpaulo
4504280405Srpaulo
4505280405Srpaulo
4506280405Srpaulo
4507280405Srpaulo
4508280405Srpaulo<hr><h3><a name="lua_pushnumber"><code>lua_pushnumber</code></a></h3><p>
4509280405Srpaulo<span class="apii">[-0, +1, &ndash;]</span>
4510280405Srpaulo<pre>void lua_pushnumber (lua_State *L, lua_Number n);</pre>
4511280405Srpaulo
4512280405Srpaulo<p>
4513280405SrpauloPushes a float with value <code>n</code> onto the stack.
4514280405Srpaulo
4515280405Srpaulo
4516280405Srpaulo
4517280405Srpaulo
4518280405Srpaulo
4519280405Srpaulo<hr><h3><a name="lua_pushstring"><code>lua_pushstring</code></a></h3><p>
4520326344Simp<span class="apii">[-0, +1, <em>m</em>]</span>
4521280405Srpaulo<pre>const char *lua_pushstring (lua_State *L, const char *s);</pre>
4522280405Srpaulo
4523280405Srpaulo<p>
4524280405SrpauloPushes the zero-terminated string pointed to by <code>s</code>
4525280405Srpauloonto the stack.
4526280405SrpauloLua makes (or reuses) an internal copy of the given string,
4527280405Srpauloso the memory at <code>s</code> can be freed or reused immediately after
4528280405Srpaulothe function returns.
4529280405Srpaulo
4530280405Srpaulo
4531280405Srpaulo<p>
4532280405SrpauloReturns a pointer to the internal copy of the string.
4533280405Srpaulo
4534280405Srpaulo
4535280405Srpaulo<p>
4536280405SrpauloIf <code>s</code> is <code>NULL</code>, pushes <b>nil</b> and returns <code>NULL</code>.
4537280405Srpaulo
4538280405Srpaulo
4539280405Srpaulo
4540280405Srpaulo
4541280405Srpaulo
4542280405Srpaulo<hr><h3><a name="lua_pushthread"><code>lua_pushthread</code></a></h3><p>
4543280405Srpaulo<span class="apii">[-0, +1, &ndash;]</span>
4544280405Srpaulo<pre>int lua_pushthread (lua_State *L);</pre>
4545280405Srpaulo
4546280405Srpaulo<p>
4547280405SrpauloPushes the thread represented by <code>L</code> onto the stack.
4548280405SrpauloReturns 1 if this thread is the main thread of its state.
4549280405Srpaulo
4550280405Srpaulo
4551280405Srpaulo
4552280405Srpaulo
4553280405Srpaulo
4554280405Srpaulo<hr><h3><a name="lua_pushvalue"><code>lua_pushvalue</code></a></h3><p>
4555280405Srpaulo<span class="apii">[-0, +1, &ndash;]</span>
4556280405Srpaulo<pre>void lua_pushvalue (lua_State *L, int index);</pre>
4557280405Srpaulo
4558280405Srpaulo<p>
4559280405SrpauloPushes a copy of the element at the given index
4560280405Srpauloonto the stack.
4561280405Srpaulo
4562280405Srpaulo
4563280405Srpaulo
4564280405Srpaulo
4565280405Srpaulo
4566280405Srpaulo<hr><h3><a name="lua_pushvfstring"><code>lua_pushvfstring</code></a></h3><p>
4567326344Simp<span class="apii">[-0, +1, <em>m</em>]</span>
4568280405Srpaulo<pre>const char *lua_pushvfstring (lua_State *L,
4569280405Srpaulo                              const char *fmt,
4570280405Srpaulo                              va_list argp);</pre>
4571280405Srpaulo
4572280405Srpaulo<p>
4573280405SrpauloEquivalent to <a href="#lua_pushfstring"><code>lua_pushfstring</code></a>, except that it receives a <code>va_list</code>
4574280405Srpauloinstead of a variable number of arguments.
4575280405Srpaulo
4576280405Srpaulo
4577280405Srpaulo
4578280405Srpaulo
4579280405Srpaulo
4580280405Srpaulo<hr><h3><a name="lua_rawequal"><code>lua_rawequal</code></a></h3><p>
4581280405Srpaulo<span class="apii">[-0, +0, &ndash;]</span>
4582280405Srpaulo<pre>int lua_rawequal (lua_State *L, int index1, int index2);</pre>
4583280405Srpaulo
4584280405Srpaulo<p>
4585280405SrpauloReturns 1 if the two values in indices <code>index1</code> and
4586280405Srpaulo<code>index2</code> are primitively equal
4587326344Simp(that is, without calling the <code>__eq</code> metamethod).
4588280405SrpauloOtherwise returns&nbsp;0.
4589280405SrpauloAlso returns&nbsp;0 if any of the indices are not valid.
4590280405Srpaulo
4591280405Srpaulo
4592280405Srpaulo
4593280405Srpaulo
4594280405Srpaulo
4595280405Srpaulo<hr><h3><a name="lua_rawget"><code>lua_rawget</code></a></h3><p>
4596280405Srpaulo<span class="apii">[-1, +1, &ndash;]</span>
4597280405Srpaulo<pre>int lua_rawget (lua_State *L, int index);</pre>
4598280405Srpaulo
4599280405Srpaulo<p>
4600280405SrpauloSimilar to <a href="#lua_gettable"><code>lua_gettable</code></a>, but does a raw access
4601280405Srpaulo(i.e., without metamethods).
4602280405Srpaulo
4603280405Srpaulo
4604280405Srpaulo
4605280405Srpaulo
4606280405Srpaulo
4607280405Srpaulo<hr><h3><a name="lua_rawgeti"><code>lua_rawgeti</code></a></h3><p>
4608280405Srpaulo<span class="apii">[-0, +1, &ndash;]</span>
4609280405Srpaulo<pre>int lua_rawgeti (lua_State *L, int index, lua_Integer n);</pre>
4610280405Srpaulo
4611280405Srpaulo<p>
4612280405SrpauloPushes onto the stack the value <code>t[n]</code>,
4613280405Srpaulowhere <code>t</code> is the table at the given index.
4614326344SimpThe access is raw,
4615326344Simpthat is, it does not invoke the <code>__index</code> metamethod.
4616280405Srpaulo
4617280405Srpaulo
4618280405Srpaulo<p>
4619280405SrpauloReturns the type of the pushed value.
4620280405Srpaulo
4621280405Srpaulo
4622280405Srpaulo
4623280405Srpaulo
4624280405Srpaulo
4625280405Srpaulo<hr><h3><a name="lua_rawgetp"><code>lua_rawgetp</code></a></h3><p>
4626280405Srpaulo<span class="apii">[-0, +1, &ndash;]</span>
4627280405Srpaulo<pre>int lua_rawgetp (lua_State *L, int index, const void *p);</pre>
4628280405Srpaulo
4629280405Srpaulo<p>
4630280405SrpauloPushes onto the stack the value <code>t[k]</code>,
4631280405Srpaulowhere <code>t</code> is the table at the given index and
4632280405Srpaulo<code>k</code> is the pointer <code>p</code> represented as a light userdata.
4633280405SrpauloThe access is raw;
4634326344Simpthat is, it does not invoke the <code>__index</code> metamethod.
4635280405Srpaulo
4636280405Srpaulo
4637280405Srpaulo<p>
4638280405SrpauloReturns the type of the pushed value.
4639280405Srpaulo
4640280405Srpaulo
4641280405Srpaulo
4642280405Srpaulo
4643280405Srpaulo
4644280405Srpaulo<hr><h3><a name="lua_rawlen"><code>lua_rawlen</code></a></h3><p>
4645280405Srpaulo<span class="apii">[-0, +0, &ndash;]</span>
4646280405Srpaulo<pre>size_t lua_rawlen (lua_State *L, int index);</pre>
4647280405Srpaulo
4648280405Srpaulo<p>
4649280405SrpauloReturns the raw "length" of the value at the given index:
4650280405Srpaulofor strings, this is the string length;
4651280405Srpaulofor tables, this is the result of the length operator ('<code>#</code>')
4652280405Srpaulowith no metamethods;
4653280405Srpaulofor userdata, this is the size of the block of memory allocated
4654280405Srpaulofor the userdata;
4655280405Srpaulofor other values, it is&nbsp;0.
4656280405Srpaulo
4657280405Srpaulo
4658280405Srpaulo
4659280405Srpaulo
4660280405Srpaulo
4661280405Srpaulo<hr><h3><a name="lua_rawset"><code>lua_rawset</code></a></h3><p>
4662326344Simp<span class="apii">[-2, +0, <em>m</em>]</span>
4663280405Srpaulo<pre>void lua_rawset (lua_State *L, int index);</pre>
4664280405Srpaulo
4665280405Srpaulo<p>
4666280405SrpauloSimilar to <a href="#lua_settable"><code>lua_settable</code></a>, but does a raw assignment
4667280405Srpaulo(i.e., without metamethods).
4668280405Srpaulo
4669280405Srpaulo
4670280405Srpaulo
4671280405Srpaulo
4672280405Srpaulo
4673280405Srpaulo<hr><h3><a name="lua_rawseti"><code>lua_rawseti</code></a></h3><p>
4674326344Simp<span class="apii">[-1, +0, <em>m</em>]</span>
4675280405Srpaulo<pre>void lua_rawseti (lua_State *L, int index, lua_Integer i);</pre>
4676280405Srpaulo
4677280405Srpaulo<p>
4678280405SrpauloDoes the equivalent of <code>t[i] = v</code>,
4679280405Srpaulowhere <code>t</code> is the table at the given index
4680280405Srpauloand <code>v</code> is the value at the top of the stack.
4681280405Srpaulo
4682280405Srpaulo
4683280405Srpaulo<p>
4684280405SrpauloThis function pops the value from the stack.
4685326344SimpThe assignment is raw,
4686326344Simpthat is, it does not invoke the <code>__newindex</code> metamethod.
4687280405Srpaulo
4688280405Srpaulo
4689280405Srpaulo
4690280405Srpaulo
4691280405Srpaulo
4692280405Srpaulo<hr><h3><a name="lua_rawsetp"><code>lua_rawsetp</code></a></h3><p>
4693326344Simp<span class="apii">[-1, +0, <em>m</em>]</span>
4694280405Srpaulo<pre>void lua_rawsetp (lua_State *L, int index, const void *p);</pre>
4695280405Srpaulo
4696280405Srpaulo<p>
4697326344SimpDoes the equivalent of <code>t[p] = v</code>,
4698280405Srpaulowhere <code>t</code> is the table at the given index,
4699326344Simp<code>p</code> is encoded as a light userdata,
4700280405Srpauloand <code>v</code> is the value at the top of the stack.
4701280405Srpaulo
4702280405Srpaulo
4703280405Srpaulo<p>
4704280405SrpauloThis function pops the value from the stack.
4705326344SimpThe assignment is raw,
4706326344Simpthat is, it does not invoke <code>__newindex</code> metamethod.
4707280405Srpaulo
4708280405Srpaulo
4709280405Srpaulo
4710280405Srpaulo
4711280405Srpaulo
4712280405Srpaulo<hr><h3><a name="lua_Reader"><code>lua_Reader</code></a></h3>
4713280405Srpaulo<pre>typedef const char * (*lua_Reader) (lua_State *L,
4714280405Srpaulo                                    void *data,
4715280405Srpaulo                                    size_t *size);</pre>
4716280405Srpaulo
4717280405Srpaulo<p>
4718280405SrpauloThe reader function used by <a href="#lua_load"><code>lua_load</code></a>.
4719280405SrpauloEvery time it needs another piece of the chunk,
4720280405Srpaulo<a href="#lua_load"><code>lua_load</code></a> calls the reader,
4721280405Srpaulopassing along its <code>data</code> parameter.
4722280405SrpauloThe reader must return a pointer to a block of memory
4723280405Srpaulowith a new piece of the chunk
4724280405Srpauloand set <code>size</code> to the block size.
4725280405SrpauloThe block must exist until the reader function is called again.
4726280405SrpauloTo signal the end of the chunk,
4727280405Srpaulothe reader must return <code>NULL</code> or set <code>size</code> to zero.
4728280405SrpauloThe reader function may return pieces of any size greater than zero.
4729280405Srpaulo
4730280405Srpaulo
4731280405Srpaulo
4732280405Srpaulo
4733280405Srpaulo
4734280405Srpaulo<hr><h3><a name="lua_register"><code>lua_register</code></a></h3><p>
4735280405Srpaulo<span class="apii">[-0, +0, <em>e</em>]</span>
4736280405Srpaulo<pre>void lua_register (lua_State *L, const char *name, lua_CFunction f);</pre>
4737280405Srpaulo
4738280405Srpaulo<p>
4739326344SimpSets the C&nbsp;function <code>f</code> as the new value of global <code>name</code>.
4740280405SrpauloIt is defined as a macro:
4741280405Srpaulo
4742280405Srpaulo<pre>
4743280405Srpaulo     #define lua_register(L,n,f) \
4744280405Srpaulo            (lua_pushcfunction(L, f), lua_setglobal(L, n))
4745280405Srpaulo</pre>
4746280405Srpaulo
4747280405Srpaulo
4748280405Srpaulo
4749280405Srpaulo
4750280405Srpaulo<hr><h3><a name="lua_remove"><code>lua_remove</code></a></h3><p>
4751280405Srpaulo<span class="apii">[-1, +0, &ndash;]</span>
4752280405Srpaulo<pre>void lua_remove (lua_State *L, int index);</pre>
4753280405Srpaulo
4754280405Srpaulo<p>
4755280405SrpauloRemoves the element at the given valid index,
4756280405Srpauloshifting down the elements above this index to fill the gap.
4757280405SrpauloThis function cannot be called with a pseudo-index,
4758280405Srpaulobecause a pseudo-index is not an actual stack position.
4759280405Srpaulo
4760280405Srpaulo
4761280405Srpaulo
4762280405Srpaulo
4763280405Srpaulo
4764280405Srpaulo<hr><h3><a name="lua_replace"><code>lua_replace</code></a></h3><p>
4765280405Srpaulo<span class="apii">[-1, +0, &ndash;]</span>
4766280405Srpaulo<pre>void lua_replace (lua_State *L, int index);</pre>
4767280405Srpaulo
4768280405Srpaulo<p>
4769280405SrpauloMoves the top element into the given valid index
4770280405Srpaulowithout shifting any element
4771326344Simp(therefore replacing the value at that given index),
4772280405Srpauloand then pops the top element.
4773280405Srpaulo
4774280405Srpaulo
4775280405Srpaulo
4776280405Srpaulo
4777280405Srpaulo
4778280405Srpaulo<hr><h3><a name="lua_resume"><code>lua_resume</code></a></h3><p>
4779280405Srpaulo<span class="apii">[-?, +?, &ndash;]</span>
4780280405Srpaulo<pre>int lua_resume (lua_State *L, lua_State *from, int nargs);</pre>
4781280405Srpaulo
4782280405Srpaulo<p>
4783326344SimpStarts and resumes a coroutine in the given thread <code>L</code>.
4784280405Srpaulo
4785280405Srpaulo
4786280405Srpaulo<p>
4787280405SrpauloTo start a coroutine,
4788280405Srpauloyou push onto the thread stack the main function plus any arguments;
4789280405Srpaulothen you call <a href="#lua_resume"><code>lua_resume</code></a>,
4790280405Srpaulowith <code>nargs</code> being the number of arguments.
4791280405SrpauloThis call returns when the coroutine suspends or finishes its execution.
4792280405SrpauloWhen it returns, the stack contains all values passed to <a href="#lua_yield"><code>lua_yield</code></a>,
4793280405Srpauloor all values returned by the body function.
4794280405Srpaulo<a href="#lua_resume"><code>lua_resume</code></a> returns
4795280405Srpaulo<a href="#pdf-LUA_YIELD"><code>LUA_YIELD</code></a> if the coroutine yields,
4796280405Srpaulo<a href="#pdf-LUA_OK"><code>LUA_OK</code></a> if the coroutine finishes its execution
4797280405Srpaulowithout errors,
4798280405Srpauloor an error code in case of errors (see <a href="#lua_pcall"><code>lua_pcall</code></a>).
4799280405Srpaulo
4800280405Srpaulo
4801280405Srpaulo<p>
4802280405SrpauloIn case of errors,
4803280405Srpaulothe stack is not unwound,
4804280405Srpauloso you can use the debug API over it.
4805326344SimpThe error object is on the top of the stack.
4806280405Srpaulo
4807280405Srpaulo
4808280405Srpaulo<p>
4809280405SrpauloTo resume a coroutine,
4810280405Srpauloyou remove any results from the last <a href="#lua_yield"><code>lua_yield</code></a>,
4811280405Srpauloput on its stack only the values to
4812280405Srpaulobe passed as results from <code>yield</code>,
4813280405Srpauloand then call <a href="#lua_resume"><code>lua_resume</code></a>.
4814280405Srpaulo
4815280405Srpaulo
4816280405Srpaulo<p>
4817280405SrpauloThe parameter <code>from</code> represents the coroutine that is resuming <code>L</code>.
4818280405SrpauloIf there is no such coroutine,
4819280405Srpaulothis parameter can be <code>NULL</code>.
4820280405Srpaulo
4821280405Srpaulo
4822280405Srpaulo
4823280405Srpaulo
4824280405Srpaulo
4825280405Srpaulo<hr><h3><a name="lua_rotate"><code>lua_rotate</code></a></h3><p>
4826280405Srpaulo<span class="apii">[-0, +0, &ndash;]</span>
4827280405Srpaulo<pre>void lua_rotate (lua_State *L, int idx, int n);</pre>
4828280405Srpaulo
4829280405Srpaulo<p>
4830326344SimpRotates the stack elements between the valid index <code>idx</code>
4831326344Simpand the top of the stack.
4832326344SimpThe elements are rotated <code>n</code> positions in the direction of the top,
4833326344Simpfor a positive <code>n</code>,
4834280405Srpauloor <code>-n</code> positions in the direction of the bottom,
4835280405Srpaulofor a negative <code>n</code>.
4836280405SrpauloThe absolute value of <code>n</code> must not be greater than the size
4837280405Srpauloof the slice being rotated.
4838326344SimpThis function cannot be called with a pseudo-index,
4839326344Simpbecause a pseudo-index is not an actual stack position.
4840280405Srpaulo
4841280405Srpaulo
4842280405Srpaulo
4843280405Srpaulo
4844280405Srpaulo
4845280405Srpaulo<hr><h3><a name="lua_setallocf"><code>lua_setallocf</code></a></h3><p>
4846280405Srpaulo<span class="apii">[-0, +0, &ndash;]</span>
4847280405Srpaulo<pre>void lua_setallocf (lua_State *L, lua_Alloc f, void *ud);</pre>
4848280405Srpaulo
4849280405Srpaulo<p>
4850280405SrpauloChanges the allocator function of a given state to <code>f</code>
4851280405Srpaulowith user data <code>ud</code>.
4852280405Srpaulo
4853280405Srpaulo
4854280405Srpaulo
4855280405Srpaulo
4856280405Srpaulo
4857280405Srpaulo<hr><h3><a name="lua_setfield"><code>lua_setfield</code></a></h3><p>
4858280405Srpaulo<span class="apii">[-1, +0, <em>e</em>]</span>
4859280405Srpaulo<pre>void lua_setfield (lua_State *L, int index, const char *k);</pre>
4860280405Srpaulo
4861280405Srpaulo<p>
4862280405SrpauloDoes the equivalent to <code>t[k] = v</code>,
4863280405Srpaulowhere <code>t</code> is the value at the given index
4864280405Srpauloand <code>v</code> is the value at the top of the stack.
4865280405Srpaulo
4866280405Srpaulo
4867280405Srpaulo<p>
4868280405SrpauloThis function pops the value from the stack.
4869280405SrpauloAs in Lua, this function may trigger a metamethod
4870280405Srpaulofor the "newindex" event (see <a href="#2.4">&sect;2.4</a>).
4871280405Srpaulo
4872280405Srpaulo
4873280405Srpaulo
4874280405Srpaulo
4875280405Srpaulo
4876280405Srpaulo<hr><h3><a name="lua_setglobal"><code>lua_setglobal</code></a></h3><p>
4877280405Srpaulo<span class="apii">[-1, +0, <em>e</em>]</span>
4878280405Srpaulo<pre>void lua_setglobal (lua_State *L, const char *name);</pre>
4879280405Srpaulo
4880280405Srpaulo<p>
4881280405SrpauloPops a value from the stack and
4882280405Srpaulosets it as the new value of global <code>name</code>.
4883280405Srpaulo
4884280405Srpaulo
4885280405Srpaulo
4886280405Srpaulo
4887280405Srpaulo
4888280405Srpaulo<hr><h3><a name="lua_seti"><code>lua_seti</code></a></h3><p>
4889280405Srpaulo<span class="apii">[-1, +0, <em>e</em>]</span>
4890280405Srpaulo<pre>void lua_seti (lua_State *L, int index, lua_Integer n);</pre>
4891280405Srpaulo
4892280405Srpaulo<p>
4893280405SrpauloDoes the equivalent to <code>t[n] = v</code>,
4894280405Srpaulowhere <code>t</code> is the value at the given index
4895280405Srpauloand <code>v</code> is the value at the top of the stack.
4896280405Srpaulo
4897280405Srpaulo
4898280405Srpaulo<p>
4899280405SrpauloThis function pops the value from the stack.
4900280405SrpauloAs in Lua, this function may trigger a metamethod
4901280405Srpaulofor the "newindex" event (see <a href="#2.4">&sect;2.4</a>).
4902280405Srpaulo
4903280405Srpaulo
4904280405Srpaulo
4905280405Srpaulo
4906280405Srpaulo
4907280405Srpaulo<hr><h3><a name="lua_setmetatable"><code>lua_setmetatable</code></a></h3><p>
4908280405Srpaulo<span class="apii">[-1, +0, &ndash;]</span>
4909280405Srpaulo<pre>void lua_setmetatable (lua_State *L, int index);</pre>
4910280405Srpaulo
4911280405Srpaulo<p>
4912280405SrpauloPops a table from the stack and
4913280405Srpaulosets it as the new metatable for the value at the given index.
4914280405Srpaulo
4915280405Srpaulo
4916280405Srpaulo
4917280405Srpaulo
4918280405Srpaulo
4919280405Srpaulo<hr><h3><a name="lua_settable"><code>lua_settable</code></a></h3><p>
4920280405Srpaulo<span class="apii">[-2, +0, <em>e</em>]</span>
4921280405Srpaulo<pre>void lua_settable (lua_State *L, int index);</pre>
4922280405Srpaulo
4923280405Srpaulo<p>
4924280405SrpauloDoes the equivalent to <code>t[k] = v</code>,
4925280405Srpaulowhere <code>t</code> is the value at the given index,
4926280405Srpaulo<code>v</code> is the value at the top of the stack,
4927280405Srpauloand <code>k</code> is the value just below the top.
4928280405Srpaulo
4929280405Srpaulo
4930280405Srpaulo<p>
4931280405SrpauloThis function pops both the key and the value from the stack.
4932280405SrpauloAs in Lua, this function may trigger a metamethod
4933280405Srpaulofor the "newindex" event (see <a href="#2.4">&sect;2.4</a>).
4934280405Srpaulo
4935280405Srpaulo
4936280405Srpaulo
4937280405Srpaulo
4938280405Srpaulo
4939280405Srpaulo<hr><h3><a name="lua_settop"><code>lua_settop</code></a></h3><p>
4940280405Srpaulo<span class="apii">[-?, +?, &ndash;]</span>
4941280405Srpaulo<pre>void lua_settop (lua_State *L, int index);</pre>
4942280405Srpaulo
4943280405Srpaulo<p>
4944280405SrpauloAccepts any index, or&nbsp;0,
4945280405Srpauloand sets the stack top to this index.
4946280405SrpauloIf the new top is larger than the old one,
4947280405Srpaulothen the new elements are filled with <b>nil</b>.
4948280405SrpauloIf <code>index</code> is&nbsp;0, then all stack elements are removed.
4949280405Srpaulo
4950280405Srpaulo
4951280405Srpaulo
4952280405Srpaulo
4953280405Srpaulo
4954280405Srpaulo<hr><h3><a name="lua_setuservalue"><code>lua_setuservalue</code></a></h3><p>
4955280405Srpaulo<span class="apii">[-1, +0, &ndash;]</span>
4956280405Srpaulo<pre>void lua_setuservalue (lua_State *L, int index);</pre>
4957280405Srpaulo
4958280405Srpaulo<p>
4959280405SrpauloPops a value from the stack and sets it as
4960326344Simpthe new value associated to the full userdata at the given index.
4961280405Srpaulo
4962280405Srpaulo
4963280405Srpaulo
4964280405Srpaulo
4965280405Srpaulo
4966280405Srpaulo<hr><h3><a name="lua_State"><code>lua_State</code></a></h3>
4967280405Srpaulo<pre>typedef struct lua_State lua_State;</pre>
4968280405Srpaulo
4969280405Srpaulo<p>
4970280405SrpauloAn opaque structure that points to a thread and indirectly
4971280405Srpaulo(through the thread) to the whole state of a Lua interpreter.
4972280405SrpauloThe Lua library is fully reentrant:
4973280405Srpauloit has no global variables.
4974280405SrpauloAll information about a state is accessible through this structure.
4975280405Srpaulo
4976280405Srpaulo
4977280405Srpaulo<p>
4978280405SrpauloA pointer to this structure must be passed as the first argument to
4979280405Srpauloevery function in the library, except to <a href="#lua_newstate"><code>lua_newstate</code></a>,
4980280405Srpaulowhich creates a Lua state from scratch.
4981280405Srpaulo
4982280405Srpaulo
4983280405Srpaulo
4984280405Srpaulo
4985280405Srpaulo
4986280405Srpaulo<hr><h3><a name="lua_status"><code>lua_status</code></a></h3><p>
4987280405Srpaulo<span class="apii">[-0, +0, &ndash;]</span>
4988280405Srpaulo<pre>int lua_status (lua_State *L);</pre>
4989280405Srpaulo
4990280405Srpaulo<p>
4991280405SrpauloReturns the status of the thread <code>L</code>.
4992280405Srpaulo
4993280405Srpaulo
4994280405Srpaulo<p>
4995280405SrpauloThe status can be 0 (<a href="#pdf-LUA_OK"><code>LUA_OK</code></a>) for a normal thread,
4996280405Srpauloan error code if the thread finished the execution
4997280405Srpauloof a <a href="#lua_resume"><code>lua_resume</code></a> with an error,
4998280405Srpauloor <a name="pdf-LUA_YIELD"><code>LUA_YIELD</code></a> if the thread is suspended.
4999280405Srpaulo
5000280405Srpaulo
5001280405Srpaulo<p>
5002280405SrpauloYou can only call functions in threads with status <a href="#pdf-LUA_OK"><code>LUA_OK</code></a>.
5003280405SrpauloYou can resume threads with status <a href="#pdf-LUA_OK"><code>LUA_OK</code></a>
5004280405Srpaulo(to start a new coroutine) or <a href="#pdf-LUA_YIELD"><code>LUA_YIELD</code></a>
5005280405Srpaulo(to resume a coroutine).
5006280405Srpaulo
5007280405Srpaulo
5008280405Srpaulo
5009280405Srpaulo
5010280405Srpaulo
5011280405Srpaulo<hr><h3><a name="lua_stringtonumber"><code>lua_stringtonumber</code></a></h3><p>
5012280405Srpaulo<span class="apii">[-0, +1, &ndash;]</span>
5013280405Srpaulo<pre>size_t lua_stringtonumber (lua_State *L, const char *s);</pre>
5014280405Srpaulo
5015280405Srpaulo<p>
5016280405SrpauloConverts the zero-terminated string <code>s</code> to a number,
5017280405Srpaulopushes that number into the stack,
5018280405Srpauloand returns the total size of the string,
5019280405Srpaulothat is, its length plus one.
5020280405SrpauloThe conversion can result in an integer or a float,
5021280405Srpauloaccording to the lexical conventions of Lua (see <a href="#3.1">&sect;3.1</a>).
5022280405SrpauloThe string may have leading and trailing spaces and a sign.
5023280405SrpauloIf the string is not a valid numeral,
5024280405Srpauloreturns 0 and pushes nothing.
5025280405Srpaulo(Note that the result can be used as a boolean,
5026280405Srpaulotrue if the conversion succeeds.)
5027280405Srpaulo
5028280405Srpaulo
5029280405Srpaulo
5030280405Srpaulo
5031280405Srpaulo
5032280405Srpaulo<hr><h3><a name="lua_toboolean"><code>lua_toboolean</code></a></h3><p>
5033280405Srpaulo<span class="apii">[-0, +0, &ndash;]</span>
5034280405Srpaulo<pre>int lua_toboolean (lua_State *L, int index);</pre>
5035280405Srpaulo
5036280405Srpaulo<p>
5037280405SrpauloConverts the Lua value at the given index to a C&nbsp;boolean
5038280405Srpaulovalue (0&nbsp;or&nbsp;1).
5039280405SrpauloLike all tests in Lua,
5040280405Srpaulo<a href="#lua_toboolean"><code>lua_toboolean</code></a> returns true for any Lua value
5041280405Srpaulodifferent from <b>false</b> and <b>nil</b>;
5042280405Srpaulootherwise it returns false.
5043280405Srpaulo(If you want to accept only actual boolean values,
5044280405Srpaulouse <a href="#lua_isboolean"><code>lua_isboolean</code></a> to test the value's type.)
5045280405Srpaulo
5046280405Srpaulo
5047280405Srpaulo
5048280405Srpaulo
5049280405Srpaulo
5050280405Srpaulo<hr><h3><a name="lua_tocfunction"><code>lua_tocfunction</code></a></h3><p>
5051280405Srpaulo<span class="apii">[-0, +0, &ndash;]</span>
5052280405Srpaulo<pre>lua_CFunction lua_tocfunction (lua_State *L, int index);</pre>
5053280405Srpaulo
5054280405Srpaulo<p>
5055280405SrpauloConverts a value at the given index to a C&nbsp;function.
5056280405SrpauloThat value must be a C&nbsp;function;
5057280405Srpaulootherwise, returns <code>NULL</code>.
5058280405Srpaulo
5059280405Srpaulo
5060280405Srpaulo
5061280405Srpaulo
5062280405Srpaulo
5063280405Srpaulo<hr><h3><a name="lua_tointeger"><code>lua_tointeger</code></a></h3><p>
5064280405Srpaulo<span class="apii">[-0, +0, &ndash;]</span>
5065280405Srpaulo<pre>lua_Integer lua_tointeger (lua_State *L, int index);</pre>
5066280405Srpaulo
5067280405Srpaulo<p>
5068280405SrpauloEquivalent to <a href="#lua_tointegerx"><code>lua_tointegerx</code></a> with <code>isnum</code> equal to <code>NULL</code>.
5069280405Srpaulo
5070280405Srpaulo
5071280405Srpaulo
5072280405Srpaulo
5073280405Srpaulo
5074280405Srpaulo<hr><h3><a name="lua_tointegerx"><code>lua_tointegerx</code></a></h3><p>
5075280405Srpaulo<span class="apii">[-0, +0, &ndash;]</span>
5076280405Srpaulo<pre>lua_Integer lua_tointegerx (lua_State *L, int index, int *isnum);</pre>
5077280405Srpaulo
5078280405Srpaulo<p>
5079280405SrpauloConverts the Lua value at the given index
5080280405Srpauloto the signed integral type <a href="#lua_Integer"><code>lua_Integer</code></a>.
5081280405SrpauloThe Lua value must be an integer,
5082280405Srpauloor a number or string convertible to an integer (see <a href="#3.4.3">&sect;3.4.3</a>);
5083280405Srpaulootherwise, <code>lua_tointegerx</code> returns&nbsp;0.
5084280405Srpaulo
5085280405Srpaulo
5086280405Srpaulo<p>
5087280405SrpauloIf <code>isnum</code> is not <code>NULL</code>,
5088280405Srpauloits referent is assigned a boolean value that
5089280405Srpauloindicates whether the operation succeeded.
5090280405Srpaulo
5091280405Srpaulo
5092280405Srpaulo
5093280405Srpaulo
5094280405Srpaulo
5095280405Srpaulo<hr><h3><a name="lua_tolstring"><code>lua_tolstring</code></a></h3><p>
5096326344Simp<span class="apii">[-0, +0, <em>m</em>]</span>
5097280405Srpaulo<pre>const char *lua_tolstring (lua_State *L, int index, size_t *len);</pre>
5098280405Srpaulo
5099280405Srpaulo<p>
5100280405SrpauloConverts the Lua value at the given index to a C&nbsp;string.
5101280405SrpauloIf <code>len</code> is not <code>NULL</code>,
5102326344Simpit sets <code>*len</code> with the string length.
5103280405SrpauloThe Lua value must be a string or a number;
5104280405Srpaulootherwise, the function returns <code>NULL</code>.
5105280405SrpauloIf the value is a number,
5106280405Srpaulothen <code>lua_tolstring</code> also
5107280405Srpaulo<em>changes the actual value in the stack to a string</em>.
5108280405Srpaulo(This change confuses <a href="#lua_next"><code>lua_next</code></a>
5109280405Srpaulowhen <code>lua_tolstring</code> is applied to keys during a table traversal.)
5110280405Srpaulo
5111280405Srpaulo
5112280405Srpaulo<p>
5113326344Simp<code>lua_tolstring</code> returns a pointer
5114280405Srpauloto a string inside the Lua state.
5115280405SrpauloThis string always has a zero ('<code>\0</code>')
5116280405Srpauloafter its last character (as in&nbsp;C),
5117280405Srpaulobut can contain other zeros in its body.
5118280405Srpaulo
5119280405Srpaulo
5120280405Srpaulo<p>
5121280405SrpauloBecause Lua has garbage collection,
5122280405Srpaulothere is no guarantee that the pointer returned by <code>lua_tolstring</code>
5123280405Srpaulowill be valid after the corresponding Lua value is removed from the stack.
5124280405Srpaulo
5125280405Srpaulo
5126280405Srpaulo
5127280405Srpaulo
5128280405Srpaulo
5129280405Srpaulo<hr><h3><a name="lua_tonumber"><code>lua_tonumber</code></a></h3><p>
5130280405Srpaulo<span class="apii">[-0, +0, &ndash;]</span>
5131280405Srpaulo<pre>lua_Number lua_tonumber (lua_State *L, int index);</pre>
5132280405Srpaulo
5133280405Srpaulo<p>
5134280405SrpauloEquivalent to <a href="#lua_tonumberx"><code>lua_tonumberx</code></a> with <code>isnum</code> equal to <code>NULL</code>.
5135280405Srpaulo
5136280405Srpaulo
5137280405Srpaulo
5138280405Srpaulo
5139280405Srpaulo
5140280405Srpaulo<hr><h3><a name="lua_tonumberx"><code>lua_tonumberx</code></a></h3><p>
5141280405Srpaulo<span class="apii">[-0, +0, &ndash;]</span>
5142280405Srpaulo<pre>lua_Number lua_tonumberx (lua_State *L, int index, int *isnum);</pre>
5143280405Srpaulo
5144280405Srpaulo<p>
5145280405SrpauloConverts the Lua value at the given index
5146280405Srpauloto the C&nbsp;type <a href="#lua_Number"><code>lua_Number</code></a> (see <a href="#lua_Number"><code>lua_Number</code></a>).
5147280405SrpauloThe Lua value must be a number or a string convertible to a number
5148280405Srpaulo(see <a href="#3.4.3">&sect;3.4.3</a>);
5149280405Srpaulootherwise, <a href="#lua_tonumberx"><code>lua_tonumberx</code></a> returns&nbsp;0.
5150280405Srpaulo
5151280405Srpaulo
5152280405Srpaulo<p>
5153280405SrpauloIf <code>isnum</code> is not <code>NULL</code>,
5154280405Srpauloits referent is assigned a boolean value that
5155280405Srpauloindicates whether the operation succeeded.
5156280405Srpaulo
5157280405Srpaulo
5158280405Srpaulo
5159280405Srpaulo
5160280405Srpaulo
5161280405Srpaulo<hr><h3><a name="lua_topointer"><code>lua_topointer</code></a></h3><p>
5162280405Srpaulo<span class="apii">[-0, +0, &ndash;]</span>
5163280405Srpaulo<pre>const void *lua_topointer (lua_State *L, int index);</pre>
5164280405Srpaulo
5165280405Srpaulo<p>
5166280405SrpauloConverts the value at the given index to a generic
5167280405SrpauloC&nbsp;pointer (<code>void*</code>).
5168280405SrpauloThe value can be a userdata, a table, a thread, or a function;
5169280405Srpaulootherwise, <code>lua_topointer</code> returns <code>NULL</code>.
5170280405SrpauloDifferent objects will give different pointers.
5171280405SrpauloThere is no way to convert the pointer back to its original value.
5172280405Srpaulo
5173280405Srpaulo
5174280405Srpaulo<p>
5175326344SimpTypically this function is used only for hashing and debug information.
5176280405Srpaulo
5177280405Srpaulo
5178280405Srpaulo
5179280405Srpaulo
5180280405Srpaulo
5181280405Srpaulo<hr><h3><a name="lua_tostring"><code>lua_tostring</code></a></h3><p>
5182326344Simp<span class="apii">[-0, +0, <em>m</em>]</span>
5183280405Srpaulo<pre>const char *lua_tostring (lua_State *L, int index);</pre>
5184280405Srpaulo
5185280405Srpaulo<p>
5186280405SrpauloEquivalent to <a href="#lua_tolstring"><code>lua_tolstring</code></a> with <code>len</code> equal to <code>NULL</code>.
5187280405Srpaulo
5188280405Srpaulo
5189280405Srpaulo
5190280405Srpaulo
5191280405Srpaulo
5192280405Srpaulo<hr><h3><a name="lua_tothread"><code>lua_tothread</code></a></h3><p>
5193280405Srpaulo<span class="apii">[-0, +0, &ndash;]</span>
5194280405Srpaulo<pre>lua_State *lua_tothread (lua_State *L, int index);</pre>
5195280405Srpaulo
5196280405Srpaulo<p>
5197280405SrpauloConverts the value at the given index to a Lua thread
5198280405Srpaulo(represented as <code>lua_State*</code>).
5199280405SrpauloThis value must be a thread;
5200280405Srpaulootherwise, the function returns <code>NULL</code>.
5201280405Srpaulo
5202280405Srpaulo
5203280405Srpaulo
5204280405Srpaulo
5205280405Srpaulo
5206280405Srpaulo<hr><h3><a name="lua_touserdata"><code>lua_touserdata</code></a></h3><p>
5207280405Srpaulo<span class="apii">[-0, +0, &ndash;]</span>
5208280405Srpaulo<pre>void *lua_touserdata (lua_State *L, int index);</pre>
5209280405Srpaulo
5210280405Srpaulo<p>
5211280405SrpauloIf the value at the given index is a full userdata,
5212280405Srpauloreturns its block address.
5213280405SrpauloIf the value is a light userdata,
5214280405Srpauloreturns its pointer.
5215280405SrpauloOtherwise, returns <code>NULL</code>.
5216280405Srpaulo
5217280405Srpaulo
5218280405Srpaulo
5219280405Srpaulo
5220280405Srpaulo
5221280405Srpaulo<hr><h3><a name="lua_type"><code>lua_type</code></a></h3><p>
5222280405Srpaulo<span class="apii">[-0, +0, &ndash;]</span>
5223280405Srpaulo<pre>int lua_type (lua_State *L, int index);</pre>
5224280405Srpaulo
5225280405Srpaulo<p>
5226280405SrpauloReturns the type of the value in the given valid index,
5227280405Srpauloor <code>LUA_TNONE</code> for a non-valid (but acceptable) index.
5228280405SrpauloThe types returned by <a href="#lua_type"><code>lua_type</code></a> are coded by the following constants
5229280405Srpaulodefined in <code>lua.h</code>:
5230326344Simp<a name="pdf-LUA_TNIL"><code>LUA_TNIL</code></a> (0),
5231280405Srpaulo<a name="pdf-LUA_TNUMBER"><code>LUA_TNUMBER</code></a>,
5232280405Srpaulo<a name="pdf-LUA_TBOOLEAN"><code>LUA_TBOOLEAN</code></a>,
5233280405Srpaulo<a name="pdf-LUA_TSTRING"><code>LUA_TSTRING</code></a>,
5234280405Srpaulo<a name="pdf-LUA_TTABLE"><code>LUA_TTABLE</code></a>,
5235280405Srpaulo<a name="pdf-LUA_TFUNCTION"><code>LUA_TFUNCTION</code></a>,
5236280405Srpaulo<a name="pdf-LUA_TUSERDATA"><code>LUA_TUSERDATA</code></a>,
5237280405Srpaulo<a name="pdf-LUA_TTHREAD"><code>LUA_TTHREAD</code></a>,
5238280405Srpauloand
5239280405Srpaulo<a name="pdf-LUA_TLIGHTUSERDATA"><code>LUA_TLIGHTUSERDATA</code></a>.
5240280405Srpaulo
5241280405Srpaulo
5242280405Srpaulo
5243280405Srpaulo
5244280405Srpaulo
5245280405Srpaulo<hr><h3><a name="lua_typename"><code>lua_typename</code></a></h3><p>
5246280405Srpaulo<span class="apii">[-0, +0, &ndash;]</span>
5247280405Srpaulo<pre>const char *lua_typename (lua_State *L, int tp);</pre>
5248280405Srpaulo
5249280405Srpaulo<p>
5250280405SrpauloReturns the name of the type encoded by the value <code>tp</code>,
5251280405Srpaulowhich must be one the values returned by <a href="#lua_type"><code>lua_type</code></a>.
5252280405Srpaulo
5253280405Srpaulo
5254280405Srpaulo
5255280405Srpaulo
5256280405Srpaulo
5257280405Srpaulo<hr><h3><a name="lua_Unsigned"><code>lua_Unsigned</code></a></h3>
5258280405Srpaulo<pre>typedef ... lua_Unsigned;</pre>
5259280405Srpaulo
5260280405Srpaulo<p>
5261280405SrpauloThe unsigned version of <a href="#lua_Integer"><code>lua_Integer</code></a>.
5262280405Srpaulo
5263280405Srpaulo
5264280405Srpaulo
5265280405Srpaulo
5266280405Srpaulo
5267280405Srpaulo<hr><h3><a name="lua_upvalueindex"><code>lua_upvalueindex</code></a></h3><p>
5268280405Srpaulo<span class="apii">[-0, +0, &ndash;]</span>
5269280405Srpaulo<pre>int lua_upvalueindex (int i);</pre>
5270280405Srpaulo
5271280405Srpaulo<p>
5272280405SrpauloReturns the pseudo-index that represents the <code>i</code>-th upvalue of
5273280405Srpaulothe running function (see <a href="#4.4">&sect;4.4</a>).
5274280405Srpaulo
5275280405Srpaulo
5276280405Srpaulo
5277280405Srpaulo
5278280405Srpaulo
5279280405Srpaulo<hr><h3><a name="lua_version"><code>lua_version</code></a></h3><p>
5280326344Simp<span class="apii">[-0, +0, &ndash;]</span>
5281280405Srpaulo<pre>const lua_Number *lua_version (lua_State *L);</pre>
5282280405Srpaulo
5283280405Srpaulo<p>
5284326344SimpReturns the address of the version number
5285326344Simp(a C static variable)
5286326344Simpstored in the Lua core.
5287280405SrpauloWhen called with a valid <a href="#lua_State"><code>lua_State</code></a>,
5288280405Srpauloreturns the address of the version used to create that state.
5289280405SrpauloWhen called with <code>NULL</code>,
5290280405Srpauloreturns the address of the version running the call.
5291280405Srpaulo
5292280405Srpaulo
5293280405Srpaulo
5294280405Srpaulo
5295280405Srpaulo
5296280405Srpaulo<hr><h3><a name="lua_Writer"><code>lua_Writer</code></a></h3>
5297280405Srpaulo<pre>typedef int (*lua_Writer) (lua_State *L,
5298280405Srpaulo                           const void* p,
5299280405Srpaulo                           size_t sz,
5300280405Srpaulo                           void* ud);</pre>
5301280405Srpaulo
5302280405Srpaulo<p>
5303280405SrpauloThe type of the writer function used by <a href="#lua_dump"><code>lua_dump</code></a>.
5304280405SrpauloEvery time it produces another piece of chunk,
5305280405Srpaulo<a href="#lua_dump"><code>lua_dump</code></a> calls the writer,
5306280405Srpaulopassing along the buffer to be written (<code>p</code>),
5307280405Srpauloits size (<code>sz</code>),
5308280405Srpauloand the <code>data</code> parameter supplied to <a href="#lua_dump"><code>lua_dump</code></a>.
5309280405Srpaulo
5310280405Srpaulo
5311280405Srpaulo<p>
5312280405SrpauloThe writer returns an error code:
5313280405Srpaulo0&nbsp;means no errors;
5314280405Srpauloany other value means an error and stops <a href="#lua_dump"><code>lua_dump</code></a> from
5315280405Srpaulocalling the writer again.
5316280405Srpaulo
5317280405Srpaulo
5318280405Srpaulo
5319280405Srpaulo
5320280405Srpaulo
5321280405Srpaulo<hr><h3><a name="lua_xmove"><code>lua_xmove</code></a></h3><p>
5322280405Srpaulo<span class="apii">[-?, +?, &ndash;]</span>
5323280405Srpaulo<pre>void lua_xmove (lua_State *from, lua_State *to, int n);</pre>
5324280405Srpaulo
5325280405Srpaulo<p>
5326280405SrpauloExchange values between different threads of the same state.
5327280405Srpaulo
5328280405Srpaulo
5329280405Srpaulo<p>
5330280405SrpauloThis function pops <code>n</code> values from the stack <code>from</code>,
5331280405Srpauloand pushes them onto the stack <code>to</code>.
5332280405Srpaulo
5333280405Srpaulo
5334280405Srpaulo
5335280405Srpaulo
5336280405Srpaulo
5337280405Srpaulo<hr><h3><a name="lua_yield"><code>lua_yield</code></a></h3><p>
5338280405Srpaulo<span class="apii">[-?, +?, <em>e</em>]</span>
5339280405Srpaulo<pre>int lua_yield (lua_State *L, int nresults);</pre>
5340280405Srpaulo
5341280405Srpaulo<p>
5342280405SrpauloThis function is equivalent to <a href="#lua_yieldk"><code>lua_yieldk</code></a>,
5343280405Srpaulobut it has no continuation (see <a href="#4.7">&sect;4.7</a>).
5344280405SrpauloTherefore, when the thread resumes,
5345280405Srpauloit continues the function that called
5346280405Srpaulothe function calling <code>lua_yield</code>.
5347280405Srpaulo
5348280405Srpaulo
5349280405Srpaulo
5350280405Srpaulo
5351280405Srpaulo
5352280405Srpaulo<hr><h3><a name="lua_yieldk"><code>lua_yieldk</code></a></h3><p>
5353280405Srpaulo<span class="apii">[-?, +?, <em>e</em>]</span>
5354280405Srpaulo<pre>int lua_yieldk (lua_State *L,
5355280405Srpaulo                int nresults,
5356280405Srpaulo                lua_KContext ctx,
5357280405Srpaulo                lua_KFunction k);</pre>
5358280405Srpaulo
5359280405Srpaulo<p>
5360280405SrpauloYields a coroutine (thread).
5361280405Srpaulo
5362280405Srpaulo
5363280405Srpaulo<p>
5364280405SrpauloWhen a C&nbsp;function calls <a href="#lua_yieldk"><code>lua_yieldk</code></a>,
5365280405Srpaulothe running coroutine suspends its execution,
5366280405Srpauloand the call to <a href="#lua_resume"><code>lua_resume</code></a> that started this coroutine returns.
5367280405SrpauloThe parameter <code>nresults</code> is the number of values from the stack
5368280405Srpaulothat will be passed as results to <a href="#lua_resume"><code>lua_resume</code></a>.
5369280405Srpaulo
5370280405Srpaulo
5371280405Srpaulo<p>
5372280405SrpauloWhen the coroutine is resumed again,
5373280405SrpauloLua calls the given continuation function <code>k</code> to continue
5374326344Simpthe execution of the C&nbsp;function that yielded (see <a href="#4.7">&sect;4.7</a>).
5375280405SrpauloThis continuation function receives the same stack
5376280405Srpaulofrom the previous function,
5377280405Srpaulowith the <code>n</code> results removed and
5378280405Srpauloreplaced by the arguments passed to <a href="#lua_resume"><code>lua_resume</code></a>.
5379280405SrpauloMoreover,
5380280405Srpaulothe continuation function receives the value <code>ctx</code>
5381280405Srpaulothat was passed to <a href="#lua_yieldk"><code>lua_yieldk</code></a>.
5382280405Srpaulo
5383280405Srpaulo
5384280405Srpaulo<p>
5385280405SrpauloUsually, this function does not return;
5386280405Srpaulowhen the coroutine eventually resumes,
5387280405Srpauloit continues executing the continuation function.
5388280405SrpauloHowever, there is one special case,
5389280405Srpaulowhich is when this function is called
5390326344Simpfrom inside a line or a count hook (see <a href="#4.9">&sect;4.9</a>).
5391280405SrpauloIn that case, <code>lua_yieldk</code> should be called with no continuation
5392326344Simp(probably in the form of <a href="#lua_yield"><code>lua_yield</code></a>) and no results,
5393280405Srpauloand the hook should return immediately after the call.
5394280405SrpauloLua will yield and,
5395280405Srpaulowhen the coroutine resumes again,
5396280405Srpauloit will continue the normal execution
5397280405Srpauloof the (Lua) function that triggered the hook.
5398280405Srpaulo
5399280405Srpaulo
5400280405Srpaulo<p>
5401280405SrpauloThis function can raise an error if it is called from a thread
5402280405Srpaulowith a pending C call with no continuation function,
5403280405Srpauloor it is called from a thread that is not running inside a resume
5404280405Srpaulo(e.g., the main thread).
5405280405Srpaulo
5406280405Srpaulo
5407280405Srpaulo
5408280405Srpaulo
5409280405Srpaulo
5410280405Srpaulo
5411280405Srpaulo
5412280405Srpaulo<h2>4.9 &ndash; <a name="4.9">The Debug Interface</a></h2>
5413280405Srpaulo
5414280405Srpaulo<p>
5415280405SrpauloLua has no built-in debugging facilities.
5416280405SrpauloInstead, it offers a special interface
5417280405Srpauloby means of functions and <em>hooks</em>.
5418280405SrpauloThis interface allows the construction of different
5419280405Srpaulokinds of debuggers, profilers, and other tools
5420280405Srpaulothat need "inside information" from the interpreter.
5421280405Srpaulo
5422280405Srpaulo
5423280405Srpaulo
5424280405Srpaulo<hr><h3><a name="lua_Debug"><code>lua_Debug</code></a></h3>
5425280405Srpaulo<pre>typedef struct lua_Debug {
5426280405Srpaulo  int event;
5427280405Srpaulo  const char *name;           /* (n) */
5428280405Srpaulo  const char *namewhat;       /* (n) */
5429280405Srpaulo  const char *what;           /* (S) */
5430280405Srpaulo  const char *source;         /* (S) */
5431280405Srpaulo  int currentline;            /* (l) */
5432280405Srpaulo  int linedefined;            /* (S) */
5433280405Srpaulo  int lastlinedefined;        /* (S) */
5434280405Srpaulo  unsigned char nups;         /* (u) number of upvalues */
5435280405Srpaulo  unsigned char nparams;      /* (u) number of parameters */
5436280405Srpaulo  char isvararg;              /* (u) */
5437280405Srpaulo  char istailcall;            /* (t) */
5438280405Srpaulo  char short_src[LUA_IDSIZE]; /* (S) */
5439280405Srpaulo  /* private part */
5440280405Srpaulo  <em>other fields</em>
5441280405Srpaulo} lua_Debug;</pre>
5442280405Srpaulo
5443280405Srpaulo<p>
5444280405SrpauloA structure used to carry different pieces of
5445280405Srpauloinformation about a function or an activation record.
5446280405Srpaulo<a href="#lua_getstack"><code>lua_getstack</code></a> fills only the private part
5447280405Srpauloof this structure, for later use.
5448280405SrpauloTo fill the other fields of <a href="#lua_Debug"><code>lua_Debug</code></a> with useful information,
5449280405Srpaulocall <a href="#lua_getinfo"><code>lua_getinfo</code></a>.
5450280405Srpaulo
5451280405Srpaulo
5452280405Srpaulo<p>
5453280405SrpauloThe fields of <a href="#lua_Debug"><code>lua_Debug</code></a> have the following meaning:
5454280405Srpaulo
5455280405Srpaulo<ul>
5456280405Srpaulo
5457280405Srpaulo<li><b><code>source</code>: </b>
5458280405Srpaulothe name of the chunk that created the function.
5459280405SrpauloIf <code>source</code> starts with a '<code>@</code>',
5460280405Srpauloit means that the function was defined in a file where
5461280405Srpaulothe file name follows the '<code>@</code>'.
5462280405SrpauloIf <code>source</code> starts with a '<code>=</code>',
5463280405Srpaulothe remainder of its contents describe the source in a user-dependent manner.
5464280405SrpauloOtherwise,
5465280405Srpaulothe function was defined in a string where
5466280405Srpaulo<code>source</code> is that string.
5467280405Srpaulo</li>
5468280405Srpaulo
5469280405Srpaulo<li><b><code>short_src</code>: </b>
5470280405Srpauloa "printable" version of <code>source</code>, to be used in error messages.
5471280405Srpaulo</li>
5472280405Srpaulo
5473280405Srpaulo<li><b><code>linedefined</code>: </b>
5474280405Srpaulothe line number where the definition of the function starts.
5475280405Srpaulo</li>
5476280405Srpaulo
5477280405Srpaulo<li><b><code>lastlinedefined</code>: </b>
5478280405Srpaulothe line number where the definition of the function ends.
5479280405Srpaulo</li>
5480280405Srpaulo
5481280405Srpaulo<li><b><code>what</code>: </b>
5482280405Srpaulothe string <code>"Lua"</code> if the function is a Lua function,
5483280405Srpaulo<code>"C"</code> if it is a C&nbsp;function,
5484280405Srpaulo<code>"main"</code> if it is the main part of a chunk.
5485280405Srpaulo</li>
5486280405Srpaulo
5487280405Srpaulo<li><b><code>currentline</code>: </b>
5488280405Srpaulothe current line where the given function is executing.
5489280405SrpauloWhen no line information is available,
5490280405Srpaulo<code>currentline</code> is set to -1.
5491280405Srpaulo</li>
5492280405Srpaulo
5493280405Srpaulo<li><b><code>name</code>: </b>
5494280405Srpauloa reasonable name for the given function.
5495280405SrpauloBecause functions in Lua are first-class values,
5496280405Srpaulothey do not have a fixed name:
5497280405Srpaulosome functions can be the value of multiple global variables,
5498280405Srpaulowhile others can be stored only in a table field.
5499280405SrpauloThe <code>lua_getinfo</code> function checks how the function was
5500280405Srpaulocalled to find a suitable name.
5501280405SrpauloIf it cannot find a name,
5502280405Srpaulothen <code>name</code> is set to <code>NULL</code>.
5503280405Srpaulo</li>
5504280405Srpaulo
5505280405Srpaulo<li><b><code>namewhat</code>: </b>
5506280405Srpauloexplains the <code>name</code> field.
5507280405SrpauloThe value of <code>namewhat</code> can be
5508280405Srpaulo<code>"global"</code>, <code>"local"</code>, <code>"method"</code>,
5509280405Srpaulo<code>"field"</code>, <code>"upvalue"</code>, or <code>""</code> (the empty string),
5510280405Srpauloaccording to how the function was called.
5511280405Srpaulo(Lua uses the empty string when no other option seems to apply.)
5512280405Srpaulo</li>
5513280405Srpaulo
5514280405Srpaulo<li><b><code>istailcall</code>: </b>
5515280405Srpaulotrue if this function invocation was called by a tail call.
5516280405SrpauloIn this case, the caller of this level is not in the stack.
5517280405Srpaulo</li>
5518280405Srpaulo
5519280405Srpaulo<li><b><code>nups</code>: </b>
5520280405Srpaulothe number of upvalues of the function.
5521280405Srpaulo</li>
5522280405Srpaulo
5523280405Srpaulo<li><b><code>nparams</code>: </b>
5524280405Srpaulothe number of fixed parameters of the function
5525280405Srpaulo(always 0&nbsp;for C&nbsp;functions).
5526280405Srpaulo</li>
5527280405Srpaulo
5528280405Srpaulo<li><b><code>isvararg</code>: </b>
5529280405Srpaulotrue if the function is a vararg function
5530280405Srpaulo(always true for C&nbsp;functions).
5531280405Srpaulo</li>
5532280405Srpaulo
5533280405Srpaulo</ul>
5534280405Srpaulo
5535280405Srpaulo
5536280405Srpaulo
5537280405Srpaulo
5538280405Srpaulo<hr><h3><a name="lua_gethook"><code>lua_gethook</code></a></h3><p>
5539280405Srpaulo<span class="apii">[-0, +0, &ndash;]</span>
5540280405Srpaulo<pre>lua_Hook lua_gethook (lua_State *L);</pre>
5541280405Srpaulo
5542280405Srpaulo<p>
5543280405SrpauloReturns the current hook function.
5544280405Srpaulo
5545280405Srpaulo
5546280405Srpaulo
5547280405Srpaulo
5548280405Srpaulo
5549280405Srpaulo<hr><h3><a name="lua_gethookcount"><code>lua_gethookcount</code></a></h3><p>
5550280405Srpaulo<span class="apii">[-0, +0, &ndash;]</span>
5551280405Srpaulo<pre>int lua_gethookcount (lua_State *L);</pre>
5552280405Srpaulo
5553280405Srpaulo<p>
5554280405SrpauloReturns the current hook count.
5555280405Srpaulo
5556280405Srpaulo
5557280405Srpaulo
5558280405Srpaulo
5559280405Srpaulo
5560280405Srpaulo<hr><h3><a name="lua_gethookmask"><code>lua_gethookmask</code></a></h3><p>
5561280405Srpaulo<span class="apii">[-0, +0, &ndash;]</span>
5562280405Srpaulo<pre>int lua_gethookmask (lua_State *L);</pre>
5563280405Srpaulo
5564280405Srpaulo<p>
5565280405SrpauloReturns the current hook mask.
5566280405Srpaulo
5567280405Srpaulo
5568280405Srpaulo
5569280405Srpaulo
5570280405Srpaulo
5571280405Srpaulo<hr><h3><a name="lua_getinfo"><code>lua_getinfo</code></a></h3><p>
5572280405Srpaulo<span class="apii">[-(0|1), +(0|1|2), <em>e</em>]</span>
5573280405Srpaulo<pre>int lua_getinfo (lua_State *L, const char *what, lua_Debug *ar);</pre>
5574280405Srpaulo
5575280405Srpaulo<p>
5576280405SrpauloGets information about a specific function or function invocation.
5577280405Srpaulo
5578280405Srpaulo
5579280405Srpaulo<p>
5580280405SrpauloTo get information about a function invocation,
5581280405Srpaulothe parameter <code>ar</code> must be a valid activation record that was
5582280405Srpaulofilled by a previous call to <a href="#lua_getstack"><code>lua_getstack</code></a> or
5583280405Srpaulogiven as argument to a hook (see <a href="#lua_Hook"><code>lua_Hook</code></a>).
5584280405Srpaulo
5585280405Srpaulo
5586280405Srpaulo<p>
5587280405SrpauloTo get information about a function you push it onto the stack
5588280405Srpauloand start the <code>what</code> string with the character '<code>&gt;</code>'.
5589280405Srpaulo(In that case,
5590280405Srpaulo<code>lua_getinfo</code> pops the function from the top of the stack.)
5591280405SrpauloFor instance, to know in which line a function <code>f</code> was defined,
5592280405Srpauloyou can write the following code:
5593280405Srpaulo
5594280405Srpaulo<pre>
5595280405Srpaulo     lua_Debug ar;
5596280405Srpaulo     lua_getglobal(L, "f");  /* get global 'f' */
5597280405Srpaulo     lua_getinfo(L, "&gt;S", &amp;ar);
5598280405Srpaulo     printf("%d\n", ar.linedefined);
5599280405Srpaulo</pre>
5600280405Srpaulo
5601280405Srpaulo<p>
5602280405SrpauloEach character in the string <code>what</code>
5603280405Srpauloselects some fields of the structure <code>ar</code> to be filled or
5604280405Srpauloa value to be pushed on the stack:
5605280405Srpaulo
5606280405Srpaulo<ul>
5607280405Srpaulo
5608280405Srpaulo<li><b>'<code>n</code>': </b> fills in the field <code>name</code> and <code>namewhat</code>;
5609280405Srpaulo</li>
5610280405Srpaulo
5611280405Srpaulo<li><b>'<code>S</code>': </b>
5612280405Srpaulofills in the fields <code>source</code>, <code>short_src</code>,
5613280405Srpaulo<code>linedefined</code>, <code>lastlinedefined</code>, and <code>what</code>;
5614280405Srpaulo</li>
5615280405Srpaulo
5616280405Srpaulo<li><b>'<code>l</code>': </b> fills in the field <code>currentline</code>;
5617280405Srpaulo</li>
5618280405Srpaulo
5619280405Srpaulo<li><b>'<code>t</code>': </b> fills in the field <code>istailcall</code>;
5620280405Srpaulo</li>
5621280405Srpaulo
5622280405Srpaulo<li><b>'<code>u</code>': </b> fills in the fields
5623280405Srpaulo<code>nups</code>, <code>nparams</code>, and <code>isvararg</code>;
5624280405Srpaulo</li>
5625280405Srpaulo
5626280405Srpaulo<li><b>'<code>f</code>': </b>
5627280405Srpaulopushes onto the stack the function that is
5628280405Srpaulorunning at the given level;
5629280405Srpaulo</li>
5630280405Srpaulo
5631280405Srpaulo<li><b>'<code>L</code>': </b>
5632280405Srpaulopushes onto the stack a table whose indices are the
5633280405Srpaulonumbers of the lines that are valid on the function.
5634280405Srpaulo(A <em>valid line</em> is a line with some associated code,
5635280405Srpaulothat is, a line where you can put a break point.
5636280405SrpauloNon-valid lines include empty lines and comments.)
5637280405Srpaulo
5638280405Srpaulo
5639280405Srpaulo<p>
5640280405SrpauloIf this option is given together with option '<code>f</code>',
5641280405Srpauloits table is pushed after the function.
5642280405Srpaulo</li>
5643280405Srpaulo
5644280405Srpaulo</ul>
5645280405Srpaulo
5646280405Srpaulo<p>
5647280405SrpauloThis function returns 0 on error
5648280405Srpaulo(for instance, an invalid option in <code>what</code>).
5649280405Srpaulo
5650280405Srpaulo
5651280405Srpaulo
5652280405Srpaulo
5653280405Srpaulo
5654280405Srpaulo<hr><h3><a name="lua_getlocal"><code>lua_getlocal</code></a></h3><p>
5655280405Srpaulo<span class="apii">[-0, +(0|1), &ndash;]</span>
5656280405Srpaulo<pre>const char *lua_getlocal (lua_State *L, const lua_Debug *ar, int n);</pre>
5657280405Srpaulo
5658280405Srpaulo<p>
5659280405SrpauloGets information about a local variable of
5660280405Srpauloa given activation record or a given function.
5661280405Srpaulo
5662280405Srpaulo
5663280405Srpaulo<p>
5664280405SrpauloIn the first case,
5665280405Srpaulothe parameter <code>ar</code> must be a valid activation record that was
5666280405Srpaulofilled by a previous call to <a href="#lua_getstack"><code>lua_getstack</code></a> or
5667280405Srpaulogiven as argument to a hook (see <a href="#lua_Hook"><code>lua_Hook</code></a>).
5668280405SrpauloThe index <code>n</code> selects which local variable to inspect;
5669280405Srpaulosee <a href="#pdf-debug.getlocal"><code>debug.getlocal</code></a> for details about variable indices
5670280405Srpauloand names.
5671280405Srpaulo
5672280405Srpaulo
5673280405Srpaulo<p>
5674280405Srpaulo<a href="#lua_getlocal"><code>lua_getlocal</code></a> pushes the variable's value onto the stack
5675280405Srpauloand returns its name.
5676280405Srpaulo
5677280405Srpaulo
5678280405Srpaulo<p>
5679280405SrpauloIn the second case, <code>ar</code> must be <code>NULL</code> and the function
5680280405Srpauloto be inspected must be at the top of the stack.
5681280405SrpauloIn this case, only parameters of Lua functions are visible
5682280405Srpaulo(as there is no information about what variables are active)
5683280405Srpauloand no values are pushed onto the stack.
5684280405Srpaulo
5685280405Srpaulo
5686280405Srpaulo<p>
5687280405SrpauloReturns <code>NULL</code> (and pushes nothing)
5688280405Srpaulowhen the index is greater than
5689280405Srpaulothe number of active local variables.
5690280405Srpaulo
5691280405Srpaulo
5692280405Srpaulo
5693280405Srpaulo
5694280405Srpaulo
5695280405Srpaulo<hr><h3><a name="lua_getstack"><code>lua_getstack</code></a></h3><p>
5696280405Srpaulo<span class="apii">[-0, +0, &ndash;]</span>
5697280405Srpaulo<pre>int lua_getstack (lua_State *L, int level, lua_Debug *ar);</pre>
5698280405Srpaulo
5699280405Srpaulo<p>
5700280405SrpauloGets information about the interpreter runtime stack.
5701280405Srpaulo
5702280405Srpaulo
5703280405Srpaulo<p>
5704280405SrpauloThis function fills parts of a <a href="#lua_Debug"><code>lua_Debug</code></a> structure with
5705280405Srpauloan identification of the <em>activation record</em>
5706280405Srpauloof the function executing at a given level.
5707280405SrpauloLevel&nbsp;0 is the current running function,
5708280405Srpaulowhereas level <em>n+1</em> is the function that has called level <em>n</em>
5709280405Srpaulo(except for tail calls, which do not count on the stack).
5710280405SrpauloWhen there are no errors, <a href="#lua_getstack"><code>lua_getstack</code></a> returns 1;
5711280405Srpaulowhen called with a level greater than the stack depth,
5712280405Srpauloit returns 0.
5713280405Srpaulo
5714280405Srpaulo
5715280405Srpaulo
5716280405Srpaulo
5717280405Srpaulo
5718280405Srpaulo<hr><h3><a name="lua_getupvalue"><code>lua_getupvalue</code></a></h3><p>
5719280405Srpaulo<span class="apii">[-0, +(0|1), &ndash;]</span>
5720280405Srpaulo<pre>const char *lua_getupvalue (lua_State *L, int funcindex, int n);</pre>
5721280405Srpaulo
5722280405Srpaulo<p>
5723326344SimpGets information about the <code>n</code>-th upvalue
5724326344Simpof the closure at index <code>funcindex</code>.
5725326344SimpIt pushes the upvalue's value onto the stack
5726280405Srpauloand returns its name.
5727326344SimpReturns <code>NULL</code> (and pushes nothing)
5728326344Simpwhen the index <code>n</code> is greater than the number of upvalues.
5729280405Srpaulo
5730280405Srpaulo
5731280405Srpaulo<p>
5732280405SrpauloFor C&nbsp;functions, this function uses the empty string <code>""</code>
5733280405Srpauloas a name for all upvalues.
5734326344Simp(For Lua functions,
5735326344Simpupvalues are the external local variables that the function uses,
5736326344Simpand that are consequently included in its closure.)
5737280405Srpaulo
5738280405Srpaulo
5739326344Simp<p>
5740326344SimpUpvalues have no particular order,
5741326344Simpas they are active through the whole function.
5742326344SimpThey are numbered in an arbitrary order.
5743280405Srpaulo
5744280405Srpaulo
5745280405Srpaulo
5746326344Simp
5747326344Simp
5748280405Srpaulo<hr><h3><a name="lua_Hook"><code>lua_Hook</code></a></h3>
5749280405Srpaulo<pre>typedef void (*lua_Hook) (lua_State *L, lua_Debug *ar);</pre>
5750280405Srpaulo
5751280405Srpaulo<p>
5752280405SrpauloType for debugging hook functions.
5753280405Srpaulo
5754280405Srpaulo
5755280405Srpaulo<p>
5756280405SrpauloWhenever a hook is called, its <code>ar</code> argument has its field
5757280405Srpaulo<code>event</code> set to the specific event that triggered the hook.
5758280405SrpauloLua identifies these events with the following constants:
5759280405Srpaulo<a name="pdf-LUA_HOOKCALL"><code>LUA_HOOKCALL</code></a>, <a name="pdf-LUA_HOOKRET"><code>LUA_HOOKRET</code></a>,
5760280405Srpaulo<a name="pdf-LUA_HOOKTAILCALL"><code>LUA_HOOKTAILCALL</code></a>, <a name="pdf-LUA_HOOKLINE"><code>LUA_HOOKLINE</code></a>,
5761280405Srpauloand <a name="pdf-LUA_HOOKCOUNT"><code>LUA_HOOKCOUNT</code></a>.
5762280405SrpauloMoreover, for line events, the field <code>currentline</code> is also set.
5763280405SrpauloTo get the value of any other field in <code>ar</code>,
5764280405Srpaulothe hook must call <a href="#lua_getinfo"><code>lua_getinfo</code></a>.
5765280405Srpaulo
5766280405Srpaulo
5767280405Srpaulo<p>
5768280405SrpauloFor call events, <code>event</code> can be <code>LUA_HOOKCALL</code>,
5769280405Srpaulothe normal value, or <code>LUA_HOOKTAILCALL</code>, for a tail call;
5770280405Srpauloin this case, there will be no corresponding return event.
5771280405Srpaulo
5772280405Srpaulo
5773280405Srpaulo<p>
5774280405SrpauloWhile Lua is running a hook, it disables other calls to hooks.
5775280405SrpauloTherefore, if a hook calls back Lua to execute a function or a chunk,
5776280405Srpaulothis execution occurs without any calls to hooks.
5777280405Srpaulo
5778280405Srpaulo
5779280405Srpaulo<p>
5780280405SrpauloHook functions cannot have continuations,
5781280405Srpaulothat is, they cannot call <a href="#lua_yieldk"><code>lua_yieldk</code></a>,
5782280405Srpaulo<a href="#lua_pcallk"><code>lua_pcallk</code></a>, or <a href="#lua_callk"><code>lua_callk</code></a> with a non-null <code>k</code>.
5783280405Srpaulo
5784280405Srpaulo
5785280405Srpaulo<p>
5786280405SrpauloHook functions can yield under the following conditions:
5787326344SimpOnly count and line events can yield;
5788326344Simpto yield, a hook function must finish its execution
5789326344Simpcalling <a href="#lua_yield"><code>lua_yield</code></a> with <code>nresults</code> equal to zero
5790326344Simp(that is, with no values).
5791280405Srpaulo
5792280405Srpaulo
5793280405Srpaulo
5794280405Srpaulo
5795280405Srpaulo
5796280405Srpaulo<hr><h3><a name="lua_sethook"><code>lua_sethook</code></a></h3><p>
5797280405Srpaulo<span class="apii">[-0, +0, &ndash;]</span>
5798280405Srpaulo<pre>void lua_sethook (lua_State *L, lua_Hook f, int mask, int count);</pre>
5799280405Srpaulo
5800280405Srpaulo<p>
5801280405SrpauloSets the debugging hook function.
5802280405Srpaulo
5803280405Srpaulo
5804280405Srpaulo<p>
5805280405SrpauloArgument <code>f</code> is the hook function.
5806280405Srpaulo<code>mask</code> specifies on which events the hook will be called:
5807326344Simpit is formed by a bitwise OR of the constants
5808280405Srpaulo<a name="pdf-LUA_MASKCALL"><code>LUA_MASKCALL</code></a>,
5809280405Srpaulo<a name="pdf-LUA_MASKRET"><code>LUA_MASKRET</code></a>,
5810280405Srpaulo<a name="pdf-LUA_MASKLINE"><code>LUA_MASKLINE</code></a>,
5811280405Srpauloand <a name="pdf-LUA_MASKCOUNT"><code>LUA_MASKCOUNT</code></a>.
5812280405SrpauloThe <code>count</code> argument is only meaningful when the mask
5813280405Srpauloincludes <code>LUA_MASKCOUNT</code>.
5814280405SrpauloFor each event, the hook is called as explained below:
5815280405Srpaulo
5816280405Srpaulo<ul>
5817280405Srpaulo
5818280405Srpaulo<li><b>The call hook: </b> is called when the interpreter calls a function.
5819280405SrpauloThe hook is called just after Lua enters the new function,
5820280405Srpaulobefore the function gets its arguments.
5821280405Srpaulo</li>
5822280405Srpaulo
5823280405Srpaulo<li><b>The return hook: </b> is called when the interpreter returns from a function.
5824280405SrpauloThe hook is called just before Lua leaves the function.
5825280405SrpauloThere is no standard way to access the values
5826280405Srpauloto be returned by the function.
5827280405Srpaulo</li>
5828280405Srpaulo
5829280405Srpaulo<li><b>The line hook: </b> is called when the interpreter is about to
5830280405Srpaulostart the execution of a new line of code,
5831280405Srpauloor when it jumps back in the code (even to the same line).
5832280405Srpaulo(This event only happens while Lua is executing a Lua function.)
5833280405Srpaulo</li>
5834280405Srpaulo
5835280405Srpaulo<li><b>The count hook: </b> is called after the interpreter executes every
5836280405Srpaulo<code>count</code> instructions.
5837280405Srpaulo(This event only happens while Lua is executing a Lua function.)
5838280405Srpaulo</li>
5839280405Srpaulo
5840280405Srpaulo</ul>
5841280405Srpaulo
5842280405Srpaulo<p>
5843280405SrpauloA hook is disabled by setting <code>mask</code> to zero.
5844280405Srpaulo
5845280405Srpaulo
5846280405Srpaulo
5847280405Srpaulo
5848280405Srpaulo
5849280405Srpaulo<hr><h3><a name="lua_setlocal"><code>lua_setlocal</code></a></h3><p>
5850280405Srpaulo<span class="apii">[-(0|1), +0, &ndash;]</span>
5851280405Srpaulo<pre>const char *lua_setlocal (lua_State *L, const lua_Debug *ar, int n);</pre>
5852280405Srpaulo
5853280405Srpaulo<p>
5854280405SrpauloSets the value of a local variable of a given activation record.
5855326344SimpIt assigns the value at the top of the stack
5856280405Srpauloto the variable and returns its name.
5857280405SrpauloIt also pops the value from the stack.
5858280405Srpaulo
5859280405Srpaulo
5860280405Srpaulo<p>
5861280405SrpauloReturns <code>NULL</code> (and pops nothing)
5862280405Srpaulowhen the index is greater than
5863280405Srpaulothe number of active local variables.
5864280405Srpaulo
5865280405Srpaulo
5866326344Simp<p>
5867326344SimpParameters <code>ar</code> and <code>n</code> are as in function <a href="#lua_getlocal"><code>lua_getlocal</code></a>.
5868280405Srpaulo
5869280405Srpaulo
5870280405Srpaulo
5871326344Simp
5872326344Simp
5873280405Srpaulo<hr><h3><a name="lua_setupvalue"><code>lua_setupvalue</code></a></h3><p>
5874280405Srpaulo<span class="apii">[-(0|1), +0, &ndash;]</span>
5875280405Srpaulo<pre>const char *lua_setupvalue (lua_State *L, int funcindex, int n);</pre>
5876280405Srpaulo
5877280405Srpaulo<p>
5878280405SrpauloSets the value of a closure's upvalue.
5879280405SrpauloIt assigns the value at the top of the stack
5880280405Srpauloto the upvalue and returns its name.
5881280405SrpauloIt also pops the value from the stack.
5882280405Srpaulo
5883280405Srpaulo
5884280405Srpaulo<p>
5885280405SrpauloReturns <code>NULL</code> (and pops nothing)
5886326344Simpwhen the index <code>n</code> is greater than the number of upvalues.
5887280405Srpaulo
5888280405Srpaulo
5889326344Simp<p>
5890326344SimpParameters <code>funcindex</code> and <code>n</code> are as in function <a href="#lua_getupvalue"><code>lua_getupvalue</code></a>.
5891280405Srpaulo
5892280405Srpaulo
5893280405Srpaulo
5894326344Simp
5895326344Simp
5896280405Srpaulo<hr><h3><a name="lua_upvalueid"><code>lua_upvalueid</code></a></h3><p>
5897280405Srpaulo<span class="apii">[-0, +0, &ndash;]</span>
5898280405Srpaulo<pre>void *lua_upvalueid (lua_State *L, int funcindex, int n);</pre>
5899280405Srpaulo
5900280405Srpaulo<p>
5901280405SrpauloReturns a unique identifier for the upvalue numbered <code>n</code>
5902280405Srpaulofrom the closure at index <code>funcindex</code>.
5903280405Srpaulo
5904280405Srpaulo
5905280405Srpaulo<p>
5906280405SrpauloThese unique identifiers allow a program to check whether different
5907280405Srpauloclosures share upvalues.
5908280405SrpauloLua closures that share an upvalue
5909280405Srpaulo(that is, that access a same external local variable)
5910280405Srpaulowill return identical ids for those upvalue indices.
5911280405Srpaulo
5912280405Srpaulo
5913326344Simp<p>
5914326344SimpParameters <code>funcindex</code> and <code>n</code> are as in function <a href="#lua_getupvalue"><code>lua_getupvalue</code></a>,
5915326344Simpbut <code>n</code> cannot be greater than the number of upvalues.
5916280405Srpaulo
5917280405Srpaulo
5918280405Srpaulo
5919326344Simp
5920326344Simp
5921280405Srpaulo<hr><h3><a name="lua_upvaluejoin"><code>lua_upvaluejoin</code></a></h3><p>
5922280405Srpaulo<span class="apii">[-0, +0, &ndash;]</span>
5923280405Srpaulo<pre>void lua_upvaluejoin (lua_State *L, int funcindex1, int n1,
5924280405Srpaulo                                    int funcindex2, int n2);</pre>
5925280405Srpaulo
5926280405Srpaulo<p>
5927280405SrpauloMake the <code>n1</code>-th upvalue of the Lua closure at index <code>funcindex1</code>
5928280405Srpaulorefer to the <code>n2</code>-th upvalue of the Lua closure at index <code>funcindex2</code>.
5929280405Srpaulo
5930280405Srpaulo
5931280405Srpaulo
5932280405Srpaulo
5933280405Srpaulo
5934280405Srpaulo
5935280405Srpaulo
5936280405Srpaulo<h1>5 &ndash; <a name="5">The Auxiliary Library</a></h1>
5937280405Srpaulo
5938280405Srpaulo<p>
5939280405Srpaulo
5940280405SrpauloThe <em>auxiliary library</em> provides several convenient functions
5941280405Srpauloto interface C with Lua.
5942280405SrpauloWhile the basic API provides the primitive functions for all
5943280405Srpaulointeractions between C and Lua,
5944280405Srpaulothe auxiliary library provides higher-level functions for some
5945280405Srpaulocommon tasks.
5946280405Srpaulo
5947280405Srpaulo
5948280405Srpaulo<p>
5949280405SrpauloAll functions and types from the auxiliary library
5950280405Srpauloare defined in header file <code>lauxlib.h</code> and
5951280405Srpaulohave a prefix <code>luaL_</code>.
5952280405Srpaulo
5953280405Srpaulo
5954280405Srpaulo<p>
5955280405SrpauloAll functions in the auxiliary library are built on
5956280405Srpaulotop of the basic API,
5957280405Srpauloand so they provide nothing that cannot be done with that API.
5958280405SrpauloNevertheless, the use of the auxiliary library ensures
5959280405Srpaulomore consistency to your code.
5960280405Srpaulo
5961280405Srpaulo
5962280405Srpaulo<p>
5963280405SrpauloSeveral functions in the auxiliary library use internally some
5964280405Srpauloextra stack slots.
5965280405SrpauloWhen a function in the auxiliary library uses less than five slots,
5966280405Srpauloit does not check the stack size;
5967280405Srpauloit simply assumes that there are enough slots.
5968280405Srpaulo
5969280405Srpaulo
5970280405Srpaulo<p>
5971280405SrpauloSeveral functions in the auxiliary library are used to
5972280405Srpaulocheck C&nbsp;function arguments.
5973280405SrpauloBecause the error message is formatted for arguments
5974280405Srpaulo(e.g., "<code>bad argument #1</code>"),
5975280405Srpauloyou should not use these functions for other stack values.
5976280405Srpaulo
5977280405Srpaulo
5978280405Srpaulo<p>
5979280405SrpauloFunctions called <code>luaL_check*</code>
5980280405Srpauloalways raise an error if the check is not satisfied.
5981280405Srpaulo
5982280405Srpaulo
5983280405Srpaulo
5984280405Srpaulo<h2>5.1 &ndash; <a name="5.1">Functions and Types</a></h2>
5985280405Srpaulo
5986280405Srpaulo<p>
5987280405SrpauloHere we list all functions and types from the auxiliary library
5988280405Srpauloin alphabetical order.
5989280405Srpaulo
5990280405Srpaulo
5991280405Srpaulo
5992280405Srpaulo<hr><h3><a name="luaL_addchar"><code>luaL_addchar</code></a></h3><p>
5993326344Simp<span class="apii">[-?, +?, <em>m</em>]</span>
5994280405Srpaulo<pre>void luaL_addchar (luaL_Buffer *B, char c);</pre>
5995280405Srpaulo
5996280405Srpaulo<p>
5997280405SrpauloAdds the byte <code>c</code> to the buffer <code>B</code>
5998280405Srpaulo(see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>).
5999280405Srpaulo
6000280405Srpaulo
6001280405Srpaulo
6002280405Srpaulo
6003280405Srpaulo
6004280405Srpaulo<hr><h3><a name="luaL_addlstring"><code>luaL_addlstring</code></a></h3><p>
6005326344Simp<span class="apii">[-?, +?, <em>m</em>]</span>
6006280405Srpaulo<pre>void luaL_addlstring (luaL_Buffer *B, const char *s, size_t l);</pre>
6007280405Srpaulo
6008280405Srpaulo<p>
6009280405SrpauloAdds the string pointed to by <code>s</code> with length <code>l</code> to
6010280405Srpaulothe buffer <code>B</code>
6011280405Srpaulo(see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>).
6012280405SrpauloThe string can contain embedded zeros.
6013280405Srpaulo
6014280405Srpaulo
6015280405Srpaulo
6016280405Srpaulo
6017280405Srpaulo
6018280405Srpaulo<hr><h3><a name="luaL_addsize"><code>luaL_addsize</code></a></h3><p>
6019326344Simp<span class="apii">[-?, +?, &ndash;]</span>
6020280405Srpaulo<pre>void luaL_addsize (luaL_Buffer *B, size_t n);</pre>
6021280405Srpaulo
6022280405Srpaulo<p>
6023280405SrpauloAdds to the buffer <code>B</code> (see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>)
6024280405Srpauloa string of length <code>n</code> previously copied to the
6025280405Srpaulobuffer area (see <a href="#luaL_prepbuffer"><code>luaL_prepbuffer</code></a>).
6026280405Srpaulo
6027280405Srpaulo
6028280405Srpaulo
6029280405Srpaulo
6030280405Srpaulo
6031280405Srpaulo<hr><h3><a name="luaL_addstring"><code>luaL_addstring</code></a></h3><p>
6032326344Simp<span class="apii">[-?, +?, <em>m</em>]</span>
6033280405Srpaulo<pre>void luaL_addstring (luaL_Buffer *B, const char *s);</pre>
6034280405Srpaulo
6035280405Srpaulo<p>
6036280405SrpauloAdds the zero-terminated string pointed to by <code>s</code>
6037280405Srpauloto the buffer <code>B</code>
6038280405Srpaulo(see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>).
6039280405Srpaulo
6040280405Srpaulo
6041280405Srpaulo
6042280405Srpaulo
6043280405Srpaulo
6044280405Srpaulo<hr><h3><a name="luaL_addvalue"><code>luaL_addvalue</code></a></h3><p>
6045326344Simp<span class="apii">[-1, +?, <em>m</em>]</span>
6046280405Srpaulo<pre>void luaL_addvalue (luaL_Buffer *B);</pre>
6047280405Srpaulo
6048280405Srpaulo<p>
6049280405SrpauloAdds the value at the top of the stack
6050280405Srpauloto the buffer <code>B</code>
6051280405Srpaulo(see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>).
6052280405SrpauloPops the value.
6053280405Srpaulo
6054280405Srpaulo
6055280405Srpaulo<p>
6056280405SrpauloThis is the only function on string buffers that can (and must)
6057280405Srpaulobe called with an extra element on the stack,
6058280405Srpaulowhich is the value to be added to the buffer.
6059280405Srpaulo
6060280405Srpaulo
6061280405Srpaulo
6062280405Srpaulo
6063280405Srpaulo
6064280405Srpaulo<hr><h3><a name="luaL_argcheck"><code>luaL_argcheck</code></a></h3><p>
6065280405Srpaulo<span class="apii">[-0, +0, <em>v</em>]</span>
6066280405Srpaulo<pre>void luaL_argcheck (lua_State *L,
6067280405Srpaulo                    int cond,
6068280405Srpaulo                    int arg,
6069280405Srpaulo                    const char *extramsg);</pre>
6070280405Srpaulo
6071280405Srpaulo<p>
6072280405SrpauloChecks whether <code>cond</code> is true.
6073280405SrpauloIf it is not, raises an error with a standard message (see <a href="#luaL_argerror"><code>luaL_argerror</code></a>).
6074280405Srpaulo
6075280405Srpaulo
6076280405Srpaulo
6077280405Srpaulo
6078280405Srpaulo
6079280405Srpaulo<hr><h3><a name="luaL_argerror"><code>luaL_argerror</code></a></h3><p>
6080280405Srpaulo<span class="apii">[-0, +0, <em>v</em>]</span>
6081280405Srpaulo<pre>int luaL_argerror (lua_State *L, int arg, const char *extramsg);</pre>
6082280405Srpaulo
6083280405Srpaulo<p>
6084280405SrpauloRaises an error reporting a problem with argument <code>arg</code>
6085326344Simpof the C&nbsp;function that called it,
6086280405Srpaulousing a standard message
6087280405Srpaulothat includes <code>extramsg</code> as a comment:
6088280405Srpaulo
6089280405Srpaulo<pre>
6090280405Srpaulo     bad argument #<em>arg</em> to '<em>funcname</em>' (<em>extramsg</em>)
6091280405Srpaulo</pre><p>
6092280405SrpauloThis function never returns.
6093280405Srpaulo
6094280405Srpaulo
6095280405Srpaulo
6096280405Srpaulo
6097280405Srpaulo
6098280405Srpaulo<hr><h3><a name="luaL_Buffer"><code>luaL_Buffer</code></a></h3>
6099280405Srpaulo<pre>typedef struct luaL_Buffer luaL_Buffer;</pre>
6100280405Srpaulo
6101280405Srpaulo<p>
6102280405SrpauloType for a <em>string buffer</em>.
6103280405Srpaulo
6104280405Srpaulo
6105280405Srpaulo<p>
6106280405SrpauloA string buffer allows C&nbsp;code to build Lua strings piecemeal.
6107280405SrpauloIts pattern of use is as follows:
6108280405Srpaulo
6109280405Srpaulo<ul>
6110280405Srpaulo
6111280405Srpaulo<li>First declare a variable <code>b</code> of type <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>.</li>
6112280405Srpaulo
6113280405Srpaulo<li>Then initialize it with a call <code>luaL_buffinit(L, &amp;b)</code>.</li>
6114280405Srpaulo
6115280405Srpaulo<li>
6116280405SrpauloThen add string pieces to the buffer calling any of
6117280405Srpaulothe <code>luaL_add*</code> functions.
6118280405Srpaulo</li>
6119280405Srpaulo
6120280405Srpaulo<li>
6121280405SrpauloFinish by calling <code>luaL_pushresult(&amp;b)</code>.
6122280405SrpauloThis call leaves the final string on the top of the stack.
6123280405Srpaulo</li>
6124280405Srpaulo
6125280405Srpaulo</ul>
6126280405Srpaulo
6127280405Srpaulo<p>
6128280405SrpauloIf you know beforehand the total size of the resulting string,
6129280405Srpauloyou can use the buffer like this:
6130280405Srpaulo
6131280405Srpaulo<ul>
6132280405Srpaulo
6133280405Srpaulo<li>First declare a variable <code>b</code> of type <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>.</li>
6134280405Srpaulo
6135280405Srpaulo<li>Then initialize it and preallocate a space of
6136280405Srpaulosize <code>sz</code> with a call <code>luaL_buffinitsize(L, &amp;b, sz)</code>.</li>
6137280405Srpaulo
6138280405Srpaulo<li>Then copy the string into that space.</li>
6139280405Srpaulo
6140280405Srpaulo<li>
6141280405SrpauloFinish by calling <code>luaL_pushresultsize(&amp;b, sz)</code>,
6142280405Srpaulowhere <code>sz</code> is the total size of the resulting string
6143280405Srpaulocopied into that space.
6144280405Srpaulo</li>
6145280405Srpaulo
6146280405Srpaulo</ul>
6147280405Srpaulo
6148280405Srpaulo<p>
6149280405SrpauloDuring its normal operation,
6150280405Srpauloa string buffer uses a variable number of stack slots.
6151280405SrpauloSo, while using a buffer, you cannot assume that you know where
6152280405Srpaulothe top of the stack is.
6153280405SrpauloYou can use the stack between successive calls to buffer operations
6154280405Srpauloas long as that use is balanced;
6155280405Srpaulothat is,
6156280405Srpaulowhen you call a buffer operation,
6157280405Srpaulothe stack is at the same level
6158280405Srpauloit was immediately after the previous buffer operation.
6159280405Srpaulo(The only exception to this rule is <a href="#luaL_addvalue"><code>luaL_addvalue</code></a>.)
6160280405SrpauloAfter calling <a href="#luaL_pushresult"><code>luaL_pushresult</code></a> the stack is back to its
6161280405Srpaulolevel when the buffer was initialized,
6162280405Srpauloplus the final string on its top.
6163280405Srpaulo
6164280405Srpaulo
6165280405Srpaulo
6166280405Srpaulo
6167280405Srpaulo
6168280405Srpaulo<hr><h3><a name="luaL_buffinit"><code>luaL_buffinit</code></a></h3><p>
6169280405Srpaulo<span class="apii">[-0, +0, &ndash;]</span>
6170280405Srpaulo<pre>void luaL_buffinit (lua_State *L, luaL_Buffer *B);</pre>
6171280405Srpaulo
6172280405Srpaulo<p>
6173280405SrpauloInitializes a buffer <code>B</code>.
6174280405SrpauloThis function does not allocate any space;
6175280405Srpaulothe buffer must be declared as a variable
6176280405Srpaulo(see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>).
6177280405Srpaulo
6178280405Srpaulo
6179280405Srpaulo
6180280405Srpaulo
6181280405Srpaulo
6182280405Srpaulo<hr><h3><a name="luaL_buffinitsize"><code>luaL_buffinitsize</code></a></h3><p>
6183326344Simp<span class="apii">[-?, +?, <em>m</em>]</span>
6184280405Srpaulo<pre>char *luaL_buffinitsize (lua_State *L, luaL_Buffer *B, size_t sz);</pre>
6185280405Srpaulo
6186280405Srpaulo<p>
6187280405SrpauloEquivalent to the sequence
6188280405Srpaulo<a href="#luaL_buffinit"><code>luaL_buffinit</code></a>, <a href="#luaL_prepbuffsize"><code>luaL_prepbuffsize</code></a>.
6189280405Srpaulo
6190280405Srpaulo
6191280405Srpaulo
6192280405Srpaulo
6193280405Srpaulo
6194280405Srpaulo<hr><h3><a name="luaL_callmeta"><code>luaL_callmeta</code></a></h3><p>
6195280405Srpaulo<span class="apii">[-0, +(0|1), <em>e</em>]</span>
6196280405Srpaulo<pre>int luaL_callmeta (lua_State *L, int obj, const char *e);</pre>
6197280405Srpaulo
6198280405Srpaulo<p>
6199280405SrpauloCalls a metamethod.
6200280405Srpaulo
6201280405Srpaulo
6202280405Srpaulo<p>
6203280405SrpauloIf the object at index <code>obj</code> has a metatable and this
6204280405Srpaulometatable has a field <code>e</code>,
6205280405Srpaulothis function calls this field passing the object as its only argument.
6206280405SrpauloIn this case this function returns true and pushes onto the
6207280405Srpaulostack the value returned by the call.
6208280405SrpauloIf there is no metatable or no metamethod,
6209280405Srpaulothis function returns false (without pushing any value on the stack).
6210280405Srpaulo
6211280405Srpaulo
6212280405Srpaulo
6213280405Srpaulo
6214280405Srpaulo
6215280405Srpaulo<hr><h3><a name="luaL_checkany"><code>luaL_checkany</code></a></h3><p>
6216280405Srpaulo<span class="apii">[-0, +0, <em>v</em>]</span>
6217280405Srpaulo<pre>void luaL_checkany (lua_State *L, int arg);</pre>
6218280405Srpaulo
6219280405Srpaulo<p>
6220280405SrpauloChecks whether the function has an argument
6221280405Srpauloof any type (including <b>nil</b>) at position <code>arg</code>.
6222280405Srpaulo
6223280405Srpaulo
6224280405Srpaulo
6225280405Srpaulo
6226280405Srpaulo
6227280405Srpaulo<hr><h3><a name="luaL_checkinteger"><code>luaL_checkinteger</code></a></h3><p>
6228280405Srpaulo<span class="apii">[-0, +0, <em>v</em>]</span>
6229280405Srpaulo<pre>lua_Integer luaL_checkinteger (lua_State *L, int arg);</pre>
6230280405Srpaulo
6231280405Srpaulo<p>
6232280405SrpauloChecks whether the function argument <code>arg</code> is an integer
6233280405Srpaulo(or can be converted to an integer)
6234280405Srpauloand returns this integer cast to a <a href="#lua_Integer"><code>lua_Integer</code></a>.
6235280405Srpaulo
6236280405Srpaulo
6237280405Srpaulo
6238280405Srpaulo
6239280405Srpaulo
6240280405Srpaulo<hr><h3><a name="luaL_checklstring"><code>luaL_checklstring</code></a></h3><p>
6241280405Srpaulo<span class="apii">[-0, +0, <em>v</em>]</span>
6242280405Srpaulo<pre>const char *luaL_checklstring (lua_State *L, int arg, size_t *l);</pre>
6243280405Srpaulo
6244280405Srpaulo<p>
6245280405SrpauloChecks whether the function argument <code>arg</code> is a string
6246280405Srpauloand returns this string;
6247280405Srpauloif <code>l</code> is not <code>NULL</code> fills <code>*l</code>
6248280405Srpaulowith the string's length.
6249280405Srpaulo
6250280405Srpaulo
6251280405Srpaulo<p>
6252280405SrpauloThis function uses <a href="#lua_tolstring"><code>lua_tolstring</code></a> to get its result,
6253280405Srpauloso all conversions and caveats of that function apply here.
6254280405Srpaulo
6255280405Srpaulo
6256280405Srpaulo
6257280405Srpaulo
6258280405Srpaulo
6259280405Srpaulo<hr><h3><a name="luaL_checknumber"><code>luaL_checknumber</code></a></h3><p>
6260280405Srpaulo<span class="apii">[-0, +0, <em>v</em>]</span>
6261280405Srpaulo<pre>lua_Number luaL_checknumber (lua_State *L, int arg);</pre>
6262280405Srpaulo
6263280405Srpaulo<p>
6264280405SrpauloChecks whether the function argument <code>arg</code> is a number
6265280405Srpauloand returns this number.
6266280405Srpaulo
6267280405Srpaulo
6268280405Srpaulo
6269280405Srpaulo
6270280405Srpaulo
6271280405Srpaulo<hr><h3><a name="luaL_checkoption"><code>luaL_checkoption</code></a></h3><p>
6272280405Srpaulo<span class="apii">[-0, +0, <em>v</em>]</span>
6273280405Srpaulo<pre>int luaL_checkoption (lua_State *L,
6274280405Srpaulo                      int arg,
6275280405Srpaulo                      const char *def,
6276280405Srpaulo                      const char *const lst[]);</pre>
6277280405Srpaulo
6278280405Srpaulo<p>
6279280405SrpauloChecks whether the function argument <code>arg</code> is a string and
6280280405Srpaulosearches for this string in the array <code>lst</code>
6281280405Srpaulo(which must be NULL-terminated).
6282280405SrpauloReturns the index in the array where the string was found.
6283280405SrpauloRaises an error if the argument is not a string or
6284280405Srpauloif the string cannot be found.
6285280405Srpaulo
6286280405Srpaulo
6287280405Srpaulo<p>
6288280405SrpauloIf <code>def</code> is not <code>NULL</code>,
6289280405Srpaulothe function uses <code>def</code> as a default value when
6290280405Srpaulothere is no argument <code>arg</code> or when this argument is <b>nil</b>.
6291280405Srpaulo
6292280405Srpaulo
6293280405Srpaulo<p>
6294280405SrpauloThis is a useful function for mapping strings to C&nbsp;enums.
6295280405Srpaulo(The usual convention in Lua libraries is
6296280405Srpauloto use strings instead of numbers to select options.)
6297280405Srpaulo
6298280405Srpaulo
6299280405Srpaulo
6300280405Srpaulo
6301280405Srpaulo
6302280405Srpaulo<hr><h3><a name="luaL_checkstack"><code>luaL_checkstack</code></a></h3><p>
6303280405Srpaulo<span class="apii">[-0, +0, <em>v</em>]</span>
6304280405Srpaulo<pre>void luaL_checkstack (lua_State *L, int sz, const char *msg);</pre>
6305280405Srpaulo
6306280405Srpaulo<p>
6307280405SrpauloGrows the stack size to <code>top + sz</code> elements,
6308280405Srpauloraising an error if the stack cannot grow to that size.
6309280405Srpaulo<code>msg</code> is an additional text to go into the error message
6310280405Srpaulo(or <code>NULL</code> for no additional text).
6311280405Srpaulo
6312280405Srpaulo
6313280405Srpaulo
6314280405Srpaulo
6315280405Srpaulo
6316280405Srpaulo<hr><h3><a name="luaL_checkstring"><code>luaL_checkstring</code></a></h3><p>
6317280405Srpaulo<span class="apii">[-0, +0, <em>v</em>]</span>
6318280405Srpaulo<pre>const char *luaL_checkstring (lua_State *L, int arg);</pre>
6319280405Srpaulo
6320280405Srpaulo<p>
6321280405SrpauloChecks whether the function argument <code>arg</code> is a string
6322280405Srpauloand returns this string.
6323280405Srpaulo
6324280405Srpaulo
6325280405Srpaulo<p>
6326280405SrpauloThis function uses <a href="#lua_tolstring"><code>lua_tolstring</code></a> to get its result,
6327280405Srpauloso all conversions and caveats of that function apply here.
6328280405Srpaulo
6329280405Srpaulo
6330280405Srpaulo
6331280405Srpaulo
6332280405Srpaulo
6333280405Srpaulo<hr><h3><a name="luaL_checktype"><code>luaL_checktype</code></a></h3><p>
6334280405Srpaulo<span class="apii">[-0, +0, <em>v</em>]</span>
6335280405Srpaulo<pre>void luaL_checktype (lua_State *L, int arg, int t);</pre>
6336280405Srpaulo
6337280405Srpaulo<p>
6338280405SrpauloChecks whether the function argument <code>arg</code> has type <code>t</code>.
6339280405SrpauloSee <a href="#lua_type"><code>lua_type</code></a> for the encoding of types for <code>t</code>.
6340280405Srpaulo
6341280405Srpaulo
6342280405Srpaulo
6343280405Srpaulo
6344280405Srpaulo
6345280405Srpaulo<hr><h3><a name="luaL_checkudata"><code>luaL_checkudata</code></a></h3><p>
6346280405Srpaulo<span class="apii">[-0, +0, <em>v</em>]</span>
6347280405Srpaulo<pre>void *luaL_checkudata (lua_State *L, int arg, const char *tname);</pre>
6348280405Srpaulo
6349280405Srpaulo<p>
6350280405SrpauloChecks whether the function argument <code>arg</code> is a userdata
6351280405Srpauloof the type <code>tname</code> (see <a href="#luaL_newmetatable"><code>luaL_newmetatable</code></a>) and
6352280405Srpauloreturns the userdata address (see <a href="#lua_touserdata"><code>lua_touserdata</code></a>).
6353280405Srpaulo
6354280405Srpaulo
6355280405Srpaulo
6356280405Srpaulo
6357280405Srpaulo
6358280405Srpaulo<hr><h3><a name="luaL_checkversion"><code>luaL_checkversion</code></a></h3><p>
6359326344Simp<span class="apii">[-0, +0, <em>v</em>]</span>
6360280405Srpaulo<pre>void luaL_checkversion (lua_State *L);</pre>
6361280405Srpaulo
6362280405Srpaulo<p>
6363280405SrpauloChecks whether the core running the call,
6364280405Srpaulothe core that created the Lua state,
6365280405Srpauloand the code making the call are all using the same version of Lua.
6366280405SrpauloAlso checks whether the core running the call
6367280405Srpauloand the core that created the Lua state
6368280405Srpauloare using the same address space.
6369280405Srpaulo
6370280405Srpaulo
6371280405Srpaulo
6372280405Srpaulo
6373280405Srpaulo
6374280405Srpaulo<hr><h3><a name="luaL_dofile"><code>luaL_dofile</code></a></h3><p>
6375280405Srpaulo<span class="apii">[-0, +?, <em>e</em>]</span>
6376280405Srpaulo<pre>int luaL_dofile (lua_State *L, const char *filename);</pre>
6377280405Srpaulo
6378280405Srpaulo<p>
6379280405SrpauloLoads and runs the given file.
6380280405SrpauloIt is defined as the following macro:
6381280405Srpaulo
6382280405Srpaulo<pre>
6383280405Srpaulo     (luaL_loadfile(L, filename) || lua_pcall(L, 0, LUA_MULTRET, 0))
6384280405Srpaulo</pre><p>
6385280405SrpauloIt returns false if there are no errors
6386280405Srpauloor true in case of errors.
6387280405Srpaulo
6388280405Srpaulo
6389280405Srpaulo
6390280405Srpaulo
6391280405Srpaulo
6392280405Srpaulo<hr><h3><a name="luaL_dostring"><code>luaL_dostring</code></a></h3><p>
6393280405Srpaulo<span class="apii">[-0, +?, &ndash;]</span>
6394280405Srpaulo<pre>int luaL_dostring (lua_State *L, const char *str);</pre>
6395280405Srpaulo
6396280405Srpaulo<p>
6397280405SrpauloLoads and runs the given string.
6398280405SrpauloIt is defined as the following macro:
6399280405Srpaulo
6400280405Srpaulo<pre>
6401280405Srpaulo     (luaL_loadstring(L, str) || lua_pcall(L, 0, LUA_MULTRET, 0))
6402280405Srpaulo</pre><p>
6403280405SrpauloIt returns false if there are no errors
6404280405Srpauloor true in case of errors.
6405280405Srpaulo
6406280405Srpaulo
6407280405Srpaulo
6408280405Srpaulo
6409280405Srpaulo
6410280405Srpaulo<hr><h3><a name="luaL_error"><code>luaL_error</code></a></h3><p>
6411280405Srpaulo<span class="apii">[-0, +0, <em>v</em>]</span>
6412280405Srpaulo<pre>int luaL_error (lua_State *L, const char *fmt, ...);</pre>
6413280405Srpaulo
6414280405Srpaulo<p>
6415280405SrpauloRaises an error.
6416280405SrpauloThe error message format is given by <code>fmt</code>
6417280405Srpauloplus any extra arguments,
6418280405Srpaulofollowing the same rules of <a href="#lua_pushfstring"><code>lua_pushfstring</code></a>.
6419280405SrpauloIt also adds at the beginning of the message the file name and
6420280405Srpaulothe line number where the error occurred,
6421280405Srpauloif this information is available.
6422280405Srpaulo
6423280405Srpaulo
6424280405Srpaulo<p>
6425280405SrpauloThis function never returns,
6426280405Srpaulobut it is an idiom to use it in C&nbsp;functions
6427280405Srpauloas <code>return luaL_error(<em>args</em>)</code>.
6428280405Srpaulo
6429280405Srpaulo
6430280405Srpaulo
6431280405Srpaulo
6432280405Srpaulo
6433280405Srpaulo<hr><h3><a name="luaL_execresult"><code>luaL_execresult</code></a></h3><p>
6434326344Simp<span class="apii">[-0, +3, <em>m</em>]</span>
6435280405Srpaulo<pre>int luaL_execresult (lua_State *L, int stat);</pre>
6436280405Srpaulo
6437280405Srpaulo<p>
6438280405SrpauloThis function produces the return values for
6439280405Srpauloprocess-related functions in the standard library
6440280405Srpaulo(<a href="#pdf-os.execute"><code>os.execute</code></a> and <a href="#pdf-io.close"><code>io.close</code></a>).
6441280405Srpaulo
6442280405Srpaulo
6443280405Srpaulo
6444280405Srpaulo
6445280405Srpaulo
6446280405Srpaulo<hr><h3><a name="luaL_fileresult"><code>luaL_fileresult</code></a></h3><p>
6447326344Simp<span class="apii">[-0, +(1|3), <em>m</em>]</span>
6448280405Srpaulo<pre>int luaL_fileresult (lua_State *L, int stat, const char *fname);</pre>
6449280405Srpaulo
6450280405Srpaulo<p>
6451280405SrpauloThis function produces the return values for
6452280405Srpaulofile-related functions in the standard library
6453280405Srpaulo(<a href="#pdf-io.open"><code>io.open</code></a>, <a href="#pdf-os.rename"><code>os.rename</code></a>, <a href="#pdf-file:seek"><code>file:seek</code></a>, etc.).
6454280405Srpaulo
6455280405Srpaulo
6456280405Srpaulo
6457280405Srpaulo
6458280405Srpaulo
6459280405Srpaulo<hr><h3><a name="luaL_getmetafield"><code>luaL_getmetafield</code></a></h3><p>
6460326344Simp<span class="apii">[-0, +(0|1), <em>m</em>]</span>
6461280405Srpaulo<pre>int luaL_getmetafield (lua_State *L, int obj, const char *e);</pre>
6462280405Srpaulo
6463280405Srpaulo<p>
6464280405SrpauloPushes onto the stack the field <code>e</code> from the metatable
6465280405Srpauloof the object at index <code>obj</code> and returns the type of pushed value.
6466280405SrpauloIf the object does not have a metatable,
6467280405Srpauloor if the metatable does not have this field,
6468280405Srpaulopushes nothing and returns <code>LUA_TNIL</code>.
6469280405Srpaulo
6470280405Srpaulo
6471280405Srpaulo
6472280405Srpaulo
6473280405Srpaulo
6474280405Srpaulo<hr><h3><a name="luaL_getmetatable"><code>luaL_getmetatable</code></a></h3><p>
6475326344Simp<span class="apii">[-0, +1, <em>m</em>]</span>
6476280405Srpaulo<pre>int luaL_getmetatable (lua_State *L, const char *tname);</pre>
6477280405Srpaulo
6478280405Srpaulo<p>
6479280405SrpauloPushes onto the stack the metatable associated with name <code>tname</code>
6480326344Simpin the registry (see <a href="#luaL_newmetatable"><code>luaL_newmetatable</code></a>)
6481326344Simp(<b>nil</b> if there is no metatable associated with that name).
6482326344SimpReturns the type of the pushed value.
6483280405Srpaulo
6484280405Srpaulo
6485280405Srpaulo
6486280405Srpaulo
6487280405Srpaulo
6488280405Srpaulo<hr><h3><a name="luaL_getsubtable"><code>luaL_getsubtable</code></a></h3><p>
6489280405Srpaulo<span class="apii">[-0, +1, <em>e</em>]</span>
6490280405Srpaulo<pre>int luaL_getsubtable (lua_State *L, int idx, const char *fname);</pre>
6491280405Srpaulo
6492280405Srpaulo<p>
6493280405SrpauloEnsures that the value <code>t[fname]</code>,
6494280405Srpaulowhere <code>t</code> is the value at index <code>idx</code>,
6495280405Srpaulois a table,
6496280405Srpauloand pushes that table onto the stack.
6497280405SrpauloReturns true if it finds a previous table there
6498280405Srpauloand false if it creates a new table.
6499280405Srpaulo
6500280405Srpaulo
6501280405Srpaulo
6502280405Srpaulo
6503280405Srpaulo
6504280405Srpaulo<hr><h3><a name="luaL_gsub"><code>luaL_gsub</code></a></h3><p>
6505326344Simp<span class="apii">[-0, +1, <em>m</em>]</span>
6506280405Srpaulo<pre>const char *luaL_gsub (lua_State *L,
6507280405Srpaulo                       const char *s,
6508280405Srpaulo                       const char *p,
6509280405Srpaulo                       const char *r);</pre>
6510280405Srpaulo
6511280405Srpaulo<p>
6512280405SrpauloCreates a copy of string <code>s</code> by replacing
6513280405Srpauloany occurrence of the string <code>p</code>
6514280405Srpaulowith the string <code>r</code>.
6515280405SrpauloPushes the resulting string on the stack and returns it.
6516280405Srpaulo
6517280405Srpaulo
6518280405Srpaulo
6519280405Srpaulo
6520280405Srpaulo
6521280405Srpaulo<hr><h3><a name="luaL_len"><code>luaL_len</code></a></h3><p>
6522280405Srpaulo<span class="apii">[-0, +0, <em>e</em>]</span>
6523280405Srpaulo<pre>lua_Integer luaL_len (lua_State *L, int index);</pre>
6524280405Srpaulo
6525280405Srpaulo<p>
6526280405SrpauloReturns the "length" of the value at the given index
6527280405Srpauloas a number;
6528280405Srpauloit is equivalent to the '<code>#</code>' operator in Lua (see <a href="#3.4.7">&sect;3.4.7</a>).
6529280405SrpauloRaises an error if the result of the operation is not an integer.
6530280405Srpaulo(This case only can happen through metamethods.)
6531280405Srpaulo
6532280405Srpaulo
6533280405Srpaulo
6534280405Srpaulo
6535280405Srpaulo
6536280405Srpaulo<hr><h3><a name="luaL_loadbuffer"><code>luaL_loadbuffer</code></a></h3><p>
6537280405Srpaulo<span class="apii">[-0, +1, &ndash;]</span>
6538280405Srpaulo<pre>int luaL_loadbuffer (lua_State *L,
6539280405Srpaulo                     const char *buff,
6540280405Srpaulo                     size_t sz,
6541280405Srpaulo                     const char *name);</pre>
6542280405Srpaulo
6543280405Srpaulo<p>
6544280405SrpauloEquivalent to <a href="#luaL_loadbufferx"><code>luaL_loadbufferx</code></a> with <code>mode</code> equal to <code>NULL</code>.
6545280405Srpaulo
6546280405Srpaulo
6547280405Srpaulo
6548280405Srpaulo
6549280405Srpaulo
6550280405Srpaulo<hr><h3><a name="luaL_loadbufferx"><code>luaL_loadbufferx</code></a></h3><p>
6551280405Srpaulo<span class="apii">[-0, +1, &ndash;]</span>
6552280405Srpaulo<pre>int luaL_loadbufferx (lua_State *L,
6553280405Srpaulo                      const char *buff,
6554280405Srpaulo                      size_t sz,
6555280405Srpaulo                      const char *name,
6556280405Srpaulo                      const char *mode);</pre>
6557280405Srpaulo
6558280405Srpaulo<p>
6559280405SrpauloLoads a buffer as a Lua chunk.
6560280405SrpauloThis function uses <a href="#lua_load"><code>lua_load</code></a> to load the chunk in the
6561280405Srpaulobuffer pointed to by <code>buff</code> with size <code>sz</code>.
6562280405Srpaulo
6563280405Srpaulo
6564280405Srpaulo<p>
6565280405SrpauloThis function returns the same results as <a href="#lua_load"><code>lua_load</code></a>.
6566280405Srpaulo<code>name</code> is the chunk name,
6567280405Srpauloused for debug information and error messages.
6568280405SrpauloThe string <code>mode</code> works as in function <a href="#lua_load"><code>lua_load</code></a>.
6569280405Srpaulo
6570280405Srpaulo
6571280405Srpaulo
6572280405Srpaulo
6573280405Srpaulo
6574280405Srpaulo<hr><h3><a name="luaL_loadfile"><code>luaL_loadfile</code></a></h3><p>
6575326344Simp<span class="apii">[-0, +1, <em>m</em>]</span>
6576280405Srpaulo<pre>int luaL_loadfile (lua_State *L, const char *filename);</pre>
6577280405Srpaulo
6578280405Srpaulo<p>
6579280405SrpauloEquivalent to <a href="#luaL_loadfilex"><code>luaL_loadfilex</code></a> with <code>mode</code> equal to <code>NULL</code>.
6580280405Srpaulo
6581280405Srpaulo
6582280405Srpaulo
6583280405Srpaulo
6584280405Srpaulo
6585280405Srpaulo<hr><h3><a name="luaL_loadfilex"><code>luaL_loadfilex</code></a></h3><p>
6586326344Simp<span class="apii">[-0, +1, <em>m</em>]</span>
6587280405Srpaulo<pre>int luaL_loadfilex (lua_State *L, const char *filename,
6588280405Srpaulo                                            const char *mode);</pre>
6589280405Srpaulo
6590280405Srpaulo<p>
6591280405SrpauloLoads a file as a Lua chunk.
6592280405SrpauloThis function uses <a href="#lua_load"><code>lua_load</code></a> to load the chunk in the file
6593280405Srpaulonamed <code>filename</code>.
6594280405SrpauloIf <code>filename</code> is <code>NULL</code>,
6595280405Srpaulothen it loads from the standard input.
6596280405SrpauloThe first line in the file is ignored if it starts with a <code>#</code>.
6597280405Srpaulo
6598280405Srpaulo
6599280405Srpaulo<p>
6600280405SrpauloThe string <code>mode</code> works as in function <a href="#lua_load"><code>lua_load</code></a>.
6601280405Srpaulo
6602280405Srpaulo
6603280405Srpaulo<p>
6604280405SrpauloThis function returns the same results as <a href="#lua_load"><code>lua_load</code></a>,
6605280405Srpaulobut it has an extra error code <a name="pdf-LUA_ERRFILE"><code>LUA_ERRFILE</code></a>
6606326344Simpfor file-related errors
6607326344Simp(e.g., it cannot open or read the file).
6608280405Srpaulo
6609280405Srpaulo
6610280405Srpaulo<p>
6611280405SrpauloAs <a href="#lua_load"><code>lua_load</code></a>, this function only loads the chunk;
6612280405Srpauloit does not run it.
6613280405Srpaulo
6614280405Srpaulo
6615280405Srpaulo
6616280405Srpaulo
6617280405Srpaulo
6618280405Srpaulo<hr><h3><a name="luaL_loadstring"><code>luaL_loadstring</code></a></h3><p>
6619280405Srpaulo<span class="apii">[-0, +1, &ndash;]</span>
6620280405Srpaulo<pre>int luaL_loadstring (lua_State *L, const char *s);</pre>
6621280405Srpaulo
6622280405Srpaulo<p>
6623280405SrpauloLoads a string as a Lua chunk.
6624280405SrpauloThis function uses <a href="#lua_load"><code>lua_load</code></a> to load the chunk in
6625280405Srpaulothe zero-terminated string <code>s</code>.
6626280405Srpaulo
6627280405Srpaulo
6628280405Srpaulo<p>
6629280405SrpauloThis function returns the same results as <a href="#lua_load"><code>lua_load</code></a>.
6630280405Srpaulo
6631280405Srpaulo
6632280405Srpaulo<p>
6633280405SrpauloAlso as <a href="#lua_load"><code>lua_load</code></a>, this function only loads the chunk;
6634280405Srpauloit does not run it.
6635280405Srpaulo
6636280405Srpaulo
6637280405Srpaulo
6638280405Srpaulo
6639280405Srpaulo
6640280405Srpaulo<hr><h3><a name="luaL_newlib"><code>luaL_newlib</code></a></h3><p>
6641326344Simp<span class="apii">[-0, +1, <em>m</em>]</span>
6642280405Srpaulo<pre>void luaL_newlib (lua_State *L, const luaL_Reg l[]);</pre>
6643280405Srpaulo
6644280405Srpaulo<p>
6645280405SrpauloCreates a new table and registers there
6646280405Srpaulothe functions in list <code>l</code>.
6647280405Srpaulo
6648280405Srpaulo
6649280405Srpaulo<p>
6650280405SrpauloIt is implemented as the following macro:
6651280405Srpaulo
6652280405Srpaulo<pre>
6653280405Srpaulo     (luaL_newlibtable(L,l), luaL_setfuncs(L,l,0))
6654280405Srpaulo</pre><p>
6655280405SrpauloThe array <code>l</code> must be the actual array,
6656280405Srpaulonot a pointer to it.
6657280405Srpaulo
6658280405Srpaulo
6659280405Srpaulo
6660280405Srpaulo
6661280405Srpaulo
6662280405Srpaulo<hr><h3><a name="luaL_newlibtable"><code>luaL_newlibtable</code></a></h3><p>
6663326344Simp<span class="apii">[-0, +1, <em>m</em>]</span>
6664280405Srpaulo<pre>void luaL_newlibtable (lua_State *L, const luaL_Reg l[]);</pre>
6665280405Srpaulo
6666280405Srpaulo<p>
6667280405SrpauloCreates a new table with a size optimized
6668280405Srpauloto store all entries in the array <code>l</code>
6669280405Srpaulo(but does not actually store them).
6670280405SrpauloIt is intended to be used in conjunction with <a href="#luaL_setfuncs"><code>luaL_setfuncs</code></a>
6671280405Srpaulo(see <a href="#luaL_newlib"><code>luaL_newlib</code></a>).
6672280405Srpaulo
6673280405Srpaulo
6674280405Srpaulo<p>
6675280405SrpauloIt is implemented as a macro.
6676280405SrpauloThe array <code>l</code> must be the actual array,
6677280405Srpaulonot a pointer to it.
6678280405Srpaulo
6679280405Srpaulo
6680280405Srpaulo
6681280405Srpaulo
6682280405Srpaulo
6683280405Srpaulo<hr><h3><a name="luaL_newmetatable"><code>luaL_newmetatable</code></a></h3><p>
6684326344Simp<span class="apii">[-0, +1, <em>m</em>]</span>
6685280405Srpaulo<pre>int luaL_newmetatable (lua_State *L, const char *tname);</pre>
6686280405Srpaulo
6687280405Srpaulo<p>
6688280405SrpauloIf the registry already has the key <code>tname</code>,
6689280405Srpauloreturns 0.
6690280405SrpauloOtherwise,
6691280405Srpaulocreates a new table to be used as a metatable for userdata,
6692280405Srpauloadds to this new table the pair <code>__name = tname</code>,
6693280405Srpauloadds to the registry the pair <code>[tname] = new table</code>,
6694280405Srpauloand returns 1.
6695280405Srpaulo(The entry <code>__name</code> is used by some error-reporting functions.)
6696280405Srpaulo
6697280405Srpaulo
6698280405Srpaulo<p>
6699280405SrpauloIn both cases pushes onto the stack the final value associated
6700280405Srpaulowith <code>tname</code> in the registry.
6701280405Srpaulo
6702280405Srpaulo
6703280405Srpaulo
6704280405Srpaulo
6705280405Srpaulo
6706280405Srpaulo<hr><h3><a name="luaL_newstate"><code>luaL_newstate</code></a></h3><p>
6707280405Srpaulo<span class="apii">[-0, +0, &ndash;]</span>
6708280405Srpaulo<pre>lua_State *luaL_newstate (void);</pre>
6709280405Srpaulo
6710280405Srpaulo<p>
6711280405SrpauloCreates a new Lua state.
6712280405SrpauloIt calls <a href="#lua_newstate"><code>lua_newstate</code></a> with an
6713280405Srpauloallocator based on the standard&nbsp;C <code>realloc</code> function
6714280405Srpauloand then sets a panic function (see <a href="#4.6">&sect;4.6</a>) that prints
6715280405Srpauloan error message to the standard error output in case of fatal
6716280405Srpauloerrors.
6717280405Srpaulo
6718280405Srpaulo
6719280405Srpaulo<p>
6720280405SrpauloReturns the new state,
6721280405Srpauloor <code>NULL</code> if there is a memory allocation error.
6722280405Srpaulo
6723280405Srpaulo
6724280405Srpaulo
6725280405Srpaulo
6726280405Srpaulo
6727280405Srpaulo<hr><h3><a name="luaL_openlibs"><code>luaL_openlibs</code></a></h3><p>
6728280405Srpaulo<span class="apii">[-0, +0, <em>e</em>]</span>
6729280405Srpaulo<pre>void luaL_openlibs (lua_State *L);</pre>
6730280405Srpaulo
6731280405Srpaulo<p>
6732280405SrpauloOpens all standard Lua libraries into the given state.
6733280405Srpaulo
6734280405Srpaulo
6735280405Srpaulo
6736280405Srpaulo
6737280405Srpaulo
6738326344Simp<hr><h3><a name="luaL_opt"><code>luaL_opt</code></a></h3><p>
6739326344Simp<span class="apii">[-0, +0, <em>e</em>]</span>
6740326344Simp<pre>T luaL_opt (L, func, arg, dflt);</pre>
6741326344Simp
6742326344Simp<p>
6743326344SimpThis macro is defined as follows:
6744326344Simp
6745326344Simp<pre>
6746326344Simp     (lua_isnoneornil(L,(arg)) ? (dflt) : func(L,(arg)))
6747326344Simp</pre><p>
6748326344SimpIn words, if the argument <code>arg</code> is nil or absent,
6749326344Simpthe macro results in the default <code>dflt</code>.
6750326344SimpOtherwise, it results in the result of calling <code>func</code>
6751326344Simpwith the state <code>L</code> and the argument index <code>arg</code> as
6752326344Simpparameters.
6753326344SimpNote that it evaluates the expression <code>dflt</code> only if needed.
6754326344Simp
6755326344Simp
6756326344Simp
6757326344Simp
6758326344Simp
6759280405Srpaulo<hr><h3><a name="luaL_optinteger"><code>luaL_optinteger</code></a></h3><p>
6760280405Srpaulo<span class="apii">[-0, +0, <em>v</em>]</span>
6761280405Srpaulo<pre>lua_Integer luaL_optinteger (lua_State *L,
6762280405Srpaulo                             int arg,
6763280405Srpaulo                             lua_Integer d);</pre>
6764280405Srpaulo
6765280405Srpaulo<p>
6766280405SrpauloIf the function argument <code>arg</code> is an integer
6767280405Srpaulo(or convertible to an integer),
6768280405Srpauloreturns this integer.
6769280405SrpauloIf this argument is absent or is <b>nil</b>,
6770280405Srpauloreturns <code>d</code>.
6771280405SrpauloOtherwise, raises an error.
6772280405Srpaulo
6773280405Srpaulo
6774280405Srpaulo
6775280405Srpaulo
6776280405Srpaulo
6777280405Srpaulo<hr><h3><a name="luaL_optlstring"><code>luaL_optlstring</code></a></h3><p>
6778280405Srpaulo<span class="apii">[-0, +0, <em>v</em>]</span>
6779280405Srpaulo<pre>const char *luaL_optlstring (lua_State *L,
6780280405Srpaulo                             int arg,
6781280405Srpaulo                             const char *d,
6782280405Srpaulo                             size_t *l);</pre>
6783280405Srpaulo
6784280405Srpaulo<p>
6785280405SrpauloIf the function argument <code>arg</code> is a string,
6786280405Srpauloreturns this string.
6787280405SrpauloIf this argument is absent or is <b>nil</b>,
6788280405Srpauloreturns <code>d</code>.
6789280405SrpauloOtherwise, raises an error.
6790280405Srpaulo
6791280405Srpaulo
6792280405Srpaulo<p>
6793280405SrpauloIf <code>l</code> is not <code>NULL</code>,
6794280405Srpaulofills the position <code>*l</code> with the result's length.
6795326344SimpIf the result is <code>NULL</code>
6796326344Simp(only possible when returning <code>d</code> and <code>d == NULL</code>),
6797326344Simpits length is considered zero.
6798280405Srpaulo
6799280405Srpaulo
6800326344Simp<p>
6801326344SimpThis function uses <a href="#lua_tolstring"><code>lua_tolstring</code></a> to get its result,
6802326344Simpso all conversions and caveats of that function apply here.
6803280405Srpaulo
6804280405Srpaulo
6805280405Srpaulo
6806326344Simp
6807326344Simp
6808280405Srpaulo<hr><h3><a name="luaL_optnumber"><code>luaL_optnumber</code></a></h3><p>
6809280405Srpaulo<span class="apii">[-0, +0, <em>v</em>]</span>
6810280405Srpaulo<pre>lua_Number luaL_optnumber (lua_State *L, int arg, lua_Number d);</pre>
6811280405Srpaulo
6812280405Srpaulo<p>
6813280405SrpauloIf the function argument <code>arg</code> is a number,
6814280405Srpauloreturns this number.
6815280405SrpauloIf this argument is absent or is <b>nil</b>,
6816280405Srpauloreturns <code>d</code>.
6817280405SrpauloOtherwise, raises an error.
6818280405Srpaulo
6819280405Srpaulo
6820280405Srpaulo
6821280405Srpaulo
6822280405Srpaulo
6823280405Srpaulo<hr><h3><a name="luaL_optstring"><code>luaL_optstring</code></a></h3><p>
6824280405Srpaulo<span class="apii">[-0, +0, <em>v</em>]</span>
6825280405Srpaulo<pre>const char *luaL_optstring (lua_State *L,
6826280405Srpaulo                            int arg,
6827280405Srpaulo                            const char *d);</pre>
6828280405Srpaulo
6829280405Srpaulo<p>
6830280405SrpauloIf the function argument <code>arg</code> is a string,
6831280405Srpauloreturns this string.
6832280405SrpauloIf this argument is absent or is <b>nil</b>,
6833280405Srpauloreturns <code>d</code>.
6834280405SrpauloOtherwise, raises an error.
6835280405Srpaulo
6836280405Srpaulo
6837280405Srpaulo
6838280405Srpaulo
6839280405Srpaulo
6840280405Srpaulo<hr><h3><a name="luaL_prepbuffer"><code>luaL_prepbuffer</code></a></h3><p>
6841326344Simp<span class="apii">[-?, +?, <em>m</em>]</span>
6842280405Srpaulo<pre>char *luaL_prepbuffer (luaL_Buffer *B);</pre>
6843280405Srpaulo
6844280405Srpaulo<p>
6845280405SrpauloEquivalent to <a href="#luaL_prepbuffsize"><code>luaL_prepbuffsize</code></a>
6846280405Srpaulowith the predefined size <a name="pdf-LUAL_BUFFERSIZE"><code>LUAL_BUFFERSIZE</code></a>.
6847280405Srpaulo
6848280405Srpaulo
6849280405Srpaulo
6850280405Srpaulo
6851280405Srpaulo
6852280405Srpaulo<hr><h3><a name="luaL_prepbuffsize"><code>luaL_prepbuffsize</code></a></h3><p>
6853326344Simp<span class="apii">[-?, +?, <em>m</em>]</span>
6854280405Srpaulo<pre>char *luaL_prepbuffsize (luaL_Buffer *B, size_t sz);</pre>
6855280405Srpaulo
6856280405Srpaulo<p>
6857280405SrpauloReturns an address to a space of size <code>sz</code>
6858280405Srpaulowhere you can copy a string to be added to buffer <code>B</code>
6859280405Srpaulo(see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>).
6860280405SrpauloAfter copying the string into this space you must call
6861280405Srpaulo<a href="#luaL_addsize"><code>luaL_addsize</code></a> with the size of the string to actually add
6862280405Srpauloit to the buffer.
6863280405Srpaulo
6864280405Srpaulo
6865280405Srpaulo
6866280405Srpaulo
6867280405Srpaulo
6868280405Srpaulo<hr><h3><a name="luaL_pushresult"><code>luaL_pushresult</code></a></h3><p>
6869326344Simp<span class="apii">[-?, +1, <em>m</em>]</span>
6870280405Srpaulo<pre>void luaL_pushresult (luaL_Buffer *B);</pre>
6871280405Srpaulo
6872280405Srpaulo<p>
6873280405SrpauloFinishes the use of buffer <code>B</code> leaving the final string on
6874280405Srpaulothe top of the stack.
6875280405Srpaulo
6876280405Srpaulo
6877280405Srpaulo
6878280405Srpaulo
6879280405Srpaulo
6880280405Srpaulo<hr><h3><a name="luaL_pushresultsize"><code>luaL_pushresultsize</code></a></h3><p>
6881326344Simp<span class="apii">[-?, +1, <em>m</em>]</span>
6882280405Srpaulo<pre>void luaL_pushresultsize (luaL_Buffer *B, size_t sz);</pre>
6883280405Srpaulo
6884280405Srpaulo<p>
6885280405SrpauloEquivalent to the sequence <a href="#luaL_addsize"><code>luaL_addsize</code></a>, <a href="#luaL_pushresult"><code>luaL_pushresult</code></a>.
6886280405Srpaulo
6887280405Srpaulo
6888280405Srpaulo
6889280405Srpaulo
6890280405Srpaulo
6891280405Srpaulo<hr><h3><a name="luaL_ref"><code>luaL_ref</code></a></h3><p>
6892326344Simp<span class="apii">[-1, +0, <em>m</em>]</span>
6893280405Srpaulo<pre>int luaL_ref (lua_State *L, int t);</pre>
6894280405Srpaulo
6895280405Srpaulo<p>
6896280405SrpauloCreates and returns a <em>reference</em>,
6897280405Srpauloin the table at index <code>t</code>,
6898280405Srpaulofor the object at the top of the stack (and pops the object).
6899280405Srpaulo
6900280405Srpaulo
6901280405Srpaulo<p>
6902280405SrpauloA reference is a unique integer key.
6903280405SrpauloAs long as you do not manually add integer keys into table <code>t</code>,
6904280405Srpaulo<a href="#luaL_ref"><code>luaL_ref</code></a> ensures the uniqueness of the key it returns.
6905280405SrpauloYou can retrieve an object referred by reference <code>r</code>
6906280405Srpauloby calling <code>lua_rawgeti(L, t, r)</code>.
6907280405SrpauloFunction <a href="#luaL_unref"><code>luaL_unref</code></a> frees a reference and its associated object.
6908280405Srpaulo
6909280405Srpaulo
6910280405Srpaulo<p>
6911280405SrpauloIf the object at the top of the stack is <b>nil</b>,
6912280405Srpaulo<a href="#luaL_ref"><code>luaL_ref</code></a> returns the constant <a name="pdf-LUA_REFNIL"><code>LUA_REFNIL</code></a>.
6913280405SrpauloThe constant <a name="pdf-LUA_NOREF"><code>LUA_NOREF</code></a> is guaranteed to be different
6914280405Srpaulofrom any reference returned by <a href="#luaL_ref"><code>luaL_ref</code></a>.
6915280405Srpaulo
6916280405Srpaulo
6917280405Srpaulo
6918280405Srpaulo
6919280405Srpaulo
6920280405Srpaulo<hr><h3><a name="luaL_Reg"><code>luaL_Reg</code></a></h3>
6921280405Srpaulo<pre>typedef struct luaL_Reg {
6922280405Srpaulo  const char *name;
6923280405Srpaulo  lua_CFunction func;
6924280405Srpaulo} luaL_Reg;</pre>
6925280405Srpaulo
6926280405Srpaulo<p>
6927280405SrpauloType for arrays of functions to be registered by
6928280405Srpaulo<a href="#luaL_setfuncs"><code>luaL_setfuncs</code></a>.
6929280405Srpaulo<code>name</code> is the function name and <code>func</code> is a pointer to
6930280405Srpaulothe function.
6931280405SrpauloAny array of <a href="#luaL_Reg"><code>luaL_Reg</code></a> must end with a sentinel entry
6932280405Srpauloin which both <code>name</code> and <code>func</code> are <code>NULL</code>.
6933280405Srpaulo
6934280405Srpaulo
6935280405Srpaulo
6936280405Srpaulo
6937280405Srpaulo
6938280405Srpaulo<hr><h3><a name="luaL_requiref"><code>luaL_requiref</code></a></h3><p>
6939280405Srpaulo<span class="apii">[-0, +1, <em>e</em>]</span>
6940280405Srpaulo<pre>void luaL_requiref (lua_State *L, const char *modname,
6941280405Srpaulo                    lua_CFunction openf, int glb);</pre>
6942280405Srpaulo
6943280405Srpaulo<p>
6944280405SrpauloIf <code>modname</code> is not already present in <a href="#pdf-package.loaded"><code>package.loaded</code></a>,
6945280405Srpaulocalls function <code>openf</code> with string <code>modname</code> as an argument
6946280405Srpauloand sets the call result in <code>package.loaded[modname]</code>,
6947280405Srpauloas if that function has been called through <a href="#pdf-require"><code>require</code></a>.
6948280405Srpaulo
6949280405Srpaulo
6950280405Srpaulo<p>
6951280405SrpauloIf <code>glb</code> is true,
6952280405Srpauloalso stores the module into global <code>modname</code>.
6953280405Srpaulo
6954280405Srpaulo
6955280405Srpaulo<p>
6956280405SrpauloLeaves a copy of the module on the stack.
6957280405Srpaulo
6958280405Srpaulo
6959280405Srpaulo
6960280405Srpaulo
6961280405Srpaulo
6962280405Srpaulo<hr><h3><a name="luaL_setfuncs"><code>luaL_setfuncs</code></a></h3><p>
6963326344Simp<span class="apii">[-nup, +0, <em>m</em>]</span>
6964280405Srpaulo<pre>void luaL_setfuncs (lua_State *L, const luaL_Reg *l, int nup);</pre>
6965280405Srpaulo
6966280405Srpaulo<p>
6967280405SrpauloRegisters all functions in the array <code>l</code>
6968280405Srpaulo(see <a href="#luaL_Reg"><code>luaL_Reg</code></a>) into the table on the top of the stack
6969280405Srpaulo(below optional upvalues, see next).
6970280405Srpaulo
6971280405Srpaulo
6972280405Srpaulo<p>
6973280405SrpauloWhen <code>nup</code> is not zero,
6974280405Srpauloall functions are created sharing <code>nup</code> upvalues,
6975280405Srpaulowhich must be previously pushed on the stack
6976280405Srpauloon top of the library table.
6977280405SrpauloThese values are popped from the stack after the registration.
6978280405Srpaulo
6979280405Srpaulo
6980280405Srpaulo
6981280405Srpaulo
6982280405Srpaulo
6983280405Srpaulo<hr><h3><a name="luaL_setmetatable"><code>luaL_setmetatable</code></a></h3><p>
6984280405Srpaulo<span class="apii">[-0, +0, &ndash;]</span>
6985280405Srpaulo<pre>void luaL_setmetatable (lua_State *L, const char *tname);</pre>
6986280405Srpaulo
6987280405Srpaulo<p>
6988280405SrpauloSets the metatable of the object at the top of the stack
6989280405Srpauloas the metatable associated with name <code>tname</code>
6990280405Srpauloin the registry (see <a href="#luaL_newmetatable"><code>luaL_newmetatable</code></a>).
6991280405Srpaulo
6992280405Srpaulo
6993280405Srpaulo
6994280405Srpaulo
6995280405Srpaulo
6996280405Srpaulo<hr><h3><a name="luaL_Stream"><code>luaL_Stream</code></a></h3>
6997280405Srpaulo<pre>typedef struct luaL_Stream {
6998280405Srpaulo  FILE *f;
6999280405Srpaulo  lua_CFunction closef;
7000280405Srpaulo} luaL_Stream;</pre>
7001280405Srpaulo
7002280405Srpaulo<p>
7003280405SrpauloThe standard representation for file handles,
7004280405Srpaulowhich is used by the standard I/O library.
7005280405Srpaulo
7006280405Srpaulo
7007280405Srpaulo<p>
7008280405SrpauloA file handle is implemented as a full userdata,
7009280405Srpaulowith a metatable called <code>LUA_FILEHANDLE</code>
7010280405Srpaulo(where <code>LUA_FILEHANDLE</code> is a macro with the actual metatable's name).
7011280405SrpauloThe metatable is created by the I/O library
7012280405Srpaulo(see <a href="#luaL_newmetatable"><code>luaL_newmetatable</code></a>).
7013280405Srpaulo
7014280405Srpaulo
7015280405Srpaulo<p>
7016280405SrpauloThis userdata must start with the structure <code>luaL_Stream</code>;
7017280405Srpauloit can contain other data after this initial structure.
7018280405SrpauloField <code>f</code> points to the corresponding C stream
7019280405Srpaulo(or it can be <code>NULL</code> to indicate an incompletely created handle).
7020280405SrpauloField <code>closef</code> points to a Lua function
7021280405Srpaulothat will be called to close the stream
7022280405Srpaulowhen the handle is closed or collected;
7023280405Srpaulothis function receives the file handle as its sole argument and
7024280405Srpaulomust return either <b>true</b> (in case of success)
7025280405Srpauloor <b>nil</b> plus an error message (in case of error).
7026280405SrpauloOnce Lua calls this field,
7027326344Simpit changes the field value to <code>NULL</code>
7028280405Srpauloto signal that the handle is closed.
7029280405Srpaulo
7030280405Srpaulo
7031280405Srpaulo
7032280405Srpaulo
7033280405Srpaulo
7034280405Srpaulo<hr><h3><a name="luaL_testudata"><code>luaL_testudata</code></a></h3><p>
7035326344Simp<span class="apii">[-0, +0, <em>m</em>]</span>
7036280405Srpaulo<pre>void *luaL_testudata (lua_State *L, int arg, const char *tname);</pre>
7037280405Srpaulo
7038280405Srpaulo<p>
7039280405SrpauloThis function works like <a href="#luaL_checkudata"><code>luaL_checkudata</code></a>,
7040280405Srpauloexcept that, when the test fails,
7041280405Srpauloit returns <code>NULL</code> instead of raising an error.
7042280405Srpaulo
7043280405Srpaulo
7044280405Srpaulo
7045280405Srpaulo
7046280405Srpaulo
7047280405Srpaulo<hr><h3><a name="luaL_tolstring"><code>luaL_tolstring</code></a></h3><p>
7048280405Srpaulo<span class="apii">[-0, +1, <em>e</em>]</span>
7049280405Srpaulo<pre>const char *luaL_tolstring (lua_State *L, int idx, size_t *len);</pre>
7050280405Srpaulo
7051280405Srpaulo<p>
7052280405SrpauloConverts any Lua value at the given index to a C&nbsp;string
7053280405Srpauloin a reasonable format.
7054280405SrpauloThe resulting string is pushed onto the stack and also
7055280405Srpauloreturned by the function.
7056280405SrpauloIf <code>len</code> is not <code>NULL</code>,
7057280405Srpaulothe function also sets <code>*len</code> with the string length.
7058280405Srpaulo
7059280405Srpaulo
7060280405Srpaulo<p>
7061326344SimpIf the value has a metatable with a <code>__tostring</code> field,
7062280405Srpaulothen <code>luaL_tolstring</code> calls the corresponding metamethod
7063280405Srpaulowith the value as argument,
7064280405Srpauloand uses the result of the call as its result.
7065280405Srpaulo
7066280405Srpaulo
7067280405Srpaulo
7068280405Srpaulo
7069280405Srpaulo
7070280405Srpaulo<hr><h3><a name="luaL_traceback"><code>luaL_traceback</code></a></h3><p>
7071326344Simp<span class="apii">[-0, +1, <em>m</em>]</span>
7072280405Srpaulo<pre>void luaL_traceback (lua_State *L, lua_State *L1, const char *msg,
7073280405Srpaulo                     int level);</pre>
7074280405Srpaulo
7075280405Srpaulo<p>
7076280405SrpauloCreates and pushes a traceback of the stack <code>L1</code>.
7077280405SrpauloIf <code>msg</code> is not <code>NULL</code> it is appended
7078280405Srpauloat the beginning of the traceback.
7079280405SrpauloThe <code>level</code> parameter tells at which level
7080280405Srpauloto start the traceback.
7081280405Srpaulo
7082280405Srpaulo
7083280405Srpaulo
7084280405Srpaulo
7085280405Srpaulo
7086280405Srpaulo<hr><h3><a name="luaL_typename"><code>luaL_typename</code></a></h3><p>
7087280405Srpaulo<span class="apii">[-0, +0, &ndash;]</span>
7088280405Srpaulo<pre>const char *luaL_typename (lua_State *L, int index);</pre>
7089280405Srpaulo
7090280405Srpaulo<p>
7091280405SrpauloReturns the name of the type of the value at the given index.
7092280405Srpaulo
7093280405Srpaulo
7094280405Srpaulo
7095280405Srpaulo
7096280405Srpaulo
7097280405Srpaulo<hr><h3><a name="luaL_unref"><code>luaL_unref</code></a></h3><p>
7098280405Srpaulo<span class="apii">[-0, +0, &ndash;]</span>
7099280405Srpaulo<pre>void luaL_unref (lua_State *L, int t, int ref);</pre>
7100280405Srpaulo
7101280405Srpaulo<p>
7102280405SrpauloReleases reference <code>ref</code> from the table at index <code>t</code>
7103280405Srpaulo(see <a href="#luaL_ref"><code>luaL_ref</code></a>).
7104280405SrpauloThe entry is removed from the table,
7105280405Srpauloso that the referred object can be collected.
7106280405SrpauloThe reference <code>ref</code> is also freed to be used again.
7107280405Srpaulo
7108280405Srpaulo
7109280405Srpaulo<p>
7110280405SrpauloIf <code>ref</code> is <a href="#pdf-LUA_NOREF"><code>LUA_NOREF</code></a> or <a href="#pdf-LUA_REFNIL"><code>LUA_REFNIL</code></a>,
7111280405Srpaulo<a href="#luaL_unref"><code>luaL_unref</code></a> does nothing.
7112280405Srpaulo
7113280405Srpaulo
7114280405Srpaulo
7115280405Srpaulo
7116280405Srpaulo
7117280405Srpaulo<hr><h3><a name="luaL_where"><code>luaL_where</code></a></h3><p>
7118326344Simp<span class="apii">[-0, +1, <em>m</em>]</span>
7119280405Srpaulo<pre>void luaL_where (lua_State *L, int lvl);</pre>
7120280405Srpaulo
7121280405Srpaulo<p>
7122280405SrpauloPushes onto the stack a string identifying the current position
7123280405Srpauloof the control at level <code>lvl</code> in the call stack.
7124280405SrpauloTypically this string has the following format:
7125280405Srpaulo
7126280405Srpaulo<pre>
7127280405Srpaulo     <em>chunkname</em>:<em>currentline</em>:
7128280405Srpaulo</pre><p>
7129280405SrpauloLevel&nbsp;0 is the running function,
7130280405Srpaulolevel&nbsp;1 is the function that called the running function,
7131280405Srpauloetc.
7132280405Srpaulo
7133280405Srpaulo
7134280405Srpaulo<p>
7135280405SrpauloThis function is used to build a prefix for error messages.
7136280405Srpaulo
7137280405Srpaulo
7138280405Srpaulo
7139280405Srpaulo
7140280405Srpaulo
7141280405Srpaulo
7142280405Srpaulo
7143280405Srpaulo<h1>6 &ndash; <a name="6">Standard Libraries</a></h1>
7144280405Srpaulo
7145280405Srpaulo<p>
7146280405SrpauloThe standard Lua libraries provide useful functions
7147280405Srpaulothat are implemented directly through the C&nbsp;API.
7148280405SrpauloSome of these functions provide essential services to the language
7149280405Srpaulo(e.g., <a href="#pdf-type"><code>type</code></a> and <a href="#pdf-getmetatable"><code>getmetatable</code></a>);
7150280405Srpauloothers provide access to "outside" services (e.g., I/O);
7151280405Srpauloand others could be implemented in Lua itself,
7152280405Srpaulobut are quite useful or have critical performance requirements that
7153280405Srpaulodeserve an implementation in C (e.g., <a href="#pdf-table.sort"><code>table.sort</code></a>).
7154280405Srpaulo
7155280405Srpaulo
7156280405Srpaulo<p>
7157280405SrpauloAll libraries are implemented through the official C&nbsp;API
7158280405Srpauloand are provided as separate C&nbsp;modules.
7159280405SrpauloCurrently, Lua has the following standard libraries:
7160280405Srpaulo
7161280405Srpaulo<ul>
7162280405Srpaulo
7163280405Srpaulo<li>basic library (<a href="#6.1">&sect;6.1</a>);</li>
7164280405Srpaulo
7165280405Srpaulo<li>coroutine library (<a href="#6.2">&sect;6.2</a>);</li>
7166280405Srpaulo
7167280405Srpaulo<li>package library (<a href="#6.3">&sect;6.3</a>);</li>
7168280405Srpaulo
7169280405Srpaulo<li>string manipulation (<a href="#6.4">&sect;6.4</a>);</li>
7170280405Srpaulo
7171280405Srpaulo<li>basic UTF-8 support (<a href="#6.5">&sect;6.5</a>);</li>
7172280405Srpaulo
7173280405Srpaulo<li>table manipulation (<a href="#6.6">&sect;6.6</a>);</li>
7174280405Srpaulo
7175280405Srpaulo<li>mathematical functions (<a href="#6.7">&sect;6.7</a>) (sin, log, etc.);</li>
7176280405Srpaulo
7177280405Srpaulo<li>input and output (<a href="#6.8">&sect;6.8</a>);</li>
7178280405Srpaulo
7179280405Srpaulo<li>operating system facilities (<a href="#6.9">&sect;6.9</a>);</li>
7180280405Srpaulo
7181280405Srpaulo<li>debug facilities (<a href="#6.10">&sect;6.10</a>).</li>
7182280405Srpaulo
7183280405Srpaulo</ul><p>
7184280405SrpauloExcept for the basic and the package libraries,
7185280405Srpauloeach library provides all its functions as fields of a global table
7186280405Srpauloor as methods of its objects.
7187280405Srpaulo
7188280405Srpaulo
7189280405Srpaulo<p>
7190280405SrpauloTo have access to these libraries,
7191280405Srpaulothe C&nbsp;host program should call the <a href="#luaL_openlibs"><code>luaL_openlibs</code></a> function,
7192280405Srpaulowhich opens all standard libraries.
7193280405SrpauloAlternatively,
7194280405Srpaulothe host program can open them individually by using
7195280405Srpaulo<a href="#luaL_requiref"><code>luaL_requiref</code></a> to call
7196280405Srpaulo<a name="pdf-luaopen_base"><code>luaopen_base</code></a> (for the basic library),
7197280405Srpaulo<a name="pdf-luaopen_package"><code>luaopen_package</code></a> (for the package library),
7198280405Srpaulo<a name="pdf-luaopen_coroutine"><code>luaopen_coroutine</code></a> (for the coroutine library),
7199280405Srpaulo<a name="pdf-luaopen_string"><code>luaopen_string</code></a> (for the string library),
7200280405Srpaulo<a name="pdf-luaopen_utf8"><code>luaopen_utf8</code></a> (for the UTF8 library),
7201280405Srpaulo<a name="pdf-luaopen_table"><code>luaopen_table</code></a> (for the table library),
7202280405Srpaulo<a name="pdf-luaopen_math"><code>luaopen_math</code></a> (for the mathematical library),
7203280405Srpaulo<a name="pdf-luaopen_io"><code>luaopen_io</code></a> (for the I/O library),
7204280405Srpaulo<a name="pdf-luaopen_os"><code>luaopen_os</code></a> (for the operating system library),
7205280405Srpauloand <a name="pdf-luaopen_debug"><code>luaopen_debug</code></a> (for the debug library).
7206280405SrpauloThese functions are declared in <a name="pdf-lualib.h"><code>lualib.h</code></a>.
7207280405Srpaulo
7208280405Srpaulo
7209280405Srpaulo
7210280405Srpaulo<h2>6.1 &ndash; <a name="6.1">Basic Functions</a></h2>
7211280405Srpaulo
7212280405Srpaulo<p>
7213280405SrpauloThe basic library provides core functions to Lua.
7214280405SrpauloIf you do not include this library in your application,
7215280405Srpauloyou should check carefully whether you need to provide
7216280405Srpauloimplementations for some of its facilities.
7217280405Srpaulo
7218280405Srpaulo
7219280405Srpaulo<p>
7220280405Srpaulo<hr><h3><a name="pdf-assert"><code>assert (v [, message])</code></a></h3>
7221280405Srpaulo
7222280405Srpaulo
7223280405Srpaulo<p>
7224280405SrpauloCalls <a href="#pdf-error"><code>error</code></a> if
7225280405Srpaulothe value of its argument <code>v</code> is false (i.e., <b>nil</b> or <b>false</b>);
7226280405Srpaulootherwise, returns all its arguments.
7227280405SrpauloIn case of error,
7228280405Srpaulo<code>message</code> is the error object;
7229280405Srpaulowhen absent, it defaults to "<code>assertion failed!</code>"
7230280405Srpaulo
7231280405Srpaulo
7232280405Srpaulo
7233280405Srpaulo
7234280405Srpaulo<p>
7235280405Srpaulo<hr><h3><a name="pdf-collectgarbage"><code>collectgarbage ([opt [, arg]])</code></a></h3>
7236280405Srpaulo
7237280405Srpaulo
7238280405Srpaulo<p>
7239280405SrpauloThis function is a generic interface to the garbage collector.
7240280405SrpauloIt performs different functions according to its first argument, <code>opt</code>:
7241280405Srpaulo
7242280405Srpaulo<ul>
7243280405Srpaulo
7244280405Srpaulo<li><b>"<code>collect</code>": </b>
7245280405Srpauloperforms a full garbage-collection cycle.
7246280405SrpauloThis is the default option.
7247280405Srpaulo</li>
7248280405Srpaulo
7249280405Srpaulo<li><b>"<code>stop</code>": </b>
7250280405Srpaulostops automatic execution of the garbage collector.
7251280405SrpauloThe collector will run only when explicitly invoked,
7252280405Srpaulountil a call to restart it.
7253280405Srpaulo</li>
7254280405Srpaulo
7255280405Srpaulo<li><b>"<code>restart</code>": </b>
7256280405Srpaulorestarts automatic execution of the garbage collector.
7257280405Srpaulo</li>
7258280405Srpaulo
7259280405Srpaulo<li><b>"<code>count</code>": </b>
7260280405Srpauloreturns the total memory in use by Lua in Kbytes.
7261280405SrpauloThe value has a fractional part,
7262280405Srpauloso that it multiplied by 1024
7263280405Srpaulogives the exact number of bytes in use by Lua
7264280405Srpaulo(except for overflows).
7265280405Srpaulo</li>
7266280405Srpaulo
7267280405Srpaulo<li><b>"<code>step</code>": </b>
7268280405Srpauloperforms a garbage-collection step.
7269280405SrpauloThe step "size" is controlled by <code>arg</code>.
7270280405SrpauloWith a zero value,
7271280405Srpaulothe collector will perform one basic (indivisible) step.
7272280405SrpauloFor non-zero values,
7273280405Srpaulothe collector will perform as if that amount of memory
7274280405Srpaulo(in KBytes) had been allocated by Lua.
7275280405SrpauloReturns <b>true</b> if the step finished a collection cycle.
7276280405Srpaulo</li>
7277280405Srpaulo
7278280405Srpaulo<li><b>"<code>setpause</code>": </b>
7279280405Srpaulosets <code>arg</code> as the new value for the <em>pause</em> of
7280280405Srpaulothe collector (see <a href="#2.5">&sect;2.5</a>).
7281280405SrpauloReturns the previous value for <em>pause</em>.
7282280405Srpaulo</li>
7283280405Srpaulo
7284280405Srpaulo<li><b>"<code>setstepmul</code>": </b>
7285280405Srpaulosets <code>arg</code> as the new value for the <em>step multiplier</em> of
7286280405Srpaulothe collector (see <a href="#2.5">&sect;2.5</a>).
7287280405SrpauloReturns the previous value for <em>step</em>.
7288280405Srpaulo</li>
7289280405Srpaulo
7290280405Srpaulo<li><b>"<code>isrunning</code>": </b>
7291280405Srpauloreturns a boolean that tells whether the collector is running
7292280405Srpaulo(i.e., not stopped).
7293280405Srpaulo</li>
7294280405Srpaulo
7295280405Srpaulo</ul>
7296280405Srpaulo
7297280405Srpaulo
7298280405Srpaulo
7299280405Srpaulo<p>
7300280405Srpaulo<hr><h3><a name="pdf-dofile"><code>dofile ([filename])</code></a></h3>
7301280405SrpauloOpens the named file and executes its contents as a Lua chunk.
7302280405SrpauloWhen called without arguments,
7303280405Srpaulo<code>dofile</code> executes the contents of the standard input (<code>stdin</code>).
7304280405SrpauloReturns all values returned by the chunk.
7305280405SrpauloIn case of errors, <code>dofile</code> propagates the error
7306280405Srpauloto its caller (that is, <code>dofile</code> does not run in protected mode).
7307280405Srpaulo
7308280405Srpaulo
7309280405Srpaulo
7310280405Srpaulo
7311280405Srpaulo<p>
7312280405Srpaulo<hr><h3><a name="pdf-error"><code>error (message [, level])</code></a></h3>
7313280405SrpauloTerminates the last protected function called
7314280405Srpauloand returns <code>message</code> as the error object.
7315280405SrpauloFunction <code>error</code> never returns.
7316280405Srpaulo
7317280405Srpaulo
7318280405Srpaulo<p>
7319280405SrpauloUsually, <code>error</code> adds some information about the error position
7320280405Srpauloat the beginning of the message, if the message is a string.
7321280405SrpauloThe <code>level</code> argument specifies how to get the error position.
7322280405SrpauloWith level&nbsp;1 (the default), the error position is where the
7323280405Srpaulo<code>error</code> function was called.
7324280405SrpauloLevel&nbsp;2 points the error to where the function
7325280405Srpaulothat called <code>error</code> was called; and so on.
7326280405SrpauloPassing a level&nbsp;0 avoids the addition of error position information
7327280405Srpauloto the message.
7328280405Srpaulo
7329280405Srpaulo
7330280405Srpaulo
7331280405Srpaulo
7332280405Srpaulo<p>
7333280405Srpaulo<hr><h3><a name="pdf-_G"><code>_G</code></a></h3>
7334280405SrpauloA global variable (not a function) that
7335280405Srpauloholds the global environment (see <a href="#2.2">&sect;2.2</a>).
7336280405SrpauloLua itself does not use this variable;
7337280405Srpaulochanging its value does not affect any environment,
7338280405Srpaulonor vice versa.
7339280405Srpaulo
7340280405Srpaulo
7341280405Srpaulo
7342280405Srpaulo
7343280405Srpaulo<p>
7344280405Srpaulo<hr><h3><a name="pdf-getmetatable"><code>getmetatable (object)</code></a></h3>
7345280405Srpaulo
7346280405Srpaulo
7347280405Srpaulo<p>
7348280405SrpauloIf <code>object</code> does not have a metatable, returns <b>nil</b>.
7349280405SrpauloOtherwise,
7350326344Simpif the object's metatable has a <code>__metatable</code> field,
7351280405Srpauloreturns the associated value.
7352280405SrpauloOtherwise, returns the metatable of the given object.
7353280405Srpaulo
7354280405Srpaulo
7355280405Srpaulo
7356280405Srpaulo
7357280405Srpaulo<p>
7358280405Srpaulo<hr><h3><a name="pdf-ipairs"><code>ipairs (t)</code></a></h3>
7359280405Srpaulo
7360280405Srpaulo
7361280405Srpaulo<p>
7362280405SrpauloReturns three values (an iterator function, the table <code>t</code>, and 0)
7363280405Srpauloso that the construction
7364280405Srpaulo
7365280405Srpaulo<pre>
7366280405Srpaulo     for i,v in ipairs(t) do <em>body</em> end
7367280405Srpaulo</pre><p>
7368280405Srpaulowill iterate over the key&ndash;value pairs
7369280405Srpaulo(<code>1,t[1]</code>), (<code>2,t[2]</code>), ...,
7370280405Srpauloup to the first nil value.
7371280405Srpaulo
7372280405Srpaulo
7373280405Srpaulo
7374280405Srpaulo
7375280405Srpaulo<p>
7376280405Srpaulo<hr><h3><a name="pdf-load"><code>load (chunk [, chunkname [, mode [, env]]])</code></a></h3>
7377280405Srpaulo
7378280405Srpaulo
7379280405Srpaulo<p>
7380280405SrpauloLoads a chunk.
7381280405Srpaulo
7382280405Srpaulo
7383280405Srpaulo<p>
7384280405SrpauloIf <code>chunk</code> is a string, the chunk is this string.
7385280405SrpauloIf <code>chunk</code> is a function,
7386280405Srpaulo<code>load</code> calls it repeatedly to get the chunk pieces.
7387280405SrpauloEach call to <code>chunk</code> must return a string that concatenates
7388280405Srpaulowith previous results.
7389280405SrpauloA return of an empty string, <b>nil</b>, or no value signals the end of the chunk.
7390280405Srpaulo
7391280405Srpaulo
7392280405Srpaulo<p>
7393280405SrpauloIf there are no syntactic errors,
7394280405Srpauloreturns the compiled chunk as a function;
7395280405Srpaulootherwise, returns <b>nil</b> plus the error message.
7396280405Srpaulo
7397280405Srpaulo
7398280405Srpaulo<p>
7399280405SrpauloIf the resulting function has upvalues,
7400280405Srpaulothe first upvalue is set to the value of <code>env</code>,
7401280405Srpauloif that parameter is given,
7402280405Srpauloor to the value of the global environment.
7403280405SrpauloOther upvalues are initialized with <b>nil</b>.
7404280405Srpaulo(When you load a main chunk,
7405280405Srpaulothe resulting function will always have exactly one upvalue,
7406280405Srpaulothe <code>_ENV</code> variable (see <a href="#2.2">&sect;2.2</a>).
7407280405SrpauloHowever,
7408280405Srpaulowhen you load a binary chunk created from a function (see <a href="#pdf-string.dump"><code>string.dump</code></a>),
7409280405Srpaulothe resulting function can have an arbitrary number of upvalues.)
7410280405SrpauloAll upvalues are fresh, that is,
7411280405Srpaulothey are not shared with any other function.
7412280405Srpaulo
7413280405Srpaulo
7414280405Srpaulo<p>
7415280405Srpaulo<code>chunkname</code> is used as the name of the chunk for error messages
7416280405Srpauloand debug information (see <a href="#4.9">&sect;4.9</a>).
7417280405SrpauloWhen absent,
7418280405Srpauloit defaults to <code>chunk</code>, if <code>chunk</code> is a string,
7419280405Srpauloor to "<code>=(load)</code>" otherwise.
7420280405Srpaulo
7421280405Srpaulo
7422280405Srpaulo<p>
7423280405SrpauloThe string <code>mode</code> controls whether the chunk can be text or binary
7424280405Srpaulo(that is, a precompiled chunk).
7425280405SrpauloIt may be the string "<code>b</code>" (only binary chunks),
7426280405Srpaulo"<code>t</code>" (only text chunks),
7427280405Srpauloor "<code>bt</code>" (both binary and text).
7428280405SrpauloThe default is "<code>bt</code>".
7429280405Srpaulo
7430280405Srpaulo
7431280405Srpaulo<p>
7432280405SrpauloLua does not check the consistency of binary chunks.
7433280405SrpauloMaliciously crafted binary chunks can crash
7434280405Srpaulothe interpreter.
7435280405Srpaulo
7436280405Srpaulo
7437280405Srpaulo
7438280405Srpaulo
7439280405Srpaulo<p>
7440280405Srpaulo<hr><h3><a name="pdf-loadfile"><code>loadfile ([filename [, mode [, env]]])</code></a></h3>
7441280405Srpaulo
7442280405Srpaulo
7443280405Srpaulo<p>
7444280405SrpauloSimilar to <a href="#pdf-load"><code>load</code></a>,
7445280405Srpaulobut gets the chunk from file <code>filename</code>
7446280405Srpauloor from the standard input,
7447280405Srpauloif no file name is given.
7448280405Srpaulo
7449280405Srpaulo
7450280405Srpaulo
7451280405Srpaulo
7452280405Srpaulo<p>
7453280405Srpaulo<hr><h3><a name="pdf-next"><code>next (table [, index])</code></a></h3>
7454280405Srpaulo
7455280405Srpaulo
7456280405Srpaulo<p>
7457280405SrpauloAllows a program to traverse all fields of a table.
7458280405SrpauloIts first argument is a table and its second argument
7459280405Srpaulois an index in this table.
7460280405Srpaulo<code>next</code> returns the next index of the table
7461280405Srpauloand its associated value.
7462280405SrpauloWhen called with <b>nil</b> as its second argument,
7463280405Srpaulo<code>next</code> returns an initial index
7464280405Srpauloand its associated value.
7465280405SrpauloWhen called with the last index,
7466280405Srpauloor with <b>nil</b> in an empty table,
7467280405Srpaulo<code>next</code> returns <b>nil</b>.
7468280405SrpauloIf the second argument is absent, then it is interpreted as <b>nil</b>.
7469280405SrpauloIn particular,
7470280405Srpauloyou can use <code>next(t)</code> to check whether a table is empty.
7471280405Srpaulo
7472280405Srpaulo
7473280405Srpaulo<p>
7474280405SrpauloThe order in which the indices are enumerated is not specified,
7475280405Srpaulo<em>even for numeric indices</em>.
7476326344Simp(To traverse a table in numerical order,
7477280405Srpaulouse a numerical <b>for</b>.)
7478280405Srpaulo
7479280405Srpaulo
7480280405Srpaulo<p>
7481280405SrpauloThe behavior of <code>next</code> is undefined if,
7482280405Srpauloduring the traversal,
7483280405Srpauloyou assign any value to a non-existent field in the table.
7484280405SrpauloYou may however modify existing fields.
7485280405SrpauloIn particular, you may clear existing fields.
7486280405Srpaulo
7487280405Srpaulo
7488280405Srpaulo
7489280405Srpaulo
7490280405Srpaulo<p>
7491280405Srpaulo<hr><h3><a name="pdf-pairs"><code>pairs (t)</code></a></h3>
7492280405Srpaulo
7493280405Srpaulo
7494280405Srpaulo<p>
7495280405SrpauloIf <code>t</code> has a metamethod <code>__pairs</code>,
7496280405Srpaulocalls it with <code>t</code> as argument and returns the first three
7497280405Srpauloresults from the call.
7498280405Srpaulo
7499280405Srpaulo
7500280405Srpaulo<p>
7501280405SrpauloOtherwise,
7502280405Srpauloreturns three values: the <a href="#pdf-next"><code>next</code></a> function, the table <code>t</code>, and <b>nil</b>,
7503280405Srpauloso that the construction
7504280405Srpaulo
7505280405Srpaulo<pre>
7506280405Srpaulo     for k,v in pairs(t) do <em>body</em> end
7507280405Srpaulo</pre><p>
7508280405Srpaulowill iterate over all key&ndash;value pairs of table <code>t</code>.
7509280405Srpaulo
7510280405Srpaulo
7511280405Srpaulo<p>
7512280405SrpauloSee function <a href="#pdf-next"><code>next</code></a> for the caveats of modifying
7513280405Srpaulothe table during its traversal.
7514280405Srpaulo
7515280405Srpaulo
7516280405Srpaulo
7517280405Srpaulo
7518280405Srpaulo<p>
7519280405Srpaulo<hr><h3><a name="pdf-pcall"><code>pcall (f [, arg1, &middot;&middot;&middot;])</code></a></h3>
7520280405Srpaulo
7521280405Srpaulo
7522280405Srpaulo<p>
7523280405SrpauloCalls function <code>f</code> with
7524280405Srpaulothe given arguments in <em>protected mode</em>.
7525280405SrpauloThis means that any error inside&nbsp;<code>f</code> is not propagated;
7526280405Srpauloinstead, <code>pcall</code> catches the error
7527280405Srpauloand returns a status code.
7528280405SrpauloIts first result is the status code (a boolean),
7529280405Srpaulowhich is true if the call succeeds without errors.
7530280405SrpauloIn such case, <code>pcall</code> also returns all results from the call,
7531280405Srpauloafter this first result.
7532280405SrpauloIn case of any error, <code>pcall</code> returns <b>false</b> plus the error message.
7533280405Srpaulo
7534280405Srpaulo
7535280405Srpaulo
7536280405Srpaulo
7537280405Srpaulo<p>
7538280405Srpaulo<hr><h3><a name="pdf-print"><code>print (&middot;&middot;&middot;)</code></a></h3>
7539280405SrpauloReceives any number of arguments
7540280405Srpauloand prints their values to <code>stdout</code>,
7541280405Srpaulousing the <a href="#pdf-tostring"><code>tostring</code></a> function to convert each argument to a string.
7542280405Srpaulo<code>print</code> is not intended for formatted output,
7543280405Srpaulobut only as a quick way to show a value,
7544280405Srpaulofor instance for debugging.
7545280405SrpauloFor complete control over the output,
7546280405Srpaulouse <a href="#pdf-string.format"><code>string.format</code></a> and <a href="#pdf-io.write"><code>io.write</code></a>.
7547280405Srpaulo
7548280405Srpaulo
7549280405Srpaulo
7550280405Srpaulo
7551280405Srpaulo<p>
7552280405Srpaulo<hr><h3><a name="pdf-rawequal"><code>rawequal (v1, v2)</code></a></h3>
7553280405SrpauloChecks whether <code>v1</code> is equal to <code>v2</code>,
7554326344Simpwithout invoking the <code>__eq</code> metamethod.
7555280405SrpauloReturns a boolean.
7556280405Srpaulo
7557280405Srpaulo
7558280405Srpaulo
7559280405Srpaulo
7560280405Srpaulo<p>
7561280405Srpaulo<hr><h3><a name="pdf-rawget"><code>rawget (table, index)</code></a></h3>
7562280405SrpauloGets the real value of <code>table[index]</code>,
7563326344Simpwithout invoking the <code>__index</code> metamethod.
7564280405Srpaulo<code>table</code> must be a table;
7565280405Srpaulo<code>index</code> may be any value.
7566280405Srpaulo
7567280405Srpaulo
7568280405Srpaulo
7569280405Srpaulo
7570280405Srpaulo<p>
7571280405Srpaulo<hr><h3><a name="pdf-rawlen"><code>rawlen (v)</code></a></h3>
7572280405SrpauloReturns the length of the object <code>v</code>,
7573280405Srpaulowhich must be a table or a string,
7574326344Simpwithout invoking the <code>__len</code> metamethod.
7575280405SrpauloReturns an integer.
7576280405Srpaulo
7577280405Srpaulo
7578280405Srpaulo
7579280405Srpaulo
7580280405Srpaulo<p>
7581280405Srpaulo<hr><h3><a name="pdf-rawset"><code>rawset (table, index, value)</code></a></h3>
7582280405SrpauloSets the real value of <code>table[index]</code> to <code>value</code>,
7583326344Simpwithout invoking the <code>__newindex</code> metamethod.
7584280405Srpaulo<code>table</code> must be a table,
7585280405Srpaulo<code>index</code> any value different from <b>nil</b> and NaN,
7586280405Srpauloand <code>value</code> any Lua value.
7587280405Srpaulo
7588280405Srpaulo
7589280405Srpaulo<p>
7590280405SrpauloThis function returns <code>table</code>.
7591280405Srpaulo
7592280405Srpaulo
7593280405Srpaulo
7594280405Srpaulo
7595280405Srpaulo<p>
7596280405Srpaulo<hr><h3><a name="pdf-select"><code>select (index, &middot;&middot;&middot;)</code></a></h3>
7597280405Srpaulo
7598280405Srpaulo
7599280405Srpaulo<p>
7600280405SrpauloIf <code>index</code> is a number,
7601280405Srpauloreturns all arguments after argument number <code>index</code>;
7602280405Srpauloa negative number indexes from the end (-1 is the last argument).
7603280405SrpauloOtherwise, <code>index</code> must be the string <code>"#"</code>,
7604280405Srpauloand <code>select</code> returns the total number of extra arguments it received.
7605280405Srpaulo
7606280405Srpaulo
7607280405Srpaulo
7608280405Srpaulo
7609280405Srpaulo<p>
7610280405Srpaulo<hr><h3><a name="pdf-setmetatable"><code>setmetatable (table, metatable)</code></a></h3>
7611280405Srpaulo
7612280405Srpaulo
7613280405Srpaulo<p>
7614280405SrpauloSets the metatable for the given table.
7615326344Simp(To change the metatable of other types from Lua code,
7616326344Simpyou must use the debug library (<a href="#6.10">&sect;6.10</a>).)
7617280405SrpauloIf <code>metatable</code> is <b>nil</b>,
7618280405Srpauloremoves the metatable of the given table.
7619326344SimpIf the original metatable has a <code>__metatable</code> field,
7620280405Srpauloraises an error.
7621280405Srpaulo
7622280405Srpaulo
7623280405Srpaulo<p>
7624280405SrpauloThis function returns <code>table</code>.
7625280405Srpaulo
7626280405Srpaulo
7627280405Srpaulo
7628280405Srpaulo
7629280405Srpaulo<p>
7630280405Srpaulo<hr><h3><a name="pdf-tonumber"><code>tonumber (e [, base])</code></a></h3>
7631280405Srpaulo
7632280405Srpaulo
7633280405Srpaulo<p>
7634280405SrpauloWhen called with no <code>base</code>,
7635280405Srpaulo<code>tonumber</code> tries to convert its argument to a number.
7636280405SrpauloIf the argument is already a number or
7637280405Srpauloa string convertible to a number,
7638280405Srpaulothen <code>tonumber</code> returns this number;
7639280405Srpaulootherwise, it returns <b>nil</b>.
7640280405Srpaulo
7641280405Srpaulo
7642280405Srpaulo<p>
7643280405SrpauloThe conversion of strings can result in integers or floats,
7644280405Srpauloaccording to the lexical conventions of Lua (see <a href="#3.1">&sect;3.1</a>).
7645280405Srpaulo(The string may have leading and trailing spaces and a sign.)
7646280405Srpaulo
7647280405Srpaulo
7648280405Srpaulo<p>
7649280405SrpauloWhen called with <code>base</code>,
7650280405Srpaulothen <code>e</code> must be a string to be interpreted as
7651280405Srpauloan integer numeral in that base.
7652280405SrpauloThe base may be any integer between 2 and 36, inclusive.
7653280405SrpauloIn bases above&nbsp;10, the letter '<code>A</code>' (in either upper or lower case)
7654280405Srpaulorepresents&nbsp;10, '<code>B</code>' represents&nbsp;11, and so forth,
7655280405Srpaulowith '<code>Z</code>' representing 35.
7656280405SrpauloIf the string <code>e</code> is not a valid numeral in the given base,
7657280405Srpaulothe function returns <b>nil</b>.
7658280405Srpaulo
7659280405Srpaulo
7660280405Srpaulo
7661280405Srpaulo
7662280405Srpaulo<p>
7663280405Srpaulo<hr><h3><a name="pdf-tostring"><code>tostring (v)</code></a></h3>
7664280405SrpauloReceives a value of any type and
7665280405Srpauloconverts it to a string in a human-readable format.
7666280405Srpaulo(For complete control of how numbers are converted,
7667280405Srpaulouse <a href="#pdf-string.format"><code>string.format</code></a>.)
7668280405Srpaulo
7669280405Srpaulo
7670280405Srpaulo<p>
7671326344SimpIf the metatable of <code>v</code> has a <code>__tostring</code> field,
7672280405Srpaulothen <code>tostring</code> calls the corresponding value
7673280405Srpaulowith <code>v</code> as argument,
7674280405Srpauloand uses the result of the call as its result.
7675280405Srpaulo
7676280405Srpaulo
7677280405Srpaulo
7678280405Srpaulo
7679280405Srpaulo<p>
7680280405Srpaulo<hr><h3><a name="pdf-type"><code>type (v)</code></a></h3>
7681280405SrpauloReturns the type of its only argument, coded as a string.
7682280405SrpauloThe possible results of this function are
7683280405Srpaulo"<code>nil</code>" (a string, not the value <b>nil</b>),
7684280405Srpaulo"<code>number</code>",
7685280405Srpaulo"<code>string</code>",
7686280405Srpaulo"<code>boolean</code>",
7687280405Srpaulo"<code>table</code>",
7688280405Srpaulo"<code>function</code>",
7689280405Srpaulo"<code>thread</code>",
7690280405Srpauloand "<code>userdata</code>".
7691280405Srpaulo
7692280405Srpaulo
7693280405Srpaulo
7694280405Srpaulo
7695280405Srpaulo<p>
7696280405Srpaulo<hr><h3><a name="pdf-_VERSION"><code>_VERSION</code></a></h3>
7697326344Simp
7698326344Simp
7699326344Simp<p>
7700280405SrpauloA global variable (not a function) that
7701326344Simpholds a string containing the running Lua version.
7702280405SrpauloThe current value of this variable is "<code>Lua 5.3</code>".
7703280405Srpaulo
7704280405Srpaulo
7705280405Srpaulo
7706280405Srpaulo
7707280405Srpaulo<p>
7708280405Srpaulo<hr><h3><a name="pdf-xpcall"><code>xpcall (f, msgh [, arg1, &middot;&middot;&middot;])</code></a></h3>
7709280405Srpaulo
7710280405Srpaulo
7711280405Srpaulo<p>
7712280405SrpauloThis function is similar to <a href="#pdf-pcall"><code>pcall</code></a>,
7713280405Srpauloexcept that it sets a new message handler <code>msgh</code>.
7714280405Srpaulo
7715280405Srpaulo
7716280405Srpaulo
7717280405Srpaulo
7718280405Srpaulo
7719280405Srpaulo
7720280405Srpaulo
7721280405Srpaulo<h2>6.2 &ndash; <a name="6.2">Coroutine Manipulation</a></h2>
7722280405Srpaulo
7723280405Srpaulo<p>
7724326344SimpThis library comprises the operations to manipulate coroutines,
7725326344Simpwhich come inside the table <a name="pdf-coroutine"><code>coroutine</code></a>.
7726280405SrpauloSee <a href="#2.6">&sect;2.6</a> for a general description of coroutines.
7727280405Srpaulo
7728280405Srpaulo
7729280405Srpaulo<p>
7730280405Srpaulo<hr><h3><a name="pdf-coroutine.create"><code>coroutine.create (f)</code></a></h3>
7731280405Srpaulo
7732280405Srpaulo
7733280405Srpaulo<p>
7734280405SrpauloCreates a new coroutine, with body <code>f</code>.
7735326344Simp<code>f</code> must be a function.
7736280405SrpauloReturns this new coroutine,
7737280405Srpauloan object with type <code>"thread"</code>.
7738280405Srpaulo
7739280405Srpaulo
7740280405Srpaulo
7741280405Srpaulo
7742280405Srpaulo<p>
7743280405Srpaulo<hr><h3><a name="pdf-coroutine.isyieldable"><code>coroutine.isyieldable ()</code></a></h3>
7744280405Srpaulo
7745280405Srpaulo
7746280405Srpaulo<p>
7747280405SrpauloReturns true when the running coroutine can yield.
7748280405Srpaulo
7749280405Srpaulo
7750280405Srpaulo<p>
7751280405SrpauloA running coroutine is yieldable if it is not the main thread and
7752326344Simpit is not inside a non-yieldable C&nbsp;function.
7753280405Srpaulo
7754280405Srpaulo
7755280405Srpaulo
7756280405Srpaulo
7757280405Srpaulo<p>
7758280405Srpaulo<hr><h3><a name="pdf-coroutine.resume"><code>coroutine.resume (co [, val1, &middot;&middot;&middot;])</code></a></h3>
7759280405Srpaulo
7760280405Srpaulo
7761280405Srpaulo<p>
7762280405SrpauloStarts or continues the execution of coroutine <code>co</code>.
7763280405SrpauloThe first time you resume a coroutine,
7764280405Srpauloit starts running its body.
7765280405SrpauloThe values <code>val1</code>, ... are passed
7766280405Srpauloas the arguments to the body function.
7767280405SrpauloIf the coroutine has yielded,
7768280405Srpaulo<code>resume</code> restarts it;
7769280405Srpaulothe values <code>val1</code>, ... are passed
7770280405Srpauloas the results from the yield.
7771280405Srpaulo
7772280405Srpaulo
7773280405Srpaulo<p>
7774280405SrpauloIf the coroutine runs without any errors,
7775280405Srpaulo<code>resume</code> returns <b>true</b> plus any values passed to <code>yield</code>
7776280405Srpaulo(when the coroutine yields) or any values returned by the body function
7777280405Srpaulo(when the coroutine terminates).
7778280405SrpauloIf there is any error,
7779280405Srpaulo<code>resume</code> returns <b>false</b> plus the error message.
7780280405Srpaulo
7781280405Srpaulo
7782280405Srpaulo
7783280405Srpaulo
7784280405Srpaulo<p>
7785280405Srpaulo<hr><h3><a name="pdf-coroutine.running"><code>coroutine.running ()</code></a></h3>
7786280405Srpaulo
7787280405Srpaulo
7788280405Srpaulo<p>
7789280405SrpauloReturns the running coroutine plus a boolean,
7790280405Srpaulotrue when the running coroutine is the main one.
7791280405Srpaulo
7792280405Srpaulo
7793280405Srpaulo
7794280405Srpaulo
7795280405Srpaulo<p>
7796280405Srpaulo<hr><h3><a name="pdf-coroutine.status"><code>coroutine.status (co)</code></a></h3>
7797280405Srpaulo
7798280405Srpaulo
7799280405Srpaulo<p>
7800280405SrpauloReturns the status of coroutine <code>co</code>, as a string:
7801280405Srpaulo<code>"running"</code>,
7802280405Srpauloif the coroutine is running (that is, it called <code>status</code>);
7803280405Srpaulo<code>"suspended"</code>, if the coroutine is suspended in a call to <code>yield</code>,
7804280405Srpauloor if it has not started running yet;
7805280405Srpaulo<code>"normal"</code> if the coroutine is active but not running
7806280405Srpaulo(that is, it has resumed another coroutine);
7807280405Srpauloand <code>"dead"</code> if the coroutine has finished its body function,
7808280405Srpauloor if it has stopped with an error.
7809280405Srpaulo
7810280405Srpaulo
7811280405Srpaulo
7812280405Srpaulo
7813280405Srpaulo<p>
7814280405Srpaulo<hr><h3><a name="pdf-coroutine.wrap"><code>coroutine.wrap (f)</code></a></h3>
7815280405Srpaulo
7816280405Srpaulo
7817280405Srpaulo<p>
7818280405SrpauloCreates a new coroutine, with body <code>f</code>.
7819326344Simp<code>f</code> must be a function.
7820280405SrpauloReturns a function that resumes the coroutine each time it is called.
7821280405SrpauloAny arguments passed to the function behave as the
7822280405Srpauloextra arguments to <code>resume</code>.
7823280405SrpauloReturns the same values returned by <code>resume</code>,
7824280405Srpauloexcept the first boolean.
7825280405SrpauloIn case of error, propagates the error.
7826280405Srpaulo
7827280405Srpaulo
7828280405Srpaulo
7829280405Srpaulo
7830280405Srpaulo<p>
7831280405Srpaulo<hr><h3><a name="pdf-coroutine.yield"><code>coroutine.yield (&middot;&middot;&middot;)</code></a></h3>
7832280405Srpaulo
7833280405Srpaulo
7834280405Srpaulo<p>
7835280405SrpauloSuspends the execution of the calling coroutine.
7836280405SrpauloAny arguments to <code>yield</code> are passed as extra results to <code>resume</code>.
7837280405Srpaulo
7838280405Srpaulo
7839280405Srpaulo
7840280405Srpaulo
7841280405Srpaulo
7842280405Srpaulo
7843280405Srpaulo
7844280405Srpaulo<h2>6.3 &ndash; <a name="6.3">Modules</a></h2>
7845280405Srpaulo
7846280405Srpaulo<p>
7847280405SrpauloThe package library provides basic
7848280405Srpaulofacilities for loading modules in Lua.
7849280405SrpauloIt exports one function directly in the global environment:
7850280405Srpaulo<a href="#pdf-require"><code>require</code></a>.
7851280405SrpauloEverything else is exported in a table <a name="pdf-package"><code>package</code></a>.
7852280405Srpaulo
7853280405Srpaulo
7854280405Srpaulo<p>
7855280405Srpaulo<hr><h3><a name="pdf-require"><code>require (modname)</code></a></h3>
7856280405Srpaulo
7857280405Srpaulo
7858280405Srpaulo<p>
7859280405SrpauloLoads the given module.
7860280405SrpauloThe function starts by looking into the <a href="#pdf-package.loaded"><code>package.loaded</code></a> table
7861280405Srpauloto determine whether <code>modname</code> is already loaded.
7862280405SrpauloIf it is, then <code>require</code> returns the value stored
7863280405Srpauloat <code>package.loaded[modname]</code>.
7864280405SrpauloOtherwise, it tries to find a <em>loader</em> for the module.
7865280405Srpaulo
7866280405Srpaulo
7867280405Srpaulo<p>
7868280405SrpauloTo find a loader,
7869280405Srpaulo<code>require</code> is guided by the <a href="#pdf-package.searchers"><code>package.searchers</code></a> sequence.
7870280405SrpauloBy changing this sequence,
7871280405Srpaulowe can change how <code>require</code> looks for a module.
7872280405SrpauloThe following explanation is based on the default configuration
7873280405Srpaulofor <a href="#pdf-package.searchers"><code>package.searchers</code></a>.
7874280405Srpaulo
7875280405Srpaulo
7876280405Srpaulo<p>
7877280405SrpauloFirst <code>require</code> queries <code>package.preload[modname]</code>.
7878280405SrpauloIf it has a value,
7879280405Srpaulothis value (which must be a function) is the loader.
7880280405SrpauloOtherwise <code>require</code> searches for a Lua loader using the
7881280405Srpaulopath stored in <a href="#pdf-package.path"><code>package.path</code></a>.
7882280405SrpauloIf that also fails, it searches for a C&nbsp;loader using the
7883280405Srpaulopath stored in <a href="#pdf-package.cpath"><code>package.cpath</code></a>.
7884280405SrpauloIf that also fails,
7885280405Srpauloit tries an <em>all-in-one</em> loader (see <a href="#pdf-package.searchers"><code>package.searchers</code></a>).
7886280405Srpaulo
7887280405Srpaulo
7888280405Srpaulo<p>
7889280405SrpauloOnce a loader is found,
7890280405Srpaulo<code>require</code> calls the loader with two arguments:
7891280405Srpaulo<code>modname</code> and an extra value dependent on how it got the loader.
7892280405Srpaulo(If the loader came from a file,
7893280405Srpaulothis extra value is the file name.)
7894280405SrpauloIf the loader returns any non-nil value,
7895280405Srpaulo<code>require</code> assigns the returned value to <code>package.loaded[modname]</code>.
7896280405SrpauloIf the loader does not return a non-nil value and
7897280405Srpaulohas not assigned any value to <code>package.loaded[modname]</code>,
7898280405Srpaulothen <code>require</code> assigns <b>true</b> to this entry.
7899280405SrpauloIn any case, <code>require</code> returns the
7900280405Srpaulofinal value of <code>package.loaded[modname]</code>.
7901280405Srpaulo
7902280405Srpaulo
7903280405Srpaulo<p>
7904280405SrpauloIf there is any error loading or running the module,
7905280405Srpauloor if it cannot find any loader for the module,
7906280405Srpaulothen <code>require</code> raises an error.
7907280405Srpaulo
7908280405Srpaulo
7909280405Srpaulo
7910280405Srpaulo
7911280405Srpaulo<p>
7912280405Srpaulo<hr><h3><a name="pdf-package.config"><code>package.config</code></a></h3>
7913280405Srpaulo
7914280405Srpaulo
7915280405Srpaulo<p>
7916280405SrpauloA string describing some compile-time configurations for packages.
7917280405SrpauloThis string is a sequence of lines:
7918280405Srpaulo
7919280405Srpaulo<ul>
7920280405Srpaulo
7921280405Srpaulo<li>The first line is the directory separator string.
7922280405SrpauloDefault is '<code>\</code>' for Windows and '<code>/</code>' for all other systems.</li>
7923280405Srpaulo
7924280405Srpaulo<li>The second line is the character that separates templates in a path.
7925280405SrpauloDefault is '<code>;</code>'.</li>
7926280405Srpaulo
7927280405Srpaulo<li>The third line is the string that marks the
7928280405Srpaulosubstitution points in a template.
7929280405SrpauloDefault is '<code>?</code>'.</li>
7930280405Srpaulo
7931280405Srpaulo<li>The fourth line is a string that, in a path in Windows,
7932280405Srpaulois replaced by the executable's directory.
7933280405SrpauloDefault is '<code>!</code>'.</li>
7934280405Srpaulo
7935280405Srpaulo<li>The fifth line is a mark to ignore all text after it
7936280405Srpaulowhen building the <code>luaopen_</code> function name.
7937280405SrpauloDefault is '<code>-</code>'.</li>
7938280405Srpaulo
7939280405Srpaulo</ul>
7940280405Srpaulo
7941280405Srpaulo
7942280405Srpaulo
7943280405Srpaulo<p>
7944280405Srpaulo<hr><h3><a name="pdf-package.cpath"><code>package.cpath</code></a></h3>
7945280405Srpaulo
7946280405Srpaulo
7947280405Srpaulo<p>
7948280405SrpauloThe path used by <a href="#pdf-require"><code>require</code></a> to search for a C&nbsp;loader.
7949280405Srpaulo
7950280405Srpaulo
7951280405Srpaulo<p>
7952280405SrpauloLua initializes the C&nbsp;path <a href="#pdf-package.cpath"><code>package.cpath</code></a> in the same way
7953280405Srpauloit initializes the Lua path <a href="#pdf-package.path"><code>package.path</code></a>,
7954326344Simpusing the environment variable <a name="pdf-LUA_CPATH_5_3"><code>LUA_CPATH_5_3</code></a>,
7955326344Simpor the environment variable <a name="pdf-LUA_CPATH"><code>LUA_CPATH</code></a>,
7956280405Srpauloor a default path defined in <code>luaconf.h</code>.
7957280405Srpaulo
7958280405Srpaulo
7959280405Srpaulo
7960280405Srpaulo
7961280405Srpaulo<p>
7962280405Srpaulo<hr><h3><a name="pdf-package.loaded"><code>package.loaded</code></a></h3>
7963280405Srpaulo
7964280405Srpaulo
7965280405Srpaulo<p>
7966280405SrpauloA table used by <a href="#pdf-require"><code>require</code></a> to control which
7967280405Srpaulomodules are already loaded.
7968280405SrpauloWhen you require a module <code>modname</code> and
7969280405Srpaulo<code>package.loaded[modname]</code> is not false,
7970280405Srpaulo<a href="#pdf-require"><code>require</code></a> simply returns the value stored there.
7971280405Srpaulo
7972280405Srpaulo
7973280405Srpaulo<p>
7974280405SrpauloThis variable is only a reference to the real table;
7975280405Srpauloassignments to this variable do not change the
7976280405Srpaulotable used by <a href="#pdf-require"><code>require</code></a>.
7977280405Srpaulo
7978280405Srpaulo
7979280405Srpaulo
7980280405Srpaulo
7981280405Srpaulo<p>
7982280405Srpaulo<hr><h3><a name="pdf-package.loadlib"><code>package.loadlib (libname, funcname)</code></a></h3>
7983280405Srpaulo
7984280405Srpaulo
7985280405Srpaulo<p>
7986280405SrpauloDynamically links the host program with the C&nbsp;library <code>libname</code>.
7987280405Srpaulo
7988280405Srpaulo
7989280405Srpaulo<p>
7990280405SrpauloIf <code>funcname</code> is "<code>*</code>",
7991280405Srpaulothen it only links with the library,
7992280405Srpaulomaking the symbols exported by the library
7993280405Srpauloavailable to other dynamically linked libraries.
7994280405SrpauloOtherwise,
7995280405Srpauloit looks for a function <code>funcname</code> inside the library
7996280405Srpauloand returns this function as a C&nbsp;function.
7997280405SrpauloSo, <code>funcname</code> must follow the <a href="#lua_CFunction"><code>lua_CFunction</code></a> prototype
7998280405Srpaulo(see <a href="#lua_CFunction"><code>lua_CFunction</code></a>).
7999280405Srpaulo
8000280405Srpaulo
8001280405Srpaulo<p>
8002280405SrpauloThis is a low-level function.
8003280405SrpauloIt completely bypasses the package and module system.
8004280405SrpauloUnlike <a href="#pdf-require"><code>require</code></a>,
8005280405Srpauloit does not perform any path searching and
8006280405Srpaulodoes not automatically adds extensions.
8007280405Srpaulo<code>libname</code> must be the complete file name of the C&nbsp;library,
8008280405Srpauloincluding if necessary a path and an extension.
8009280405Srpaulo<code>funcname</code> must be the exact name exported by the C&nbsp;library
8010280405Srpaulo(which may depend on the C&nbsp;compiler and linker used).
8011280405Srpaulo
8012280405Srpaulo
8013280405Srpaulo<p>
8014280405SrpauloThis function is not supported by Standard&nbsp;C.
8015280405SrpauloAs such, it is only available on some platforms
8016280405Srpaulo(Windows, Linux, Mac OS X, Solaris, BSD,
8017280405Srpauloplus other Unix systems that support the <code>dlfcn</code> standard).
8018280405Srpaulo
8019280405Srpaulo
8020280405Srpaulo
8021280405Srpaulo
8022280405Srpaulo<p>
8023280405Srpaulo<hr><h3><a name="pdf-package.path"><code>package.path</code></a></h3>
8024280405Srpaulo
8025280405Srpaulo
8026280405Srpaulo<p>
8027280405SrpauloThe path used by <a href="#pdf-require"><code>require</code></a> to search for a Lua loader.
8028280405Srpaulo
8029280405Srpaulo
8030280405Srpaulo<p>
8031280405SrpauloAt start-up, Lua initializes this variable with
8032280405Srpaulothe value of the environment variable <a name="pdf-LUA_PATH_5_3"><code>LUA_PATH_5_3</code></a> or
8033280405Srpaulothe environment variable <a name="pdf-LUA_PATH"><code>LUA_PATH</code></a> or
8034280405Srpaulowith a default path defined in <code>luaconf.h</code>,
8035280405Srpauloif those environment variables are not defined.
8036280405SrpauloAny "<code>;;</code>" in the value of the environment variable
8037280405Srpaulois replaced by the default path.
8038280405Srpaulo
8039280405Srpaulo
8040280405Srpaulo
8041280405Srpaulo
8042280405Srpaulo<p>
8043280405Srpaulo<hr><h3><a name="pdf-package.preload"><code>package.preload</code></a></h3>
8044280405Srpaulo
8045280405Srpaulo
8046280405Srpaulo<p>
8047280405SrpauloA table to store loaders for specific modules
8048280405Srpaulo(see <a href="#pdf-require"><code>require</code></a>).
8049280405Srpaulo
8050280405Srpaulo
8051280405Srpaulo<p>
8052280405SrpauloThis variable is only a reference to the real table;
8053280405Srpauloassignments to this variable do not change the
8054280405Srpaulotable used by <a href="#pdf-require"><code>require</code></a>.
8055280405Srpaulo
8056280405Srpaulo
8057280405Srpaulo
8058280405Srpaulo
8059280405Srpaulo<p>
8060280405Srpaulo<hr><h3><a name="pdf-package.searchers"><code>package.searchers</code></a></h3>
8061280405Srpaulo
8062280405Srpaulo
8063280405Srpaulo<p>
8064280405SrpauloA table used by <a href="#pdf-require"><code>require</code></a> to control how to load modules.
8065280405Srpaulo
8066280405Srpaulo
8067280405Srpaulo<p>
8068280405SrpauloEach entry in this table is a <em>searcher function</em>.
8069280405SrpauloWhen looking for a module,
8070280405Srpaulo<a href="#pdf-require"><code>require</code></a> calls each of these searchers in ascending order,
8071280405Srpaulowith the module name (the argument given to <a href="#pdf-require"><code>require</code></a>) as its
8072280405Srpaulosole parameter.
8073280405SrpauloThe function can return another function (the module <em>loader</em>)
8074280405Srpauloplus an extra value that will be passed to that loader,
8075280405Srpauloor a string explaining why it did not find that module
8076280405Srpaulo(or <b>nil</b> if it has nothing to say).
8077280405Srpaulo
8078280405Srpaulo
8079280405Srpaulo<p>
8080280405SrpauloLua initializes this table with four searcher functions.
8081280405Srpaulo
8082280405Srpaulo
8083280405Srpaulo<p>
8084280405SrpauloThe first searcher simply looks for a loader in the
8085280405Srpaulo<a href="#pdf-package.preload"><code>package.preload</code></a> table.
8086280405Srpaulo
8087280405Srpaulo
8088280405Srpaulo<p>
8089280405SrpauloThe second searcher looks for a loader as a Lua library,
8090280405Srpaulousing the path stored at <a href="#pdf-package.path"><code>package.path</code></a>.
8091280405SrpauloThe search is done as described in function <a href="#pdf-package.searchpath"><code>package.searchpath</code></a>.
8092280405Srpaulo
8093280405Srpaulo
8094280405Srpaulo<p>
8095280405SrpauloThe third searcher looks for a loader as a C&nbsp;library,
8096280405Srpaulousing the path given by the variable <a href="#pdf-package.cpath"><code>package.cpath</code></a>.
8097280405SrpauloAgain,
8098280405Srpaulothe search is done as described in function <a href="#pdf-package.searchpath"><code>package.searchpath</code></a>.
8099280405SrpauloFor instance,
8100280405Srpauloif the C&nbsp;path is the string
8101280405Srpaulo
8102280405Srpaulo<pre>
8103280405Srpaulo     "./?.so;./?.dll;/usr/local/?/init.so"
8104280405Srpaulo</pre><p>
8105280405Srpaulothe searcher for module <code>foo</code>
8106280405Srpaulowill try to open the files <code>./foo.so</code>, <code>./foo.dll</code>,
8107280405Srpauloand <code>/usr/local/foo/init.so</code>, in that order.
8108280405SrpauloOnce it finds a C&nbsp;library,
8109280405Srpaulothis searcher first uses a dynamic link facility to link the
8110280405Srpauloapplication with the library.
8111280405SrpauloThen it tries to find a C&nbsp;function inside the library to
8112280405Srpaulobe used as the loader.
8113280405SrpauloThe name of this C&nbsp;function is the string "<code>luaopen_</code>"
8114280405Srpauloconcatenated with a copy of the module name where each dot
8115280405Srpaulois replaced by an underscore.
8116280405SrpauloMoreover, if the module name has a hyphen,
8117280405Srpauloits suffix after (and including) the first hyphen is removed.
8118280405SrpauloFor instance, if the module name is <code>a.b.c-v2.1</code>,
8119280405Srpaulothe function name will be <code>luaopen_a_b_c</code>.
8120280405Srpaulo
8121280405Srpaulo
8122280405Srpaulo<p>
8123280405SrpauloThe fourth searcher tries an <em>all-in-one loader</em>.
8124280405SrpauloIt searches the C&nbsp;path for a library for
8125280405Srpaulothe root name of the given module.
8126280405SrpauloFor instance, when requiring <code>a.b.c</code>,
8127280405Srpauloit will search for a C&nbsp;library for <code>a</code>.
8128280405SrpauloIf found, it looks into it for an open function for
8129280405Srpaulothe submodule;
8130280405Srpauloin our example, that would be <code>luaopen_a_b_c</code>.
8131280405SrpauloWith this facility, a package can pack several C&nbsp;submodules
8132280405Srpaulointo one single library,
8133280405Srpaulowith each submodule keeping its original open function.
8134280405Srpaulo
8135280405Srpaulo
8136280405Srpaulo<p>
8137280405SrpauloAll searchers except the first one (preload) return as the extra value
8138280405Srpaulothe file name where the module was found,
8139280405Srpauloas returned by <a href="#pdf-package.searchpath"><code>package.searchpath</code></a>.
8140280405SrpauloThe first searcher returns no extra value.
8141280405Srpaulo
8142280405Srpaulo
8143280405Srpaulo
8144280405Srpaulo
8145280405Srpaulo<p>
8146280405Srpaulo<hr><h3><a name="pdf-package.searchpath"><code>package.searchpath (name, path [, sep [, rep]])</code></a></h3>
8147280405Srpaulo
8148280405Srpaulo
8149280405Srpaulo<p>
8150280405SrpauloSearches for the given <code>name</code> in the given <code>path</code>.
8151280405Srpaulo
8152280405Srpaulo
8153280405Srpaulo<p>
8154280405SrpauloA path is a string containing a sequence of
8155280405Srpaulo<em>templates</em> separated by semicolons.
8156280405SrpauloFor each template,
8157280405Srpaulothe function replaces each interrogation mark (if any)
8158280405Srpauloin the template with a copy of <code>name</code>
8159280405Srpaulowherein all occurrences of <code>sep</code>
8160280405Srpaulo(a dot, by default)
8161280405Srpaulowere replaced by <code>rep</code>
8162280405Srpaulo(the system's directory separator, by default),
8163280405Srpauloand then tries to open the resulting file name.
8164280405Srpaulo
8165280405Srpaulo
8166280405Srpaulo<p>
8167280405SrpauloFor instance, if the path is the string
8168280405Srpaulo
8169280405Srpaulo<pre>
8170280405Srpaulo     "./?.lua;./?.lc;/usr/local/?/init.lua"
8171280405Srpaulo</pre><p>
8172280405Srpaulothe search for the name <code>foo.a</code>
8173280405Srpaulowill try to open the files
8174280405Srpaulo<code>./foo/a.lua</code>, <code>./foo/a.lc</code>, and
8175280405Srpaulo<code>/usr/local/foo/a/init.lua</code>, in that order.
8176280405Srpaulo
8177280405Srpaulo
8178280405Srpaulo<p>
8179280405SrpauloReturns the resulting name of the first file that it can
8180280405Srpauloopen in read mode (after closing the file),
8181280405Srpauloor <b>nil</b> plus an error message if none succeeds.
8182280405Srpaulo(This error message lists all file names it tried to open.)
8183280405Srpaulo
8184280405Srpaulo
8185280405Srpaulo
8186280405Srpaulo
8187280405Srpaulo
8188280405Srpaulo
8189280405Srpaulo
8190280405Srpaulo<h2>6.4 &ndash; <a name="6.4">String Manipulation</a></h2>
8191280405Srpaulo
8192280405Srpaulo<p>
8193280405SrpauloThis library provides generic functions for string manipulation,
8194280405Srpaulosuch as finding and extracting substrings, and pattern matching.
8195280405SrpauloWhen indexing a string in Lua, the first character is at position&nbsp;1
8196280405Srpaulo(not at&nbsp;0, as in C).
8197280405SrpauloIndices are allowed to be negative and are interpreted as indexing backwards,
8198280405Srpaulofrom the end of the string.
8199280405SrpauloThus, the last character is at position -1, and so on.
8200280405Srpaulo
8201280405Srpaulo
8202280405Srpaulo<p>
8203280405SrpauloThe string library provides all its functions inside the table
8204280405Srpaulo<a name="pdf-string"><code>string</code></a>.
8205280405SrpauloIt also sets a metatable for strings
8206280405Srpaulowhere the <code>__index</code> field points to the <code>string</code> table.
8207280405SrpauloTherefore, you can use the string functions in object-oriented style.
8208280405SrpauloFor instance, <code>string.byte(s,i)</code>
8209280405Srpaulocan be written as <code>s:byte(i)</code>.
8210280405Srpaulo
8211280405Srpaulo
8212280405Srpaulo<p>
8213280405SrpauloThe string library assumes one-byte character encodings.
8214280405Srpaulo
8215280405Srpaulo
8216280405Srpaulo<p>
8217280405Srpaulo<hr><h3><a name="pdf-string.byte"><code>string.byte (s [, i [, j]])</code></a></h3>
8218326344SimpReturns the internal numeric codes of the characters <code>s[i]</code>,
8219280405Srpaulo<code>s[i+1]</code>, ..., <code>s[j]</code>.
8220280405SrpauloThe default value for <code>i</code> is&nbsp;1;
8221280405Srpaulothe default value for <code>j</code> is&nbsp;<code>i</code>.
8222280405SrpauloThese indices are corrected
8223280405Srpaulofollowing the same rules of function <a href="#pdf-string.sub"><code>string.sub</code></a>.
8224280405Srpaulo
8225280405Srpaulo
8226280405Srpaulo<p>
8227326344SimpNumeric codes are not necessarily portable across platforms.
8228280405Srpaulo
8229280405Srpaulo
8230280405Srpaulo
8231280405Srpaulo
8232280405Srpaulo<p>
8233280405Srpaulo<hr><h3><a name="pdf-string.char"><code>string.char (&middot;&middot;&middot;)</code></a></h3>
8234280405SrpauloReceives zero or more integers.
8235280405SrpauloReturns a string with length equal to the number of arguments,
8236326344Simpin which each character has the internal numeric code equal
8237280405Srpauloto its corresponding argument.
8238280405Srpaulo
8239280405Srpaulo
8240280405Srpaulo<p>
8241326344SimpNumeric codes are not necessarily portable across platforms.
8242280405Srpaulo
8243280405Srpaulo
8244280405Srpaulo
8245280405Srpaulo
8246280405Srpaulo<p>
8247280405Srpaulo<hr><h3><a name="pdf-string.dump"><code>string.dump (function [, strip])</code></a></h3>
8248280405Srpaulo
8249280405Srpaulo
8250280405Srpaulo<p>
8251280405SrpauloReturns a string containing a binary representation
8252280405Srpaulo(a <em>binary chunk</em>)
8253280405Srpauloof the given function,
8254280405Srpauloso that a later <a href="#pdf-load"><code>load</code></a> on this string returns
8255280405Srpauloa copy of the function (but with new upvalues).
8256280405SrpauloIf <code>strip</code> is a true value,
8257326344Simpthe binary representation may not include all debug information
8258326344Simpabout the function,
8259326344Simpto save space.
8260280405Srpaulo
8261280405Srpaulo
8262280405Srpaulo<p>
8263280405SrpauloFunctions with upvalues have only their number of upvalues saved.
8264280405SrpauloWhen (re)loaded,
8265280405Srpaulothose upvalues receive fresh instances containing <b>nil</b>.
8266280405Srpaulo(You can use the debug library to serialize
8267280405Srpauloand reload the upvalues of a function
8268280405Srpauloin a way adequate to your needs.)
8269280405Srpaulo
8270280405Srpaulo
8271280405Srpaulo
8272280405Srpaulo
8273280405Srpaulo<p>
8274280405Srpaulo<hr><h3><a name="pdf-string.find"><code>string.find (s, pattern [, init [, plain]])</code></a></h3>
8275280405Srpaulo
8276280405Srpaulo
8277280405Srpaulo<p>
8278280405SrpauloLooks for the first match of
8279280405Srpaulo<code>pattern</code> (see <a href="#6.4.1">&sect;6.4.1</a>) in the string <code>s</code>.
8280280405SrpauloIf it finds a match, then <code>find</code> returns the indices of&nbsp;<code>s</code>
8281280405Srpaulowhere this occurrence starts and ends;
8282280405Srpaulootherwise, it returns <b>nil</b>.
8283326344SimpA third, optional numeric argument <code>init</code> specifies
8284280405Srpaulowhere to start the search;
8285280405Srpauloits default value is&nbsp;1 and can be negative.
8286280405SrpauloA value of <b>true</b> as a fourth, optional argument <code>plain</code>
8287280405Srpauloturns off the pattern matching facilities,
8288280405Srpauloso the function does a plain "find substring" operation,
8289280405Srpaulowith no characters in <code>pattern</code> being considered magic.
8290280405SrpauloNote that if <code>plain</code> is given, then <code>init</code> must be given as well.
8291280405Srpaulo
8292280405Srpaulo
8293280405Srpaulo<p>
8294280405SrpauloIf the pattern has captures,
8295280405Srpaulothen in a successful match
8296280405Srpaulothe captured values are also returned,
8297280405Srpauloafter the two indices.
8298280405Srpaulo
8299280405Srpaulo
8300280405Srpaulo
8301280405Srpaulo
8302280405Srpaulo<p>
8303280405Srpaulo<hr><h3><a name="pdf-string.format"><code>string.format (formatstring, &middot;&middot;&middot;)</code></a></h3>
8304280405Srpaulo
8305280405Srpaulo
8306280405Srpaulo<p>
8307280405SrpauloReturns a formatted version of its variable number of arguments
8308280405Srpaulofollowing the description given in its first argument (which must be a string).
8309280405SrpauloThe format string follows the same rules as the ISO&nbsp;C function <code>sprintf</code>.
8310280405SrpauloThe only differences are that the options/modifiers
8311280405Srpaulo<code>*</code>, <code>h</code>, <code>L</code>, <code>l</code>, <code>n</code>,
8312280405Srpauloand <code>p</code> are not supported
8313280405Srpauloand that there is an extra option, <code>q</code>.
8314326344Simp
8315326344Simp
8316326344Simp<p>
8317280405SrpauloThe <code>q</code> option formats a string between double quotes,
8318280405Srpaulousing escape sequences when necessary to ensure that
8319280405Srpauloit can safely be read back by the Lua interpreter.
8320280405SrpauloFor instance, the call
8321280405Srpaulo
8322280405Srpaulo<pre>
8323280405Srpaulo     string.format('%q', 'a string with "quotes" and \n new line')
8324280405Srpaulo</pre><p>
8325280405Srpaulomay produce the string:
8326280405Srpaulo
8327280405Srpaulo<pre>
8328280405Srpaulo     "a string with \"quotes\" and \
8329280405Srpaulo      new line"
8330280405Srpaulo</pre>
8331280405Srpaulo
8332280405Srpaulo<p>
8333280405SrpauloOptions
8334326344Simp<code>A</code>, <code>a</code>, <code>E</code>, <code>e</code>, <code>f</code>,
8335280405Srpaulo<code>G</code>, and <code>g</code> all expect a number as argument.
8336280405SrpauloOptions <code>c</code>, <code>d</code>,
8337280405Srpaulo<code>i</code>, <code>o</code>, <code>u</code>, <code>X</code>, and <code>x</code>
8338280405Srpauloexpect an integer.
8339326344SimpWhen Lua is compiled with a C89 compiler,
8340326344Simpoptions <code>A</code> and <code>a</code> (hexadecimal floats)
8341326344Simpdo not support any modifier (flags, width, length).
8342326344Simp
8343326344Simp
8344326344Simp<p>
8345326344SimpOption <code>s</code> expects a string;
8346326344Simpif its argument is not a string,
8347280405Srpauloit is converted to one following the same rules of <a href="#pdf-tostring"><code>tostring</code></a>.
8348326344SimpIf the option has any modifier (flags, width, length),
8349326344Simpthe string argument should not contain embedded zeros.
8350280405Srpaulo
8351280405Srpaulo
8352280405Srpaulo
8353280405Srpaulo
8354280405Srpaulo<p>
8355280405Srpaulo<hr><h3><a name="pdf-string.gmatch"><code>string.gmatch (s, pattern)</code></a></h3>
8356280405SrpauloReturns an iterator function that,
8357280405Srpauloeach time it is called,
8358280405Srpauloreturns the next captures from <code>pattern</code> (see <a href="#6.4.1">&sect;6.4.1</a>)
8359280405Srpauloover the string <code>s</code>.
8360280405SrpauloIf <code>pattern</code> specifies no captures,
8361280405Srpaulothen the whole match is produced in each call.
8362280405Srpaulo
8363280405Srpaulo
8364280405Srpaulo<p>
8365280405SrpauloAs an example, the following loop
8366280405Srpaulowill iterate over all the words from string <code>s</code>,
8367280405Srpauloprinting one per line:
8368280405Srpaulo
8369280405Srpaulo<pre>
8370280405Srpaulo     s = "hello world from Lua"
8371280405Srpaulo     for w in string.gmatch(s, "%a+") do
8372280405Srpaulo       print(w)
8373280405Srpaulo     end
8374280405Srpaulo</pre><p>
8375280405SrpauloThe next example collects all pairs <code>key=value</code> from the
8376280405Srpaulogiven string into a table:
8377280405Srpaulo
8378280405Srpaulo<pre>
8379280405Srpaulo     t = {}
8380280405Srpaulo     s = "from=world, to=Lua"
8381280405Srpaulo     for k, v in string.gmatch(s, "(%w+)=(%w+)") do
8382280405Srpaulo       t[k] = v
8383280405Srpaulo     end
8384280405Srpaulo</pre>
8385280405Srpaulo
8386280405Srpaulo<p>
8387280405SrpauloFor this function, a caret '<code>^</code>' at the start of a pattern does not
8388280405Srpaulowork as an anchor, as this would prevent the iteration.
8389280405Srpaulo
8390280405Srpaulo
8391280405Srpaulo
8392280405Srpaulo
8393280405Srpaulo<p>
8394280405Srpaulo<hr><h3><a name="pdf-string.gsub"><code>string.gsub (s, pattern, repl [, n])</code></a></h3>
8395280405SrpauloReturns a copy of <code>s</code>
8396280405Srpauloin which all (or the first <code>n</code>, if given)
8397280405Srpaulooccurrences of the <code>pattern</code> (see <a href="#6.4.1">&sect;6.4.1</a>) have been
8398280405Srpauloreplaced by a replacement string specified by <code>repl</code>,
8399280405Srpaulowhich can be a string, a table, or a function.
8400280405Srpaulo<code>gsub</code> also returns, as its second value,
8401280405Srpaulothe total number of matches that occurred.
8402280405SrpauloThe name <code>gsub</code> comes from <em>Global SUBstitution</em>.
8403280405Srpaulo
8404280405Srpaulo
8405280405Srpaulo<p>
8406280405SrpauloIf <code>repl</code> is a string, then its value is used for replacement.
8407280405SrpauloThe character&nbsp;<code>%</code> works as an escape character:
8408280405Srpauloany sequence in <code>repl</code> of the form <code>%<em>d</em></code>,
8409280405Srpaulowith <em>d</em> between 1 and 9,
8410280405Srpaulostands for the value of the <em>d</em>-th captured substring.
8411280405SrpauloThe sequence <code>%0</code> stands for the whole match.
8412280405SrpauloThe sequence <code>%%</code> stands for a single&nbsp;<code>%</code>.
8413280405Srpaulo
8414280405Srpaulo
8415280405Srpaulo<p>
8416280405SrpauloIf <code>repl</code> is a table, then the table is queried for every match,
8417280405Srpaulousing the first capture as the key.
8418280405Srpaulo
8419280405Srpaulo
8420280405Srpaulo<p>
8421280405SrpauloIf <code>repl</code> is a function, then this function is called every time a
8422280405Srpaulomatch occurs, with all captured substrings passed as arguments,
8423280405Srpauloin order.
8424280405Srpaulo
8425280405Srpaulo
8426280405Srpaulo<p>
8427280405SrpauloIn any case,
8428280405Srpauloif the pattern specifies no captures,
8429280405Srpaulothen it behaves as if the whole pattern was inside a capture.
8430280405Srpaulo
8431280405Srpaulo
8432280405Srpaulo<p>
8433280405SrpauloIf the value returned by the table query or by the function call
8434280405Srpaulois a string or a number,
8435280405Srpaulothen it is used as the replacement string;
8436280405Srpaulootherwise, if it is <b>false</b> or <b>nil</b>,
8437280405Srpaulothen there is no replacement
8438280405Srpaulo(that is, the original match is kept in the string).
8439280405Srpaulo
8440280405Srpaulo
8441280405Srpaulo<p>
8442280405SrpauloHere are some examples:
8443280405Srpaulo
8444280405Srpaulo<pre>
8445280405Srpaulo     x = string.gsub("hello world", "(%w+)", "%1 %1")
8446280405Srpaulo     --&gt; x="hello hello world world"
8447280405Srpaulo     
8448280405Srpaulo     x = string.gsub("hello world", "%w+", "%0 %0", 1)
8449280405Srpaulo     --&gt; x="hello hello world"
8450280405Srpaulo     
8451280405Srpaulo     x = string.gsub("hello world from Lua", "(%w+)%s*(%w+)", "%2 %1")
8452280405Srpaulo     --&gt; x="world hello Lua from"
8453280405Srpaulo     
8454280405Srpaulo     x = string.gsub("home = $HOME, user = $USER", "%$(%w+)", os.getenv)
8455280405Srpaulo     --&gt; x="home = /home/roberto, user = roberto"
8456280405Srpaulo     
8457280405Srpaulo     x = string.gsub("4+5 = $return 4+5$", "%$(.-)%$", function (s)
8458280405Srpaulo           return load(s)()
8459280405Srpaulo         end)
8460280405Srpaulo     --&gt; x="4+5 = 9"
8461280405Srpaulo     
8462280405Srpaulo     local t = {name="lua", version="5.3"}
8463280405Srpaulo     x = string.gsub("$name-$version.tar.gz", "%$(%w+)", t)
8464280405Srpaulo     --&gt; x="lua-5.3.tar.gz"
8465280405Srpaulo</pre>
8466280405Srpaulo
8467280405Srpaulo
8468280405Srpaulo
8469280405Srpaulo<p>
8470280405Srpaulo<hr><h3><a name="pdf-string.len"><code>string.len (s)</code></a></h3>
8471280405SrpauloReceives a string and returns its length.
8472280405SrpauloThe empty string <code>""</code> has length 0.
8473280405SrpauloEmbedded zeros are counted,
8474280405Srpauloso <code>"a\000bc\000"</code> has length 5.
8475280405Srpaulo
8476280405Srpaulo
8477280405Srpaulo
8478280405Srpaulo
8479280405Srpaulo<p>
8480280405Srpaulo<hr><h3><a name="pdf-string.lower"><code>string.lower (s)</code></a></h3>
8481280405SrpauloReceives a string and returns a copy of this string with all
8482280405Srpaulouppercase letters changed to lowercase.
8483280405SrpauloAll other characters are left unchanged.
8484280405SrpauloThe definition of what an uppercase letter is depends on the current locale.
8485280405Srpaulo
8486280405Srpaulo
8487280405Srpaulo
8488280405Srpaulo
8489280405Srpaulo<p>
8490280405Srpaulo<hr><h3><a name="pdf-string.match"><code>string.match (s, pattern [, init])</code></a></h3>
8491280405SrpauloLooks for the first <em>match</em> of
8492280405Srpaulo<code>pattern</code> (see <a href="#6.4.1">&sect;6.4.1</a>) in the string <code>s</code>.
8493280405SrpauloIf it finds one, then <code>match</code> returns
8494280405Srpaulothe captures from the pattern;
8495280405Srpaulootherwise it returns <b>nil</b>.
8496280405SrpauloIf <code>pattern</code> specifies no captures,
8497280405Srpaulothen the whole match is returned.
8498326344SimpA third, optional numeric argument <code>init</code> specifies
8499280405Srpaulowhere to start the search;
8500280405Srpauloits default value is&nbsp;1 and can be negative.
8501280405Srpaulo
8502280405Srpaulo
8503280405Srpaulo
8504280405Srpaulo
8505280405Srpaulo<p>
8506280405Srpaulo<hr><h3><a name="pdf-string.pack"><code>string.pack (fmt, v1, v2, &middot;&middot;&middot;)</code></a></h3>
8507280405Srpaulo
8508280405Srpaulo
8509280405Srpaulo<p>
8510280405SrpauloReturns a binary string containing the values <code>v1</code>, <code>v2</code>, etc.
8511280405Srpaulopacked (that is, serialized in binary form)
8512326344Simpaccording to the format string <code>fmt</code> (see <a href="#6.4.2">&sect;6.4.2</a>).
8513280405Srpaulo
8514280405Srpaulo
8515280405Srpaulo
8516280405Srpaulo
8517280405Srpaulo<p>
8518280405Srpaulo<hr><h3><a name="pdf-string.packsize"><code>string.packsize (fmt)</code></a></h3>
8519280405Srpaulo
8520280405Srpaulo
8521280405Srpaulo<p>
8522280405SrpauloReturns the size of a string resulting from <a href="#pdf-string.pack"><code>string.pack</code></a>
8523280405Srpaulowith the given format.
8524280405SrpauloThe format string cannot have the variable-length options
8525280405Srpaulo'<code>s</code>' or '<code>z</code>' (see <a href="#6.4.2">&sect;6.4.2</a>).
8526280405Srpaulo
8527280405Srpaulo
8528280405Srpaulo
8529280405Srpaulo
8530280405Srpaulo<p>
8531280405Srpaulo<hr><h3><a name="pdf-string.rep"><code>string.rep (s, n [, sep])</code></a></h3>
8532280405SrpauloReturns a string that is the concatenation of <code>n</code> copies of
8533280405Srpaulothe string <code>s</code> separated by the string <code>sep</code>.
8534280405SrpauloThe default value for <code>sep</code> is the empty string
8535280405Srpaulo(that is, no separator).
8536280405SrpauloReturns the empty string if <code>n</code> is not positive.
8537280405Srpaulo
8538280405Srpaulo
8539326344Simp<p>
8540326344Simp(Note that it is very easy to exhaust the memory of your machine
8541326344Simpwith a single call to this function.)
8542280405Srpaulo
8543280405Srpaulo
8544326344Simp
8545326344Simp
8546280405Srpaulo<p>
8547280405Srpaulo<hr><h3><a name="pdf-string.reverse"><code>string.reverse (s)</code></a></h3>
8548280405SrpauloReturns a string that is the string <code>s</code> reversed.
8549280405Srpaulo
8550280405Srpaulo
8551280405Srpaulo
8552280405Srpaulo
8553280405Srpaulo<p>
8554280405Srpaulo<hr><h3><a name="pdf-string.sub"><code>string.sub (s, i [, j])</code></a></h3>
8555280405SrpauloReturns the substring of <code>s</code> that
8556280405Srpaulostarts at <code>i</code>  and continues until <code>j</code>;
8557280405Srpaulo<code>i</code> and <code>j</code> can be negative.
8558280405SrpauloIf <code>j</code> is absent, then it is assumed to be equal to -1
8559280405Srpaulo(which is the same as the string length).
8560280405SrpauloIn particular,
8561280405Srpaulothe call <code>string.sub(s,1,j)</code> returns a prefix of <code>s</code>
8562280405Srpaulowith length <code>j</code>,
8563326344Simpand <code>string.sub(s, -i)</code> (for a positive <code>i</code>)
8564326344Simpreturns a suffix of <code>s</code>
8565280405Srpaulowith length <code>i</code>.
8566280405Srpaulo
8567280405Srpaulo
8568280405Srpaulo<p>
8569280405SrpauloIf, after the translation of negative indices,
8570280405Srpaulo<code>i</code> is less than 1,
8571280405Srpauloit is corrected to 1.
8572280405SrpauloIf <code>j</code> is greater than the string length,
8573280405Srpauloit is corrected to that length.
8574280405SrpauloIf, after these corrections,
8575280405Srpaulo<code>i</code> is greater than <code>j</code>,
8576280405Srpaulothe function returns the empty string.
8577280405Srpaulo
8578280405Srpaulo
8579280405Srpaulo
8580280405Srpaulo
8581280405Srpaulo<p>
8582280405Srpaulo<hr><h3><a name="pdf-string.unpack"><code>string.unpack (fmt, s [, pos])</code></a></h3>
8583280405Srpaulo
8584280405Srpaulo
8585280405Srpaulo<p>
8586280405SrpauloReturns the values packed in string <code>s</code> (see <a href="#pdf-string.pack"><code>string.pack</code></a>)
8587280405Srpauloaccording to the format string <code>fmt</code> (see <a href="#6.4.2">&sect;6.4.2</a>).
8588280405SrpauloAn optional <code>pos</code> marks where
8589280405Srpauloto start reading in <code>s</code> (default is 1).
8590280405SrpauloAfter the read values,
8591280405Srpaulothis function also returns the index of the first unread byte in <code>s</code>.
8592280405Srpaulo
8593280405Srpaulo
8594280405Srpaulo
8595280405Srpaulo
8596280405Srpaulo<p>
8597280405Srpaulo<hr><h3><a name="pdf-string.upper"><code>string.upper (s)</code></a></h3>
8598280405SrpauloReceives a string and returns a copy of this string with all
8599280405Srpaulolowercase letters changed to uppercase.
8600280405SrpauloAll other characters are left unchanged.
8601280405SrpauloThe definition of what a lowercase letter is depends on the current locale.
8602280405Srpaulo
8603280405Srpaulo
8604280405Srpaulo
8605280405Srpaulo
8606280405Srpaulo
8607280405Srpaulo<h3>6.4.1 &ndash; <a name="6.4.1">Patterns</a></h3>
8608280405Srpaulo
8609280405Srpaulo<p>
8610280405SrpauloPatterns in Lua are described by regular strings,
8611280405Srpaulowhich are interpreted as patterns by the pattern-matching functions
8612280405Srpaulo<a href="#pdf-string.find"><code>string.find</code></a>,
8613280405Srpaulo<a href="#pdf-string.gmatch"><code>string.gmatch</code></a>,
8614280405Srpaulo<a href="#pdf-string.gsub"><code>string.gsub</code></a>,
8615280405Srpauloand <a href="#pdf-string.match"><code>string.match</code></a>.
8616280405SrpauloThis section describes the syntax and the meaning
8617280405Srpaulo(that is, what they match) of these strings.
8618280405Srpaulo
8619280405Srpaulo
8620280405Srpaulo
8621280405Srpaulo<h4>Character Class:</h4><p>
8622280405SrpauloA <em>character class</em> is used to represent a set of characters.
8623280405SrpauloThe following combinations are allowed in describing a character class:
8624280405Srpaulo
8625280405Srpaulo<ul>
8626280405Srpaulo
8627280405Srpaulo<li><b><em>x</em>: </b>
8628280405Srpaulo(where <em>x</em> is not one of the <em>magic characters</em>
8629280405Srpaulo<code>^$()%.[]*+-?</code>)
8630280405Srpaulorepresents the character <em>x</em> itself.
8631280405Srpaulo</li>
8632280405Srpaulo
8633280405Srpaulo<li><b><code>.</code>: </b> (a dot) represents all characters.</li>
8634280405Srpaulo
8635280405Srpaulo<li><b><code>%a</code>: </b> represents all letters.</li>
8636280405Srpaulo
8637280405Srpaulo<li><b><code>%c</code>: </b> represents all control characters.</li>
8638280405Srpaulo
8639280405Srpaulo<li><b><code>%d</code>: </b> represents all digits.</li>
8640280405Srpaulo
8641280405Srpaulo<li><b><code>%g</code>: </b> represents all printable characters except space.</li>
8642280405Srpaulo
8643280405Srpaulo<li><b><code>%l</code>: </b> represents all lowercase letters.</li>
8644280405Srpaulo
8645280405Srpaulo<li><b><code>%p</code>: </b> represents all punctuation characters.</li>
8646280405Srpaulo
8647280405Srpaulo<li><b><code>%s</code>: </b> represents all space characters.</li>
8648280405Srpaulo
8649280405Srpaulo<li><b><code>%u</code>: </b> represents all uppercase letters.</li>
8650280405Srpaulo
8651280405Srpaulo<li><b><code>%w</code>: </b> represents all alphanumeric characters.</li>
8652280405Srpaulo
8653280405Srpaulo<li><b><code>%x</code>: </b> represents all hexadecimal digits.</li>
8654280405Srpaulo
8655280405Srpaulo<li><b><code>%<em>x</em></code>: </b> (where <em>x</em> is any non-alphanumeric character)
8656280405Srpaulorepresents the character <em>x</em>.
8657280405SrpauloThis is the standard way to escape the magic characters.
8658280405SrpauloAny non-alphanumeric character
8659326344Simp(including all punctuation characters, even the non-magical)
8660280405Srpaulocan be preceded by a '<code>%</code>'
8661280405Srpaulowhen used to represent itself in a pattern.
8662280405Srpaulo</li>
8663280405Srpaulo
8664280405Srpaulo<li><b><code>[<em>set</em>]</code>: </b>
8665280405Srpaulorepresents the class which is the union of all
8666280405Srpaulocharacters in <em>set</em>.
8667280405SrpauloA range of characters can be specified by
8668280405Srpauloseparating the end characters of the range,
8669280405Srpauloin ascending order, with a '<code>-</code>'.
8670280405SrpauloAll classes <code>%</code><em>x</em> described above can also be used as
8671280405Srpaulocomponents in <em>set</em>.
8672280405SrpauloAll other characters in <em>set</em> represent themselves.
8673280405SrpauloFor example, <code>[%w_]</code> (or <code>[_%w]</code>)
8674280405Srpaulorepresents all alphanumeric characters plus the underscore,
8675280405Srpaulo<code>[0-7]</code> represents the octal digits,
8676280405Srpauloand <code>[0-7%l%-]</code> represents the octal digits plus
8677280405Srpaulothe lowercase letters plus the '<code>-</code>' character.
8678280405Srpaulo
8679280405Srpaulo
8680280405Srpaulo<p>
8681326344SimpYou can put a closing square bracket in a set
8682326344Simpby positioning it as the first character in the set.
8683326344SimpYou can put an hyphen in a set
8684326344Simpby positioning it as the first or the last character in the set.
8685326344Simp(You can also use an escape for both cases.)
8686326344Simp
8687326344Simp
8688326344Simp<p>
8689280405SrpauloThe interaction between ranges and classes is not defined.
8690280405SrpauloTherefore, patterns like <code>[%a-z]</code> or <code>[a-%%]</code>
8691280405Srpaulohave no meaning.
8692280405Srpaulo</li>
8693280405Srpaulo
8694280405Srpaulo<li><b><code>[^<em>set</em>]</code>: </b>
8695280405Srpaulorepresents the complement of <em>set</em>,
8696280405Srpaulowhere <em>set</em> is interpreted as above.
8697280405Srpaulo</li>
8698280405Srpaulo
8699280405Srpaulo</ul><p>
8700280405SrpauloFor all classes represented by single letters (<code>%a</code>, <code>%c</code>, etc.),
8701280405Srpaulothe corresponding uppercase letter represents the complement of the class.
8702280405SrpauloFor instance, <code>%S</code> represents all non-space characters.
8703280405Srpaulo
8704280405Srpaulo
8705280405Srpaulo<p>
8706280405SrpauloThe definitions of letter, space, and other character groups
8707280405Srpaulodepend on the current locale.
8708280405SrpauloIn particular, the class <code>[a-z]</code> may not be equivalent to <code>%l</code>.
8709280405Srpaulo
8710280405Srpaulo
8711280405Srpaulo
8712280405Srpaulo
8713280405Srpaulo
8714280405Srpaulo<h4>Pattern Item:</h4><p>
8715280405SrpauloA <em>pattern item</em> can be
8716280405Srpaulo
8717280405Srpaulo<ul>
8718280405Srpaulo
8719280405Srpaulo<li>
8720280405Srpauloa single character class,
8721280405Srpaulowhich matches any single character in the class;
8722280405Srpaulo</li>
8723280405Srpaulo
8724280405Srpaulo<li>
8725280405Srpauloa single character class followed by '<code>*</code>',
8726280405Srpaulowhich matches zero or more repetitions of characters in the class.
8727280405SrpauloThese repetition items will always match the longest possible sequence;
8728280405Srpaulo</li>
8729280405Srpaulo
8730280405Srpaulo<li>
8731280405Srpauloa single character class followed by '<code>+</code>',
8732280405Srpaulowhich matches one or more repetitions of characters in the class.
8733280405SrpauloThese repetition items will always match the longest possible sequence;
8734280405Srpaulo</li>
8735280405Srpaulo
8736280405Srpaulo<li>
8737280405Srpauloa single character class followed by '<code>-</code>',
8738280405Srpaulowhich also matches zero or more repetitions of characters in the class.
8739280405SrpauloUnlike '<code>*</code>',
8740280405Srpaulothese repetition items will always match the shortest possible sequence;
8741280405Srpaulo</li>
8742280405Srpaulo
8743280405Srpaulo<li>
8744280405Srpauloa single character class followed by '<code>?</code>',
8745280405Srpaulowhich matches zero or one occurrence of a character in the class.
8746280405SrpauloIt always matches one occurrence if possible;
8747280405Srpaulo</li>
8748280405Srpaulo
8749280405Srpaulo<li>
8750280405Srpaulo<code>%<em>n</em></code>, for <em>n</em> between 1 and 9;
8751280405Srpaulosuch item matches a substring equal to the <em>n</em>-th captured string
8752280405Srpaulo(see below);
8753280405Srpaulo</li>
8754280405Srpaulo
8755280405Srpaulo<li>
8756280405Srpaulo<code>%b<em>xy</em></code>, where <em>x</em> and <em>y</em> are two distinct characters;
8757280405Srpaulosuch item matches strings that start with&nbsp;<em>x</em>, end with&nbsp;<em>y</em>,
8758280405Srpauloand where the <em>x</em> and <em>y</em> are <em>balanced</em>.
8759280405SrpauloThis means that, if one reads the string from left to right,
8760280405Srpaulocounting <em>+1</em> for an <em>x</em> and <em>-1</em> for a <em>y</em>,
8761280405Srpaulothe ending <em>y</em> is the first <em>y</em> where the count reaches 0.
8762280405SrpauloFor instance, the item <code>%b()</code> matches expressions with
8763280405Srpaulobalanced parentheses.
8764280405Srpaulo</li>
8765280405Srpaulo
8766280405Srpaulo<li>
8767280405Srpaulo<code>%f[<em>set</em>]</code>, a <em>frontier pattern</em>;
8768280405Srpaulosuch item matches an empty string at any position such that
8769280405Srpaulothe next character belongs to <em>set</em>
8770280405Srpauloand the previous character does not belong to <em>set</em>.
8771280405SrpauloThe set <em>set</em> is interpreted as previously described.
8772280405SrpauloThe beginning and the end of the subject are handled as if
8773280405Srpaulothey were the character '<code>\0</code>'.
8774280405Srpaulo</li>
8775280405Srpaulo
8776280405Srpaulo</ul>
8777280405Srpaulo
8778280405Srpaulo
8779280405Srpaulo
8780280405Srpaulo
8781280405Srpaulo<h4>Pattern:</h4><p>
8782280405SrpauloA <em>pattern</em> is a sequence of pattern items.
8783280405SrpauloA caret '<code>^</code>' at the beginning of a pattern anchors the match at the
8784280405Srpaulobeginning of the subject string.
8785280405SrpauloA '<code>$</code>' at the end of a pattern anchors the match at the
8786280405Srpauloend of the subject string.
8787280405SrpauloAt other positions,
8788280405Srpaulo'<code>^</code>' and '<code>$</code>' have no special meaning and represent themselves.
8789280405Srpaulo
8790280405Srpaulo
8791280405Srpaulo
8792280405Srpaulo
8793280405Srpaulo
8794280405Srpaulo<h4>Captures:</h4><p>
8795280405SrpauloA pattern can contain sub-patterns enclosed in parentheses;
8796280405Srpaulothey describe <em>captures</em>.
8797280405SrpauloWhen a match succeeds, the substrings of the subject string
8798280405Srpaulothat match captures are stored (<em>captured</em>) for future use.
8799280405SrpauloCaptures are numbered according to their left parentheses.
8800280405SrpauloFor instance, in the pattern <code>"(a*(.)%w(%s*))"</code>,
8801280405Srpaulothe part of the string matching <code>"a*(.)%w(%s*)"</code> is
8802280405Srpaulostored as the first capture (and therefore has number&nbsp;1);
8803280405Srpaulothe character matching "<code>.</code>" is captured with number&nbsp;2,
8804280405Srpauloand the part matching "<code>%s*</code>" has number&nbsp;3.
8805280405Srpaulo
8806280405Srpaulo
8807280405Srpaulo<p>
8808280405SrpauloAs a special case, the empty capture <code>()</code> captures
8809280405Srpaulothe current string position (a number).
8810280405SrpauloFor instance, if we apply the pattern <code>"()aa()"</code> on the
8811280405Srpaulostring <code>"flaaap"</code>, there will be two captures: 3&nbsp;and&nbsp;5.
8812280405Srpaulo
8813280405Srpaulo
8814280405Srpaulo
8815280405Srpaulo
8816280405Srpaulo
8817280405Srpaulo
8818280405Srpaulo
8819280405Srpaulo<h3>6.4.2 &ndash; <a name="6.4.2">Format Strings for Pack and Unpack</a></h3>
8820280405Srpaulo
8821280405Srpaulo<p>
8822280405SrpauloThe first argument to <a href="#pdf-string.pack"><code>string.pack</code></a>,
8823280405Srpaulo<a href="#pdf-string.packsize"><code>string.packsize</code></a>, and <a href="#pdf-string.unpack"><code>string.unpack</code></a>
8824280405Srpaulois a format string,
8825280405Srpaulowhich describes the layout of the structure being created or read.
8826280405Srpaulo
8827280405Srpaulo
8828280405Srpaulo<p>
8829280405SrpauloA format string is a sequence of conversion options.
8830280405SrpauloThe conversion options are as follows:
8831280405Srpaulo
8832280405Srpaulo<ul>
8833280405Srpaulo<li><b><code>&lt;</code>: </b>sets little endian</li>
8834280405Srpaulo<li><b><code>&gt;</code>: </b>sets big endian</li>
8835280405Srpaulo<li><b><code>=</code>: </b>sets native endian</li>
8836280405Srpaulo<li><b><code>![<em>n</em>]</code>: </b>sets maximum alignment to <code>n</code>
8837280405Srpaulo(default is native alignment)</li>
8838280405Srpaulo<li><b><code>b</code>: </b>a signed byte (<code>char</code>)</li>
8839280405Srpaulo<li><b><code>B</code>: </b>an unsigned byte (<code>char</code>)</li>
8840280405Srpaulo<li><b><code>h</code>: </b>a signed <code>short</code> (native size)</li>
8841280405Srpaulo<li><b><code>H</code>: </b>an unsigned <code>short</code> (native size)</li>
8842280405Srpaulo<li><b><code>l</code>: </b>a signed <code>long</code> (native size)</li>
8843280405Srpaulo<li><b><code>L</code>: </b>an unsigned <code>long</code> (native size)</li>
8844280405Srpaulo<li><b><code>j</code>: </b>a <code>lua_Integer</code></li>
8845280405Srpaulo<li><b><code>J</code>: </b>a <code>lua_Unsigned</code></li>
8846280405Srpaulo<li><b><code>T</code>: </b>a <code>size_t</code> (native size)</li>
8847280405Srpaulo<li><b><code>i[<em>n</em>]</code>: </b>a signed <code>int</code> with <code>n</code> bytes
8848280405Srpaulo(default is native size)</li>
8849280405Srpaulo<li><b><code>I[<em>n</em>]</code>: </b>an unsigned <code>int</code> with <code>n</code> bytes
8850280405Srpaulo(default is native size)</li>
8851280405Srpaulo<li><b><code>f</code>: </b>a <code>float</code> (native size)</li>
8852280405Srpaulo<li><b><code>d</code>: </b>a <code>double</code> (native size)</li>
8853280405Srpaulo<li><b><code>n</code>: </b>a <code>lua_Number</code></li>
8854280405Srpaulo<li><b><code>c<em>n</em></code>: </b>a fixed-sized string with <code>n</code> bytes</li>
8855280405Srpaulo<li><b><code>z</code>: </b>a zero-terminated string</li>
8856280405Srpaulo<li><b><code>s[<em>n</em>]</code>: </b>a string preceded by its length
8857280405Srpaulocoded as an unsigned integer with <code>n</code> bytes
8858280405Srpaulo(default is a <code>size_t</code>)</li>
8859280405Srpaulo<li><b><code>x</code>: </b>one byte of padding</li>
8860280405Srpaulo<li><b><code>X<em>op</em></code>: </b>an empty item that aligns
8861280405Srpauloaccording to option <code>op</code>
8862280405Srpaulo(which is otherwise ignored)</li>
8863280405Srpaulo<li><b>'<code> </code>': </b>(empty space) ignored</li>
8864280405Srpaulo</ul><p>
8865280405Srpaulo(A "<code>[<em>n</em>]</code>" means an optional integral numeral.)
8866280405SrpauloExcept for padding, spaces, and configurations
8867280405Srpaulo(options "<code>xX &lt;=&gt;!</code>"),
8868280405Srpauloeach option corresponds to an argument (in <a href="#pdf-string.pack"><code>string.pack</code></a>)
8869280405Srpauloor a result (in <a href="#pdf-string.unpack"><code>string.unpack</code></a>).
8870280405Srpaulo
8871280405Srpaulo
8872280405Srpaulo<p>
8873280405SrpauloFor options "<code>!<em>n</em></code>", "<code>s<em>n</em></code>", "<code>i<em>n</em></code>", and "<code>I<em>n</em></code>",
8874280405Srpaulo<code>n</code> can be any integer between 1 and 16.
8875280405SrpauloAll integral options check overflows;
8876280405Srpaulo<a href="#pdf-string.pack"><code>string.pack</code></a> checks whether the given value fits in the given size;
8877280405Srpaulo<a href="#pdf-string.unpack"><code>string.unpack</code></a> checks whether the read value fits in a Lua integer.
8878280405Srpaulo
8879280405Srpaulo
8880280405Srpaulo<p>
8881280405SrpauloAny format string starts as if prefixed by "<code>!1=</code>",
8882280405Srpaulothat is,
8883280405Srpaulowith maximum alignment of 1 (no alignment)
8884280405Srpauloand native endianness.
8885280405Srpaulo
8886280405Srpaulo
8887280405Srpaulo<p>
8888280405SrpauloAlignment works as follows:
8889280405SrpauloFor each option,
8890280405Srpaulothe format gets extra padding until the data starts
8891280405Srpauloat an offset that is a multiple of the minimum between the
8892280405Srpaulooption size and the maximum alignment;
8893280405Srpaulothis minimum must be a power of 2.
8894280405SrpauloOptions "<code>c</code>" and "<code>z</code>" are not aligned;
8895280405Srpaulooption "<code>s</code>" follows the alignment of its starting integer.
8896280405Srpaulo
8897280405Srpaulo
8898280405Srpaulo<p>
8899280405SrpauloAll padding is filled with zeros by <a href="#pdf-string.pack"><code>string.pack</code></a>
8900280405Srpaulo(and ignored by <a href="#pdf-string.unpack"><code>string.unpack</code></a>).
8901280405Srpaulo
8902280405Srpaulo
8903280405Srpaulo
8904280405Srpaulo
8905280405Srpaulo
8906280405Srpaulo
8907280405Srpaulo
8908280405Srpaulo<h2>6.5 &ndash; <a name="6.5">UTF-8 Support</a></h2>
8909280405Srpaulo
8910280405Srpaulo<p>
8911280405SrpauloThis library provides basic support for UTF-8 encoding.
8912280405SrpauloIt provides all its functions inside the table <a name="pdf-utf8"><code>utf8</code></a>.
8913280405SrpauloThis library does not provide any support for Unicode other
8914280405Srpaulothan the handling of the encoding.
8915280405SrpauloAny operation that needs the meaning of a character,
8916280405Srpaulosuch as character classification, is outside its scope.
8917280405Srpaulo
8918280405Srpaulo
8919280405Srpaulo<p>
8920280405SrpauloUnless stated otherwise,
8921280405Srpauloall functions that expect a byte position as a parameter
8922280405Srpauloassume that the given position is either the start of a byte sequence
8923280405Srpauloor one plus the length of the subject string.
8924280405SrpauloAs in the string library,
8925280405Srpaulonegative indices count from the end of the string.
8926280405Srpaulo
8927280405Srpaulo
8928280405Srpaulo<p>
8929280405Srpaulo<hr><h3><a name="pdf-utf8.char"><code>utf8.char (&middot;&middot;&middot;)</code></a></h3>
8930280405SrpauloReceives zero or more integers,
8931280405Srpauloconverts each one to its corresponding UTF-8 byte sequence
8932280405Srpauloand returns a string with the concatenation of all these sequences.
8933280405Srpaulo
8934280405Srpaulo
8935280405Srpaulo
8936280405Srpaulo
8937280405Srpaulo<p>
8938280405Srpaulo<hr><h3><a name="pdf-utf8.charpattern"><code>utf8.charpattern</code></a></h3>
8939280405SrpauloThe pattern (a string, not a function) "<code>[\0-\x7F\xC2-\xF4][\x80-\xBF]*</code>"
8940280405Srpaulo(see <a href="#6.4.1">&sect;6.4.1</a>),
8941280405Srpaulowhich matches exactly one UTF-8 byte sequence,
8942280405Srpauloassuming that the subject is a valid UTF-8 string.
8943280405Srpaulo
8944280405Srpaulo
8945280405Srpaulo
8946280405Srpaulo
8947280405Srpaulo<p>
8948280405Srpaulo<hr><h3><a name="pdf-utf8.codes"><code>utf8.codes (s)</code></a></h3>
8949280405Srpaulo
8950280405Srpaulo
8951280405Srpaulo<p>
8952280405SrpauloReturns values so that the construction
8953280405Srpaulo
8954280405Srpaulo<pre>
8955280405Srpaulo     for p, c in utf8.codes(s) do <em>body</em> end
8956280405Srpaulo</pre><p>
8957280405Srpaulowill iterate over all characters in string <code>s</code>,
8958280405Srpaulowith <code>p</code> being the position (in bytes) and <code>c</code> the code point
8959280405Srpauloof each character.
8960280405SrpauloIt raises an error if it meets any invalid byte sequence.
8961280405Srpaulo
8962280405Srpaulo
8963280405Srpaulo
8964280405Srpaulo
8965280405Srpaulo<p>
8966280405Srpaulo<hr><h3><a name="pdf-utf8.codepoint"><code>utf8.codepoint (s [, i [, j]])</code></a></h3>
8967280405SrpauloReturns the codepoints (as integers) from all characters in <code>s</code>
8968280405Srpaulothat start between byte position <code>i</code> and <code>j</code> (both included).
8969280405SrpauloThe default for <code>i</code> is 1 and for <code>j</code> is <code>i</code>.
8970280405SrpauloIt raises an error if it meets any invalid byte sequence.
8971280405Srpaulo
8972280405Srpaulo
8973280405Srpaulo
8974280405Srpaulo
8975280405Srpaulo<p>
8976280405Srpaulo<hr><h3><a name="pdf-utf8.len"><code>utf8.len (s [, i [, j]])</code></a></h3>
8977280405SrpauloReturns the number of UTF-8 characters in string <code>s</code>
8978280405Srpaulothat start between positions <code>i</code> and <code>j</code> (both inclusive).
8979280405SrpauloThe default for <code>i</code> is 1 and for <code>j</code> is -1.
8980280405SrpauloIf it finds any invalid byte sequence,
8981326344Simpreturns a false value plus the position of the first invalid byte.
8982280405Srpaulo
8983280405Srpaulo
8984280405Srpaulo
8985280405Srpaulo
8986280405Srpaulo<p>
8987280405Srpaulo<hr><h3><a name="pdf-utf8.offset"><code>utf8.offset (s, n [, i])</code></a></h3>
8988280405SrpauloReturns the position (in bytes) where the encoding of the
8989280405Srpaulo<code>n</code>-th character of <code>s</code>
8990280405Srpaulo(counting from position <code>i</code>) starts.
8991280405SrpauloA negative <code>n</code> gets characters before position <code>i</code>.
8992280405SrpauloThe default for <code>i</code> is 1 when <code>n</code> is non-negative
8993280405Srpauloand <code>#s + 1</code> otherwise,
8994280405Srpauloso that <code>utf8.offset(s, -n)</code> gets the offset of the
8995280405Srpaulo<code>n</code>-th character from the end of the string.
8996280405SrpauloIf the specified character is neither in the subject
8997280405Srpaulonor right after its end,
8998280405Srpaulothe function returns <b>nil</b>.
8999280405Srpaulo
9000280405Srpaulo
9001280405Srpaulo<p>
9002280405SrpauloAs a special case,
9003280405Srpaulowhen <code>n</code> is 0 the function returns the start of the encoding
9004280405Srpauloof the character that contains the <code>i</code>-th byte of <code>s</code>.
9005280405Srpaulo
9006280405Srpaulo
9007280405Srpaulo<p>
9008280405SrpauloThis function assumes that <code>s</code> is a valid UTF-8 string.
9009280405Srpaulo
9010280405Srpaulo
9011280405Srpaulo
9012280405Srpaulo
9013280405Srpaulo
9014280405Srpaulo
9015280405Srpaulo
9016280405Srpaulo<h2>6.6 &ndash; <a name="6.6">Table Manipulation</a></h2>
9017280405Srpaulo
9018280405Srpaulo<p>
9019280405SrpauloThis library provides generic functions for table manipulation.
9020280405SrpauloIt provides all its functions inside the table <a name="pdf-table"><code>table</code></a>.
9021280405Srpaulo
9022280405Srpaulo
9023280405Srpaulo<p>
9024280405SrpauloRemember that, whenever an operation needs the length of a table,
9025326344Simpall caveats about the length operator apply (see <a href="#3.4.7">&sect;3.4.7</a>).
9026280405SrpauloAll functions ignore non-numeric keys
9027280405Srpauloin the tables given as arguments.
9028280405Srpaulo
9029280405Srpaulo
9030280405Srpaulo<p>
9031280405Srpaulo<hr><h3><a name="pdf-table.concat"><code>table.concat (list [, sep [, i [, j]]])</code></a></h3>
9032280405Srpaulo
9033280405Srpaulo
9034280405Srpaulo<p>
9035280405SrpauloGiven a list where all elements are strings or numbers,
9036280405Srpauloreturns the string <code>list[i]..sep..list[i+1] &middot;&middot;&middot; sep..list[j]</code>.
9037280405SrpauloThe default value for <code>sep</code> is the empty string,
9038280405Srpaulothe default for <code>i</code> is 1,
9039280405Srpauloand the default for <code>j</code> is <code>#list</code>.
9040280405SrpauloIf <code>i</code> is greater than <code>j</code>, returns the empty string.
9041280405Srpaulo
9042280405Srpaulo
9043280405Srpaulo
9044280405Srpaulo
9045280405Srpaulo<p>
9046280405Srpaulo<hr><h3><a name="pdf-table.insert"><code>table.insert (list, [pos,] value)</code></a></h3>
9047280405Srpaulo
9048280405Srpaulo
9049280405Srpaulo<p>
9050280405SrpauloInserts element <code>value</code> at position <code>pos</code> in <code>list</code>,
9051280405Srpauloshifting up the elements
9052280405Srpaulo<code>list[pos], list[pos+1], &middot;&middot;&middot;, list[#list]</code>.
9053280405SrpauloThe default value for <code>pos</code> is <code>#list+1</code>,
9054280405Srpauloso that a call <code>table.insert(t,x)</code> inserts <code>x</code> at the end
9055280405Srpauloof list <code>t</code>.
9056280405Srpaulo
9057280405Srpaulo
9058280405Srpaulo
9059280405Srpaulo
9060280405Srpaulo<p>
9061280405Srpaulo<hr><h3><a name="pdf-table.move"><code>table.move (a1, f, e, t [,a2])</code></a></h3>
9062280405Srpaulo
9063280405Srpaulo
9064280405Srpaulo<p>
9065326344SimpMoves elements from table <code>a1</code> to table <code>a2</code>,
9066326344Simpperforming the equivalent to the following
9067280405Srpaulomultiple assignment:
9068280405Srpaulo<code>a2[t],&middot;&middot;&middot; = a1[f],&middot;&middot;&middot;,a1[e]</code>.
9069280405SrpauloThe default for <code>a2</code> is <code>a1</code>.
9070280405SrpauloThe destination range can overlap with the source range.
9071326344SimpThe number of elements to be moved must fit in a Lua integer.
9072280405Srpaulo
9073280405Srpaulo
9074326344Simp<p>
9075326344SimpReturns the destination table <code>a2</code>.
9076280405Srpaulo
9077280405Srpaulo
9078326344Simp
9079326344Simp
9080280405Srpaulo<p>
9081280405Srpaulo<hr><h3><a name="pdf-table.pack"><code>table.pack (&middot;&middot;&middot;)</code></a></h3>
9082280405Srpaulo
9083280405Srpaulo
9084280405Srpaulo<p>
9085280405SrpauloReturns a new table with all parameters stored into keys 1, 2, etc.
9086280405Srpauloand with a field "<code>n</code>" with the total number of parameters.
9087280405SrpauloNote that the resulting table may not be a sequence.
9088280405Srpaulo
9089280405Srpaulo
9090280405Srpaulo
9091280405Srpaulo
9092280405Srpaulo<p>
9093280405Srpaulo<hr><h3><a name="pdf-table.remove"><code>table.remove (list [, pos])</code></a></h3>
9094280405Srpaulo
9095280405Srpaulo
9096280405Srpaulo<p>
9097280405SrpauloRemoves from <code>list</code> the element at position <code>pos</code>,
9098280405Srpauloreturning the value of the removed element.
9099280405SrpauloWhen <code>pos</code> is an integer between 1 and <code>#list</code>,
9100280405Srpauloit shifts down the elements
9101280405Srpaulo<code>list[pos+1], list[pos+2], &middot;&middot;&middot;, list[#list]</code>
9102280405Srpauloand erases element <code>list[#list]</code>;
9103280405SrpauloThe index <code>pos</code> can also be 0 when <code>#list</code> is 0,
9104280405Srpauloor <code>#list + 1</code>;
9105280405Srpauloin those cases, the function erases the element <code>list[pos]</code>.
9106280405Srpaulo
9107280405Srpaulo
9108280405Srpaulo<p>
9109280405SrpauloThe default value for <code>pos</code> is <code>#list</code>,
9110280405Srpauloso that a call <code>table.remove(l)</code> removes the last element
9111280405Srpauloof list <code>l</code>.
9112280405Srpaulo
9113280405Srpaulo
9114280405Srpaulo
9115280405Srpaulo
9116280405Srpaulo<p>
9117280405Srpaulo<hr><h3><a name="pdf-table.sort"><code>table.sort (list [, comp])</code></a></h3>
9118280405Srpaulo
9119280405Srpaulo
9120280405Srpaulo<p>
9121280405SrpauloSorts list elements in a given order, <em>in-place</em>,
9122280405Srpaulofrom <code>list[1]</code> to <code>list[#list]</code>.
9123280405SrpauloIf <code>comp</code> is given,
9124280405Srpaulothen it must be a function that receives two list elements
9125280405Srpauloand returns true when the first element must come
9126280405Srpaulobefore the second in the final order
9127326344Simp(so that, after the sort,
9128326344Simp<code>i &lt; j</code> implies <code>not comp(list[j],list[i])</code>).
9129280405SrpauloIf <code>comp</code> is not given,
9130280405Srpaulothen the standard Lua operator <code>&lt;</code> is used instead.
9131280405Srpaulo
9132280405Srpaulo
9133280405Srpaulo<p>
9134326344SimpNote that the <code>comp</code> function must define
9135326344Simpa strict partial order over the elements in the list;
9136326344Simpthat is, it must be asymmetric and transitive.
9137326344SimpOtherwise, no valid sort may be possible.
9138326344Simp
9139326344Simp
9140326344Simp<p>
9141326344SimpThe sort algorithm is not stable:
9142326344Simpelements considered equal by the given order
9143280405Srpaulomay have their relative positions changed by the sort.
9144280405Srpaulo
9145280405Srpaulo
9146280405Srpaulo
9147280405Srpaulo
9148280405Srpaulo<p>
9149280405Srpaulo<hr><h3><a name="pdf-table.unpack"><code>table.unpack (list [, i [, j]])</code></a></h3>
9150280405Srpaulo
9151280405Srpaulo
9152280405Srpaulo<p>
9153280405SrpauloReturns the elements from the given list.
9154280405SrpauloThis function is equivalent to
9155280405Srpaulo
9156280405Srpaulo<pre>
9157280405Srpaulo     return list[i], list[i+1], &middot;&middot;&middot;, list[j]
9158280405Srpaulo</pre><p>
9159280405SrpauloBy default, <code>i</code> is&nbsp;1 and <code>j</code> is <code>#list</code>.
9160280405Srpaulo
9161280405Srpaulo
9162280405Srpaulo
9163280405Srpaulo
9164280405Srpaulo
9165280405Srpaulo
9166280405Srpaulo
9167280405Srpaulo<h2>6.7 &ndash; <a name="6.7">Mathematical Functions</a></h2>
9168280405Srpaulo
9169280405Srpaulo<p>
9170280405SrpauloThis library provides basic mathematical functions.
9171280405SrpauloIt provides all its functions and constants inside the table <a name="pdf-math"><code>math</code></a>.
9172280405SrpauloFunctions with the annotation "<code>integer/float</code>" give
9173280405Srpaulointeger results for integer arguments
9174280405Srpauloand float results for float (or mixed) arguments.
9175280405SrpauloRounding functions
9176280405Srpaulo(<a href="#pdf-math.ceil"><code>math.ceil</code></a>, <a href="#pdf-math.floor"><code>math.floor</code></a>, and <a href="#pdf-math.modf"><code>math.modf</code></a>)
9177280405Srpauloreturn an integer when the result fits in the range of an integer,
9178280405Srpauloor a float otherwise.
9179280405Srpaulo
9180280405Srpaulo
9181280405Srpaulo<p>
9182280405Srpaulo<hr><h3><a name="pdf-math.abs"><code>math.abs (x)</code></a></h3>
9183280405Srpaulo
9184280405Srpaulo
9185280405Srpaulo<p>
9186280405SrpauloReturns the absolute value of <code>x</code>. (integer/float)
9187280405Srpaulo
9188280405Srpaulo
9189280405Srpaulo
9190280405Srpaulo
9191280405Srpaulo<p>
9192280405Srpaulo<hr><h3><a name="pdf-math.acos"><code>math.acos (x)</code></a></h3>
9193280405Srpaulo
9194280405Srpaulo
9195280405Srpaulo<p>
9196280405SrpauloReturns the arc cosine of <code>x</code> (in radians).
9197280405Srpaulo
9198280405Srpaulo
9199280405Srpaulo
9200280405Srpaulo
9201280405Srpaulo<p>
9202280405Srpaulo<hr><h3><a name="pdf-math.asin"><code>math.asin (x)</code></a></h3>
9203280405Srpaulo
9204280405Srpaulo
9205280405Srpaulo<p>
9206280405SrpauloReturns the arc sine of <code>x</code> (in radians).
9207280405Srpaulo
9208280405Srpaulo
9209280405Srpaulo
9210280405Srpaulo
9211280405Srpaulo<p>
9212280405Srpaulo<hr><h3><a name="pdf-math.atan"><code>math.atan (y [, x])</code></a></h3>
9213280405Srpaulo
9214280405Srpaulo
9215280405Srpaulo<p>
9216280405Srpaulo
9217280405SrpauloReturns the arc tangent of <code>y/x</code> (in radians),
9218280405Srpaulobut uses the signs of both parameters to find the
9219280405Srpauloquadrant of the result.
9220280405Srpaulo(It also handles correctly the case of <code>x</code> being zero.)
9221280405Srpaulo
9222280405Srpaulo
9223280405Srpaulo<p>
9224280405SrpauloThe default value for <code>x</code> is 1,
9225280405Srpauloso that the call <code>math.atan(y)</code>
9226280405Srpauloreturns the arc tangent of <code>y</code>.
9227280405Srpaulo
9228280405Srpaulo
9229280405Srpaulo
9230280405Srpaulo
9231280405Srpaulo<p>
9232280405Srpaulo<hr><h3><a name="pdf-math.ceil"><code>math.ceil (x)</code></a></h3>
9233280405Srpaulo
9234280405Srpaulo
9235280405Srpaulo<p>
9236280405SrpauloReturns the smallest integral value larger than or equal to <code>x</code>.
9237280405Srpaulo
9238280405Srpaulo
9239280405Srpaulo
9240280405Srpaulo
9241280405Srpaulo<p>
9242280405Srpaulo<hr><h3><a name="pdf-math.cos"><code>math.cos (x)</code></a></h3>
9243280405Srpaulo
9244280405Srpaulo
9245280405Srpaulo<p>
9246280405SrpauloReturns the cosine of <code>x</code> (assumed to be in radians).
9247280405Srpaulo
9248280405Srpaulo
9249280405Srpaulo
9250280405Srpaulo
9251280405Srpaulo<p>
9252280405Srpaulo<hr><h3><a name="pdf-math.deg"><code>math.deg (x)</code></a></h3>
9253280405Srpaulo
9254280405Srpaulo
9255280405Srpaulo<p>
9256280405SrpauloConverts the angle <code>x</code> from radians to degrees.
9257280405Srpaulo
9258280405Srpaulo
9259280405Srpaulo
9260280405Srpaulo
9261280405Srpaulo<p>
9262280405Srpaulo<hr><h3><a name="pdf-math.exp"><code>math.exp (x)</code></a></h3>
9263280405Srpaulo
9264280405Srpaulo
9265280405Srpaulo<p>
9266280405SrpauloReturns the value <em>e<sup>x</sup></em>
9267280405Srpaulo(where <code>e</code> is the base of natural logarithms).
9268280405Srpaulo
9269280405Srpaulo
9270280405Srpaulo
9271280405Srpaulo
9272280405Srpaulo<p>
9273280405Srpaulo<hr><h3><a name="pdf-math.floor"><code>math.floor (x)</code></a></h3>
9274280405Srpaulo
9275280405Srpaulo
9276280405Srpaulo<p>
9277280405SrpauloReturns the largest integral value smaller than or equal to <code>x</code>.
9278280405Srpaulo
9279280405Srpaulo
9280280405Srpaulo
9281280405Srpaulo
9282280405Srpaulo<p>
9283280405Srpaulo<hr><h3><a name="pdf-math.fmod"><code>math.fmod (x, y)</code></a></h3>
9284280405Srpaulo
9285280405Srpaulo
9286280405Srpaulo<p>
9287280405SrpauloReturns the remainder of the division of <code>x</code> by <code>y</code>
9288280405Srpaulothat rounds the quotient towards zero. (integer/float)
9289280405Srpaulo
9290280405Srpaulo
9291280405Srpaulo
9292280405Srpaulo
9293280405Srpaulo<p>
9294280405Srpaulo<hr><h3><a name="pdf-math.huge"><code>math.huge</code></a></h3>
9295280405Srpaulo
9296280405Srpaulo
9297280405Srpaulo<p>
9298280405SrpauloThe float value <code>HUGE_VAL</code>,
9299326344Simpa value larger than any other numeric value.
9300280405Srpaulo
9301280405Srpaulo
9302280405Srpaulo
9303280405Srpaulo
9304280405Srpaulo<p>
9305280405Srpaulo<hr><h3><a name="pdf-math.log"><code>math.log (x [, base])</code></a></h3>
9306280405Srpaulo
9307280405Srpaulo
9308280405Srpaulo<p>
9309280405SrpauloReturns the logarithm of <code>x</code> in the given base.
9310280405SrpauloThe default for <code>base</code> is <em>e</em>
9311280405Srpaulo(so that the function returns the natural logarithm of <code>x</code>).
9312280405Srpaulo
9313280405Srpaulo
9314280405Srpaulo
9315280405Srpaulo
9316280405Srpaulo<p>
9317280405Srpaulo<hr><h3><a name="pdf-math.max"><code>math.max (x, &middot;&middot;&middot;)</code></a></h3>
9318280405Srpaulo
9319280405Srpaulo
9320280405Srpaulo<p>
9321280405SrpauloReturns the argument with the maximum value,
9322280405Srpauloaccording to the Lua operator <code>&lt;</code>. (integer/float)
9323280405Srpaulo
9324280405Srpaulo
9325280405Srpaulo
9326280405Srpaulo
9327280405Srpaulo<p>
9328280405Srpaulo<hr><h3><a name="pdf-math.maxinteger"><code>math.maxinteger</code></a></h3>
9329280405SrpauloAn integer with the maximum value for an integer.
9330280405Srpaulo
9331280405Srpaulo
9332280405Srpaulo
9333280405Srpaulo
9334280405Srpaulo<p>
9335280405Srpaulo<hr><h3><a name="pdf-math.min"><code>math.min (x, &middot;&middot;&middot;)</code></a></h3>
9336280405Srpaulo
9337280405Srpaulo
9338280405Srpaulo<p>
9339280405SrpauloReturns the argument with the minimum value,
9340280405Srpauloaccording to the Lua operator <code>&lt;</code>. (integer/float)
9341280405Srpaulo
9342280405Srpaulo
9343280405Srpaulo
9344280405Srpaulo
9345280405Srpaulo<p>
9346280405Srpaulo<hr><h3><a name="pdf-math.mininteger"><code>math.mininteger</code></a></h3>
9347280405SrpauloAn integer with the minimum value for an integer.
9348280405Srpaulo
9349280405Srpaulo
9350280405Srpaulo
9351280405Srpaulo
9352280405Srpaulo<p>
9353280405Srpaulo<hr><h3><a name="pdf-math.modf"><code>math.modf (x)</code></a></h3>
9354280405Srpaulo
9355280405Srpaulo
9356280405Srpaulo<p>
9357280405SrpauloReturns the integral part of <code>x</code> and the fractional part of <code>x</code>.
9358280405SrpauloIts second result is always a float.
9359280405Srpaulo
9360280405Srpaulo
9361280405Srpaulo
9362280405Srpaulo
9363280405Srpaulo<p>
9364280405Srpaulo<hr><h3><a name="pdf-math.pi"><code>math.pi</code></a></h3>
9365280405Srpaulo
9366280405Srpaulo
9367280405Srpaulo<p>
9368280405SrpauloThe value of <em>&pi;</em>.
9369280405Srpaulo
9370280405Srpaulo
9371280405Srpaulo
9372280405Srpaulo
9373280405Srpaulo<p>
9374280405Srpaulo<hr><h3><a name="pdf-math.rad"><code>math.rad (x)</code></a></h3>
9375280405Srpaulo
9376280405Srpaulo
9377280405Srpaulo<p>
9378280405SrpauloConverts the angle <code>x</code> from degrees to radians.
9379280405Srpaulo
9380280405Srpaulo
9381280405Srpaulo
9382280405Srpaulo
9383280405Srpaulo<p>
9384280405Srpaulo<hr><h3><a name="pdf-math.random"><code>math.random ([m [, n]])</code></a></h3>
9385280405Srpaulo
9386280405Srpaulo
9387280405Srpaulo<p>
9388280405SrpauloWhen called without arguments,
9389280405Srpauloreturns a pseudo-random float with uniform distribution
9390280405Srpauloin the range  <em>[0,1)</em>.  
9391280405SrpauloWhen called with two integers <code>m</code> and <code>n</code>,
9392280405Srpaulo<code>math.random</code> returns a pseudo-random integer
9393280405Srpaulowith uniform distribution in the range <em>[m, n]</em>.
9394326344Simp(The value <em>n-m</em> cannot be negative and must fit in a Lua integer.)
9395280405SrpauloThe call <code>math.random(n)</code> is equivalent to <code>math.random(1,n)</code>.
9396280405Srpaulo
9397280405Srpaulo
9398280405Srpaulo<p>
9399280405SrpauloThis function is an interface to the underling
9400280405Srpaulopseudo-random generator function provided by C.
9401280405Srpaulo
9402280405Srpaulo
9403280405Srpaulo
9404280405Srpaulo
9405280405Srpaulo<p>
9406280405Srpaulo<hr><h3><a name="pdf-math.randomseed"><code>math.randomseed (x)</code></a></h3>
9407280405Srpaulo
9408280405Srpaulo
9409280405Srpaulo<p>
9410280405SrpauloSets <code>x</code> as the "seed"
9411280405Srpaulofor the pseudo-random generator:
9412280405Srpauloequal seeds produce equal sequences of numbers.
9413280405Srpaulo
9414280405Srpaulo
9415280405Srpaulo
9416280405Srpaulo
9417280405Srpaulo<p>
9418280405Srpaulo<hr><h3><a name="pdf-math.sin"><code>math.sin (x)</code></a></h3>
9419280405Srpaulo
9420280405Srpaulo
9421280405Srpaulo<p>
9422280405SrpauloReturns the sine of <code>x</code> (assumed to be in radians).
9423280405Srpaulo
9424280405Srpaulo
9425280405Srpaulo
9426280405Srpaulo
9427280405Srpaulo<p>
9428280405Srpaulo<hr><h3><a name="pdf-math.sqrt"><code>math.sqrt (x)</code></a></h3>
9429280405Srpaulo
9430280405Srpaulo
9431280405Srpaulo<p>
9432280405SrpauloReturns the square root of <code>x</code>.
9433280405Srpaulo(You can also use the expression <code>x^0.5</code> to compute this value.)
9434280405Srpaulo
9435280405Srpaulo
9436280405Srpaulo
9437280405Srpaulo
9438280405Srpaulo<p>
9439280405Srpaulo<hr><h3><a name="pdf-math.tan"><code>math.tan (x)</code></a></h3>
9440280405Srpaulo
9441280405Srpaulo
9442280405Srpaulo<p>
9443280405SrpauloReturns the tangent of <code>x</code> (assumed to be in radians).
9444280405Srpaulo
9445280405Srpaulo
9446280405Srpaulo
9447280405Srpaulo
9448280405Srpaulo<p>
9449280405Srpaulo<hr><h3><a name="pdf-math.tointeger"><code>math.tointeger (x)</code></a></h3>
9450280405Srpaulo
9451280405Srpaulo
9452280405Srpaulo<p>
9453280405SrpauloIf the value <code>x</code> is convertible to an integer,
9454280405Srpauloreturns that integer.
9455280405SrpauloOtherwise, returns <b>nil</b>.
9456280405Srpaulo
9457280405Srpaulo
9458280405Srpaulo
9459280405Srpaulo
9460280405Srpaulo<p>
9461280405Srpaulo<hr><h3><a name="pdf-math.type"><code>math.type (x)</code></a></h3>
9462280405Srpaulo
9463280405Srpaulo
9464280405Srpaulo<p>
9465280405SrpauloReturns "<code>integer</code>" if <code>x</code> is an integer,
9466280405Srpaulo"<code>float</code>" if it is a float,
9467280405Srpauloor <b>nil</b> if <code>x</code> is not a number.
9468280405Srpaulo
9469280405Srpaulo
9470280405Srpaulo
9471280405Srpaulo
9472280405Srpaulo<p>
9473280405Srpaulo<hr><h3><a name="pdf-math.ult"><code>math.ult (m, n)</code></a></h3>
9474280405Srpaulo
9475280405Srpaulo
9476280405Srpaulo<p>
9477280405SrpauloReturns a boolean,
9478326344Simptrue if and only if integer <code>m</code> is below integer <code>n</code> when
9479280405Srpaulothey are compared as unsigned integers.
9480280405Srpaulo
9481280405Srpaulo
9482280405Srpaulo
9483280405Srpaulo
9484280405Srpaulo
9485280405Srpaulo
9486280405Srpaulo
9487280405Srpaulo<h2>6.8 &ndash; <a name="6.8">Input and Output Facilities</a></h2>
9488280405Srpaulo
9489280405Srpaulo<p>
9490280405SrpauloThe I/O library provides two different styles for file manipulation.
9491280405SrpauloThe first one uses implicit file handles;
9492280405Srpaulothat is, there are operations to set a default input file and a
9493280405Srpaulodefault output file,
9494280405Srpauloand all input/output operations are over these default files.
9495280405SrpauloThe second style uses explicit file handles.
9496280405Srpaulo
9497280405Srpaulo
9498280405Srpaulo<p>
9499280405SrpauloWhen using implicit file handles,
9500280405Srpauloall operations are supplied by table <a name="pdf-io"><code>io</code></a>.
9501280405SrpauloWhen using explicit file handles,
9502280405Srpaulothe operation <a href="#pdf-io.open"><code>io.open</code></a> returns a file handle
9503280405Srpauloand then all operations are supplied as methods of the file handle.
9504280405Srpaulo
9505280405Srpaulo
9506280405Srpaulo<p>
9507280405SrpauloThe table <code>io</code> also provides
9508280405Srpaulothree predefined file handles with their usual meanings from C:
9509280405Srpaulo<a name="pdf-io.stdin"><code>io.stdin</code></a>, <a name="pdf-io.stdout"><code>io.stdout</code></a>, and <a name="pdf-io.stderr"><code>io.stderr</code></a>.
9510280405SrpauloThe I/O library never closes these files.
9511280405Srpaulo
9512280405Srpaulo
9513280405Srpaulo<p>
9514280405SrpauloUnless otherwise stated,
9515280405Srpauloall I/O functions return <b>nil</b> on failure
9516280405Srpaulo(plus an error message as a second result and
9517280405Srpauloa system-dependent error code as a third result)
9518280405Srpauloand some value different from <b>nil</b> on success.
9519280405SrpauloOn non-POSIX systems,
9520280405Srpaulothe computation of the error message and error code
9521280405Srpauloin case of errors
9522280405Srpaulomay be not thread safe,
9523280405Srpaulobecause they rely on the global C variable <code>errno</code>.
9524280405Srpaulo
9525280405Srpaulo
9526280405Srpaulo<p>
9527280405Srpaulo<hr><h3><a name="pdf-io.close"><code>io.close ([file])</code></a></h3>
9528280405Srpaulo
9529280405Srpaulo
9530280405Srpaulo<p>
9531280405SrpauloEquivalent to <code>file:close()</code>.
9532280405SrpauloWithout a <code>file</code>, closes the default output file.
9533280405Srpaulo
9534280405Srpaulo
9535280405Srpaulo
9536280405Srpaulo
9537280405Srpaulo<p>
9538280405Srpaulo<hr><h3><a name="pdf-io.flush"><code>io.flush ()</code></a></h3>
9539280405Srpaulo
9540280405Srpaulo
9541280405Srpaulo<p>
9542280405SrpauloEquivalent to <code>io.output():flush()</code>.
9543280405Srpaulo
9544280405Srpaulo
9545280405Srpaulo
9546280405Srpaulo
9547280405Srpaulo<p>
9548280405Srpaulo<hr><h3><a name="pdf-io.input"><code>io.input ([file])</code></a></h3>
9549280405Srpaulo
9550280405Srpaulo
9551280405Srpaulo<p>
9552280405SrpauloWhen called with a file name, it opens the named file (in text mode),
9553280405Srpauloand sets its handle as the default input file.
9554280405SrpauloWhen called with a file handle,
9555280405Srpauloit simply sets this file handle as the default input file.
9556280405SrpauloWhen called without parameters,
9557280405Srpauloit returns the current default input file.
9558280405Srpaulo
9559280405Srpaulo
9560280405Srpaulo<p>
9561280405SrpauloIn case of errors this function raises the error,
9562280405Srpauloinstead of returning an error code.
9563280405Srpaulo
9564280405Srpaulo
9565280405Srpaulo
9566280405Srpaulo
9567280405Srpaulo<p>
9568326344Simp<hr><h3><a name="pdf-io.lines"><code>io.lines ([filename, &middot;&middot;&middot;])</code></a></h3>
9569280405Srpaulo
9570280405Srpaulo
9571280405Srpaulo<p>
9572280405SrpauloOpens the given file name in read mode
9573280405Srpauloand returns an iterator function that
9574280405Srpauloworks like <code>file:lines(&middot;&middot;&middot;)</code> over the opened file.
9575280405SrpauloWhen the iterator function detects the end of file,
9576280405Srpauloit returns no values (to finish the loop) and automatically closes the file.
9577280405Srpaulo
9578280405Srpaulo
9579280405Srpaulo<p>
9580280405SrpauloThe call <code>io.lines()</code> (with no file name) is equivalent
9581280405Srpauloto <code>io.input():lines("*l")</code>;
9582280405Srpaulothat is, it iterates over the lines of the default input file.
9583280405SrpauloIn this case it does not close the file when the loop ends.
9584280405Srpaulo
9585280405Srpaulo
9586280405Srpaulo<p>
9587280405SrpauloIn case of errors this function raises the error,
9588280405Srpauloinstead of returning an error code.
9589280405Srpaulo
9590280405Srpaulo
9591280405Srpaulo
9592280405Srpaulo
9593280405Srpaulo<p>
9594280405Srpaulo<hr><h3><a name="pdf-io.open"><code>io.open (filename [, mode])</code></a></h3>
9595280405Srpaulo
9596280405Srpaulo
9597280405Srpaulo<p>
9598280405SrpauloThis function opens a file,
9599280405Srpauloin the mode specified in the string <code>mode</code>.
9600326344SimpIn case of success,
9601326344Simpit returns a new file handle.
9602280405Srpaulo
9603280405Srpaulo
9604280405Srpaulo<p>
9605280405SrpauloThe <code>mode</code> string can be any of the following:
9606280405Srpaulo
9607280405Srpaulo<ul>
9608280405Srpaulo<li><b>"<code>r</code>": </b> read mode (the default);</li>
9609280405Srpaulo<li><b>"<code>w</code>": </b> write mode;</li>
9610280405Srpaulo<li><b>"<code>a</code>": </b> append mode;</li>
9611280405Srpaulo<li><b>"<code>r+</code>": </b> update mode, all previous data is preserved;</li>
9612280405Srpaulo<li><b>"<code>w+</code>": </b> update mode, all previous data is erased;</li>
9613280405Srpaulo<li><b>"<code>a+</code>": </b> append update mode, previous data is preserved,
9614280405Srpaulo  writing is only allowed at the end of file.</li>
9615280405Srpaulo</ul><p>
9616280405SrpauloThe <code>mode</code> string can also have a '<code>b</code>' at the end,
9617280405Srpaulowhich is needed in some systems to open the file in binary mode.
9618280405Srpaulo
9619280405Srpaulo
9620280405Srpaulo
9621280405Srpaulo
9622280405Srpaulo<p>
9623280405Srpaulo<hr><h3><a name="pdf-io.output"><code>io.output ([file])</code></a></h3>
9624280405Srpaulo
9625280405Srpaulo
9626280405Srpaulo<p>
9627280405SrpauloSimilar to <a href="#pdf-io.input"><code>io.input</code></a>, but operates over the default output file.
9628280405Srpaulo
9629280405Srpaulo
9630280405Srpaulo
9631280405Srpaulo
9632280405Srpaulo<p>
9633280405Srpaulo<hr><h3><a name="pdf-io.popen"><code>io.popen (prog [, mode])</code></a></h3>
9634280405Srpaulo
9635280405Srpaulo
9636280405Srpaulo<p>
9637280405SrpauloThis function is system dependent and is not available
9638280405Srpauloon all platforms.
9639280405Srpaulo
9640280405Srpaulo
9641280405Srpaulo<p>
9642280405SrpauloStarts program <code>prog</code> in a separated process and returns
9643280405Srpauloa file handle that you can use to read data from this program
9644280405Srpaulo(if <code>mode</code> is <code>"r"</code>, the default)
9645280405Srpauloor to write data to this program
9646280405Srpaulo(if <code>mode</code> is <code>"w"</code>).
9647280405Srpaulo
9648280405Srpaulo
9649280405Srpaulo
9650280405Srpaulo
9651280405Srpaulo<p>
9652280405Srpaulo<hr><h3><a name="pdf-io.read"><code>io.read (&middot;&middot;&middot;)</code></a></h3>
9653280405Srpaulo
9654280405Srpaulo
9655280405Srpaulo<p>
9656280405SrpauloEquivalent to <code>io.input():read(&middot;&middot;&middot;)</code>.
9657280405Srpaulo
9658280405Srpaulo
9659280405Srpaulo
9660280405Srpaulo
9661280405Srpaulo<p>
9662280405Srpaulo<hr><h3><a name="pdf-io.tmpfile"><code>io.tmpfile ()</code></a></h3>
9663280405Srpaulo
9664280405Srpaulo
9665280405Srpaulo<p>
9666326344SimpIn case of success,
9667326344Simpreturns a handle for a temporary file.
9668280405SrpauloThis file is opened in update mode
9669280405Srpauloand it is automatically removed when the program ends.
9670280405Srpaulo
9671280405Srpaulo
9672280405Srpaulo
9673280405Srpaulo
9674280405Srpaulo<p>
9675280405Srpaulo<hr><h3><a name="pdf-io.type"><code>io.type (obj)</code></a></h3>
9676280405Srpaulo
9677280405Srpaulo
9678280405Srpaulo<p>
9679280405SrpauloChecks whether <code>obj</code> is a valid file handle.
9680280405SrpauloReturns the string <code>"file"</code> if <code>obj</code> is an open file handle,
9681280405Srpaulo<code>"closed file"</code> if <code>obj</code> is a closed file handle,
9682280405Srpauloor <b>nil</b> if <code>obj</code> is not a file handle.
9683280405Srpaulo
9684280405Srpaulo
9685280405Srpaulo
9686280405Srpaulo
9687280405Srpaulo<p>
9688280405Srpaulo<hr><h3><a name="pdf-io.write"><code>io.write (&middot;&middot;&middot;)</code></a></h3>
9689280405Srpaulo
9690280405Srpaulo
9691280405Srpaulo<p>
9692280405SrpauloEquivalent to <code>io.output():write(&middot;&middot;&middot;)</code>.
9693280405Srpaulo
9694280405Srpaulo
9695280405Srpaulo
9696280405Srpaulo
9697280405Srpaulo<p>
9698280405Srpaulo<hr><h3><a name="pdf-file:close"><code>file:close ()</code></a></h3>
9699280405Srpaulo
9700280405Srpaulo
9701280405Srpaulo<p>
9702280405SrpauloCloses <code>file</code>.
9703280405SrpauloNote that files are automatically closed when
9704280405Srpaulotheir handles are garbage collected,
9705280405Srpaulobut that takes an unpredictable amount of time to happen.
9706280405Srpaulo
9707280405Srpaulo
9708280405Srpaulo<p>
9709280405SrpauloWhen closing a file handle created with <a href="#pdf-io.popen"><code>io.popen</code></a>,
9710280405Srpaulo<a href="#pdf-file:close"><code>file:close</code></a> returns the same values
9711280405Srpauloreturned by <a href="#pdf-os.execute"><code>os.execute</code></a>.
9712280405Srpaulo
9713280405Srpaulo
9714280405Srpaulo
9715280405Srpaulo
9716280405Srpaulo<p>
9717280405Srpaulo<hr><h3><a name="pdf-file:flush"><code>file:flush ()</code></a></h3>
9718280405Srpaulo
9719280405Srpaulo
9720280405Srpaulo<p>
9721280405SrpauloSaves any written data to <code>file</code>.
9722280405Srpaulo
9723280405Srpaulo
9724280405Srpaulo
9725280405Srpaulo
9726280405Srpaulo<p>
9727280405Srpaulo<hr><h3><a name="pdf-file:lines"><code>file:lines (&middot;&middot;&middot;)</code></a></h3>
9728280405Srpaulo
9729280405Srpaulo
9730280405Srpaulo<p>
9731280405SrpauloReturns an iterator function that,
9732280405Srpauloeach time it is called,
9733280405Srpauloreads the file according to the given formats.
9734280405SrpauloWhen no format is given,
9735280405Srpaulouses "<code>l</code>" as a default.
9736280405SrpauloAs an example, the construction
9737280405Srpaulo
9738280405Srpaulo<pre>
9739280405Srpaulo     for c in file:lines(1) do <em>body</em> end
9740280405Srpaulo</pre><p>
9741280405Srpaulowill iterate over all characters of the file,
9742280405Srpaulostarting at the current position.
9743280405SrpauloUnlike <a href="#pdf-io.lines"><code>io.lines</code></a>, this function does not close the file
9744280405Srpaulowhen the loop ends.
9745280405Srpaulo
9746280405Srpaulo
9747280405Srpaulo<p>
9748280405SrpauloIn case of errors this function raises the error,
9749280405Srpauloinstead of returning an error code.
9750280405Srpaulo
9751280405Srpaulo
9752280405Srpaulo
9753280405Srpaulo
9754280405Srpaulo<p>
9755280405Srpaulo<hr><h3><a name="pdf-file:read"><code>file:read (&middot;&middot;&middot;)</code></a></h3>
9756280405Srpaulo
9757280405Srpaulo
9758280405Srpaulo<p>
9759280405SrpauloReads the file <code>file</code>,
9760280405Srpauloaccording to the given formats, which specify what to read.
9761280405SrpauloFor each format,
9762280405Srpaulothe function returns a string or a number with the characters read,
9763280405Srpauloor <b>nil</b> if it cannot read data with the specified format.
9764280405Srpaulo(In this latter case,
9765280405Srpaulothe function does not read subsequent formats.)
9766280405SrpauloWhen called without formats,
9767280405Srpauloit uses a default format that reads the next line
9768280405Srpaulo(see below).
9769280405Srpaulo
9770280405Srpaulo
9771280405Srpaulo<p>
9772280405SrpauloThe available formats are
9773280405Srpaulo
9774280405Srpaulo<ul>
9775280405Srpaulo
9776280405Srpaulo<li><b>"<code>n</code>": </b>
9777280405Srpauloreads a numeral and returns it as a float or an integer,
9778280405Srpaulofollowing the lexical conventions of Lua.
9779280405Srpaulo(The numeral may have leading spaces and a sign.)
9780280405SrpauloThis format always reads the longest input sequence that
9781326344Simpis a valid prefix for a numeral;
9782326344Simpif that prefix does not form a valid numeral
9783280405Srpaulo(e.g., an empty string, "<code>0x</code>", or "<code>3.4e-</code>"),
9784280405Srpauloit is discarded and the function returns <b>nil</b>.
9785280405Srpaulo</li>
9786280405Srpaulo
9787280405Srpaulo<li><b>"<code>a</code>": </b>
9788280405Srpauloreads the whole file, starting at the current position.
9789280405SrpauloOn end of file, it returns the empty string.
9790280405Srpaulo</li>
9791280405Srpaulo
9792280405Srpaulo<li><b>"<code>l</code>": </b>
9793280405Srpauloreads the next line skipping the end of line,
9794280405Srpauloreturning <b>nil</b> on end of file.
9795280405SrpauloThis is the default format.
9796280405Srpaulo</li>
9797280405Srpaulo
9798280405Srpaulo<li><b>"<code>L</code>": </b>
9799280405Srpauloreads the next line keeping the end-of-line character (if present),
9800280405Srpauloreturning <b>nil</b> on end of file.
9801280405Srpaulo</li>
9802280405Srpaulo
9803280405Srpaulo<li><b><em>number</em>: </b>
9804280405Srpauloreads a string with up to this number of bytes,
9805280405Srpauloreturning <b>nil</b> on end of file.
9806280405SrpauloIf <code>number</code> is zero,
9807280405Srpauloit reads nothing and returns an empty string,
9808280405Srpauloor <b>nil</b> on end of file.
9809280405Srpaulo</li>
9810280405Srpaulo
9811280405Srpaulo</ul><p>
9812280405SrpauloThe formats "<code>l</code>" and "<code>L</code>" should be used only for text files.
9813280405Srpaulo
9814280405Srpaulo
9815280405Srpaulo
9816280405Srpaulo
9817280405Srpaulo<p>
9818280405Srpaulo<hr><h3><a name="pdf-file:seek"><code>file:seek ([whence [, offset]])</code></a></h3>
9819280405Srpaulo
9820280405Srpaulo
9821280405Srpaulo<p>
9822280405SrpauloSets and gets the file position,
9823280405Srpaulomeasured from the beginning of the file,
9824280405Srpauloto the position given by <code>offset</code> plus a base
9825280405Srpaulospecified by the string <code>whence</code>, as follows:
9826280405Srpaulo
9827280405Srpaulo<ul>
9828280405Srpaulo<li><b>"<code>set</code>": </b> base is position 0 (beginning of the file);</li>
9829280405Srpaulo<li><b>"<code>cur</code>": </b> base is current position;</li>
9830280405Srpaulo<li><b>"<code>end</code>": </b> base is end of file;</li>
9831280405Srpaulo</ul><p>
9832280405SrpauloIn case of success, <code>seek</code> returns the final file position,
9833280405Srpaulomeasured in bytes from the beginning of the file.
9834280405SrpauloIf <code>seek</code> fails, it returns <b>nil</b>,
9835280405Srpauloplus a string describing the error.
9836280405Srpaulo
9837280405Srpaulo
9838280405Srpaulo<p>
9839280405SrpauloThe default value for <code>whence</code> is <code>"cur"</code>,
9840280405Srpauloand for <code>offset</code> is 0.
9841280405SrpauloTherefore, the call <code>file:seek()</code> returns the current
9842280405Srpaulofile position, without changing it;
9843280405Srpaulothe call <code>file:seek("set")</code> sets the position to the
9844280405Srpaulobeginning of the file (and returns 0);
9845280405Srpauloand the call <code>file:seek("end")</code> sets the position to the
9846280405Srpauloend of the file, and returns its size.
9847280405Srpaulo
9848280405Srpaulo
9849280405Srpaulo
9850280405Srpaulo
9851280405Srpaulo<p>
9852280405Srpaulo<hr><h3><a name="pdf-file:setvbuf"><code>file:setvbuf (mode [, size])</code></a></h3>
9853280405Srpaulo
9854280405Srpaulo
9855280405Srpaulo<p>
9856280405SrpauloSets the buffering mode for an output file.
9857280405SrpauloThere are three available modes:
9858280405Srpaulo
9859280405Srpaulo<ul>
9860280405Srpaulo
9861280405Srpaulo<li><b>"<code>no</code>": </b>
9862280405Srpaulono buffering; the result of any output operation appears immediately.
9863280405Srpaulo</li>
9864280405Srpaulo
9865280405Srpaulo<li><b>"<code>full</code>": </b>
9866280405Srpaulofull buffering; output operation is performed only
9867280405Srpaulowhen the buffer is full or when
9868280405Srpauloyou explicitly <code>flush</code> the file (see <a href="#pdf-io.flush"><code>io.flush</code></a>).
9869280405Srpaulo</li>
9870280405Srpaulo
9871280405Srpaulo<li><b>"<code>line</code>": </b>
9872280405Srpauloline buffering; output is buffered until a newline is output
9873280405Srpauloor there is any input from some special files
9874280405Srpaulo(such as a terminal device).
9875280405Srpaulo</li>
9876280405Srpaulo
9877280405Srpaulo</ul><p>
9878280405SrpauloFor the last two cases, <code>size</code>
9879280405Srpaulospecifies the size of the buffer, in bytes.
9880280405SrpauloThe default is an appropriate size.
9881280405Srpaulo
9882280405Srpaulo
9883280405Srpaulo
9884280405Srpaulo
9885280405Srpaulo<p>
9886280405Srpaulo<hr><h3><a name="pdf-file:write"><code>file:write (&middot;&middot;&middot;)</code></a></h3>
9887280405Srpaulo
9888280405Srpaulo
9889280405Srpaulo<p>
9890280405SrpauloWrites the value of each of its arguments to <code>file</code>.
9891280405SrpauloThe arguments must be strings or numbers.
9892280405Srpaulo
9893280405Srpaulo
9894280405Srpaulo<p>
9895280405SrpauloIn case of success, this function returns <code>file</code>.
9896280405SrpauloOtherwise it returns <b>nil</b> plus a string describing the error.
9897280405Srpaulo
9898280405Srpaulo
9899280405Srpaulo
9900280405Srpaulo
9901280405Srpaulo
9902280405Srpaulo
9903280405Srpaulo
9904280405Srpaulo<h2>6.9 &ndash; <a name="6.9">Operating System Facilities</a></h2>
9905280405Srpaulo
9906280405Srpaulo<p>
9907280405SrpauloThis library is implemented through table <a name="pdf-os"><code>os</code></a>.
9908280405Srpaulo
9909280405Srpaulo
9910280405Srpaulo<p>
9911280405Srpaulo<hr><h3><a name="pdf-os.clock"><code>os.clock ()</code></a></h3>
9912280405Srpaulo
9913280405Srpaulo
9914280405Srpaulo<p>
9915280405SrpauloReturns an approximation of the amount in seconds of CPU time
9916280405Srpauloused by the program.
9917280405Srpaulo
9918280405Srpaulo
9919280405Srpaulo
9920280405Srpaulo
9921280405Srpaulo<p>
9922280405Srpaulo<hr><h3><a name="pdf-os.date"><code>os.date ([format [, time]])</code></a></h3>
9923280405Srpaulo
9924280405Srpaulo
9925280405Srpaulo<p>
9926280405SrpauloReturns a string or a table containing date and time,
9927280405Srpauloformatted according to the given string <code>format</code>.
9928280405Srpaulo
9929280405Srpaulo
9930280405Srpaulo<p>
9931280405SrpauloIf the <code>time</code> argument is present,
9932280405Srpaulothis is the time to be formatted
9933280405Srpaulo(see the <a href="#pdf-os.time"><code>os.time</code></a> function for a description of this value).
9934280405SrpauloOtherwise, <code>date</code> formats the current time.
9935280405Srpaulo
9936280405Srpaulo
9937280405Srpaulo<p>
9938280405SrpauloIf <code>format</code> starts with '<code>!</code>',
9939280405Srpaulothen the date is formatted in Coordinated Universal Time.
9940280405SrpauloAfter this optional character,
9941280405Srpauloif <code>format</code> is the string "<code>*t</code>",
9942280405Srpaulothen <code>date</code> returns a table with the following fields:
9943326344Simp<code>year</code>, <code>month</code> (1&ndash;12), <code>day</code> (1&ndash;31),
9944280405Srpaulo<code>hour</code> (0&ndash;23), <code>min</code> (0&ndash;59), <code>sec</code> (0&ndash;61),
9945326344Simp<code>wday</code> (weekday, 1&ndash;7, Sunday is&nbsp;1),
9946326344Simp<code>yday</code> (day of the year, 1&ndash;366),
9947280405Srpauloand <code>isdst</code> (daylight saving flag, a boolean).
9948280405SrpauloThis last field may be absent
9949280405Srpauloif the information is not available.
9950280405Srpaulo
9951280405Srpaulo
9952280405Srpaulo<p>
9953280405SrpauloIf <code>format</code> is not "<code>*t</code>",
9954280405Srpaulothen <code>date</code> returns the date as a string,
9955280405Srpauloformatted according to the same rules as the ISO&nbsp;C function <code>strftime</code>.
9956280405Srpaulo
9957280405Srpaulo
9958280405Srpaulo<p>
9959280405SrpauloWhen called without arguments,
9960280405Srpaulo<code>date</code> returns a reasonable date and time representation that depends on
9961326344Simpthe host system and on the current locale.
9962326344Simp(More specifically, <code>os.date()</code> is equivalent to <code>os.date("%c")</code>.)
9963280405Srpaulo
9964280405Srpaulo
9965280405Srpaulo<p>
9966280405SrpauloOn non-POSIX systems,
9967280405Srpaulothis function may be not thread safe
9968280405Srpaulobecause of its reliance on C&nbsp;function <code>gmtime</code> and C&nbsp;function <code>localtime</code>.
9969280405Srpaulo
9970280405Srpaulo
9971280405Srpaulo
9972280405Srpaulo
9973280405Srpaulo<p>
9974280405Srpaulo<hr><h3><a name="pdf-os.difftime"><code>os.difftime (t2, t1)</code></a></h3>
9975280405Srpaulo
9976280405Srpaulo
9977280405Srpaulo<p>
9978280405SrpauloReturns the difference, in seconds,
9979280405Srpaulofrom time <code>t1</code> to time <code>t2</code>
9980280405Srpaulo(where the times are values returned by <a href="#pdf-os.time"><code>os.time</code></a>).
9981280405SrpauloIn POSIX, Windows, and some other systems,
9982280405Srpaulothis value is exactly <code>t2</code><em>-</em><code>t1</code>.
9983280405Srpaulo
9984280405Srpaulo
9985280405Srpaulo
9986280405Srpaulo
9987280405Srpaulo<p>
9988280405Srpaulo<hr><h3><a name="pdf-os.execute"><code>os.execute ([command])</code></a></h3>
9989280405Srpaulo
9990280405Srpaulo
9991280405Srpaulo<p>
9992280405SrpauloThis function is equivalent to the ISO&nbsp;C function <code>system</code>.
9993280405SrpauloIt passes <code>command</code> to be executed by an operating system shell.
9994280405SrpauloIts first result is <b>true</b>
9995280405Srpauloif the command terminated successfully,
9996280405Srpauloor <b>nil</b> otherwise.
9997280405SrpauloAfter this first result
9998280405Srpaulothe function returns a string plus a number,
9999280405Srpauloas follows:
10000280405Srpaulo
10001280405Srpaulo<ul>
10002280405Srpaulo
10003280405Srpaulo<li><b>"<code>exit</code>": </b>
10004280405Srpaulothe command terminated normally;
10005280405Srpaulothe following number is the exit status of the command.
10006280405Srpaulo</li>
10007280405Srpaulo
10008280405Srpaulo<li><b>"<code>signal</code>": </b>
10009280405Srpaulothe command was terminated by a signal;
10010280405Srpaulothe following number is the signal that terminated the command.
10011280405Srpaulo</li>
10012280405Srpaulo
10013280405Srpaulo</ul>
10014280405Srpaulo
10015280405Srpaulo<p>
10016280405SrpauloWhen called without a <code>command</code>,
10017280405Srpaulo<code>os.execute</code> returns a boolean that is true if a shell is available.
10018280405Srpaulo
10019280405Srpaulo
10020280405Srpaulo
10021280405Srpaulo
10022280405Srpaulo<p>
10023280405Srpaulo<hr><h3><a name="pdf-os.exit"><code>os.exit ([code [, close]])</code></a></h3>
10024280405Srpaulo
10025280405Srpaulo
10026280405Srpaulo<p>
10027280405SrpauloCalls the ISO&nbsp;C function <code>exit</code> to terminate the host program.
10028280405SrpauloIf <code>code</code> is <b>true</b>,
10029280405Srpaulothe returned status is <code>EXIT_SUCCESS</code>;
10030280405Srpauloif <code>code</code> is <b>false</b>,
10031280405Srpaulothe returned status is <code>EXIT_FAILURE</code>;
10032280405Srpauloif <code>code</code> is a number,
10033280405Srpaulothe returned status is this number.
10034280405SrpauloThe default value for <code>code</code> is <b>true</b>.
10035280405Srpaulo
10036280405Srpaulo
10037280405Srpaulo<p>
10038280405SrpauloIf the optional second argument <code>close</code> is true,
10039280405Srpaulocloses the Lua state before exiting.
10040280405Srpaulo
10041280405Srpaulo
10042280405Srpaulo
10043280405Srpaulo
10044280405Srpaulo<p>
10045280405Srpaulo<hr><h3><a name="pdf-os.getenv"><code>os.getenv (varname)</code></a></h3>
10046280405Srpaulo
10047280405Srpaulo
10048280405Srpaulo<p>
10049280405SrpauloReturns the value of the process environment variable <code>varname</code>,
10050280405Srpauloor <b>nil</b> if the variable is not defined.
10051280405Srpaulo
10052280405Srpaulo
10053280405Srpaulo
10054280405Srpaulo
10055280405Srpaulo<p>
10056280405Srpaulo<hr><h3><a name="pdf-os.remove"><code>os.remove (filename)</code></a></h3>
10057280405Srpaulo
10058280405Srpaulo
10059280405Srpaulo<p>
10060280405SrpauloDeletes the file (or empty directory, on POSIX systems)
10061280405Srpaulowith the given name.
10062280405SrpauloIf this function fails, it returns <b>nil</b>,
10063280405Srpauloplus a string describing the error and the error code.
10064326344SimpOtherwise, it returns true.
10065280405Srpaulo
10066280405Srpaulo
10067280405Srpaulo
10068280405Srpaulo
10069280405Srpaulo<p>
10070280405Srpaulo<hr><h3><a name="pdf-os.rename"><code>os.rename (oldname, newname)</code></a></h3>
10071280405Srpaulo
10072280405Srpaulo
10073280405Srpaulo<p>
10074326344SimpRenames the file or directory named <code>oldname</code> to <code>newname</code>.
10075280405SrpauloIf this function fails, it returns <b>nil</b>,
10076280405Srpauloplus a string describing the error and the error code.
10077326344SimpOtherwise, it returns true.
10078280405Srpaulo
10079280405Srpaulo
10080280405Srpaulo
10081280405Srpaulo
10082280405Srpaulo<p>
10083280405Srpaulo<hr><h3><a name="pdf-os.setlocale"><code>os.setlocale (locale [, category])</code></a></h3>
10084280405Srpaulo
10085280405Srpaulo
10086280405Srpaulo<p>
10087280405SrpauloSets the current locale of the program.
10088280405Srpaulo<code>locale</code> is a system-dependent string specifying a locale;
10089280405Srpaulo<code>category</code> is an optional string describing which category to change:
10090280405Srpaulo<code>"all"</code>, <code>"collate"</code>, <code>"ctype"</code>,
10091280405Srpaulo<code>"monetary"</code>, <code>"numeric"</code>, or <code>"time"</code>;
10092280405Srpaulothe default category is <code>"all"</code>.
10093280405SrpauloThe function returns the name of the new locale,
10094280405Srpauloor <b>nil</b> if the request cannot be honored.
10095280405Srpaulo
10096280405Srpaulo
10097280405Srpaulo<p>
10098280405SrpauloIf <code>locale</code> is the empty string,
10099280405Srpaulothe current locale is set to an implementation-defined native locale.
10100280405SrpauloIf <code>locale</code> is the string "<code>C</code>",
10101280405Srpaulothe current locale is set to the standard C locale.
10102280405Srpaulo
10103280405Srpaulo
10104280405Srpaulo<p>
10105280405SrpauloWhen called with <b>nil</b> as the first argument,
10106280405Srpaulothis function only returns the name of the current locale
10107280405Srpaulofor the given category.
10108280405Srpaulo
10109280405Srpaulo
10110280405Srpaulo<p>
10111280405SrpauloThis function may be not thread safe
10112280405Srpaulobecause of its reliance on C&nbsp;function <code>setlocale</code>.
10113280405Srpaulo
10114280405Srpaulo
10115280405Srpaulo
10116280405Srpaulo
10117280405Srpaulo<p>
10118280405Srpaulo<hr><h3><a name="pdf-os.time"><code>os.time ([table])</code></a></h3>
10119280405Srpaulo
10120280405Srpaulo
10121280405Srpaulo<p>
10122280405SrpauloReturns the current time when called without arguments,
10123326344Simpor a time representing the local date and time specified by the given table.
10124280405SrpauloThis table must have fields <code>year</code>, <code>month</code>, and <code>day</code>,
10125280405Srpauloand may have fields
10126280405Srpaulo<code>hour</code> (default is 12),
10127280405Srpaulo<code>min</code> (default is 0),
10128280405Srpaulo<code>sec</code> (default is 0),
10129280405Srpauloand <code>isdst</code> (default is <b>nil</b>).
10130326344SimpOther fields are ignored.
10131280405SrpauloFor a description of these fields, see the <a href="#pdf-os.date"><code>os.date</code></a> function.
10132280405Srpaulo
10133280405Srpaulo
10134280405Srpaulo<p>
10135326344SimpThe values in these fields do not need to be inside their valid ranges.
10136326344SimpFor instance, if <code>sec</code> is -10,
10137326344Simpit means -10 seconds from the time specified by the other fields;
10138326344Simpif <code>hour</code> is 1000,
10139326344Simpit means +1000 hours from the time specified by the other fields.
10140326344Simp
10141326344Simp
10142326344Simp<p>
10143280405SrpauloThe returned value is a number, whose meaning depends on your system.
10144280405SrpauloIn POSIX, Windows, and some other systems,
10145280405Srpaulothis number counts the number
10146280405Srpauloof seconds since some given start time (the "epoch").
10147280405SrpauloIn other systems, the meaning is not specified,
10148280405Srpauloand the number returned by <code>time</code> can be used only as an argument to
10149280405Srpaulo<a href="#pdf-os.date"><code>os.date</code></a> and <a href="#pdf-os.difftime"><code>os.difftime</code></a>.
10150280405Srpaulo
10151280405Srpaulo
10152280405Srpaulo
10153280405Srpaulo
10154280405Srpaulo<p>
10155280405Srpaulo<hr><h3><a name="pdf-os.tmpname"><code>os.tmpname ()</code></a></h3>
10156280405Srpaulo
10157280405Srpaulo
10158280405Srpaulo<p>
10159280405SrpauloReturns a string with a file name that can
10160280405Srpaulobe used for a temporary file.
10161280405SrpauloThe file must be explicitly opened before its use
10162280405Srpauloand explicitly removed when no longer needed.
10163280405Srpaulo
10164280405Srpaulo
10165280405Srpaulo<p>
10166280405SrpauloOn POSIX systems,
10167280405Srpaulothis function also creates a file with that name,
10168280405Srpauloto avoid security risks.
10169280405Srpaulo(Someone else might create the file with wrong permissions
10170280405Srpauloin the time between getting the name and creating the file.)
10171280405SrpauloYou still have to open the file to use it
10172280405Srpauloand to remove it (even if you do not use it).
10173280405Srpaulo
10174280405Srpaulo
10175280405Srpaulo<p>
10176280405SrpauloWhen possible,
10177280405Srpauloyou may prefer to use <a href="#pdf-io.tmpfile"><code>io.tmpfile</code></a>,
10178280405Srpaulowhich automatically removes the file when the program ends.
10179280405Srpaulo
10180280405Srpaulo
10181280405Srpaulo
10182280405Srpaulo
10183280405Srpaulo
10184280405Srpaulo
10185280405Srpaulo
10186280405Srpaulo<h2>6.10 &ndash; <a name="6.10">The Debug Library</a></h2>
10187280405Srpaulo
10188280405Srpaulo<p>
10189280405SrpauloThis library provides
10190280405Srpaulothe functionality of the debug interface (<a href="#4.9">&sect;4.9</a>) to Lua programs.
10191280405SrpauloYou should exert care when using this library.
10192280405SrpauloSeveral of its functions
10193280405Srpauloviolate basic assumptions about Lua code
10194280405Srpaulo(e.g., that variables local to a function
10195280405Srpaulocannot be accessed from outside;
10196280405Srpaulothat userdata metatables cannot be changed by Lua code;
10197280405Srpaulothat Lua programs do not crash)
10198280405Srpauloand therefore can compromise otherwise secure code.
10199280405SrpauloMoreover, some functions in this library may be slow.
10200280405Srpaulo
10201280405Srpaulo
10202280405Srpaulo<p>
10203280405SrpauloAll functions in this library are provided
10204280405Srpauloinside the <a name="pdf-debug"><code>debug</code></a> table.
10205280405SrpauloAll functions that operate over a thread
10206280405Srpaulohave an optional first argument which is the
10207280405Srpaulothread to operate over.
10208280405SrpauloThe default is always the current thread.
10209280405Srpaulo
10210280405Srpaulo
10211280405Srpaulo<p>
10212280405Srpaulo<hr><h3><a name="pdf-debug.debug"><code>debug.debug ()</code></a></h3>
10213280405Srpaulo
10214280405Srpaulo
10215280405Srpaulo<p>
10216280405SrpauloEnters an interactive mode with the user,
10217280405Srpaulorunning each string that the user enters.
10218280405SrpauloUsing simple commands and other debug facilities,
10219280405Srpaulothe user can inspect global and local variables,
10220280405Srpaulochange their values, evaluate expressions, and so on.
10221280405SrpauloA line containing only the word <code>cont</code> finishes this function,
10222280405Srpauloso that the caller continues its execution.
10223280405Srpaulo
10224280405Srpaulo
10225280405Srpaulo<p>
10226280405SrpauloNote that commands for <code>debug.debug</code> are not lexically nested
10227280405Srpaulowithin any function and so have no direct access to local variables.
10228280405Srpaulo
10229280405Srpaulo
10230280405Srpaulo
10231280405Srpaulo
10232280405Srpaulo<p>
10233280405Srpaulo<hr><h3><a name="pdf-debug.gethook"><code>debug.gethook ([thread])</code></a></h3>
10234280405Srpaulo
10235280405Srpaulo
10236280405Srpaulo<p>
10237280405SrpauloReturns the current hook settings of the thread, as three values:
10238280405Srpaulothe current hook function, the current hook mask,
10239280405Srpauloand the current hook count
10240280405Srpaulo(as set by the <a href="#pdf-debug.sethook"><code>debug.sethook</code></a> function).
10241280405Srpaulo
10242280405Srpaulo
10243280405Srpaulo
10244280405Srpaulo
10245280405Srpaulo<p>
10246280405Srpaulo<hr><h3><a name="pdf-debug.getinfo"><code>debug.getinfo ([thread,] f [, what])</code></a></h3>
10247280405Srpaulo
10248280405Srpaulo
10249280405Srpaulo<p>
10250280405SrpauloReturns a table with information about a function.
10251280405SrpauloYou can give the function directly
10252280405Srpauloor you can give a number as the value of <code>f</code>,
10253280405Srpaulowhich means the function running at level <code>f</code> of the call stack
10254280405Srpauloof the given thread:
10255280405Srpaulolevel&nbsp;0 is the current function (<code>getinfo</code> itself);
10256280405Srpaulolevel&nbsp;1 is the function that called <code>getinfo</code>
10257280405Srpaulo(except for tail calls, which do not count on the stack);
10258280405Srpauloand so on.
10259280405SrpauloIf <code>f</code> is a number larger than the number of active functions,
10260280405Srpaulothen <code>getinfo</code> returns <b>nil</b>.
10261280405Srpaulo
10262280405Srpaulo
10263280405Srpaulo<p>
10264280405SrpauloThe returned table can contain all the fields returned by <a href="#lua_getinfo"><code>lua_getinfo</code></a>,
10265280405Srpaulowith the string <code>what</code> describing which fields to fill in.
10266280405SrpauloThe default for <code>what</code> is to get all information available,
10267280405Srpauloexcept the table of valid lines.
10268280405SrpauloIf present,
10269280405Srpaulothe option '<code>f</code>'
10270280405Srpauloadds a field named <code>func</code> with the function itself.
10271280405SrpauloIf present,
10272280405Srpaulothe option '<code>L</code>'
10273280405Srpauloadds a field named <code>activelines</code> with the table of
10274280405Srpaulovalid lines.
10275280405Srpaulo
10276280405Srpaulo
10277280405Srpaulo<p>
10278280405SrpauloFor instance, the expression <code>debug.getinfo(1,"n").name</code> returns
10279326344Simpa name for the current function,
10280280405Srpauloif a reasonable name can be found,
10281280405Srpauloand the expression <code>debug.getinfo(print)</code>
10282280405Srpauloreturns a table with all available information
10283280405Srpauloabout the <a href="#pdf-print"><code>print</code></a> function.
10284280405Srpaulo
10285280405Srpaulo
10286280405Srpaulo
10287280405Srpaulo
10288280405Srpaulo<p>
10289280405Srpaulo<hr><h3><a name="pdf-debug.getlocal"><code>debug.getlocal ([thread,] f, local)</code></a></h3>
10290280405Srpaulo
10291280405Srpaulo
10292280405Srpaulo<p>
10293280405SrpauloThis function returns the name and the value of the local variable
10294280405Srpaulowith index <code>local</code> of the function at level <code>f</code> of the stack.
10295280405SrpauloThis function accesses not only explicit local variables,
10296280405Srpaulobut also parameters, temporaries, etc.
10297280405Srpaulo
10298280405Srpaulo
10299280405Srpaulo<p>
10300280405SrpauloThe first parameter or local variable has index&nbsp;1, and so on,
10301280405Srpaulofollowing the order that they are declared in the code,
10302280405Srpaulocounting only the variables that are active
10303280405Srpauloin the current scope of the function.
10304280405SrpauloNegative indices refer to vararg parameters;
10305280405Srpaulo-1 is the first vararg parameter.
10306280405SrpauloThe function returns <b>nil</b> if there is no variable with the given index,
10307280405Srpauloand raises an error when called with a level out of range.
10308280405Srpaulo(You can call <a href="#pdf-debug.getinfo"><code>debug.getinfo</code></a> to check whether the level is valid.)
10309280405Srpaulo
10310280405Srpaulo
10311280405Srpaulo<p>
10312280405SrpauloVariable names starting with '<code>(</code>' (open parenthesis) 
10313280405Srpaulorepresent variables with no known names
10314280405Srpaulo(internal variables such as loop control variables,
10315280405Srpauloand variables from chunks saved without debug information).
10316280405Srpaulo
10317280405Srpaulo
10318280405Srpaulo<p>
10319280405SrpauloThe parameter <code>f</code> may also be a function.
10320280405SrpauloIn that case, <code>getlocal</code> returns only the name of function parameters.
10321280405Srpaulo
10322280405Srpaulo
10323280405Srpaulo
10324280405Srpaulo
10325280405Srpaulo<p>
10326280405Srpaulo<hr><h3><a name="pdf-debug.getmetatable"><code>debug.getmetatable (value)</code></a></h3>
10327280405Srpaulo
10328280405Srpaulo
10329280405Srpaulo<p>
10330280405SrpauloReturns the metatable of the given <code>value</code>
10331280405Srpauloor <b>nil</b> if it does not have a metatable.
10332280405Srpaulo
10333280405Srpaulo
10334280405Srpaulo
10335280405Srpaulo
10336280405Srpaulo<p>
10337280405Srpaulo<hr><h3><a name="pdf-debug.getregistry"><code>debug.getregistry ()</code></a></h3>
10338280405Srpaulo
10339280405Srpaulo
10340280405Srpaulo<p>
10341280405SrpauloReturns the registry table (see <a href="#4.5">&sect;4.5</a>).
10342280405Srpaulo
10343280405Srpaulo
10344280405Srpaulo
10345280405Srpaulo
10346280405Srpaulo<p>
10347280405Srpaulo<hr><h3><a name="pdf-debug.getupvalue"><code>debug.getupvalue (f, up)</code></a></h3>
10348280405Srpaulo
10349280405Srpaulo
10350280405Srpaulo<p>
10351280405SrpauloThis function returns the name and the value of the upvalue
10352280405Srpaulowith index <code>up</code> of the function <code>f</code>.
10353280405SrpauloThe function returns <b>nil</b> if there is no upvalue with the given index.
10354280405Srpaulo
10355280405Srpaulo
10356280405Srpaulo<p>
10357280405SrpauloVariable names starting with '<code>(</code>' (open parenthesis) 
10358280405Srpaulorepresent variables with no known names
10359280405Srpaulo(variables from chunks saved without debug information).
10360280405Srpaulo
10361280405Srpaulo
10362280405Srpaulo
10363280405Srpaulo
10364280405Srpaulo<p>
10365280405Srpaulo<hr><h3><a name="pdf-debug.getuservalue"><code>debug.getuservalue (u)</code></a></h3>
10366280405Srpaulo
10367280405Srpaulo
10368280405Srpaulo<p>
10369280405SrpauloReturns the Lua value associated to <code>u</code>.
10370326344SimpIf <code>u</code> is not a full userdata,
10371280405Srpauloreturns <b>nil</b>.
10372280405Srpaulo
10373280405Srpaulo
10374280405Srpaulo
10375280405Srpaulo
10376280405Srpaulo<p>
10377280405Srpaulo<hr><h3><a name="pdf-debug.sethook"><code>debug.sethook ([thread,] hook, mask [, count])</code></a></h3>
10378280405Srpaulo
10379280405Srpaulo
10380280405Srpaulo<p>
10381280405SrpauloSets the given function as a hook.
10382280405SrpauloThe string <code>mask</code> and the number <code>count</code> describe
10383280405Srpaulowhen the hook will be called.
10384280405SrpauloThe string mask may have any combination of the following characters,
10385280405Srpaulowith the given meaning:
10386280405Srpaulo
10387280405Srpaulo<ul>
10388280405Srpaulo<li><b>'<code>c</code>': </b> the hook is called every time Lua calls a function;</li>
10389280405Srpaulo<li><b>'<code>r</code>': </b> the hook is called every time Lua returns from a function;</li>
10390280405Srpaulo<li><b>'<code>l</code>': </b> the hook is called every time Lua enters a new line of code.</li>
10391280405Srpaulo</ul><p>
10392280405SrpauloMoreover,
10393280405Srpaulowith a <code>count</code> different from zero,
10394280405Srpaulothe hook is called also after every <code>count</code> instructions.
10395280405Srpaulo
10396280405Srpaulo
10397280405Srpaulo<p>
10398280405SrpauloWhen called without arguments,
10399280405Srpaulo<a href="#pdf-debug.sethook"><code>debug.sethook</code></a> turns off the hook.
10400280405Srpaulo
10401280405Srpaulo
10402280405Srpaulo<p>
10403280405SrpauloWhen the hook is called, its first parameter is a string
10404280405Srpaulodescribing the event that has triggered its call:
10405280405Srpaulo<code>"call"</code> (or <code>"tail call"</code>),
10406280405Srpaulo<code>"return"</code>,
10407280405Srpaulo<code>"line"</code>, and <code>"count"</code>.
10408280405SrpauloFor line events,
10409280405Srpaulothe hook also gets the new line number as its second parameter.
10410280405SrpauloInside a hook,
10411280405Srpauloyou can call <code>getinfo</code> with level&nbsp;2 to get more information about
10412280405Srpaulothe running function
10413280405Srpaulo(level&nbsp;0 is the <code>getinfo</code> function,
10414280405Srpauloand level&nbsp;1 is the hook function).
10415280405Srpaulo
10416280405Srpaulo
10417280405Srpaulo
10418280405Srpaulo
10419280405Srpaulo<p>
10420280405Srpaulo<hr><h3><a name="pdf-debug.setlocal"><code>debug.setlocal ([thread,] level, local, value)</code></a></h3>
10421280405Srpaulo
10422280405Srpaulo
10423280405Srpaulo<p>
10424280405SrpauloThis function assigns the value <code>value</code> to the local variable
10425280405Srpaulowith index <code>local</code> of the function at level <code>level</code> of the stack.
10426280405SrpauloThe function returns <b>nil</b> if there is no local
10427280405Srpaulovariable with the given index,
10428280405Srpauloand raises an error when called with a <code>level</code> out of range.
10429280405Srpaulo(You can call <code>getinfo</code> to check whether the level is valid.)
10430280405SrpauloOtherwise, it returns the name of the local variable.
10431280405Srpaulo
10432280405Srpaulo
10433280405Srpaulo<p>
10434280405SrpauloSee <a href="#pdf-debug.getlocal"><code>debug.getlocal</code></a> for more information about
10435280405Srpaulovariable indices and names.
10436280405Srpaulo
10437280405Srpaulo
10438280405Srpaulo
10439280405Srpaulo
10440280405Srpaulo<p>
10441280405Srpaulo<hr><h3><a name="pdf-debug.setmetatable"><code>debug.setmetatable (value, table)</code></a></h3>
10442280405Srpaulo
10443280405Srpaulo
10444280405Srpaulo<p>
10445280405SrpauloSets the metatable for the given <code>value</code> to the given <code>table</code>
10446280405Srpaulo(which can be <b>nil</b>).
10447280405SrpauloReturns <code>value</code>.
10448280405Srpaulo
10449280405Srpaulo
10450280405Srpaulo
10451280405Srpaulo
10452280405Srpaulo<p>
10453280405Srpaulo<hr><h3><a name="pdf-debug.setupvalue"><code>debug.setupvalue (f, up, value)</code></a></h3>
10454280405Srpaulo
10455280405Srpaulo
10456280405Srpaulo<p>
10457280405SrpauloThis function assigns the value <code>value</code> to the upvalue
10458280405Srpaulowith index <code>up</code> of the function <code>f</code>.
10459280405SrpauloThe function returns <b>nil</b> if there is no upvalue
10460280405Srpaulowith the given index.
10461280405SrpauloOtherwise, it returns the name of the upvalue.
10462280405Srpaulo
10463280405Srpaulo
10464280405Srpaulo
10465280405Srpaulo
10466280405Srpaulo<p>
10467280405Srpaulo<hr><h3><a name="pdf-debug.setuservalue"><code>debug.setuservalue (udata, value)</code></a></h3>
10468280405Srpaulo
10469280405Srpaulo
10470280405Srpaulo<p>
10471280405SrpauloSets the given <code>value</code> as
10472280405Srpaulothe Lua value associated to the given <code>udata</code>.
10473280405Srpaulo<code>udata</code> must be a full userdata.
10474280405Srpaulo
10475280405Srpaulo
10476280405Srpaulo<p>
10477280405SrpauloReturns <code>udata</code>.
10478280405Srpaulo
10479280405Srpaulo
10480280405Srpaulo
10481280405Srpaulo
10482280405Srpaulo<p>
10483280405Srpaulo<hr><h3><a name="pdf-debug.traceback"><code>debug.traceback ([thread,] [message [, level]])</code></a></h3>
10484280405Srpaulo
10485280405Srpaulo
10486280405Srpaulo<p>
10487280405SrpauloIf <code>message</code> is present but is neither a string nor <b>nil</b>,
10488280405Srpaulothis function returns <code>message</code> without further processing.
10489280405SrpauloOtherwise,
10490280405Srpauloit returns a string with a traceback of the call stack.
10491280405SrpauloThe optional <code>message</code> string is appended
10492280405Srpauloat the beginning of the traceback.
10493280405SrpauloAn optional <code>level</code> number tells at which level
10494280405Srpauloto start the traceback
10495280405Srpaulo(default is 1, the function calling <code>traceback</code>).
10496280405Srpaulo
10497280405Srpaulo
10498280405Srpaulo
10499280405Srpaulo
10500280405Srpaulo<p>
10501280405Srpaulo<hr><h3><a name="pdf-debug.upvalueid"><code>debug.upvalueid (f, n)</code></a></h3>
10502280405Srpaulo
10503280405Srpaulo
10504280405Srpaulo<p>
10505280405SrpauloReturns a unique identifier (as a light userdata)
10506280405Srpaulofor the upvalue numbered <code>n</code>
10507280405Srpaulofrom the given function.
10508280405Srpaulo
10509280405Srpaulo
10510280405Srpaulo<p>
10511280405SrpauloThese unique identifiers allow a program to check whether different
10512280405Srpauloclosures share upvalues.
10513280405SrpauloLua closures that share an upvalue
10514280405Srpaulo(that is, that access a same external local variable)
10515280405Srpaulowill return identical ids for those upvalue indices.
10516280405Srpaulo
10517280405Srpaulo
10518280405Srpaulo
10519280405Srpaulo
10520280405Srpaulo<p>
10521280405Srpaulo<hr><h3><a name="pdf-debug.upvaluejoin"><code>debug.upvaluejoin (f1, n1, f2, n2)</code></a></h3>
10522280405Srpaulo
10523280405Srpaulo
10524280405Srpaulo<p>
10525280405SrpauloMake the <code>n1</code>-th upvalue of the Lua closure <code>f1</code>
10526280405Srpaulorefer to the <code>n2</code>-th upvalue of the Lua closure <code>f2</code>.
10527280405Srpaulo
10528280405Srpaulo
10529280405Srpaulo
10530280405Srpaulo
10531280405Srpaulo
10532280405Srpaulo
10533280405Srpaulo
10534280405Srpaulo<h1>7 &ndash; <a name="7">Lua Standalone</a></h1>
10535280405Srpaulo
10536280405Srpaulo<p>
10537280405SrpauloAlthough Lua has been designed as an extension language,
10538280405Srpauloto be embedded in a host C&nbsp;program,
10539280405Srpauloit is also frequently used as a standalone language.
10540280405SrpauloAn interpreter for Lua as a standalone language,
10541280405Srpaulocalled simply <code>lua</code>,
10542280405Srpaulois provided with the standard distribution.
10543280405SrpauloThe standalone interpreter includes
10544280405Srpauloall standard libraries, including the debug library.
10545280405SrpauloIts usage is:
10546280405Srpaulo
10547280405Srpaulo<pre>
10548280405Srpaulo     lua [options] [script [args]]
10549280405Srpaulo</pre><p>
10550280405SrpauloThe options are:
10551280405Srpaulo
10552280405Srpaulo<ul>
10553280405Srpaulo<li><b><code>-e <em>stat</em></code>: </b> executes string <em>stat</em>;</li>
10554280405Srpaulo<li><b><code>-l <em>mod</em></code>: </b> "requires" <em>mod</em>;</li>
10555280405Srpaulo<li><b><code>-i</code>: </b> enters interactive mode after running <em>script</em>;</li>
10556280405Srpaulo<li><b><code>-v</code>: </b> prints version information;</li>
10557280405Srpaulo<li><b><code>-E</code>: </b> ignores environment variables;</li>
10558280405Srpaulo<li><b><code>--</code>: </b> stops handling options;</li>
10559280405Srpaulo<li><b><code>-</code>: </b> executes <code>stdin</code> as a file and stops handling options.</li>
10560280405Srpaulo</ul><p>
10561280405SrpauloAfter handling its options, <code>lua</code> runs the given <em>script</em>.
10562280405SrpauloWhen called without arguments,
10563280405Srpaulo<code>lua</code> behaves as <code>lua -v -i</code>
10564280405Srpaulowhen the standard input (<code>stdin</code>) is a terminal,
10565280405Srpauloand as <code>lua -</code> otherwise.
10566280405Srpaulo
10567280405Srpaulo
10568280405Srpaulo<p>
10569326344SimpWhen called without option <code>-E</code>,
10570280405Srpaulothe interpreter checks for an environment variable <a name="pdf-LUA_INIT_5_3"><code>LUA_INIT_5_3</code></a>
10571280405Srpaulo(or <a name="pdf-LUA_INIT"><code>LUA_INIT</code></a> if the versioned name is not defined)
10572280405Srpaulobefore running any argument.
10573280405SrpauloIf the variable content has the format <code>@<em>filename</em></code>,
10574280405Srpaulothen <code>lua</code> executes the file.
10575280405SrpauloOtherwise, <code>lua</code> executes the string itself.
10576280405Srpaulo
10577280405Srpaulo
10578280405Srpaulo<p>
10579280405SrpauloWhen called with option <code>-E</code>,
10580280405Srpaulobesides ignoring <code>LUA_INIT</code>,
10581280405SrpauloLua also ignores
10582280405Srpaulothe values of <code>LUA_PATH</code> and <code>LUA_CPATH</code>,
10583280405Srpaulosetting the values of
10584280405Srpaulo<a href="#pdf-package.path"><code>package.path</code></a> and <a href="#pdf-package.cpath"><code>package.cpath</code></a>
10585280405Srpaulowith the default paths defined in <code>luaconf.h</code>.
10586280405Srpaulo
10587280405Srpaulo
10588280405Srpaulo<p>
10589280405SrpauloAll options are handled in order, except <code>-i</code> and <code>-E</code>.
10590280405SrpauloFor instance, an invocation like
10591280405Srpaulo
10592280405Srpaulo<pre>
10593280405Srpaulo     $ lua -e'a=1' -e 'print(a)' script.lua
10594280405Srpaulo</pre><p>
10595280405Srpaulowill first set <code>a</code> to 1, then print the value of <code>a</code>,
10596280405Srpauloand finally run the file <code>script.lua</code> with no arguments.
10597280405Srpaulo(Here <code>$</code> is the shell prompt. Your prompt may be different.)
10598280405Srpaulo
10599280405Srpaulo
10600280405Srpaulo<p>
10601280405SrpauloBefore running any code,
10602280405Srpaulo<code>lua</code> collects all command-line arguments
10603280405Srpauloin a global table called <code>arg</code>.
10604280405SrpauloThe script name goes to index 0,
10605280405Srpaulothe first argument after the script name goes to index 1,
10606280405Srpauloand so on.
10607280405SrpauloAny arguments before the script name
10608280405Srpaulo(that is, the interpreter name plus its options)
10609280405Srpaulogo to negative indices.
10610280405SrpauloFor instance, in the call
10611280405Srpaulo
10612280405Srpaulo<pre>
10613280405Srpaulo     $ lua -la b.lua t1 t2
10614280405Srpaulo</pre><p>
10615280405Srpaulothe table is like this:
10616280405Srpaulo
10617280405Srpaulo<pre>
10618280405Srpaulo     arg = { [-2] = "lua", [-1] = "-la",
10619280405Srpaulo             [0] = "b.lua",
10620280405Srpaulo             [1] = "t1", [2] = "t2" }
10621280405Srpaulo</pre><p>
10622280405SrpauloIf there is no script in the call,
10623280405Srpaulothe interpreter name goes to index 0,
10624280405Srpaulofollowed by the other arguments.
10625280405SrpauloFor instance, the call
10626280405Srpaulo
10627280405Srpaulo<pre>
10628280405Srpaulo     $ lua -e "print(arg[1])"
10629280405Srpaulo</pre><p>
10630280405Srpaulowill print "<code>-e</code>".
10631280405SrpauloIf there is a script,
10632280405Srpaulothe script is called with parameters
10633280405Srpaulo<code>arg[1]</code>, &middot;&middot;&middot;, <code>arg[#arg]</code>.
10634280405Srpaulo(Like all chunks in Lua,
10635280405Srpaulothe script is compiled as a vararg function.)
10636280405Srpaulo
10637280405Srpaulo
10638280405Srpaulo<p>
10639280405SrpauloIn interactive mode,
10640280405SrpauloLua repeatedly prompts and waits for a line.
10641280405SrpauloAfter reading a line,
10642280405SrpauloLua first try to interpret the line as an expression.
10643280405SrpauloIf it succeeds, it prints its value.
10644280405SrpauloOtherwise, it interprets the line as a statement.
10645280405SrpauloIf you write an incomplete statement,
10646280405Srpaulothe interpreter waits for its completion
10647280405Srpauloby issuing a different prompt.
10648280405Srpaulo
10649280405Srpaulo
10650280405Srpaulo<p>
10651326344SimpIf the global variable <a name="pdf-_PROMPT"><code>_PROMPT</code></a> contains a string,
10652326344Simpthen its value is used as the prompt.
10653326344SimpSimilarly, if the global variable <a name="pdf-_PROMPT2"><code>_PROMPT2</code></a> contains a string,
10654326344Simpits value is used as the secondary prompt
10655326344Simp(issued during incomplete statements).
10656326344Simp
10657326344Simp
10658326344Simp<p>
10659280405SrpauloIn case of unprotected errors in the script,
10660280405Srpaulothe interpreter reports the error to the standard error stream.
10661326344SimpIf the error object is not a string but
10662280405Srpaulohas a metamethod <code>__tostring</code>,
10663280405Srpaulothe interpreter calls this metamethod to produce the final message.
10664280405SrpauloOtherwise, the interpreter converts the error object to a string
10665280405Srpauloand adds a stack traceback to it.
10666280405Srpaulo
10667280405Srpaulo
10668280405Srpaulo<p>
10669280405SrpauloWhen finishing normally,
10670280405Srpaulothe interpreter closes its main Lua state
10671280405Srpaulo(see <a href="#lua_close"><code>lua_close</code></a>).
10672280405SrpauloThe script can avoid this step by
10673280405Srpaulocalling <a href="#pdf-os.exit"><code>os.exit</code></a> to terminate.
10674280405Srpaulo
10675280405Srpaulo
10676280405Srpaulo<p>
10677280405SrpauloTo allow the use of Lua as a
10678280405Srpauloscript interpreter in Unix systems,
10679280405Srpaulothe standalone interpreter skips
10680280405Srpaulothe first line of a chunk if it starts with <code>#</code>.
10681280405SrpauloTherefore, Lua scripts can be made into executable programs
10682280405Srpauloby using <code>chmod +x</code> and the&nbsp;<code>#!</code> form,
10683280405Srpauloas in
10684280405Srpaulo
10685280405Srpaulo<pre>
10686280405Srpaulo     #!/usr/local/bin/lua
10687280405Srpaulo</pre><p>
10688280405Srpaulo(Of course,
10689280405Srpaulothe location of the Lua interpreter may be different in your machine.
10690280405SrpauloIf <code>lua</code> is in your <code>PATH</code>,
10691280405Srpaulothen
10692280405Srpaulo
10693280405Srpaulo<pre>
10694280405Srpaulo     #!/usr/bin/env lua
10695280405Srpaulo</pre><p>
10696280405Srpaulois a more portable solution.)
10697280405Srpaulo
10698280405Srpaulo
10699280405Srpaulo
10700280405Srpaulo<h1>8 &ndash; <a name="8">Incompatibilities with the Previous Version</a></h1>
10701280405Srpaulo
10702280405Srpaulo<p>
10703280405SrpauloHere we list the incompatibilities that you may find when moving a program
10704280405Srpaulofrom Lua&nbsp;5.2 to Lua&nbsp;5.3.
10705280405SrpauloYou can avoid some incompatibilities by compiling Lua with
10706280405Srpauloappropriate options (see file <code>luaconf.h</code>).
10707280405SrpauloHowever,
10708280405Srpauloall these compatibility options will be removed in the future.
10709280405Srpaulo
10710280405Srpaulo
10711280405Srpaulo<p>
10712280405SrpauloLua versions can always change the C API in ways that
10713280405Srpaulodo not imply source-code changes in a program,
10714280405Srpaulosuch as the numeric values for constants
10715280405Srpauloor the implementation of functions as macros.
10716280405SrpauloTherefore,
10717280405Srpauloyou should not assume that binaries are compatible between
10718280405Srpaulodifferent Lua versions.
10719280405SrpauloAlways recompile clients of the Lua API when
10720280405Srpaulousing a new version.
10721280405Srpaulo
10722280405Srpaulo
10723280405Srpaulo<p>
10724280405SrpauloSimilarly, Lua versions can always change the internal representation
10725280405Srpauloof precompiled chunks;
10726280405Srpauloprecompiled chunks are not compatible between different Lua versions.
10727280405Srpaulo
10728280405Srpaulo
10729280405Srpaulo<p>
10730280405SrpauloThe standard paths in the official distribution may
10731280405Srpaulochange between versions.
10732280405Srpaulo
10733280405Srpaulo
10734280405Srpaulo
10735280405Srpaulo<h2>8.1 &ndash; <a name="8.1">Changes in the Language</a></h2>
10736280405Srpaulo<ul>
10737280405Srpaulo
10738280405Srpaulo<li>
10739280405SrpauloThe main difference between Lua&nbsp;5.2 and Lua&nbsp;5.3 is the
10740280405Srpaulointroduction of an integer subtype for numbers.
10741280405SrpauloAlthough this change should not affect "normal" computations,
10742280405Srpaulosome computations
10743280405Srpaulo(mainly those that involve some kind of overflow)
10744280405Srpaulocan give different results.
10745280405Srpaulo
10746280405Srpaulo
10747280405Srpaulo<p>
10748280405SrpauloYou can fix these differences by forcing a number to be a float
10749280405Srpaulo(in Lua&nbsp;5.2 all numbers were float),
10750280405Srpauloin particular writing constants with an ending <code>.0</code>
10751280405Srpauloor using <code>x = x + 0.0</code> to convert a variable.
10752280405Srpaulo(This recommendation is only for a quick fix
10753280405Srpaulofor an occasional incompatibility;
10754280405Srpauloit is not a general guideline for good programming.
10755280405SrpauloFor good programming,
10756280405Srpaulouse floats where you need floats
10757280405Srpauloand integers where you need integers.)
10758280405Srpaulo</li>
10759280405Srpaulo
10760280405Srpaulo<li>
10761280405SrpauloThe conversion of a float to a string now adds a <code>.0</code> suffix
10762280405Srpauloto the result if it looks like an integer.
10763280405Srpaulo(For instance, the float 2.0 will be printed as <code>2.0</code>,
10764280405Srpaulonot as <code>2</code>.)
10765280405SrpauloYou should always use an explicit format
10766280405Srpaulowhen you need a specific format for numbers.
10767280405Srpaulo
10768280405Srpaulo
10769280405Srpaulo<p>
10770280405Srpaulo(Formally this is not an incompatibility,
10771280405Srpaulobecause Lua does not specify how numbers are formatted as strings,
10772280405Srpaulobut some programs assumed a specific format.)
10773280405Srpaulo</li>
10774280405Srpaulo
10775280405Srpaulo<li>
10776280405SrpauloThe generational mode for the garbage collector was removed.
10777280405Srpaulo(It was an experimental feature in Lua&nbsp;5.2.)
10778280405Srpaulo</li>
10779280405Srpaulo
10780280405Srpaulo</ul>
10781280405Srpaulo
10782280405Srpaulo
10783280405Srpaulo
10784280405Srpaulo
10785280405Srpaulo<h2>8.2 &ndash; <a name="8.2">Changes in the Libraries</a></h2>
10786280405Srpaulo<ul>
10787280405Srpaulo
10788280405Srpaulo<li>
10789280405SrpauloThe <code>bit32</code> library has been deprecated.
10790280405SrpauloIt is easy to require a compatible external library or,
10791280405Srpaulobetter yet, to replace its functions with appropriate bitwise operations.
10792280405Srpaulo(Keep in mind that <code>bit32</code> operates on 32-bit integers,
10793326344Simpwhile the bitwise operators in Lua&nbsp;5.3 operate on Lua integers,
10794326344Simpwhich by default have 64&nbsp;bits.)
10795280405Srpaulo</li>
10796280405Srpaulo
10797280405Srpaulo<li>
10798280405SrpauloThe Table library now respects metamethods
10799280405Srpaulofor setting and getting elements.
10800280405Srpaulo</li>
10801280405Srpaulo
10802280405Srpaulo<li>
10803280405SrpauloThe <a href="#pdf-ipairs"><code>ipairs</code></a> iterator now respects metamethods and
10804280405Srpauloits <code>__ipairs</code> metamethod has been deprecated.
10805280405Srpaulo</li>
10806280405Srpaulo
10807280405Srpaulo<li>
10808280405SrpauloOption names in <a href="#pdf-io.read"><code>io.read</code></a> do not have a starting '<code>*</code>' anymore.
10809326344SimpFor compatibility, Lua will continue to accept (and ignore) this character.
10810280405Srpaulo</li>
10811280405Srpaulo
10812280405Srpaulo<li>
10813280405SrpauloThe following functions were deprecated in the mathematical library:
10814280405Srpaulo<code>atan2</code>, <code>cosh</code>, <code>sinh</code>, <code>tanh</code>, <code>pow</code>,
10815280405Srpaulo<code>frexp</code>, and <code>ldexp</code>.
10816280405SrpauloYou can replace <code>math.pow(x,y)</code> with <code>x^y</code>;
10817280405Srpauloyou can replace <code>math.atan2</code> with <code>math.atan</code>,
10818280405Srpaulowhich now accepts one or two parameters;
10819280405Srpauloyou can replace <code>math.ldexp(x,exp)</code> with <code>x * 2.0^exp</code>.
10820280405SrpauloFor the other operations,
10821280405Srpauloyou can either use an external library or
10822280405Srpauloimplement them in Lua.
10823280405Srpaulo</li>
10824280405Srpaulo
10825280405Srpaulo<li>
10826280405SrpauloThe searcher for C loaders used by <a href="#pdf-require"><code>require</code></a>
10827280405Srpaulochanged the way it handles versioned names.
10828280405SrpauloNow, the version should come after the module name
10829280405Srpaulo(as is usual in most other tools).
10830280405SrpauloFor compatibility, that searcher still tries the old format
10831280405Srpauloif it cannot find an open function according to the new style.
10832280405Srpaulo(Lua&nbsp;5.2 already worked that way,
10833280405Srpaulobut it did not document the change.)
10834280405Srpaulo</li>
10835280405Srpaulo
10836326344Simp<li>
10837326344SimpThe call <code>collectgarbage("count")</code> now returns only one result.
10838326344Simp(You can compute that second result from the fractional part
10839326344Simpof the first result.)
10840326344Simp</li>
10841326344Simp
10842280405Srpaulo</ul>
10843280405Srpaulo
10844280405Srpaulo
10845280405Srpaulo
10846280405Srpaulo
10847280405Srpaulo<h2>8.3 &ndash; <a name="8.3">Changes in the API</a></h2>
10848280405Srpaulo
10849280405Srpaulo
10850280405Srpaulo<ul>
10851280405Srpaulo
10852280405Srpaulo<li>
10853280405SrpauloContinuation functions now receive as parameters what they needed
10854280405Srpauloto get through <code>lua_getctx</code>,
10855280405Srpauloso <code>lua_getctx</code> has been removed.
10856280405SrpauloAdapt your code accordingly.
10857280405Srpaulo</li>
10858280405Srpaulo
10859280405Srpaulo<li>
10860280405SrpauloFunction <a href="#lua_dump"><code>lua_dump</code></a> has an extra parameter, <code>strip</code>.
10861280405SrpauloUse 0 as the value of this parameter to get the old behavior.
10862280405Srpaulo</li>
10863280405Srpaulo
10864280405Srpaulo<li>
10865280405SrpauloFunctions to inject/project unsigned integers
10866280405Srpaulo(<code>lua_pushunsigned</code>, <code>lua_tounsigned</code>, <code>lua_tounsignedx</code>,
10867280405Srpaulo<code>luaL_checkunsigned</code>, <code>luaL_optunsigned</code>)
10868280405Srpaulowere deprecated.
10869280405SrpauloUse their signed equivalents with a type cast.
10870280405Srpaulo</li>
10871280405Srpaulo
10872280405Srpaulo<li>
10873280405SrpauloMacros to project non-default integer types
10874280405Srpaulo(<code>luaL_checkint</code>, <code>luaL_optint</code>, <code>luaL_checklong</code>, <code>luaL_optlong</code>)
10875280405Srpaulowere deprecated.
10876280405SrpauloUse their equivalent over <a href="#lua_Integer"><code>lua_Integer</code></a> with a type cast
10877280405Srpaulo(or, when possible, use <a href="#lua_Integer"><code>lua_Integer</code></a> in your code).
10878280405Srpaulo</li>
10879280405Srpaulo
10880280405Srpaulo</ul>
10881280405Srpaulo
10882280405Srpaulo
10883280405Srpaulo
10884280405Srpaulo
10885280405Srpaulo<h1>9 &ndash; <a name="9">The Complete Syntax of Lua</a></h1>
10886280405Srpaulo
10887280405Srpaulo<p>
10888280405SrpauloHere is the complete syntax of Lua in extended BNF.
10889280405SrpauloAs usual in extended BNF,
10890280405Srpaulo{A} means 0 or more As,
10891280405Srpauloand [A] means an optional A.
10892280405Srpaulo(For operator precedences, see <a href="#3.4.8">&sect;3.4.8</a>;
10893280405Srpaulofor a description of the terminals
10894280405SrpauloName, Numeral,
10895280405Srpauloand LiteralString, see <a href="#3.1">&sect;3.1</a>.)
10896280405Srpaulo
10897280405Srpaulo
10898280405Srpaulo
10899280405Srpaulo
10900280405Srpaulo<pre>
10901280405Srpaulo
10902280405Srpaulo	chunk ::= block
10903280405Srpaulo
10904280405Srpaulo	block ::= {stat} [retstat]
10905280405Srpaulo
10906280405Srpaulo	stat ::=  &lsquo;<b>;</b>&rsquo; | 
10907280405Srpaulo		 varlist &lsquo;<b>=</b>&rsquo; explist | 
10908280405Srpaulo		 functioncall | 
10909280405Srpaulo		 label | 
10910280405Srpaulo		 <b>break</b> | 
10911280405Srpaulo		 <b>goto</b> Name | 
10912280405Srpaulo		 <b>do</b> block <b>end</b> | 
10913280405Srpaulo		 <b>while</b> exp <b>do</b> block <b>end</b> | 
10914280405Srpaulo		 <b>repeat</b> block <b>until</b> exp | 
10915280405Srpaulo		 <b>if</b> exp <b>then</b> block {<b>elseif</b> exp <b>then</b> block} [<b>else</b> block] <b>end</b> | 
10916280405Srpaulo		 <b>for</b> Name &lsquo;<b>=</b>&rsquo; exp &lsquo;<b>,</b>&rsquo; exp [&lsquo;<b>,</b>&rsquo; exp] <b>do</b> block <b>end</b> | 
10917280405Srpaulo		 <b>for</b> namelist <b>in</b> explist <b>do</b> block <b>end</b> | 
10918280405Srpaulo		 <b>function</b> funcname funcbody | 
10919280405Srpaulo		 <b>local</b> <b>function</b> Name funcbody | 
10920280405Srpaulo		 <b>local</b> namelist [&lsquo;<b>=</b>&rsquo; explist] 
10921280405Srpaulo
10922280405Srpaulo	retstat ::= <b>return</b> [explist] [&lsquo;<b>;</b>&rsquo;]
10923280405Srpaulo
10924280405Srpaulo	label ::= &lsquo;<b>::</b>&rsquo; Name &lsquo;<b>::</b>&rsquo;
10925280405Srpaulo
10926280405Srpaulo	funcname ::= Name {&lsquo;<b>.</b>&rsquo; Name} [&lsquo;<b>:</b>&rsquo; Name]
10927280405Srpaulo
10928280405Srpaulo	varlist ::= var {&lsquo;<b>,</b>&rsquo; var}
10929280405Srpaulo
10930280405Srpaulo	var ::=  Name | prefixexp &lsquo;<b>[</b>&rsquo; exp &lsquo;<b>]</b>&rsquo; | prefixexp &lsquo;<b>.</b>&rsquo; Name 
10931280405Srpaulo
10932280405Srpaulo	namelist ::= Name {&lsquo;<b>,</b>&rsquo; Name}
10933280405Srpaulo
10934280405Srpaulo	explist ::= exp {&lsquo;<b>,</b>&rsquo; exp}
10935280405Srpaulo
10936280405Srpaulo	exp ::=  <b>nil</b> | <b>false</b> | <b>true</b> | Numeral | LiteralString | &lsquo;<b>...</b>&rsquo; | functiondef | 
10937280405Srpaulo		 prefixexp | tableconstructor | exp binop exp | unop exp 
10938280405Srpaulo
10939280405Srpaulo	prefixexp ::= var | functioncall | &lsquo;<b>(</b>&rsquo; exp &lsquo;<b>)</b>&rsquo;
10940280405Srpaulo
10941280405Srpaulo	functioncall ::=  prefixexp args | prefixexp &lsquo;<b>:</b>&rsquo; Name args 
10942280405Srpaulo
10943280405Srpaulo	args ::=  &lsquo;<b>(</b>&rsquo; [explist] &lsquo;<b>)</b>&rsquo; | tableconstructor | LiteralString 
10944280405Srpaulo
10945280405Srpaulo	functiondef ::= <b>function</b> funcbody
10946280405Srpaulo
10947280405Srpaulo	funcbody ::= &lsquo;<b>(</b>&rsquo; [parlist] &lsquo;<b>)</b>&rsquo; block <b>end</b>
10948280405Srpaulo
10949280405Srpaulo	parlist ::= namelist [&lsquo;<b>,</b>&rsquo; &lsquo;<b>...</b>&rsquo;] | &lsquo;<b>...</b>&rsquo;
10950280405Srpaulo
10951280405Srpaulo	tableconstructor ::= &lsquo;<b>{</b>&rsquo; [fieldlist] &lsquo;<b>}</b>&rsquo;
10952280405Srpaulo
10953280405Srpaulo	fieldlist ::= field {fieldsep field} [fieldsep]
10954280405Srpaulo
10955280405Srpaulo	field ::= &lsquo;<b>[</b>&rsquo; exp &lsquo;<b>]</b>&rsquo; &lsquo;<b>=</b>&rsquo; exp | Name &lsquo;<b>=</b>&rsquo; exp | exp
10956280405Srpaulo
10957280405Srpaulo	fieldsep ::= &lsquo;<b>,</b>&rsquo; | &lsquo;<b>;</b>&rsquo;
10958280405Srpaulo
10959280405Srpaulo	binop ::=  &lsquo;<b>+</b>&rsquo; | &lsquo;<b>-</b>&rsquo; | &lsquo;<b>*</b>&rsquo; | &lsquo;<b>/</b>&rsquo; | &lsquo;<b>//</b>&rsquo; | &lsquo;<b>^</b>&rsquo; | &lsquo;<b>%</b>&rsquo; | 
10960280405Srpaulo		 &lsquo;<b>&amp;</b>&rsquo; | &lsquo;<b>~</b>&rsquo; | &lsquo;<b>|</b>&rsquo; | &lsquo;<b>&gt;&gt;</b>&rsquo; | &lsquo;<b>&lt;&lt;</b>&rsquo; | &lsquo;<b>..</b>&rsquo; | 
10961280405Srpaulo		 &lsquo;<b>&lt;</b>&rsquo; | &lsquo;<b>&lt;=</b>&rsquo; | &lsquo;<b>&gt;</b>&rsquo; | &lsquo;<b>&gt;=</b>&rsquo; | &lsquo;<b>==</b>&rsquo; | &lsquo;<b>~=</b>&rsquo; | 
10962280405Srpaulo		 <b>and</b> | <b>or</b>
10963280405Srpaulo
10964280405Srpaulo	unop ::= &lsquo;<b>-</b>&rsquo; | <b>not</b> | &lsquo;<b>#</b>&rsquo; | &lsquo;<b>~</b>&rsquo;
10965280405Srpaulo
10966280405Srpaulo</pre>
10967280405Srpaulo
10968280405Srpaulo<p>
10969280405Srpaulo
10970280405Srpaulo
10971280405Srpaulo
10972280405Srpaulo
10973280405Srpaulo
10974280405Srpaulo
10975280405Srpaulo
10976326344Simp<P CLASS="footer">
10977280405SrpauloLast update:
10978326344SimpMon Jan  9 13:30:53 BRST 2017
10979326344Simp</P>
10980280405Srpaulo<!--
10981326344SimpLast change: revised for Lua 5.3.4
10982280405Srpaulo-->
10983280405Srpaulo
10984280405Srpaulo</body></html>
10985280405Srpaulo
10986