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>
22344220SkevansCopyright &copy; 2015&ndash;2018 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
38344220Skevans<!-- $Id: manual.of,v 1.167.1.2 2018/06/26 15:49:07 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,
206344220Skevansthat is, arrays that can have as indices not only numbers,
207344220Skevansbut 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.
403344220SkevansUnless stated otherwise,
404344220Skevansmetamethods should be function values.
405280405Srpaulo
406280405Srpaulo
407280405Srpaulo<p>
408280405SrpauloYou can query the metatable of any value
409280405Srpaulousing the <a href="#pdf-getmetatable"><code>getmetatable</code></a> function.
410326344SimpLua queries metamethods in metatables using a raw access (see <a href="#pdf-rawget"><code>rawget</code></a>).
411326344SimpSo, to retrieve the metamethod for event <code>ev</code> in object <code>o</code>,
412326344SimpLua does the equivalent to the following code:
413280405Srpaulo
414326344Simp<pre>
415326344Simp     rawget(getmetatable(<em>o</em>) or {}, "__<em>ev</em>")
416326344Simp</pre>
417280405Srpaulo
418280405Srpaulo<p>
419280405SrpauloYou can replace the metatable of tables
420280405Srpaulousing the <a href="#pdf-setmetatable"><code>setmetatable</code></a> function.
421326344SimpYou cannot change the metatable of other types from Lua code
422280405Srpaulo(except by using the debug library (<a href="#6.10">&sect;6.10</a>));
423326344Simpyou should use the C&nbsp;API for that.
424280405Srpaulo
425280405Srpaulo
426280405Srpaulo<p>
427280405SrpauloTables and full userdata have individual metatables
428280405Srpaulo(although multiple tables and userdata can share their metatables).
429280405SrpauloValues of all other types share one single metatable per type;
430280405Srpaulothat is, there is one single metatable for all numbers,
431280405Srpauloone for all strings, etc.
432280405SrpauloBy default, a value has no metatable,
433280405Srpaulobut the string library sets a metatable for the string type (see <a href="#6.4">&sect;6.4</a>).
434280405Srpaulo
435280405Srpaulo
436280405Srpaulo<p>
437280405SrpauloA metatable controls how an object behaves in
438280405Srpauloarithmetic operations, bitwise operations,
439280405Srpauloorder comparisons, concatenation, length operation, calls, and indexing.
440280405SrpauloA metatable also can define a function to be called
441280405Srpaulowhen a userdata or a table is garbage collected (<a href="#2.5">&sect;2.5</a>).
442280405Srpaulo
443280405Srpaulo
444280405Srpaulo<p>
445326344SimpFor the unary operators (negation, length, and bitwise NOT),
446280405Srpaulothe metamethod is computed and called with a dummy second operand,
447280405Srpauloequal to the first one.
448280405SrpauloThis extra operand is only to simplify Lua's internals
449280405Srpaulo(by making these operators behave like a binary operation)
450280405Srpauloand may be removed in future versions.
451280405Srpaulo(For most uses this extra operand is irrelevant.)
452280405Srpaulo
453280405Srpaulo
454326344Simp<p>
455326344SimpA detailed list of events controlled by metatables is given next.
456326344SimpEach operation is identified by its corresponding key.
457280405Srpaulo
458326344Simp
459326344Simp
460280405Srpaulo<ul>
461280405Srpaulo
462326344Simp<li><b><code>__add</code>: </b>
463326344Simpthe addition (<code>+</code>) operation.
464280405SrpauloIf any operand for an addition is not a number
465280405Srpaulo(nor a string coercible to a number),
466280405SrpauloLua will try to call a metamethod.
467280405SrpauloFirst, Lua will check the first operand (even if it is valid).
468326344SimpIf that operand does not define a metamethod for <code>__add</code>,
469280405Srpaulothen Lua will check the second operand.
470280405SrpauloIf Lua can find a metamethod,
471280405Srpauloit calls the metamethod with the two operands as arguments,
472280405Srpauloand the result of the call
473280405Srpaulo(adjusted to one value)
474280405Srpaulois the result of the operation.
475280405SrpauloOtherwise,
476280405Srpauloit raises an error.
477280405Srpaulo</li>
478280405Srpaulo
479326344Simp<li><b><code>__sub</code>: </b>
480326344Simpthe subtraction (<code>-</code>) operation.
481326344SimpBehavior similar to the addition operation.
482280405Srpaulo</li>
483280405Srpaulo
484326344Simp<li><b><code>__mul</code>: </b>
485326344Simpthe multiplication (<code>*</code>) operation.
486326344SimpBehavior similar to the addition operation.
487280405Srpaulo</li>
488280405Srpaulo
489326344Simp<li><b><code>__div</code>: </b>
490326344Simpthe division (<code>/</code>) operation.
491326344SimpBehavior similar to the addition operation.
492280405Srpaulo</li>
493280405Srpaulo
494326344Simp<li><b><code>__mod</code>: </b>
495326344Simpthe modulo (<code>%</code>) operation.
496326344SimpBehavior similar to the addition operation.
497280405Srpaulo</li>
498280405Srpaulo
499326344Simp<li><b><code>__pow</code>: </b>
500326344Simpthe exponentiation (<code>^</code>) operation.
501326344SimpBehavior similar to the addition operation.
502280405Srpaulo</li>
503280405Srpaulo
504326344Simp<li><b><code>__unm</code>: </b>
505326344Simpthe negation (unary <code>-</code>) operation.
506326344SimpBehavior similar to the addition operation.
507280405Srpaulo</li>
508280405Srpaulo
509326344Simp<li><b><code>__idiv</code>: </b>
510326344Simpthe floor division (<code>//</code>) operation.
511326344SimpBehavior similar to the addition operation.
512280405Srpaulo</li>
513280405Srpaulo
514326344Simp<li><b><code>__band</code>: </b>
515326344Simpthe bitwise AND (<code>&amp;</code>) operation.
516326344SimpBehavior similar to the addition operation,
517280405Srpauloexcept that Lua will try a metamethod
518326344Simpif any operand is neither an integer
519280405Srpaulonor a value coercible to an integer (see <a href="#3.4.3">&sect;3.4.3</a>).
520280405Srpaulo</li>
521280405Srpaulo
522326344Simp<li><b><code>__bor</code>: </b>
523326344Simpthe bitwise OR (<code>|</code>) operation.
524326344SimpBehavior similar to the bitwise AND operation.
525280405Srpaulo</li>
526280405Srpaulo
527326344Simp<li><b><code>__bxor</code>: </b>
528326344Simpthe bitwise exclusive OR (binary <code>~</code>) operation.
529326344SimpBehavior similar to the bitwise AND operation.
530280405Srpaulo</li>
531280405Srpaulo
532326344Simp<li><b><code>__bnot</code>: </b>
533326344Simpthe bitwise NOT (unary <code>~</code>) operation.
534326344SimpBehavior similar to the bitwise AND operation.
535280405Srpaulo</li>
536280405Srpaulo
537326344Simp<li><b><code>__shl</code>: </b>
538326344Simpthe bitwise left shift (<code>&lt;&lt;</code>) operation.
539326344SimpBehavior similar to the bitwise AND operation.
540280405Srpaulo</li>
541280405Srpaulo
542326344Simp<li><b><code>__shr</code>: </b>
543326344Simpthe bitwise right shift (<code>&gt;&gt;</code>) operation.
544326344SimpBehavior similar to the bitwise AND operation.
545280405Srpaulo</li>
546280405Srpaulo
547326344Simp<li><b><code>__concat</code>: </b>
548326344Simpthe concatenation (<code>..</code>) operation.
549326344SimpBehavior similar to the addition operation,
550280405Srpauloexcept that Lua will try a metamethod
551326344Simpif any operand is neither a string nor a number
552280405Srpaulo(which is always coercible to a string).
553280405Srpaulo</li>
554280405Srpaulo
555326344Simp<li><b><code>__len</code>: </b>
556326344Simpthe length (<code>#</code>) operation.
557280405SrpauloIf the object is not a string,
558280405SrpauloLua will try its metamethod.
559280405SrpauloIf there is a metamethod,
560280405SrpauloLua calls it with the object as argument,
561280405Srpauloand the result of the call
562280405Srpaulo(always adjusted to one value)
563280405Srpaulois the result of the operation.
564280405SrpauloIf there is no metamethod but the object is a table,
565280405Srpaulothen Lua uses the table length operation (see <a href="#3.4.7">&sect;3.4.7</a>).
566280405SrpauloOtherwise, Lua raises an error.
567280405Srpaulo</li>
568280405Srpaulo
569326344Simp<li><b><code>__eq</code>: </b>
570326344Simpthe equal (<code>==</code>) operation.
571326344SimpBehavior similar to the addition operation,
572280405Srpauloexcept that Lua will try a metamethod only when the values
573280405Srpaulobeing compared are either both tables or both full userdata
574280405Srpauloand they are not primitively equal.
575280405SrpauloThe result of the call is always converted to a boolean.
576280405Srpaulo</li>
577280405Srpaulo
578326344Simp<li><b><code>__lt</code>: </b>
579326344Simpthe less than (<code>&lt;</code>) operation.
580326344SimpBehavior similar to the addition operation,
581280405Srpauloexcept that Lua will try a metamethod only when the values
582280405Srpaulobeing compared are neither both numbers nor both strings.
583280405SrpauloThe result of the call is always converted to a boolean.
584280405Srpaulo</li>
585280405Srpaulo
586326344Simp<li><b><code>__le</code>: </b>
587326344Simpthe less equal (<code>&lt;=</code>) operation.
588280405SrpauloUnlike other operations,
589326344Simpthe less-equal operation can use two different events.
590326344SimpFirst, Lua looks for the <code>__le</code> metamethod in both operands,
591326344Simplike in the less than operation.
592280405SrpauloIf it cannot find such a metamethod,
593326344Simpthen it will try the <code>__lt</code> metamethod,
594280405Srpauloassuming that <code>a &lt;= b</code> is equivalent to <code>not (b &lt; a)</code>.
595280405SrpauloAs with the other comparison operators,
596280405Srpaulothe result is always a boolean.
597326344Simp(This use of the <code>__lt</code> event can be removed in future versions;
598326344Simpit is also slower than a real <code>__le</code> metamethod.)
599280405Srpaulo</li>
600280405Srpaulo
601326344Simp<li><b><code>__index</code>: </b>
602344220SkevansThe indexing access operation <code>table[key]</code>.
603280405SrpauloThis event happens when <code>table</code> is not a table or
604280405Srpaulowhen <code>key</code> is not present in <code>table</code>.
605280405SrpauloThe metamethod is looked up in <code>table</code>.
606280405Srpaulo
607280405Srpaulo
608280405Srpaulo<p>
609280405SrpauloDespite the name,
610280405Srpaulothe metamethod for this event can be either a function or a table.
611280405SrpauloIf it is a function,
612326344Simpit is called with <code>table</code> and <code>key</code> as arguments,
613326344Simpand the result of the call
614326344Simp(adjusted to one value)
615326344Simpis the result of the operation.
616280405SrpauloIf it is a table,
617280405Srpaulothe final result is the result of indexing this table with <code>key</code>.
618280405Srpaulo(This indexing is regular, not raw,
619280405Srpauloand therefore can trigger another metamethod.)
620280405Srpaulo</li>
621280405Srpaulo
622326344Simp<li><b><code>__newindex</code>: </b>
623280405SrpauloThe indexing assignment <code>table[key] = value</code>.
624280405SrpauloLike the index event,
625280405Srpaulothis event happens when <code>table</code> is not a table or
626280405Srpaulowhen <code>key</code> is not present in <code>table</code>.
627280405SrpauloThe metamethod is looked up in <code>table</code>.
628280405Srpaulo
629280405Srpaulo
630280405Srpaulo<p>
631280405SrpauloLike with indexing,
632280405Srpaulothe metamethod for this event can be either a function or a table.
633280405SrpauloIf it is a function,
634280405Srpauloit is called with <code>table</code>, <code>key</code>, and <code>value</code> as arguments.
635280405SrpauloIf it is a table,
636280405SrpauloLua does an indexing assignment to this table with the same key and value.
637280405Srpaulo(This assignment is regular, not raw,
638280405Srpauloand therefore can trigger another metamethod.)
639280405Srpaulo
640280405Srpaulo
641280405Srpaulo<p>
642326344SimpWhenever there is a <code>__newindex</code> metamethod,
643280405SrpauloLua does not perform the primitive assignment.
644280405Srpaulo(If necessary,
645280405Srpaulothe metamethod itself can call <a href="#pdf-rawset"><code>rawset</code></a>
646280405Srpauloto do the assignment.)
647280405Srpaulo</li>
648280405Srpaulo
649326344Simp<li><b><code>__call</code>: </b>
650280405SrpauloThe call operation <code>func(args)</code>.
651280405SrpauloThis event happens when Lua tries to call a non-function value
652280405Srpaulo(that is, <code>func</code> is not a function).
653280405SrpauloThe metamethod is looked up in <code>func</code>.
654280405SrpauloIf present,
655280405Srpaulothe metamethod is called with <code>func</code> as its first argument,
656280405Srpaulofollowed by the arguments of the original call (<code>args</code>).
657326344SimpAll results of the call
658326344Simpare the result of the operation.
659326344Simp(This is the only metamethod that allows multiple results.)
660280405Srpaulo</li>
661280405Srpaulo
662280405Srpaulo</ul>
663280405Srpaulo
664326344Simp<p>
665326344SimpIt is a good practice to add all needed metamethods to a table
666326344Simpbefore setting it as a metatable of some object.
667326344SimpIn particular, the <code>__gc</code> metamethod works only when this order
668326344Simpis followed (see <a href="#2.5.1">&sect;2.5.1</a>).
669280405Srpaulo
670280405Srpaulo
671326344Simp<p>
672326344SimpBecause metatables are regular tables,
673326344Simpthey can contain arbitrary fields,
674326344Simpnot only the event names defined above.
675326344SimpSome functions in the standard library
676326344Simp(e.g., <a href="#pdf-tostring"><code>tostring</code></a>)
677326344Simpuse other fields in metatables for their own purposes.
678280405Srpaulo
679326344Simp
680326344Simp
681326344Simp
682326344Simp
683280405Srpaulo<h2>2.5 &ndash; <a name="2.5">Garbage Collection</a></h2>
684280405Srpaulo
685280405Srpaulo<p>
686280405SrpauloLua performs automatic memory management.
687280405SrpauloThis means that
688280405Srpauloyou do not have to worry about allocating memory for new objects
689280405Srpauloor freeing it when the objects are no longer needed.
690280405SrpauloLua manages memory automatically by running
691280405Srpauloa <em>garbage collector</em> to collect all <em>dead objects</em>
692280405Srpaulo(that is, objects that are no longer accessible from Lua).
693280405SrpauloAll memory used by Lua is subject to automatic management:
694280405Srpaulostrings, tables, userdata, functions, threads, internal structures, etc.
695280405Srpaulo
696280405Srpaulo
697280405Srpaulo<p>
698280405SrpauloLua implements an incremental mark-and-sweep collector.
699280405SrpauloIt uses two numbers to control its garbage-collection cycles:
700280405Srpaulothe <em>garbage-collector pause</em> and
701280405Srpaulothe <em>garbage-collector step multiplier</em>.
702280405SrpauloBoth use percentage points as units
703280405Srpaulo(e.g., a value of 100 means an internal value of 1).
704280405Srpaulo
705280405Srpaulo
706280405Srpaulo<p>
707280405SrpauloThe garbage-collector pause
708280405Srpaulocontrols how long the collector waits before starting a new cycle.
709280405SrpauloLarger values make the collector less aggressive.
710280405SrpauloValues smaller than 100 mean the collector will not wait to
711280405Srpaulostart a new cycle.
712280405SrpauloA value of 200 means that the collector waits for the total memory in use
713280405Srpauloto double before starting a new cycle.
714280405Srpaulo
715280405Srpaulo
716280405Srpaulo<p>
717280405SrpauloThe garbage-collector step multiplier
718280405Srpaulocontrols the relative speed of the collector relative to
719280405Srpaulomemory allocation.
720280405SrpauloLarger values make the collector more aggressive but also increase
721280405Srpaulothe size of each incremental step.
722280405SrpauloYou should not use values smaller than 100,
723280405Srpaulobecause they make the collector too slow and
724280405Srpaulocan result in the collector never finishing a cycle.
725280405SrpauloThe default is 200,
726280405Srpaulowhich means that the collector runs at "twice"
727280405Srpaulothe speed of memory allocation.
728280405Srpaulo
729280405Srpaulo
730280405Srpaulo<p>
731280405SrpauloIf you set the step multiplier to a very large number
732280405Srpaulo(larger than 10% of the maximum number of
733280405Srpaulobytes that the program may use),
734280405Srpaulothe collector behaves like a stop-the-world collector.
735280405SrpauloIf you then set the pause to 200,
736280405Srpaulothe collector behaves as in old Lua versions,
737280405Srpaulodoing a complete collection every time Lua doubles its
738280405Srpaulomemory usage.
739280405Srpaulo
740280405Srpaulo
741280405Srpaulo<p>
742280405SrpauloYou can change these numbers by calling <a href="#lua_gc"><code>lua_gc</code></a> in C
743280405Srpauloor <a href="#pdf-collectgarbage"><code>collectgarbage</code></a> in Lua.
744280405SrpauloYou can also use these functions to control
745280405Srpaulothe collector directly (e.g., stop and restart it).
746280405Srpaulo
747280405Srpaulo
748280405Srpaulo
749280405Srpaulo<h3>2.5.1 &ndash; <a name="2.5.1">Garbage-Collection Metamethods</a></h3>
750280405Srpaulo
751280405Srpaulo<p>
752280405SrpauloYou can set garbage-collector metamethods for tables
753280405Srpauloand, using the C&nbsp;API,
754280405Srpaulofor full userdata (see <a href="#2.4">&sect;2.4</a>).
755280405SrpauloThese metamethods are also called <em>finalizers</em>.
756280405SrpauloFinalizers allow you to coordinate Lua's garbage collection
757280405Srpaulowith external resource management
758280405Srpaulo(such as closing files, network or database connections,
759280405Srpauloor freeing your own memory).
760280405Srpaulo
761280405Srpaulo
762280405Srpaulo<p>
763280405SrpauloFor an object (table or userdata) to be finalized when collected,
764280405Srpauloyou must <em>mark</em> it for finalization.
765280405Srpaulo
766280405SrpauloYou mark an object for finalization when you set its metatable
767280405Srpauloand the metatable has a field indexed by the string "<code>__gc</code>".
768280405SrpauloNote that if you set a metatable without a <code>__gc</code> field
769280405Srpauloand later create that field in the metatable,
770280405Srpaulothe object will not be marked for finalization.
771280405Srpaulo
772280405Srpaulo
773280405Srpaulo<p>
774280405SrpauloWhen a marked object becomes garbage,
775280405Srpauloit is not collected immediately by the garbage collector.
776280405SrpauloInstead, Lua puts it in a list.
777280405SrpauloAfter the collection,
778280405SrpauloLua goes through that list.
779280405SrpauloFor each object in the list,
780280405Srpauloit checks the object's <code>__gc</code> metamethod:
781280405SrpauloIf it is a function,
782280405SrpauloLua calls it with the object as its single argument;
783280405Srpauloif the metamethod is not a function,
784280405SrpauloLua simply ignores it.
785280405Srpaulo
786280405Srpaulo
787280405Srpaulo<p>
788280405SrpauloAt the end of each garbage-collection cycle,
789280405Srpaulothe finalizers for objects are called in
790280405Srpaulothe reverse order that the objects were marked for finalization,
791280405Srpauloamong those collected in that cycle;
792280405Srpaulothat is, the first finalizer to be called is the one associated
793280405Srpaulowith the object marked last in the program.
794280405SrpauloThe execution of each finalizer may occur at any point during
795280405Srpaulothe execution of the regular code.
796280405Srpaulo
797280405Srpaulo
798280405Srpaulo<p>
799280405SrpauloBecause the object being collected must still be used by the finalizer,
800280405Srpaulothat object (and other objects accessible only through it)
801280405Srpaulomust be <em>resurrected</em> by Lua.
802280405SrpauloUsually, this resurrection is transient,
803280405Srpauloand the object memory is freed in the next garbage-collection cycle.
804280405SrpauloHowever, if the finalizer stores the object in some global place
805280405Srpaulo(e.g., a global variable),
806280405Srpaulothen the resurrection is permanent.
807280405SrpauloMoreover, if the finalizer marks a finalizing object for finalization again,
808280405Srpauloits finalizer will be called again in the next cycle where the
809280405Srpauloobject is unreachable.
810280405SrpauloIn any case,
811326344Simpthe object memory is freed only in a GC cycle where
812280405Srpaulothe object is unreachable and not marked for finalization.
813280405Srpaulo
814280405Srpaulo
815280405Srpaulo<p>
816280405SrpauloWhen you close a state (see <a href="#lua_close"><code>lua_close</code></a>),
817280405SrpauloLua calls the finalizers of all objects marked for finalization,
818280405Srpaulofollowing the reverse order that they were marked.
819280405SrpauloIf any finalizer marks objects for collection during that phase,
820280405Srpaulothese marks have no effect.
821280405Srpaulo
822280405Srpaulo
823280405Srpaulo
824280405Srpaulo
825280405Srpaulo
826280405Srpaulo<h3>2.5.2 &ndash; <a name="2.5.2">Weak Tables</a></h3>
827280405Srpaulo
828280405Srpaulo<p>
829280405SrpauloA <em>weak table</em> is a table whose elements are
830280405Srpaulo<em>weak references</em>.
831280405SrpauloA weak reference is ignored by the garbage collector.
832280405SrpauloIn other words,
833280405Srpauloif the only references to an object are weak references,
834280405Srpaulothen the garbage collector will collect that object.
835280405Srpaulo
836280405Srpaulo
837280405Srpaulo<p>
838280405SrpauloA weak table can have weak keys, weak values, or both.
839326344SimpA table with weak values allows the collection of its values,
840326344Simpbut prevents the collection of its keys.
841280405SrpauloA table with both weak keys and weak values allows the collection of
842280405Srpauloboth keys and values.
843280405SrpauloIn any case, if either the key or the value is collected,
844280405Srpaulothe whole pair is removed from the table.
845280405SrpauloThe weakness of a table is controlled by the
846280405Srpaulo<code>__mode</code> field of its metatable.
847280405SrpauloIf the <code>__mode</code> field is a string containing the character&nbsp;'<code>k</code>',
848280405Srpaulothe keys in the table are weak.
849280405SrpauloIf <code>__mode</code> contains '<code>v</code>',
850280405Srpaulothe values in the table are weak.
851280405Srpaulo
852280405Srpaulo
853280405Srpaulo<p>
854280405SrpauloA table with weak keys and strong values
855280405Srpaulois also called an <em>ephemeron table</em>.
856280405SrpauloIn an ephemeron table,
857280405Srpauloa value is considered reachable only if its key is reachable.
858280405SrpauloIn particular,
859280405Srpauloif the only reference to a key comes through its value,
860280405Srpaulothe pair is removed.
861280405Srpaulo
862280405Srpaulo
863280405Srpaulo<p>
864280405SrpauloAny change in the weakness of a table may take effect only
865280405Srpauloat the next collect cycle.
866280405SrpauloIn particular, if you change the weakness to a stronger mode,
867280405SrpauloLua may still collect some items from that table
868280405Srpaulobefore the change takes effect.
869280405Srpaulo
870280405Srpaulo
871280405Srpaulo<p>
872280405SrpauloOnly objects that have an explicit construction
873280405Srpauloare removed from weak tables.
874326344SimpValues, such as numbers and light C&nbsp;functions,
875280405Srpauloare not subject to garbage collection,
876280405Srpauloand therefore are not removed from weak tables
877280405Srpaulo(unless their associated values are collected).
878280405SrpauloAlthough strings are subject to garbage collection,
879280405Srpaulothey do not have an explicit construction,
880280405Srpauloand therefore are not removed from weak tables.
881280405Srpaulo
882280405Srpaulo
883280405Srpaulo<p>
884280405SrpauloResurrected objects
885280405Srpaulo(that is, objects being finalized
886280405Srpauloand objects accessible only through objects being finalized)
887280405Srpaulohave a special behavior in weak tables.
888280405SrpauloThey are removed from weak values before running their finalizers,
889280405Srpaulobut are removed from weak keys only in the next collection
890280405Srpauloafter running their finalizers, when such objects are actually freed.
891280405SrpauloThis behavior allows the finalizer to access properties
892280405Srpauloassociated with the object through weak tables.
893280405Srpaulo
894280405Srpaulo
895280405Srpaulo<p>
896280405SrpauloIf a weak table is among the resurrected objects in a collection cycle,
897280405Srpauloit may not be properly cleared until the next cycle.
898280405Srpaulo
899280405Srpaulo
900280405Srpaulo
901280405Srpaulo
902280405Srpaulo
903280405Srpaulo
904280405Srpaulo
905280405Srpaulo<h2>2.6 &ndash; <a name="2.6">Coroutines</a></h2>
906280405Srpaulo
907280405Srpaulo<p>
908280405SrpauloLua supports coroutines,
909280405Srpauloalso called <em>collaborative multithreading</em>.
910280405SrpauloA coroutine in Lua represents an independent thread of execution.
911280405SrpauloUnlike threads in multithread systems, however,
912280405Srpauloa coroutine only suspends its execution by explicitly calling
913280405Srpauloa yield function.
914280405Srpaulo
915280405Srpaulo
916280405Srpaulo<p>
917280405SrpauloYou create a coroutine by calling <a href="#pdf-coroutine.create"><code>coroutine.create</code></a>.
918280405SrpauloIts sole argument is a function
919280405Srpaulothat is the main function of the coroutine.
920280405SrpauloThe <code>create</code> function only creates a new coroutine and
921280405Srpauloreturns a handle to it (an object of type <em>thread</em>);
922280405Srpauloit does not start the coroutine.
923280405Srpaulo
924280405Srpaulo
925280405Srpaulo<p>
926280405SrpauloYou execute a coroutine by calling <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a>.
927280405SrpauloWhen you first call <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a>,
928280405Srpaulopassing as its first argument
929280405Srpauloa thread returned by <a href="#pdf-coroutine.create"><code>coroutine.create</code></a>,
930326344Simpthe coroutine starts its execution by
931326344Simpcalling its main function.
932280405SrpauloExtra arguments passed to <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a> are passed
933326344Simpas arguments to that function.
934280405SrpauloAfter the coroutine starts running,
935280405Srpauloit runs until it terminates or <em>yields</em>.
936280405Srpaulo
937280405Srpaulo
938280405Srpaulo<p>
939280405SrpauloA coroutine can terminate its execution in two ways:
940280405Srpaulonormally, when its main function returns
941280405Srpaulo(explicitly or implicitly, after the last instruction);
942280405Srpauloand abnormally, if there is an unprotected error.
943280405SrpauloIn case of normal termination,
944280405Srpaulo<a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a> returns <b>true</b>,
945280405Srpauloplus any values returned by the coroutine main function.
946280405SrpauloIn case of errors, <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a> returns <b>false</b>
947326344Simpplus an error object.
948280405Srpaulo
949280405Srpaulo
950280405Srpaulo<p>
951280405SrpauloA coroutine yields by calling <a href="#pdf-coroutine.yield"><code>coroutine.yield</code></a>.
952280405SrpauloWhen a coroutine yields,
953280405Srpaulothe corresponding <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a> returns immediately,
954280405Srpauloeven if the yield happens inside nested function calls
955280405Srpaulo(that is, not in the main function,
956280405Srpaulobut in a function directly or indirectly called by the main function).
957280405SrpauloIn the case of a yield, <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a> also returns <b>true</b>,
958280405Srpauloplus any values passed to <a href="#pdf-coroutine.yield"><code>coroutine.yield</code></a>.
959280405SrpauloThe next time you resume the same coroutine,
960280405Srpauloit continues its execution from the point where it yielded,
961280405Srpaulowith the call to <a href="#pdf-coroutine.yield"><code>coroutine.yield</code></a> returning any extra
962280405Srpauloarguments passed to <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a>.
963280405Srpaulo
964280405Srpaulo
965280405Srpaulo<p>
966280405SrpauloLike <a href="#pdf-coroutine.create"><code>coroutine.create</code></a>,
967280405Srpaulothe <a href="#pdf-coroutine.wrap"><code>coroutine.wrap</code></a> function also creates a coroutine,
968280405Srpaulobut instead of returning the coroutine itself,
969280405Srpauloit returns a function that, when called, resumes the coroutine.
970280405SrpauloAny arguments passed to this function
971280405Srpaulogo as extra arguments to <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a>.
972280405Srpaulo<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>,
973280405Srpauloexcept the first one (the boolean error code).
974280405SrpauloUnlike <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a>,
975280405Srpaulo<a href="#pdf-coroutine.wrap"><code>coroutine.wrap</code></a> does not catch errors;
976280405Srpauloany error is propagated to the caller.
977280405Srpaulo
978280405Srpaulo
979280405Srpaulo<p>
980280405SrpauloAs an example of how coroutines work,
981280405Srpauloconsider the following code:
982280405Srpaulo
983280405Srpaulo<pre>
984280405Srpaulo     function foo (a)
985280405Srpaulo       print("foo", a)
986280405Srpaulo       return coroutine.yield(2*a)
987280405Srpaulo     end
988280405Srpaulo     
989280405Srpaulo     co = coroutine.create(function (a,b)
990280405Srpaulo           print("co-body", a, b)
991280405Srpaulo           local r = foo(a+1)
992280405Srpaulo           print("co-body", r)
993280405Srpaulo           local r, s = coroutine.yield(a+b, a-b)
994280405Srpaulo           print("co-body", r, s)
995280405Srpaulo           return b, "end"
996280405Srpaulo     end)
997280405Srpaulo     
998280405Srpaulo     print("main", coroutine.resume(co, 1, 10))
999280405Srpaulo     print("main", coroutine.resume(co, "r"))
1000280405Srpaulo     print("main", coroutine.resume(co, "x", "y"))
1001280405Srpaulo     print("main", coroutine.resume(co, "x", "y"))
1002280405Srpaulo</pre><p>
1003280405SrpauloWhen you run it, it produces the following output:
1004280405Srpaulo
1005280405Srpaulo<pre>
1006280405Srpaulo     co-body 1       10
1007280405Srpaulo     foo     2
1008280405Srpaulo     main    true    4
1009280405Srpaulo     co-body r
1010280405Srpaulo     main    true    11      -9
1011280405Srpaulo     co-body x       y
1012280405Srpaulo     main    true    10      end
1013280405Srpaulo     main    false   cannot resume dead coroutine
1014280405Srpaulo</pre>
1015280405Srpaulo
1016280405Srpaulo<p>
1017280405SrpauloYou can also create and manipulate coroutines through the C API:
1018280405Srpaulosee functions <a href="#lua_newthread"><code>lua_newthread</code></a>, <a href="#lua_resume"><code>lua_resume</code></a>,
1019280405Srpauloand <a href="#lua_yield"><code>lua_yield</code></a>.
1020280405Srpaulo
1021280405Srpaulo
1022280405Srpaulo
1023280405Srpaulo
1024280405Srpaulo
1025280405Srpaulo<h1>3 &ndash; <a name="3">The Language</a></h1>
1026280405Srpaulo
1027280405Srpaulo<p>
1028280405SrpauloThis section describes the lexis, the syntax, and the semantics of Lua.
1029280405SrpauloIn other words,
1030280405Srpaulothis section describes
1031280405Srpaulowhich tokens are valid,
1032280405Srpaulohow they can be combined,
1033280405Srpauloand what their combinations mean.
1034280405Srpaulo
1035280405Srpaulo
1036280405Srpaulo<p>
1037280405SrpauloLanguage constructs will be explained using the usual extended BNF notation,
1038280405Srpauloin which
1039280405Srpaulo{<em>a</em>}&nbsp;means&nbsp;0 or more <em>a</em>'s, and
1040280405Srpaulo[<em>a</em>]&nbsp;means an optional <em>a</em>.
1041280405SrpauloNon-terminals are shown like non-terminal,
1042280405Srpaulokeywords are shown like <b>kword</b>,
1043280405Srpauloand other terminal symbols are shown like &lsquo;<b>=</b>&rsquo;.
1044280405SrpauloThe complete syntax of Lua can be found in <a href="#9">&sect;9</a>
1045280405Srpauloat the end of this manual.
1046280405Srpaulo
1047280405Srpaulo
1048280405Srpaulo
1049280405Srpaulo<h2>3.1 &ndash; <a name="3.1">Lexical Conventions</a></h2>
1050280405Srpaulo
1051280405Srpaulo<p>
1052280405SrpauloLua is a free-form language.
1053280405SrpauloIt ignores spaces (including new lines) and comments
1054280405Srpaulobetween lexical elements (tokens),
1055280405Srpauloexcept as delimiters between names and keywords.
1056280405Srpaulo
1057280405Srpaulo
1058280405Srpaulo<p>
1059280405Srpaulo<em>Names</em>
1060280405Srpaulo(also called <em>identifiers</em>)
1061280405Srpauloin Lua can be any string of letters,
1062280405Srpaulodigits, and underscores,
1063326344Simpnot beginning with a digit and
1064326344Simpnot being a reserved word.
1065280405SrpauloIdentifiers are used to name variables, table fields, and labels.
1066280405Srpaulo
1067280405Srpaulo
1068280405Srpaulo<p>
1069280405SrpauloThe following <em>keywords</em> are reserved
1070280405Srpauloand cannot be used as names:
1071280405Srpaulo
1072280405Srpaulo
1073280405Srpaulo<pre>
1074280405Srpaulo     and       break     do        else      elseif    end
1075280405Srpaulo     false     for       function  goto      if        in
1076280405Srpaulo     local     nil       not       or        repeat    return
1077280405Srpaulo     then      true      until     while
1078280405Srpaulo</pre>
1079280405Srpaulo
1080280405Srpaulo<p>
1081280405SrpauloLua is a case-sensitive language:
1082280405Srpaulo<code>and</code> is a reserved word, but <code>And</code> and <code>AND</code>
1083280405Srpauloare two different, valid names.
1084280405SrpauloAs a convention,
1085326344Simpprograms should avoid creating
1086280405Srpaulonames that start with an underscore followed by
1087280405Srpauloone or more uppercase letters (such as <a href="#pdf-_VERSION"><code>_VERSION</code></a>).
1088280405Srpaulo
1089280405Srpaulo
1090280405Srpaulo<p>
1091280405SrpauloThe following strings denote other tokens:
1092280405Srpaulo
1093280405Srpaulo<pre>
1094280405Srpaulo     +     -     *     /     %     ^     #
1095280405Srpaulo     &amp;     ~     |     &lt;&lt;    &gt;&gt;    //
1096280405Srpaulo     ==    ~=    &lt;=    &gt;=    &lt;     &gt;     =
1097280405Srpaulo     (     )     {     }     [     ]     ::
1098280405Srpaulo     ;     :     ,     .     ..    ...
1099280405Srpaulo</pre>
1100280405Srpaulo
1101280405Srpaulo<p>
1102326344SimpA <em>short literal string</em>
1103280405Srpaulocan be delimited by matching single or double quotes,
1104280405Srpauloand can contain the following C-like escape sequences:
1105280405Srpaulo'<code>\a</code>' (bell),
1106280405Srpaulo'<code>\b</code>' (backspace),
1107280405Srpaulo'<code>\f</code>' (form feed),
1108280405Srpaulo'<code>\n</code>' (newline),
1109280405Srpaulo'<code>\r</code>' (carriage return),
1110280405Srpaulo'<code>\t</code>' (horizontal tab),
1111280405Srpaulo'<code>\v</code>' (vertical tab),
1112280405Srpaulo'<code>\\</code>' (backslash),
1113280405Srpaulo'<code>\"</code>' (quotation mark [double quote]),
1114280405Srpauloand '<code>\'</code>' (apostrophe [single quote]).
1115326344SimpA backslash followed by a line break
1116280405Srpauloresults in a newline in the string.
1117280405SrpauloThe escape sequence '<code>\z</code>' skips the following span
1118280405Srpauloof white-space characters,
1119280405Srpauloincluding line breaks;
1120280405Srpauloit is particularly useful to break and indent a long literal string
1121280405Srpaulointo multiple lines without adding the newlines and spaces
1122280405Srpaulointo the string contents.
1123326344SimpA short literal string cannot contain unescaped line breaks
1124326344Simpnor escapes not forming a valid escape sequence.
1125280405Srpaulo
1126280405Srpaulo
1127280405Srpaulo<p>
1128326344SimpWe can specify any byte in a short literal string by its numeric value
1129326344Simp(including embedded zeros).
1130280405SrpauloThis can be done
1131280405Srpaulowith the escape sequence <code>\x<em>XX</em></code>,
1132280405Srpaulowhere <em>XX</em> is a sequence of exactly two hexadecimal digits,
1133280405Srpauloor with the escape sequence <code>\<em>ddd</em></code>,
1134280405Srpaulowhere <em>ddd</em> is a sequence of up to three decimal digits.
1135280405Srpaulo(Note that if a decimal escape sequence is to be followed by a digit,
1136280405Srpauloit must be expressed using exactly three digits.)
1137280405Srpaulo
1138280405Srpaulo
1139280405Srpaulo<p>
1140280405SrpauloThe UTF-8 encoding of a Unicode character
1141280405Srpaulocan be inserted in a literal string with
1142280405Srpaulothe escape sequence <code>\u{<em>XXX</em>}</code>
1143280405Srpaulo(note the mandatory enclosing brackets),
1144280405Srpaulowhere <em>XXX</em> is a sequence of one or more hexadecimal digits
1145280405Srpaulorepresenting the character code point.
1146280405Srpaulo
1147280405Srpaulo
1148280405Srpaulo<p>
1149280405SrpauloLiteral strings can also be defined using a long format
1150280405Srpauloenclosed by <em>long brackets</em>.
1151280405SrpauloWe define an <em>opening long bracket of level <em>n</em></em> as an opening
1152280405Srpaulosquare bracket followed by <em>n</em> equal signs followed by another
1153280405Srpauloopening square bracket.
1154280405SrpauloSo, an opening long bracket of level&nbsp;0 is written as <code>[[</code>, 
1155280405Srpauloan opening long bracket of level&nbsp;1 is written as <code>[=[</code>, 
1156280405Srpauloand so on.
1157280405SrpauloA <em>closing long bracket</em> is defined similarly;
1158280405Srpaulofor instance,
1159280405Srpauloa closing long bracket of level&nbsp;4 is written as  <code>]====]</code>.
1160280405SrpauloA <em>long literal</em> starts with an opening long bracket of any level and
1161280405Srpauloends at the first closing long bracket of the same level.
1162280405SrpauloIt can contain any text except a closing bracket of the same level.
1163280405SrpauloLiterals in this bracketed form can run for several lines,
1164280405Srpaulodo not interpret any escape sequences,
1165280405Srpauloand ignore long brackets of any other level.
1166280405SrpauloAny kind of end-of-line sequence
1167280405Srpaulo(carriage return, newline, carriage return followed by newline,
1168280405Srpauloor newline followed by carriage return)
1169280405Srpaulois converted to a simple newline.
1170280405Srpaulo
1171280405Srpaulo
1172280405Srpaulo<p>
1173280405SrpauloFor convenience,
1174280405Srpaulowhen the opening long bracket is immediately followed by a newline,
1175280405Srpaulothe newline is not included in the string.
1176280405SrpauloAs an example, in a system using ASCII
1177280405Srpaulo(in which '<code>a</code>' is coded as&nbsp;97,
1178280405Srpaulonewline is coded as&nbsp;10, and '<code>1</code>' is coded as&nbsp;49),
1179280405Srpaulothe five literal strings below denote the same string:
1180280405Srpaulo
1181280405Srpaulo<pre>
1182280405Srpaulo     a = 'alo\n123"'
1183280405Srpaulo     a = "alo\n123\""
1184280405Srpaulo     a = '\97lo\10\04923"'
1185280405Srpaulo     a = [[alo
1186280405Srpaulo     123"]]
1187280405Srpaulo     a = [==[
1188280405Srpaulo     alo
1189280405Srpaulo     123"]==]
1190280405Srpaulo</pre>
1191280405Srpaulo
1192280405Srpaulo<p>
1193326344SimpAny byte in a literal string not
1194326344Simpexplicitly affected by the previous rules represents itself.
1195326344SimpHowever, Lua opens files for parsing in text mode,
1196326344Simpand the system file functions may have problems with
1197326344Simpsome control characters.
1198326344SimpSo, it is safer to represent
1199326344Simpnon-text data as a quoted literal with
1200326344Simpexplicit escape sequences for the non-text characters.
1201326344Simp
1202326344Simp
1203326344Simp<p>
1204326344SimpA <em>numeric constant</em> (or <em>numeral</em>)
1205280405Srpaulocan be written with an optional fractional part
1206280405Srpauloand an optional decimal exponent,
1207280405Srpaulomarked by a letter '<code>e</code>' or '<code>E</code>'.
1208280405SrpauloLua also accepts hexadecimal constants,
1209280405Srpaulowhich start with <code>0x</code> or <code>0X</code>.
1210280405SrpauloHexadecimal constants also accept an optional fractional part
1211280405Srpauloplus an optional binary exponent,
1212280405Srpaulomarked by a letter '<code>p</code>' or '<code>P</code>'.
1213326344SimpA numeric constant with a radix point or an exponent
1214280405Srpaulodenotes a float;
1215326344Simpotherwise,
1216326344Simpif its value fits in an integer,
1217326344Simpit denotes an integer.
1218280405SrpauloExamples of valid integer constants are
1219280405Srpaulo
1220280405Srpaulo<pre>
1221280405Srpaulo     3   345   0xff   0xBEBADA
1222280405Srpaulo</pre><p>
1223280405SrpauloExamples of valid float constants are
1224280405Srpaulo
1225280405Srpaulo<pre>
1226280405Srpaulo     3.0     3.1416     314.16e-2     0.31416E1     34e1
1227280405Srpaulo     0x0.1E  0xA23p-4   0X1.921FB54442D18P+1
1228280405Srpaulo</pre>
1229280405Srpaulo
1230280405Srpaulo<p>
1231280405SrpauloA <em>comment</em> starts with a double hyphen (<code>--</code>)
1232280405Srpauloanywhere outside a string.
1233280405SrpauloIf the text immediately after <code>--</code> is not an opening long bracket,
1234280405Srpaulothe comment is a <em>short comment</em>,
1235280405Srpaulowhich runs until the end of the line.
1236280405SrpauloOtherwise, it is a <em>long comment</em>,
1237280405Srpaulowhich runs until the corresponding closing long bracket.
1238280405SrpauloLong comments are frequently used to disable code temporarily.
1239280405Srpaulo
1240280405Srpaulo
1241280405Srpaulo
1242280405Srpaulo
1243280405Srpaulo
1244280405Srpaulo<h2>3.2 &ndash; <a name="3.2">Variables</a></h2>
1245280405Srpaulo
1246280405Srpaulo<p>
1247280405SrpauloVariables are places that store values.
1248280405SrpauloThere are three kinds of variables in Lua:
1249280405Srpauloglobal variables, local variables, and table fields.
1250280405Srpaulo
1251280405Srpaulo
1252280405Srpaulo<p>
1253280405SrpauloA single name can denote a global variable or a local variable
1254280405Srpaulo(or a function's formal parameter,
1255280405Srpaulowhich is a particular kind of local variable):
1256280405Srpaulo
1257280405Srpaulo<pre>
1258280405Srpaulo	var ::= Name
1259280405Srpaulo</pre><p>
1260280405SrpauloName denotes identifiers, as defined in <a href="#3.1">&sect;3.1</a>.
1261280405Srpaulo
1262280405Srpaulo
1263280405Srpaulo<p>
1264280405SrpauloAny variable name is assumed to be global unless explicitly declared
1265280405Srpauloas a local (see <a href="#3.3.7">&sect;3.3.7</a>).
1266280405SrpauloLocal variables are <em>lexically scoped</em>:
1267280405Srpaulolocal variables can be freely accessed by functions
1268280405Srpaulodefined inside their scope (see <a href="#3.5">&sect;3.5</a>).
1269280405Srpaulo
1270280405Srpaulo
1271280405Srpaulo<p>
1272280405SrpauloBefore the first assignment to a variable, its value is <b>nil</b>.
1273280405Srpaulo
1274280405Srpaulo
1275280405Srpaulo<p>
1276280405SrpauloSquare brackets are used to index a table:
1277280405Srpaulo
1278280405Srpaulo<pre>
1279280405Srpaulo	var ::= prefixexp &lsquo;<b>[</b>&rsquo; exp &lsquo;<b>]</b>&rsquo;
1280280405Srpaulo</pre><p>
1281344220SkevansThe meaning of accesses to table fields can be changed via metatables
1282344220Skevans(see <a href="#2.4">&sect;2.4</a>).
1283280405Srpaulo
1284280405Srpaulo
1285280405Srpaulo<p>
1286280405SrpauloThe syntax <code>var.Name</code> is just syntactic sugar for
1287280405Srpaulo<code>var["Name"]</code>:
1288280405Srpaulo
1289280405Srpaulo<pre>
1290280405Srpaulo	var ::= prefixexp &lsquo;<b>.</b>&rsquo; Name
1291280405Srpaulo</pre>
1292280405Srpaulo
1293280405Srpaulo<p>
1294280405SrpauloAn access to a global variable <code>x</code>
1295280405Srpaulois equivalent to <code>_ENV.x</code>.
1296280405SrpauloDue to the way that chunks are compiled,
1297280405Srpaulo<code>_ENV</code> is never a global name (see <a href="#2.2">&sect;2.2</a>).
1298280405Srpaulo
1299280405Srpaulo
1300280405Srpaulo
1301280405Srpaulo
1302280405Srpaulo
1303280405Srpaulo<h2>3.3 &ndash; <a name="3.3">Statements</a></h2>
1304280405Srpaulo
1305280405Srpaulo<p>
1306280405SrpauloLua supports an almost conventional set of statements,
1307280405Srpaulosimilar to those in Pascal or C.
1308280405SrpauloThis set includes
1309280405Srpauloassignments, control structures, function calls,
1310280405Srpauloand variable declarations.
1311280405Srpaulo
1312280405Srpaulo
1313280405Srpaulo
1314280405Srpaulo<h3>3.3.1 &ndash; <a name="3.3.1">Blocks</a></h3>
1315280405Srpaulo
1316280405Srpaulo<p>
1317280405SrpauloA block is a list of statements,
1318280405Srpaulowhich are executed sequentially:
1319280405Srpaulo
1320280405Srpaulo<pre>
1321280405Srpaulo	block ::= {stat}
1322280405Srpaulo</pre><p>
1323280405SrpauloLua has <em>empty statements</em>
1324280405Srpaulothat allow you to separate statements with semicolons,
1325280405Srpaulostart a block with a semicolon
1326280405Srpauloor write two semicolons in sequence:
1327280405Srpaulo
1328280405Srpaulo<pre>
1329280405Srpaulo	stat ::= &lsquo;<b>;</b>&rsquo;
1330280405Srpaulo</pre>
1331280405Srpaulo
1332280405Srpaulo<p>
1333280405SrpauloFunction calls and assignments
1334280405Srpaulocan start with an open parenthesis.
1335280405SrpauloThis possibility leads to an ambiguity in Lua's grammar.
1336280405SrpauloConsider the following fragment:
1337280405Srpaulo
1338280405Srpaulo<pre>
1339280405Srpaulo     a = b + c
1340280405Srpaulo     (print or io.write)('done')
1341280405Srpaulo</pre><p>
1342280405SrpauloThe grammar could see it in two ways:
1343280405Srpaulo
1344280405Srpaulo<pre>
1345280405Srpaulo     a = b + c(print or io.write)('done')
1346280405Srpaulo     
1347280405Srpaulo     a = b + c; (print or io.write)('done')
1348280405Srpaulo</pre><p>
1349280405SrpauloThe current parser always sees such constructions
1350280405Srpauloin the first way,
1351280405Srpaulointerpreting the open parenthesis
1352280405Srpauloas the start of the arguments to a call.
1353280405SrpauloTo avoid this ambiguity,
1354280405Srpauloit is a good practice to always precede with a semicolon
1355280405Srpaulostatements that start with a parenthesis:
1356280405Srpaulo
1357280405Srpaulo<pre>
1358280405Srpaulo     ;(print or io.write)('done')
1359280405Srpaulo</pre>
1360280405Srpaulo
1361280405Srpaulo<p>
1362280405SrpauloA block can be explicitly delimited to produce a single statement:
1363280405Srpaulo
1364280405Srpaulo<pre>
1365280405Srpaulo	stat ::= <b>do</b> block <b>end</b>
1366280405Srpaulo</pre><p>
1367280405SrpauloExplicit blocks are useful
1368280405Srpauloto control the scope of variable declarations.
1369280405SrpauloExplicit blocks are also sometimes used to
1370280405Srpauloadd a <b>return</b> statement in the middle
1371280405Srpauloof another block (see <a href="#3.3.4">&sect;3.3.4</a>).
1372280405Srpaulo
1373280405Srpaulo
1374280405Srpaulo
1375280405Srpaulo
1376280405Srpaulo
1377280405Srpaulo<h3>3.3.2 &ndash; <a name="3.3.2">Chunks</a></h3>
1378280405Srpaulo
1379280405Srpaulo<p>
1380280405SrpauloThe unit of compilation of Lua is called a <em>chunk</em>.
1381280405SrpauloSyntactically,
1382280405Srpauloa chunk is simply a block:
1383280405Srpaulo
1384280405Srpaulo<pre>
1385280405Srpaulo	chunk ::= block
1386280405Srpaulo</pre>
1387280405Srpaulo
1388280405Srpaulo<p>
1389280405SrpauloLua handles a chunk as the body of an anonymous function
1390280405Srpaulowith a variable number of arguments
1391280405Srpaulo(see <a href="#3.4.11">&sect;3.4.11</a>).
1392280405SrpauloAs such, chunks can define local variables,
1393280405Srpauloreceive arguments, and return values.
1394280405SrpauloMoreover, such anonymous function is compiled as in the
1395280405Srpauloscope of an external local variable called <code>_ENV</code> (see <a href="#2.2">&sect;2.2</a>).
1396280405SrpauloThe resulting function always has <code>_ENV</code> as its only upvalue,
1397280405Srpauloeven if it does not use that variable.
1398280405Srpaulo
1399280405Srpaulo
1400280405Srpaulo<p>
1401280405SrpauloA chunk can be stored in a file or in a string inside the host program.
1402280405SrpauloTo execute a chunk,
1403280405SrpauloLua first <em>loads</em> it,
1404280405Srpauloprecompiling the chunk's code into instructions for a virtual machine,
1405280405Srpauloand then Lua executes the compiled code
1406280405Srpaulowith an interpreter for the virtual machine.
1407280405Srpaulo
1408280405Srpaulo
1409280405Srpaulo<p>
1410280405SrpauloChunks can also be precompiled into binary form;
1411280405Srpaulosee program <code>luac</code> and function <a href="#pdf-string.dump"><code>string.dump</code></a> for details.
1412280405SrpauloPrograms in source and compiled forms are interchangeable;
1413280405SrpauloLua automatically detects the file type and acts accordingly (see <a href="#pdf-load"><code>load</code></a>).
1414280405Srpaulo
1415280405Srpaulo
1416280405Srpaulo
1417280405Srpaulo
1418280405Srpaulo
1419280405Srpaulo<h3>3.3.3 &ndash; <a name="3.3.3">Assignment</a></h3>
1420280405Srpaulo
1421280405Srpaulo<p>
1422280405SrpauloLua allows multiple assignments.
1423280405SrpauloTherefore, the syntax for assignment
1424280405Srpaulodefines a list of variables on the left side
1425280405Srpauloand a list of expressions on the right side.
1426280405SrpauloThe elements in both lists are separated by commas:
1427280405Srpaulo
1428280405Srpaulo<pre>
1429280405Srpaulo	stat ::= varlist &lsquo;<b>=</b>&rsquo; explist
1430280405Srpaulo	varlist ::= var {&lsquo;<b>,</b>&rsquo; var}
1431280405Srpaulo	explist ::= exp {&lsquo;<b>,</b>&rsquo; exp}
1432280405Srpaulo</pre><p>
1433280405SrpauloExpressions are discussed in <a href="#3.4">&sect;3.4</a>.
1434280405Srpaulo
1435280405Srpaulo
1436280405Srpaulo<p>
1437280405SrpauloBefore the assignment,
1438280405Srpaulothe list of values is <em>adjusted</em> to the length of
1439280405Srpaulothe list of variables.
1440280405SrpauloIf there are more values than needed,
1441280405Srpaulothe excess values are thrown away.
1442280405SrpauloIf there are fewer values than needed,
1443280405Srpaulothe list is extended with as many  <b>nil</b>'s as needed.
1444280405SrpauloIf the list of expressions ends with a function call,
1445280405Srpaulothen all values returned by that call enter the list of values,
1446280405Srpaulobefore the adjustment
1447280405Srpaulo(except when the call is enclosed in parentheses; see <a href="#3.4">&sect;3.4</a>).
1448280405Srpaulo
1449280405Srpaulo
1450280405Srpaulo<p>
1451280405SrpauloThe assignment statement first evaluates all its expressions
1452280405Srpauloand only then the assignments are performed.
1453280405SrpauloThus the code
1454280405Srpaulo
1455280405Srpaulo<pre>
1456280405Srpaulo     i = 3
1457280405Srpaulo     i, a[i] = i+1, 20
1458280405Srpaulo</pre><p>
1459280405Srpaulosets <code>a[3]</code> to 20, without affecting <code>a[4]</code>
1460280405Srpaulobecause the <code>i</code> in <code>a[i]</code> is evaluated (to 3)
1461280405Srpaulobefore it is assigned&nbsp;4.
1462280405SrpauloSimilarly, the line
1463280405Srpaulo
1464280405Srpaulo<pre>
1465280405Srpaulo     x, y = y, x
1466280405Srpaulo</pre><p>
1467280405Srpauloexchanges the values of <code>x</code> and <code>y</code>,
1468280405Srpauloand
1469280405Srpaulo
1470280405Srpaulo<pre>
1471280405Srpaulo     x, y, z = y, z, x
1472280405Srpaulo</pre><p>
1473280405Srpaulocyclically permutes the values of <code>x</code>, <code>y</code>, and <code>z</code>.
1474280405Srpaulo
1475280405Srpaulo
1476280405Srpaulo<p>
1477280405SrpauloAn assignment to a global name <code>x = val</code>
1478280405Srpaulois equivalent to the assignment
1479280405Srpaulo<code>_ENV.x = val</code> (see <a href="#2.2">&sect;2.2</a>).
1480280405Srpaulo
1481280405Srpaulo
1482344220Skevans<p>
1483344220SkevansThe meaning of assignments to table fields and
1484344220Skevansglobal variables (which are actually table fields, too)
1485344220Skevanscan be changed via metatables (see <a href="#2.4">&sect;2.4</a>).
1486280405Srpaulo
1487280405Srpaulo
1488280405Srpaulo
1489344220Skevans
1490344220Skevans
1491280405Srpaulo<h3>3.3.4 &ndash; <a name="3.3.4">Control Structures</a></h3><p>
1492280405SrpauloThe control structures
1493280405Srpaulo<b>if</b>, <b>while</b>, and <b>repeat</b> have the usual meaning and
1494280405Srpaulofamiliar syntax:
1495280405Srpaulo
1496280405Srpaulo
1497280405Srpaulo
1498280405Srpaulo
1499280405Srpaulo<pre>
1500280405Srpaulo	stat ::= <b>while</b> exp <b>do</b> block <b>end</b>
1501280405Srpaulo	stat ::= <b>repeat</b> block <b>until</b> exp
1502280405Srpaulo	stat ::= <b>if</b> exp <b>then</b> block {<b>elseif</b> exp <b>then</b> block} [<b>else</b> block] <b>end</b>
1503280405Srpaulo</pre><p>
1504280405SrpauloLua also has a <b>for</b> statement, in two flavors (see <a href="#3.3.5">&sect;3.3.5</a>).
1505280405Srpaulo
1506280405Srpaulo
1507280405Srpaulo<p>
1508280405SrpauloThe condition expression of a
1509280405Srpaulocontrol structure can return any value.
1510280405SrpauloBoth <b>false</b> and <b>nil</b> are considered false.
1511280405SrpauloAll values different from <b>nil</b> and <b>false</b> are considered true
1512280405Srpaulo(in particular, the number 0 and the empty string are also true).
1513280405Srpaulo
1514280405Srpaulo
1515280405Srpaulo<p>
1516280405SrpauloIn the <b>repeat</b>&ndash;<b>until</b> loop,
1517280405Srpaulothe inner block does not end at the <b>until</b> keyword,
1518280405Srpaulobut only after the condition.
1519280405SrpauloSo, the condition can refer to local variables
1520280405Srpaulodeclared inside the loop block.
1521280405Srpaulo
1522280405Srpaulo
1523280405Srpaulo<p>
1524280405SrpauloThe <b>goto</b> statement transfers the program control to a label.
1525280405SrpauloFor syntactical reasons,
1526280405Srpaulolabels in Lua are considered statements too:
1527280405Srpaulo
1528280405Srpaulo
1529280405Srpaulo
1530280405Srpaulo<pre>
1531280405Srpaulo	stat ::= <b>goto</b> Name
1532280405Srpaulo	stat ::= label
1533280405Srpaulo	label ::= &lsquo;<b>::</b>&rsquo; Name &lsquo;<b>::</b>&rsquo;
1534280405Srpaulo</pre>
1535280405Srpaulo
1536280405Srpaulo<p>
1537280405SrpauloA label is visible in the entire block where it is defined,
1538280405Srpauloexcept
1539280405Srpauloinside nested blocks where a label with the same name is defined and
1540280405Srpauloinside nested functions.
1541280405SrpauloA goto may jump to any visible label as long as it does not
1542280405Srpauloenter into the scope of a local variable.
1543280405Srpaulo
1544280405Srpaulo
1545280405Srpaulo<p>
1546280405SrpauloLabels and empty statements are called <em>void statements</em>,
1547280405Srpauloas they perform no actions.
1548280405Srpaulo
1549280405Srpaulo
1550280405Srpaulo<p>
1551280405SrpauloThe <b>break</b> statement terminates the execution of a
1552280405Srpaulo<b>while</b>, <b>repeat</b>, or <b>for</b> loop,
1553280405Srpauloskipping to the next statement after the loop:
1554280405Srpaulo
1555280405Srpaulo
1556280405Srpaulo<pre>
1557280405Srpaulo	stat ::= <b>break</b>
1558280405Srpaulo</pre><p>
1559280405SrpauloA <b>break</b> ends the innermost enclosing loop.
1560280405Srpaulo
1561280405Srpaulo
1562280405Srpaulo<p>
1563280405SrpauloThe <b>return</b> statement is used to return values
1564280405Srpaulofrom a function or a chunk
1565280405Srpaulo(which is an anonymous function).
1566280405Srpaulo
1567280405SrpauloFunctions can return more than one value,
1568280405Srpauloso the syntax for the <b>return</b> statement is
1569280405Srpaulo
1570280405Srpaulo<pre>
1571280405Srpaulo	stat ::= <b>return</b> [explist] [&lsquo;<b>;</b>&rsquo;]
1572280405Srpaulo</pre>
1573280405Srpaulo
1574280405Srpaulo<p>
1575280405SrpauloThe <b>return</b> statement can only be written
1576280405Srpauloas the last statement of a block.
1577280405SrpauloIf it is really necessary to <b>return</b> in the middle of a block,
1578280405Srpaulothen an explicit inner block can be used,
1579280405Srpauloas in the idiom <code>do return end</code>,
1580280405Srpaulobecause now <b>return</b> is the last statement in its (inner) block.
1581280405Srpaulo
1582280405Srpaulo
1583280405Srpaulo
1584280405Srpaulo
1585280405Srpaulo
1586280405Srpaulo<h3>3.3.5 &ndash; <a name="3.3.5">For Statement</a></h3>
1587280405Srpaulo
1588280405Srpaulo<p>
1589280405Srpaulo
1590280405SrpauloThe <b>for</b> statement has two forms:
1591326344Simpone numerical and one generic.
1592280405Srpaulo
1593280405Srpaulo
1594280405Srpaulo<p>
1595326344SimpThe numerical <b>for</b> loop repeats a block of code while a
1596280405Srpaulocontrol variable runs through an arithmetic progression.
1597280405SrpauloIt has the following syntax:
1598280405Srpaulo
1599280405Srpaulo<pre>
1600280405Srpaulo	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>
1601280405Srpaulo</pre><p>
1602280405SrpauloThe <em>block</em> is repeated for <em>name</em> starting at the value of
1603280405Srpaulothe first <em>exp</em>, until it passes the second <em>exp</em> by steps of the
1604280405Srpaulothird <em>exp</em>.
1605280405SrpauloMore precisely, a <b>for</b> statement like
1606280405Srpaulo
1607280405Srpaulo<pre>
1608280405Srpaulo     for v = <em>e1</em>, <em>e2</em>, <em>e3</em> do <em>block</em> end
1609280405Srpaulo</pre><p>
1610280405Srpaulois equivalent to the code:
1611280405Srpaulo
1612280405Srpaulo<pre>
1613280405Srpaulo     do
1614280405Srpaulo       local <em>var</em>, <em>limit</em>, <em>step</em> = tonumber(<em>e1</em>), tonumber(<em>e2</em>), tonumber(<em>e3</em>)
1615280405Srpaulo       if not (<em>var</em> and <em>limit</em> and <em>step</em>) then error() end
1616280405Srpaulo       <em>var</em> = <em>var</em> - <em>step</em>
1617280405Srpaulo       while true do
1618280405Srpaulo         <em>var</em> = <em>var</em> + <em>step</em>
1619280405Srpaulo         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
1620280405Srpaulo           break
1621280405Srpaulo         end
1622280405Srpaulo         local v = <em>var</em>
1623280405Srpaulo         <em>block</em>
1624280405Srpaulo       end
1625280405Srpaulo     end
1626280405Srpaulo</pre>
1627280405Srpaulo
1628280405Srpaulo<p>
1629280405SrpauloNote the following:
1630280405Srpaulo
1631280405Srpaulo<ul>
1632280405Srpaulo
1633280405Srpaulo<li>
1634280405SrpauloAll three control expressions are evaluated only once,
1635280405Srpaulobefore the loop starts.
1636280405SrpauloThey must all result in numbers.
1637280405Srpaulo</li>
1638280405Srpaulo
1639280405Srpaulo<li>
1640280405Srpaulo<code><em>var</em></code>, <code><em>limit</em></code>, and <code><em>step</em></code> are invisible variables.
1641280405SrpauloThe names shown here are for explanatory purposes only.
1642280405Srpaulo</li>
1643280405Srpaulo
1644280405Srpaulo<li>
1645280405SrpauloIf the third expression (the step) is absent,
1646280405Srpaulothen a step of&nbsp;1 is used.
1647280405Srpaulo</li>
1648280405Srpaulo
1649280405Srpaulo<li>
1650280405SrpauloYou can use <b>break</b> and <b>goto</b> to exit a <b>for</b> loop.
1651280405Srpaulo</li>
1652280405Srpaulo
1653280405Srpaulo<li>
1654280405SrpauloThe loop variable <code>v</code> is local to the loop body.
1655280405SrpauloIf you need its value after the loop,
1656280405Srpauloassign it to another variable before exiting the loop.
1657280405Srpaulo</li>
1658280405Srpaulo
1659280405Srpaulo</ul>
1660280405Srpaulo
1661280405Srpaulo<p>
1662280405SrpauloThe generic <b>for</b> statement works over functions,
1663280405Srpaulocalled <em>iterators</em>.
1664280405SrpauloOn each iteration, the iterator function is called to produce a new value,
1665280405Srpaulostopping when this new value is <b>nil</b>.
1666280405SrpauloThe generic <b>for</b> loop has the following syntax:
1667280405Srpaulo
1668280405Srpaulo<pre>
1669280405Srpaulo	stat ::= <b>for</b> namelist <b>in</b> explist <b>do</b> block <b>end</b>
1670280405Srpaulo	namelist ::= Name {&lsquo;<b>,</b>&rsquo; Name}
1671280405Srpaulo</pre><p>
1672280405SrpauloA <b>for</b> statement like
1673280405Srpaulo
1674280405Srpaulo<pre>
1675280405Srpaulo     for <em>var_1</em>, &middot;&middot;&middot;, <em>var_n</em> in <em>explist</em> do <em>block</em> end
1676280405Srpaulo</pre><p>
1677280405Srpaulois equivalent to the code:
1678280405Srpaulo
1679280405Srpaulo<pre>
1680280405Srpaulo     do
1681280405Srpaulo       local <em>f</em>, <em>s</em>, <em>var</em> = <em>explist</em>
1682280405Srpaulo       while true do
1683280405Srpaulo         local <em>var_1</em>, &middot;&middot;&middot;, <em>var_n</em> = <em>f</em>(<em>s</em>, <em>var</em>)
1684280405Srpaulo         if <em>var_1</em> == nil then break end
1685280405Srpaulo         <em>var</em> = <em>var_1</em>
1686280405Srpaulo         <em>block</em>
1687280405Srpaulo       end
1688280405Srpaulo     end
1689280405Srpaulo</pre><p>
1690280405SrpauloNote the following:
1691280405Srpaulo
1692280405Srpaulo<ul>
1693280405Srpaulo
1694280405Srpaulo<li>
1695280405Srpaulo<code><em>explist</em></code> is evaluated only once.
1696280405SrpauloIts results are an <em>iterator</em> function,
1697280405Srpauloa <em>state</em>,
1698280405Srpauloand an initial value for the first <em>iterator variable</em>.
1699280405Srpaulo</li>
1700280405Srpaulo
1701280405Srpaulo<li>
1702280405Srpaulo<code><em>f</em></code>, <code><em>s</em></code>, and <code><em>var</em></code> are invisible variables.
1703280405SrpauloThe names are here for explanatory purposes only.
1704280405Srpaulo</li>
1705280405Srpaulo
1706280405Srpaulo<li>
1707280405SrpauloYou can use <b>break</b> to exit a <b>for</b> loop.
1708280405Srpaulo</li>
1709280405Srpaulo
1710280405Srpaulo<li>
1711280405SrpauloThe loop variables <code><em>var_i</em></code> are local to the loop;
1712280405Srpauloyou cannot use their values after the <b>for</b> ends.
1713280405SrpauloIf you need these values,
1714280405Srpaulothen assign them to other variables before breaking or exiting the loop.
1715280405Srpaulo</li>
1716280405Srpaulo
1717280405Srpaulo</ul>
1718280405Srpaulo
1719280405Srpaulo
1720280405Srpaulo
1721280405Srpaulo
1722280405Srpaulo<h3>3.3.6 &ndash; <a name="3.3.6">Function Calls as Statements</a></h3><p>
1723280405SrpauloTo allow possible side-effects,
1724280405Srpaulofunction calls can be executed as statements:
1725280405Srpaulo
1726280405Srpaulo<pre>
1727280405Srpaulo	stat ::= functioncall
1728280405Srpaulo</pre><p>
1729280405SrpauloIn this case, all returned values are thrown away.
1730280405SrpauloFunction calls are explained in <a href="#3.4.10">&sect;3.4.10</a>.
1731280405Srpaulo
1732280405Srpaulo
1733280405Srpaulo
1734280405Srpaulo
1735280405Srpaulo
1736280405Srpaulo<h3>3.3.7 &ndash; <a name="3.3.7">Local Declarations</a></h3><p>
1737280405SrpauloLocal variables can be declared anywhere inside a block.
1738280405SrpauloThe declaration can include an initial assignment:
1739280405Srpaulo
1740280405Srpaulo<pre>
1741280405Srpaulo	stat ::= <b>local</b> namelist [&lsquo;<b>=</b>&rsquo; explist]
1742280405Srpaulo</pre><p>
1743280405SrpauloIf present, an initial assignment has the same semantics
1744280405Srpauloof a multiple assignment (see <a href="#3.3.3">&sect;3.3.3</a>).
1745280405SrpauloOtherwise, all variables are initialized with <b>nil</b>.
1746280405Srpaulo
1747280405Srpaulo
1748280405Srpaulo<p>
1749280405SrpauloA chunk is also a block (see <a href="#3.3.2">&sect;3.3.2</a>),
1750280405Srpauloand so local variables can be declared in a chunk outside any explicit block.
1751280405Srpaulo
1752280405Srpaulo
1753280405Srpaulo<p>
1754280405SrpauloThe visibility rules for local variables are explained in <a href="#3.5">&sect;3.5</a>.
1755280405Srpaulo
1756280405Srpaulo
1757280405Srpaulo
1758280405Srpaulo
1759280405Srpaulo
1760280405Srpaulo
1761280405Srpaulo
1762280405Srpaulo<h2>3.4 &ndash; <a name="3.4">Expressions</a></h2>
1763280405Srpaulo
1764280405Srpaulo<p>
1765280405SrpauloThe basic expressions in Lua are the following:
1766280405Srpaulo
1767280405Srpaulo<pre>
1768280405Srpaulo	exp ::= prefixexp
1769280405Srpaulo	exp ::= <b>nil</b> | <b>false</b> | <b>true</b>
1770280405Srpaulo	exp ::= Numeral
1771280405Srpaulo	exp ::= LiteralString
1772280405Srpaulo	exp ::= functiondef
1773280405Srpaulo	exp ::= tableconstructor
1774280405Srpaulo	exp ::= &lsquo;<b>...</b>&rsquo;
1775280405Srpaulo	exp ::= exp binop exp
1776280405Srpaulo	exp ::= unop exp
1777280405Srpaulo	prefixexp ::= var | functioncall | &lsquo;<b>(</b>&rsquo; exp &lsquo;<b>)</b>&rsquo;
1778280405Srpaulo</pre>
1779280405Srpaulo
1780280405Srpaulo<p>
1781280405SrpauloNumerals and literal strings are explained in <a href="#3.1">&sect;3.1</a>;
1782280405Srpaulovariables are explained in <a href="#3.2">&sect;3.2</a>;
1783280405Srpaulofunction definitions are explained in <a href="#3.4.11">&sect;3.4.11</a>;
1784280405Srpaulofunction calls are explained in <a href="#3.4.10">&sect;3.4.10</a>;
1785280405Srpaulotable constructors are explained in <a href="#3.4.9">&sect;3.4.9</a>.
1786280405SrpauloVararg expressions,
1787280405Srpaulodenoted by three dots ('<code>...</code>'), can only be used when
1788280405Srpaulodirectly inside a vararg function;
1789280405Srpaulothey are explained in <a href="#3.4.11">&sect;3.4.11</a>.
1790280405Srpaulo
1791280405Srpaulo
1792280405Srpaulo<p>
1793280405SrpauloBinary operators comprise arithmetic operators (see <a href="#3.4.1">&sect;3.4.1</a>),
1794280405Srpaulobitwise operators (see <a href="#3.4.2">&sect;3.4.2</a>),
1795280405Srpaulorelational 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>),
1796280405Srpauloand the concatenation operator (see <a href="#3.4.6">&sect;3.4.6</a>).
1797280405SrpauloUnary operators comprise the unary minus (see <a href="#3.4.1">&sect;3.4.1</a>),
1798326344Simpthe unary bitwise NOT (see <a href="#3.4.2">&sect;3.4.2</a>),
1799280405Srpaulothe unary logical <b>not</b> (see <a href="#3.4.5">&sect;3.4.5</a>),
1800280405Srpauloand the unary <em>length operator</em> (see <a href="#3.4.7">&sect;3.4.7</a>).
1801280405Srpaulo
1802280405Srpaulo
1803280405Srpaulo<p>
1804280405SrpauloBoth function calls and vararg expressions can result in multiple values.
1805280405SrpauloIf a function call is used as a statement (see <a href="#3.3.6">&sect;3.3.6</a>),
1806280405Srpaulothen its return list is adjusted to zero elements,
1807280405Srpaulothus discarding all returned values.
1808280405SrpauloIf an expression is used as the last (or the only) element
1809280405Srpauloof a list of expressions,
1810280405Srpaulothen no adjustment is made
1811280405Srpaulo(unless the expression is enclosed in parentheses).
1812280405SrpauloIn all other contexts,
1813280405SrpauloLua adjusts the result list to one element,
1814280405Srpauloeither discarding all values except the first one
1815280405Srpauloor adding a single <b>nil</b> if there are no values.
1816280405Srpaulo
1817280405Srpaulo
1818280405Srpaulo<p>
1819280405SrpauloHere are some examples:
1820280405Srpaulo
1821280405Srpaulo<pre>
1822280405Srpaulo     f()                -- adjusted to 0 results
1823280405Srpaulo     g(f(), x)          -- f() is adjusted to 1 result
1824280405Srpaulo     g(x, f())          -- g gets x plus all results from f()
1825280405Srpaulo     a,b,c = f(), x     -- f() is adjusted to 1 result (c gets nil)
1826344220Skevans     a,b = ...          -- a gets the first vararg argument, b gets
1827280405Srpaulo                        -- the second (both a and b can get nil if there
1828344220Skevans                        -- is no corresponding vararg argument)
1829280405Srpaulo     
1830280405Srpaulo     a,b,c = x, f()     -- f() is adjusted to 2 results
1831280405Srpaulo     a,b,c = f()        -- f() is adjusted to 3 results
1832280405Srpaulo     return f()         -- returns all results from f()
1833344220Skevans     return ...         -- returns all received vararg arguments
1834280405Srpaulo     return x,y,f()     -- returns x, y, and all results from f()
1835280405Srpaulo     {f()}              -- creates a list with all results from f()
1836344220Skevans     {...}              -- creates a list with all vararg arguments
1837280405Srpaulo     {f(), nil}         -- f() is adjusted to 1 result
1838280405Srpaulo</pre>
1839280405Srpaulo
1840280405Srpaulo<p>
1841280405SrpauloAny expression enclosed in parentheses always results in only one value.
1842280405SrpauloThus,
1843280405Srpaulo<code>(f(x,y,z))</code> is always a single value,
1844280405Srpauloeven if <code>f</code> returns several values.
1845280405Srpaulo(The value of <code>(f(x,y,z))</code> is the first value returned by <code>f</code>
1846280405Srpauloor <b>nil</b> if <code>f</code> does not return any values.)
1847280405Srpaulo
1848280405Srpaulo
1849280405Srpaulo
1850280405Srpaulo<h3>3.4.1 &ndash; <a name="3.4.1">Arithmetic Operators</a></h3><p>
1851280405SrpauloLua supports the following arithmetic operators:
1852280405Srpaulo
1853280405Srpaulo<ul>
1854280405Srpaulo<li><b><code>+</code>: </b>addition</li>
1855280405Srpaulo<li><b><code>-</code>: </b>subtraction</li>
1856280405Srpaulo<li><b><code>*</code>: </b>multiplication</li>
1857280405Srpaulo<li><b><code>/</code>: </b>float division</li>
1858280405Srpaulo<li><b><code>//</code>: </b>floor division</li>
1859280405Srpaulo<li><b><code>%</code>: </b>modulo</li>
1860280405Srpaulo<li><b><code>^</code>: </b>exponentiation</li>
1861280405Srpaulo<li><b><code>-</code>: </b>unary minus</li>
1862280405Srpaulo</ul>
1863280405Srpaulo
1864280405Srpaulo<p>
1865280405SrpauloWith the exception of exponentiation and float division,
1866280405Srpaulothe arithmetic operators work as follows:
1867280405SrpauloIf both operands are integers,
1868280405Srpaulothe operation is performed over integers and the result is an integer.
1869280405SrpauloOtherwise, if both operands are numbers
1870280405Srpauloor strings that can be converted to
1871280405Srpaulonumbers (see <a href="#3.4.3">&sect;3.4.3</a>),
1872280405Srpaulothen they are converted to floats,
1873280405Srpaulothe operation is performed following the usual rules
1874280405Srpaulofor floating-point arithmetic
1875280405Srpaulo(usually the IEEE 754 standard),
1876280405Srpauloand the result is a float.
1877280405Srpaulo
1878280405Srpaulo
1879280405Srpaulo<p>
1880280405SrpauloExponentiation and float division (<code>/</code>)
1881280405Srpauloalways convert their operands to floats
1882280405Srpauloand the result is always a float.
1883280405SrpauloExponentiation uses the ISO&nbsp;C function <code>pow</code>,
1884280405Srpauloso that it works for non-integer exponents too.
1885280405Srpaulo
1886280405Srpaulo
1887280405Srpaulo<p>
1888326344SimpFloor division (<code>//</code>) is a division
1889326344Simpthat rounds the quotient towards minus infinity,
1890280405Srpaulothat is, the floor of the division of its operands.
1891280405Srpaulo
1892280405Srpaulo
1893280405Srpaulo<p>
1894280405SrpauloModulo is defined as the remainder of a division
1895326344Simpthat rounds the quotient towards minus infinity (floor division).
1896280405Srpaulo
1897280405Srpaulo
1898280405Srpaulo<p>
1899280405SrpauloIn case of overflows in integer arithmetic,
1900280405Srpauloall operations <em>wrap around</em>,
1901280405Srpauloaccording to the usual rules of two-complement arithmetic.
1902280405Srpaulo(In other words,
1903280405Srpaulothey return the unique representable integer
1904280405Srpaulothat is equal modulo <em>2<sup>64</sup></em> to the mathematical result.)
1905280405Srpaulo
1906280405Srpaulo
1907280405Srpaulo
1908280405Srpaulo<h3>3.4.2 &ndash; <a name="3.4.2">Bitwise Operators</a></h3><p>
1909280405SrpauloLua supports the following bitwise operators:
1910280405Srpaulo
1911280405Srpaulo<ul>
1912326344Simp<li><b><code>&amp;</code>: </b>bitwise AND</li>
1913326344Simp<li><b><code>&#124;</code>: </b>bitwise OR</li>
1914326344Simp<li><b><code>~</code>: </b>bitwise exclusive OR</li>
1915280405Srpaulo<li><b><code>&gt;&gt;</code>: </b>right shift</li>
1916280405Srpaulo<li><b><code>&lt;&lt;</code>: </b>left shift</li>
1917326344Simp<li><b><code>~</code>: </b>unary bitwise NOT</li>
1918280405Srpaulo</ul>
1919280405Srpaulo
1920280405Srpaulo<p>
1921280405SrpauloAll bitwise operations convert its operands to integers
1922280405Srpaulo(see <a href="#3.4.3">&sect;3.4.3</a>),
1923280405Srpaulooperate on all bits of those integers,
1924280405Srpauloand result in an integer.
1925280405Srpaulo
1926280405Srpaulo
1927280405Srpaulo<p>
1928280405SrpauloBoth right and left shifts fill the vacant bits with zeros.
1929280405SrpauloNegative displacements shift to the other direction;
1930280405Srpaulodisplacements with absolute values equal to or higher than
1931280405Srpaulothe number of bits in an integer
1932280405Srpauloresult in zero (as all bits are shifted out).
1933280405Srpaulo
1934280405Srpaulo
1935280405Srpaulo
1936280405Srpaulo
1937280405Srpaulo
1938280405Srpaulo<h3>3.4.3 &ndash; <a name="3.4.3">Coercions and Conversions</a></h3><p>
1939280405SrpauloLua provides some automatic conversions between some
1940280405Srpaulotypes and representations at run time.
1941280405SrpauloBitwise operators always convert float operands to integers.
1942280405SrpauloExponentiation and float division
1943280405Srpauloalways convert integer operands to floats.
1944280405SrpauloAll other arithmetic operations applied to mixed numbers
1945280405Srpaulo(integers and floats) convert the integer operand to a float;
1946280405Srpaulothis is called the <em>usual rule</em>.
1947280405SrpauloThe C API also converts both integers to floats and
1948280405Srpaulofloats to integers, as needed.
1949280405SrpauloMoreover, string concatenation accepts numbers as arguments,
1950326344Simpbesides strings.
1951280405Srpaulo
1952280405Srpaulo
1953280405Srpaulo<p>
1954280405SrpauloLua also converts strings to numbers,
1955280405Srpaulowhenever a number is expected.
1956280405Srpaulo
1957280405Srpaulo
1958280405Srpaulo<p>
1959280405SrpauloIn a conversion from integer to float,
1960280405Srpauloif the integer value has an exact representation as a float,
1961280405Srpaulothat is the result.
1962280405SrpauloOtherwise,
1963280405Srpaulothe conversion gets the nearest higher or
1964280405Srpaulothe nearest lower representable value.
1965280405SrpauloThis kind of conversion never fails.
1966280405Srpaulo
1967280405Srpaulo
1968280405Srpaulo<p>
1969280405SrpauloThe conversion from float to integer
1970280405Srpaulochecks whether the float has an exact representation as an integer
1971280405Srpaulo(that is, the float has an integral value and
1972280405Srpauloit is in the range of integer representation).
1973280405SrpauloIf it does, that representation is the result.
1974280405SrpauloOtherwise, the conversion fails.
1975280405Srpaulo
1976280405Srpaulo
1977280405Srpaulo<p>
1978280405SrpauloThe conversion from strings to numbers goes as follows:
1979280405SrpauloFirst, the string is converted to an integer or a float,
1980280405Srpaulofollowing its syntax and the rules of the Lua lexer.
1981280405Srpaulo(The string may have also leading and trailing spaces and a sign.)
1982326344SimpThen, the resulting number (float or integer)
1983326344Simpis converted to the type (float or integer) required by the context
1984326344Simp(e.g., the operation that forced the conversion).
1985280405Srpaulo
1986280405Srpaulo
1987280405Srpaulo<p>
1988326344SimpAll conversions from strings to numbers
1989326344Simpaccept both a dot and the current locale mark
1990326344Simpas the radix character.
1991326344Simp(The Lua lexer, however, accepts only a dot.)
1992326344Simp
1993326344Simp
1994326344Simp<p>
1995280405SrpauloThe conversion from numbers to strings uses a
1996280405Srpaulonon-specified human-readable format.
1997280405SrpauloFor complete control over how numbers are converted to strings,
1998280405Srpaulouse the <code>format</code> function from the string library
1999280405Srpaulo(see <a href="#pdf-string.format"><code>string.format</code></a>).
2000280405Srpaulo
2001280405Srpaulo
2002280405Srpaulo
2003280405Srpaulo
2004280405Srpaulo
2005280405Srpaulo<h3>3.4.4 &ndash; <a name="3.4.4">Relational Operators</a></h3><p>
2006280405SrpauloLua supports the following relational operators:
2007280405Srpaulo
2008280405Srpaulo<ul>
2009280405Srpaulo<li><b><code>==</code>: </b>equality</li>
2010280405Srpaulo<li><b><code>~=</code>: </b>inequality</li>
2011280405Srpaulo<li><b><code>&lt;</code>: </b>less than</li>
2012280405Srpaulo<li><b><code>&gt;</code>: </b>greater than</li>
2013280405Srpaulo<li><b><code>&lt;=</code>: </b>less or equal</li>
2014280405Srpaulo<li><b><code>&gt;=</code>: </b>greater or equal</li>
2015280405Srpaulo</ul><p>
2016280405SrpauloThese operators always result in <b>false</b> or <b>true</b>.
2017280405Srpaulo
2018280405Srpaulo
2019280405Srpaulo<p>
2020280405SrpauloEquality (<code>==</code>) first compares the type of its operands.
2021280405SrpauloIf the types are different, then the result is <b>false</b>.
2022280405SrpauloOtherwise, the values of the operands are compared.
2023280405SrpauloStrings are compared in the obvious way.
2024326344SimpNumbers are equal if they denote the same mathematical value.
2025280405Srpaulo
2026280405Srpaulo
2027280405Srpaulo<p>
2028280405SrpauloTables, userdata, and threads
2029280405Srpauloare compared by reference:
2030280405Srpaulotwo objects are considered equal only if they are the same object.
2031280405SrpauloEvery time you create a new object
2032280405Srpaulo(a table, userdata, or thread),
2033280405Srpaulothis new object is different from any previously existing object.
2034344220SkevansA closure is always equal to itself.
2035280405SrpauloClosures with any detectable difference
2036280405Srpaulo(different behavior, different definition) are always different.
2037344220SkevansClosures created at different times but with no detectable differences
2038344220Skevansmay be classified as equal or not
2039344220Skevans(depending on internal caching details).
2040280405Srpaulo
2041280405Srpaulo
2042280405Srpaulo<p>
2043280405SrpauloYou can change the way that Lua compares tables and userdata
2044280405Srpauloby using the "eq" metamethod (see <a href="#2.4">&sect;2.4</a>).
2045280405Srpaulo
2046280405Srpaulo
2047280405Srpaulo<p>
2048280405SrpauloEquality comparisons do not convert strings to numbers
2049280405Srpauloor vice versa.
2050280405SrpauloThus, <code>"0"==0</code> evaluates to <b>false</b>,
2051280405Srpauloand <code>t[0]</code> and <code>t["0"]</code> denote different
2052280405Srpauloentries in a table.
2053280405Srpaulo
2054280405Srpaulo
2055280405Srpaulo<p>
2056280405SrpauloThe operator <code>~=</code> is exactly the negation of equality (<code>==</code>).
2057280405Srpaulo
2058280405Srpaulo
2059280405Srpaulo<p>
2060280405SrpauloThe order operators work as follows.
2061280405SrpauloIf both arguments are numbers,
2062326344Simpthen they are compared according to their mathematical values
2063326344Simp(regardless of their subtypes).
2064280405SrpauloOtherwise, if both arguments are strings,
2065280405Srpaulothen their values are compared according to the current locale.
2066280405SrpauloOtherwise, Lua tries to call the "lt" or the "le"
2067280405Srpaulometamethod (see <a href="#2.4">&sect;2.4</a>).
2068280405SrpauloA comparison <code>a &gt; b</code> is translated to <code>b &lt; a</code>
2069280405Srpauloand <code>a &gt;= b</code> is translated to <code>b &lt;= a</code>.
2070280405Srpaulo
2071280405Srpaulo
2072326344Simp<p>
2073326344SimpFollowing the IEEE 754 standard,
2074326344SimpNaN is considered neither smaller than,
2075326344Simpnor equal to, nor greater than any value (including itself).
2076280405Srpaulo
2077280405Srpaulo
2078280405Srpaulo
2079326344Simp
2080326344Simp
2081280405Srpaulo<h3>3.4.5 &ndash; <a name="3.4.5">Logical Operators</a></h3><p>
2082280405SrpauloThe logical operators in Lua are
2083280405Srpaulo<b>and</b>, <b>or</b>, and <b>not</b>.
2084280405SrpauloLike the control structures (see <a href="#3.3.4">&sect;3.3.4</a>),
2085280405Srpauloall logical operators consider both <b>false</b> and <b>nil</b> as false
2086280405Srpauloand anything else as true.
2087280405Srpaulo
2088280405Srpaulo
2089280405Srpaulo<p>
2090280405SrpauloThe negation operator <b>not</b> always returns <b>false</b> or <b>true</b>.
2091280405SrpauloThe conjunction operator <b>and</b> returns its first argument
2092280405Srpauloif this value is <b>false</b> or <b>nil</b>;
2093280405Srpaulootherwise, <b>and</b> returns its second argument.
2094280405SrpauloThe disjunction operator <b>or</b> returns its first argument
2095280405Srpauloif this value is different from <b>nil</b> and <b>false</b>;
2096280405Srpaulootherwise, <b>or</b> returns its second argument.
2097280405SrpauloBoth <b>and</b> and <b>or</b> use short-circuit evaluation;
2098280405Srpaulothat is,
2099280405Srpaulothe second operand is evaluated only if necessary.
2100280405SrpauloHere are some examples:
2101280405Srpaulo
2102280405Srpaulo<pre>
2103280405Srpaulo     10 or 20            --&gt; 10
2104280405Srpaulo     10 or error()       --&gt; 10
2105280405Srpaulo     nil or "a"          --&gt; "a"
2106280405Srpaulo     nil and 10          --&gt; nil
2107280405Srpaulo     false and error()   --&gt; false
2108280405Srpaulo     false and nil       --&gt; false
2109280405Srpaulo     false or nil        --&gt; nil
2110280405Srpaulo     10 and 20           --&gt; 20
2111280405Srpaulo</pre><p>
2112280405Srpaulo(In this manual,
2113280405Srpaulo<code>--&gt;</code> indicates the result of the preceding expression.)
2114280405Srpaulo
2115280405Srpaulo
2116280405Srpaulo
2117280405Srpaulo
2118280405Srpaulo
2119280405Srpaulo<h3>3.4.6 &ndash; <a name="3.4.6">Concatenation</a></h3><p>
2120280405SrpauloThe string concatenation operator in Lua is
2121280405Srpaulodenoted by two dots ('<code>..</code>').
2122280405SrpauloIf both operands are strings or numbers, then they are converted to
2123280405Srpaulostrings according to the rules described in <a href="#3.4.3">&sect;3.4.3</a>.
2124280405SrpauloOtherwise, the <code>__concat</code> metamethod is called (see <a href="#2.4">&sect;2.4</a>).
2125280405Srpaulo
2126280405Srpaulo
2127280405Srpaulo
2128280405Srpaulo
2129280405Srpaulo
2130280405Srpaulo<h3>3.4.7 &ndash; <a name="3.4.7">The Length Operator</a></h3>
2131280405Srpaulo
2132280405Srpaulo<p>
2133280405SrpauloThe length operator is denoted by the unary prefix operator <code>#</code>.
2134326344Simp
2135326344Simp
2136326344Simp<p>
2137280405SrpauloThe length of a string is its number of bytes
2138280405Srpaulo(that is, the usual meaning of string length when each
2139280405Srpaulocharacter is one byte).
2140280405Srpaulo
2141280405Srpaulo
2142280405Srpaulo<p>
2143326344SimpThe length operator applied on a table
2144326344Simpreturns a border in that table.
2145326344SimpA <em>border</em> in a table <code>t</code> is any natural number
2146326344Simpthat satisfies the following condition:
2147280405Srpaulo
2148326344Simp<pre>
2149326344Simp     (border == 0 or t[border] ~= nil) and t[border + 1] == nil
2150326344Simp</pre><p>
2151326344SimpIn words,
2152326344Simpa border is any (natural) index in a table
2153326344Simpwhere a non-nil value is followed by a nil value
2154326344Simp(or zero, when index 1 is nil).
2155280405Srpaulo
2156326344Simp
2157280405Srpaulo<p>
2158326344SimpA table with exactly one border is called a <em>sequence</em>.
2159326344SimpFor instance, the table <code>{10, 20, 30, 40, 50}</code> is a sequence,
2160326344Simpas it has only one border (5).
2161326344SimpThe table <code>{10, 20, 30, nil, 50}</code> has two borders (3 and 5),
2162326344Simpand therefore it is not a sequence.
2163326344SimpThe table <code>{nil, 20, 30, nil, nil, 60, nil}</code>
2164326344Simphas three borders (0, 3, and 6),
2165326344Simpso it is not a sequence, too.
2166326344SimpThe table <code>{}</code> is a sequence with border 0.
2167326344SimpNote that non-natural keys do not interfere
2168280405Srpaulowith whether a table is a sequence.
2169280405Srpaulo
2170280405Srpaulo
2171326344Simp<p>
2172326344SimpWhen <code>t</code> is a sequence,
2173326344Simp<code>#t</code> returns its only border,
2174326344Simpwhich corresponds to the intuitive notion of the length of the sequence.
2175326344SimpWhen <code>t</code> is not a sequence,
2176326344Simp<code>#t</code> can return any of its borders.
2177326344Simp(The exact one depends on details of
2178326344Simpthe internal representation of the table,
2179326344Simpwhich in turn can depend on how the table was populated and
2180326344Simpthe memory addresses of its non-numeric keys.)
2181280405Srpaulo
2182280405Srpaulo
2183326344Simp<p>
2184326344SimpThe computation of the length of a table
2185326344Simphas a guaranteed worst time of <em>O(log n)</em>,
2186326344Simpwhere <em>n</em> is the largest natural key in the table.
2187280405Srpaulo
2188326344Simp
2189326344Simp<p>
2190326344SimpA program can modify the behavior of the length operator for
2191326344Simpany value but strings through the <code>__len</code> metamethod (see <a href="#2.4">&sect;2.4</a>).
2192326344Simp
2193326344Simp
2194326344Simp
2195326344Simp
2196326344Simp
2197280405Srpaulo<h3>3.4.8 &ndash; <a name="3.4.8">Precedence</a></h3><p>
2198280405SrpauloOperator precedence in Lua follows the table below,
2199280405Srpaulofrom lower to higher priority:
2200280405Srpaulo
2201280405Srpaulo<pre>
2202280405Srpaulo     or
2203280405Srpaulo     and
2204280405Srpaulo     &lt;     &gt;     &lt;=    &gt;=    ~=    ==
2205280405Srpaulo     |
2206280405Srpaulo     ~
2207280405Srpaulo     &amp;
2208280405Srpaulo     &lt;&lt;    &gt;&gt;
2209280405Srpaulo     ..
2210280405Srpaulo     +     -
2211280405Srpaulo     *     /     //    %
2212280405Srpaulo     unary operators (not   #     -     ~)
2213280405Srpaulo     ^
2214280405Srpaulo</pre><p>
2215280405SrpauloAs usual,
2216280405Srpauloyou can use parentheses to change the precedences of an expression.
2217280405SrpauloThe concatenation ('<code>..</code>') and exponentiation ('<code>^</code>')
2218280405Srpaulooperators are right associative.
2219280405SrpauloAll other binary operators are left associative.
2220280405Srpaulo
2221280405Srpaulo
2222280405Srpaulo
2223280405Srpaulo
2224280405Srpaulo
2225280405Srpaulo<h3>3.4.9 &ndash; <a name="3.4.9">Table Constructors</a></h3><p>
2226280405SrpauloTable constructors are expressions that create tables.
2227280405SrpauloEvery time a constructor is evaluated, a new table is created.
2228280405SrpauloA constructor can be used to create an empty table
2229280405Srpauloor to create a table and initialize some of its fields.
2230280405SrpauloThe general syntax for constructors is
2231280405Srpaulo
2232280405Srpaulo<pre>
2233280405Srpaulo	tableconstructor ::= &lsquo;<b>{</b>&rsquo; [fieldlist] &lsquo;<b>}</b>&rsquo;
2234280405Srpaulo	fieldlist ::= field {fieldsep field} [fieldsep]
2235280405Srpaulo	field ::= &lsquo;<b>[</b>&rsquo; exp &lsquo;<b>]</b>&rsquo; &lsquo;<b>=</b>&rsquo; exp | Name &lsquo;<b>=</b>&rsquo; exp | exp
2236280405Srpaulo	fieldsep ::= &lsquo;<b>,</b>&rsquo; | &lsquo;<b>;</b>&rsquo;
2237280405Srpaulo</pre>
2238280405Srpaulo
2239280405Srpaulo<p>
2240280405SrpauloEach field of the form <code>[exp1] = exp2</code> adds to the new table an entry
2241280405Srpaulowith key <code>exp1</code> and value <code>exp2</code>.
2242280405SrpauloA field of the form <code>name = exp</code> is equivalent to
2243280405Srpaulo<code>["name"] = exp</code>.
2244280405SrpauloFinally, fields of the form <code>exp</code> are equivalent to
2245280405Srpaulo<code>[i] = exp</code>, where <code>i</code> are consecutive integers
2246280405Srpaulostarting with 1.
2247280405SrpauloFields in the other formats do not affect this counting.
2248280405SrpauloFor example,
2249280405Srpaulo
2250280405Srpaulo<pre>
2251280405Srpaulo     a = { [f(1)] = g; "x", "y"; x = 1, f(x), [30] = 23; 45 }
2252280405Srpaulo</pre><p>
2253280405Srpaulois equivalent to
2254280405Srpaulo
2255280405Srpaulo<pre>
2256280405Srpaulo     do
2257280405Srpaulo       local t = {}
2258280405Srpaulo       t[f(1)] = g
2259280405Srpaulo       t[1] = "x"         -- 1st exp
2260280405Srpaulo       t[2] = "y"         -- 2nd exp
2261280405Srpaulo       t.x = 1            -- t["x"] = 1
2262280405Srpaulo       t[3] = f(x)        -- 3rd exp
2263280405Srpaulo       t[30] = 23
2264280405Srpaulo       t[4] = 45          -- 4th exp
2265280405Srpaulo       a = t
2266280405Srpaulo     end
2267280405Srpaulo</pre>
2268280405Srpaulo
2269280405Srpaulo<p>
2270280405SrpauloThe order of the assignments in a constructor is undefined.
2271280405Srpaulo(This order would be relevant only when there are repeated keys.)
2272280405Srpaulo
2273280405Srpaulo
2274280405Srpaulo<p>
2275280405SrpauloIf the last field in the list has the form <code>exp</code>
2276280405Srpauloand the expression is a function call or a vararg expression,
2277280405Srpaulothen all values returned by this expression enter the list consecutively
2278280405Srpaulo(see <a href="#3.4.10">&sect;3.4.10</a>).
2279280405Srpaulo
2280280405Srpaulo
2281280405Srpaulo<p>
2282280405SrpauloThe field list can have an optional trailing separator,
2283280405Srpauloas a convenience for machine-generated code.
2284280405Srpaulo
2285280405Srpaulo
2286280405Srpaulo
2287280405Srpaulo
2288280405Srpaulo
2289280405Srpaulo<h3>3.4.10 &ndash; <a name="3.4.10">Function Calls</a></h3><p>
2290280405SrpauloA function call in Lua has the following syntax:
2291280405Srpaulo
2292280405Srpaulo<pre>
2293280405Srpaulo	functioncall ::= prefixexp args
2294280405Srpaulo</pre><p>
2295280405SrpauloIn a function call,
2296280405Srpaulofirst prefixexp and args are evaluated.
2297280405SrpauloIf the value of prefixexp has type <em>function</em>,
2298280405Srpaulothen this function is called
2299280405Srpaulowith the given arguments.
2300280405SrpauloOtherwise, the prefixexp "call" metamethod is called,
2301344220Skevanshaving as first argument the value of prefixexp,
2302280405Srpaulofollowed by the original call arguments
2303280405Srpaulo(see <a href="#2.4">&sect;2.4</a>).
2304280405Srpaulo
2305280405Srpaulo
2306280405Srpaulo<p>
2307280405SrpauloThe form
2308280405Srpaulo
2309280405Srpaulo<pre>
2310280405Srpaulo	functioncall ::= prefixexp &lsquo;<b>:</b>&rsquo; Name args
2311280405Srpaulo</pre><p>
2312280405Srpaulocan be used to call "methods".
2313280405SrpauloA call <code>v:name(<em>args</em>)</code>
2314280405Srpaulois syntactic sugar for <code>v.name(v,<em>args</em>)</code>,
2315280405Srpauloexcept that <code>v</code> is evaluated only once.
2316280405Srpaulo
2317280405Srpaulo
2318280405Srpaulo<p>
2319280405SrpauloArguments have the following syntax:
2320280405Srpaulo
2321280405Srpaulo<pre>
2322280405Srpaulo	args ::= &lsquo;<b>(</b>&rsquo; [explist] &lsquo;<b>)</b>&rsquo;
2323280405Srpaulo	args ::= tableconstructor
2324280405Srpaulo	args ::= LiteralString
2325280405Srpaulo</pre><p>
2326280405SrpauloAll argument expressions are evaluated before the call.
2327280405SrpauloA call of the form <code>f{<em>fields</em>}</code> is
2328280405Srpaulosyntactic sugar for <code>f({<em>fields</em>})</code>;
2329280405Srpaulothat is, the argument list is a single new table.
2330280405SrpauloA call of the form <code>f'<em>string</em>'</code>
2331280405Srpaulo(or <code>f"<em>string</em>"</code> or <code>f[[<em>string</em>]]</code>)
2332280405Srpaulois syntactic sugar for <code>f('<em>string</em>')</code>;
2333280405Srpaulothat is, the argument list is a single literal string.
2334280405Srpaulo
2335280405Srpaulo
2336280405Srpaulo<p>
2337280405SrpauloA call of the form <code>return <em>functioncall</em></code> is called
2338280405Srpauloa <em>tail call</em>.
2339280405SrpauloLua implements <em>proper tail calls</em>
2340280405Srpaulo(or <em>proper tail recursion</em>):
2341280405Srpauloin a tail call,
2342280405Srpaulothe called function reuses the stack entry of the calling function.
2343280405SrpauloTherefore, there is no limit on the number of nested tail calls that
2344280405Srpauloa program can execute.
2345280405SrpauloHowever, a tail call erases any debug information about the
2346280405Srpaulocalling function.
2347280405SrpauloNote that a tail call only happens with a particular syntax,
2348280405Srpaulowhere the <b>return</b> has one single function call as argument;
2349280405Srpaulothis syntax makes the calling function return exactly
2350280405Srpaulothe returns of the called function.
2351280405SrpauloSo, none of the following examples are tail calls:
2352280405Srpaulo
2353280405Srpaulo<pre>
2354280405Srpaulo     return (f(x))        -- results adjusted to 1
2355280405Srpaulo     return 2 * f(x)
2356280405Srpaulo     return x, f(x)       -- additional results
2357280405Srpaulo     f(x); return         -- results discarded
2358280405Srpaulo     return x or f(x)     -- results adjusted to 1
2359280405Srpaulo</pre>
2360280405Srpaulo
2361280405Srpaulo
2362280405Srpaulo
2363280405Srpaulo
2364280405Srpaulo<h3>3.4.11 &ndash; <a name="3.4.11">Function Definitions</a></h3>
2365280405Srpaulo
2366280405Srpaulo<p>
2367280405SrpauloThe syntax for function definition is
2368280405Srpaulo
2369280405Srpaulo<pre>
2370280405Srpaulo	functiondef ::= <b>function</b> funcbody
2371280405Srpaulo	funcbody ::= &lsquo;<b>(</b>&rsquo; [parlist] &lsquo;<b>)</b>&rsquo; block <b>end</b>
2372280405Srpaulo</pre>
2373280405Srpaulo
2374280405Srpaulo<p>
2375280405SrpauloThe following syntactic sugar simplifies function definitions:
2376280405Srpaulo
2377280405Srpaulo<pre>
2378280405Srpaulo	stat ::= <b>function</b> funcname funcbody
2379280405Srpaulo	stat ::= <b>local</b> <b>function</b> Name funcbody
2380280405Srpaulo	funcname ::= Name {&lsquo;<b>.</b>&rsquo; Name} [&lsquo;<b>:</b>&rsquo; Name]
2381280405Srpaulo</pre><p>
2382280405SrpauloThe statement
2383280405Srpaulo
2384280405Srpaulo<pre>
2385280405Srpaulo     function f () <em>body</em> end
2386280405Srpaulo</pre><p>
2387280405Srpaulotranslates to
2388280405Srpaulo
2389280405Srpaulo<pre>
2390280405Srpaulo     f = function () <em>body</em> end
2391280405Srpaulo</pre><p>
2392280405SrpauloThe statement
2393280405Srpaulo
2394280405Srpaulo<pre>
2395280405Srpaulo     function t.a.b.c.f () <em>body</em> end
2396280405Srpaulo</pre><p>
2397280405Srpaulotranslates to
2398280405Srpaulo
2399280405Srpaulo<pre>
2400280405Srpaulo     t.a.b.c.f = function () <em>body</em> end
2401280405Srpaulo</pre><p>
2402280405SrpauloThe statement
2403280405Srpaulo
2404280405Srpaulo<pre>
2405280405Srpaulo     local function f () <em>body</em> end
2406280405Srpaulo</pre><p>
2407280405Srpaulotranslates to
2408280405Srpaulo
2409280405Srpaulo<pre>
2410280405Srpaulo     local f; f = function () <em>body</em> end
2411280405Srpaulo</pre><p>
2412280405Srpaulonot to
2413280405Srpaulo
2414280405Srpaulo<pre>
2415280405Srpaulo     local f = function () <em>body</em> end
2416280405Srpaulo</pre><p>
2417280405Srpaulo(This only makes a difference when the body of the function
2418280405Srpaulocontains references to <code>f</code>.)
2419280405Srpaulo
2420280405Srpaulo
2421280405Srpaulo<p>
2422280405SrpauloA function definition is an executable expression,
2423280405Srpaulowhose value has type <em>function</em>.
2424280405SrpauloWhen Lua precompiles a chunk,
2425280405Srpauloall its function bodies are precompiled too.
2426280405SrpauloThen, whenever Lua executes the function definition,
2427280405Srpaulothe function is <em>instantiated</em> (or <em>closed</em>).
2428280405SrpauloThis function instance (or <em>closure</em>)
2429280405Srpaulois the final value of the expression.
2430280405Srpaulo
2431280405Srpaulo
2432280405Srpaulo<p>
2433280405SrpauloParameters act as local variables that are
2434280405Srpauloinitialized with the argument values:
2435280405Srpaulo
2436280405Srpaulo<pre>
2437280405Srpaulo	parlist ::= namelist [&lsquo;<b>,</b>&rsquo; &lsquo;<b>...</b>&rsquo;] | &lsquo;<b>...</b>&rsquo;
2438280405Srpaulo</pre><p>
2439280405SrpauloWhen a function is called,
2440280405Srpaulothe list of arguments is adjusted to
2441280405Srpaulothe length of the list of parameters,
2442280405Srpaulounless the function is a <em>vararg function</em>,
2443280405Srpaulowhich is indicated by three dots ('<code>...</code>')
2444280405Srpauloat the end of its parameter list.
2445280405SrpauloA vararg function does not adjust its argument list;
2446280405Srpauloinstead, it collects all extra arguments and supplies them
2447280405Srpauloto the function through a <em>vararg expression</em>,
2448280405Srpaulowhich is also written as three dots.
2449280405SrpauloThe value of this expression is a list of all actual extra arguments,
2450280405Srpaulosimilar to a function with multiple results.
2451280405SrpauloIf a vararg expression is used inside another expression
2452280405Srpauloor in the middle of a list of expressions,
2453280405Srpaulothen its return list is adjusted to one element.
2454280405SrpauloIf the expression is used as the last element of a list of expressions,
2455280405Srpaulothen no adjustment is made
2456280405Srpaulo(unless that last expression is enclosed in parentheses).
2457280405Srpaulo
2458280405Srpaulo
2459280405Srpaulo<p>
2460280405SrpauloAs an example, consider the following definitions:
2461280405Srpaulo
2462280405Srpaulo<pre>
2463280405Srpaulo     function f(a, b) end
2464280405Srpaulo     function g(a, b, ...) end
2465280405Srpaulo     function r() return 1,2,3 end
2466280405Srpaulo</pre><p>
2467280405SrpauloThen, we have the following mapping from arguments to parameters and
2468280405Srpauloto the vararg expression:
2469280405Srpaulo
2470280405Srpaulo<pre>
2471280405Srpaulo     CALL            PARAMETERS
2472280405Srpaulo     
2473280405Srpaulo     f(3)             a=3, b=nil
2474280405Srpaulo     f(3, 4)          a=3, b=4
2475280405Srpaulo     f(3, 4, 5)       a=3, b=4
2476280405Srpaulo     f(r(), 10)       a=1, b=10
2477280405Srpaulo     f(r())           a=1, b=2
2478280405Srpaulo     
2479280405Srpaulo     g(3)             a=3, b=nil, ... --&gt;  (nothing)
2480280405Srpaulo     g(3, 4)          a=3, b=4,   ... --&gt;  (nothing)
2481280405Srpaulo     g(3, 4, 5, 8)    a=3, b=4,   ... --&gt;  5  8
2482280405Srpaulo     g(5, r())        a=5, b=1,   ... --&gt;  2  3
2483280405Srpaulo</pre>
2484280405Srpaulo
2485280405Srpaulo<p>
2486280405SrpauloResults are returned using the <b>return</b> statement (see <a href="#3.3.4">&sect;3.3.4</a>).
2487280405SrpauloIf control reaches the end of a function
2488280405Srpaulowithout encountering a <b>return</b> statement,
2489280405Srpaulothen the function returns with no results.
2490280405Srpaulo
2491280405Srpaulo
2492280405Srpaulo<p>
2493280405Srpaulo
2494280405SrpauloThere is a system-dependent limit on the number of values
2495280405Srpaulothat a function may return.
2496280405SrpauloThis limit is guaranteed to be larger than 1000.
2497280405Srpaulo
2498280405Srpaulo
2499280405Srpaulo<p>
2500280405SrpauloThe <em>colon</em> syntax
2501280405Srpaulois used for defining <em>methods</em>,
2502280405Srpaulothat is, functions that have an implicit extra parameter <code>self</code>.
2503280405SrpauloThus, the statement
2504280405Srpaulo
2505280405Srpaulo<pre>
2506280405Srpaulo     function t.a.b.c:f (<em>params</em>) <em>body</em> end
2507280405Srpaulo</pre><p>
2508280405Srpaulois syntactic sugar for
2509280405Srpaulo
2510280405Srpaulo<pre>
2511280405Srpaulo     t.a.b.c.f = function (self, <em>params</em>) <em>body</em> end
2512280405Srpaulo</pre>
2513280405Srpaulo
2514280405Srpaulo
2515280405Srpaulo
2516280405Srpaulo
2517280405Srpaulo
2518280405Srpaulo
2519280405Srpaulo<h2>3.5 &ndash; <a name="3.5">Visibility Rules</a></h2>
2520280405Srpaulo
2521280405Srpaulo<p>
2522280405Srpaulo
2523280405SrpauloLua is a lexically scoped language.
2524280405SrpauloThe scope of a local variable begins at the first statement after
2525280405Srpauloits declaration and lasts until the last non-void statement
2526280405Srpauloof the innermost block that includes the declaration.
2527280405SrpauloConsider the following example:
2528280405Srpaulo
2529280405Srpaulo<pre>
2530280405Srpaulo     x = 10                -- global variable
2531280405Srpaulo     do                    -- new block
2532280405Srpaulo       local x = x         -- new 'x', with value 10
2533280405Srpaulo       print(x)            --&gt; 10
2534280405Srpaulo       x = x+1
2535280405Srpaulo       do                  -- another block
2536280405Srpaulo         local x = x+1     -- another 'x'
2537280405Srpaulo         print(x)          --&gt; 12
2538280405Srpaulo       end
2539280405Srpaulo       print(x)            --&gt; 11
2540280405Srpaulo     end
2541280405Srpaulo     print(x)              --&gt; 10  (the global one)
2542280405Srpaulo</pre>
2543280405Srpaulo
2544280405Srpaulo<p>
2545280405SrpauloNotice that, in a declaration like <code>local x = x</code>,
2546280405Srpaulothe new <code>x</code> being declared is not in scope yet,
2547280405Srpauloand so the second <code>x</code> refers to the outside variable.
2548280405Srpaulo
2549280405Srpaulo
2550280405Srpaulo<p>
2551280405SrpauloBecause of the lexical scoping rules,
2552280405Srpaulolocal variables can be freely accessed by functions
2553280405Srpaulodefined inside their scope.
2554280405SrpauloA local variable used by an inner function is called
2555280405Srpauloan <em>upvalue</em>, or <em>external local variable</em>,
2556280405Srpauloinside the inner function.
2557280405Srpaulo
2558280405Srpaulo
2559280405Srpaulo<p>
2560280405SrpauloNotice that each execution of a <b>local</b> statement
2561280405Srpaulodefines new local variables.
2562280405SrpauloConsider the following example:
2563280405Srpaulo
2564280405Srpaulo<pre>
2565280405Srpaulo     a = {}
2566280405Srpaulo     local x = 20
2567280405Srpaulo     for i=1,10 do
2568280405Srpaulo       local y = 0
2569280405Srpaulo       a[i] = function () y=y+1; return x+y end
2570280405Srpaulo     end
2571280405Srpaulo</pre><p>
2572280405SrpauloThe loop creates ten closures
2573280405Srpaulo(that is, ten instances of the anonymous function).
2574280405SrpauloEach of these closures uses a different <code>y</code> variable,
2575280405Srpaulowhile all of them share the same <code>x</code>.
2576280405Srpaulo
2577280405Srpaulo
2578280405Srpaulo
2579280405Srpaulo
2580280405Srpaulo
2581280405Srpaulo<h1>4 &ndash; <a name="4">The Application Program Interface</a></h1>
2582280405Srpaulo
2583280405Srpaulo<p>
2584280405Srpaulo
2585280405SrpauloThis section describes the C&nbsp;API for Lua, that is,
2586280405Srpaulothe set of C&nbsp;functions available to the host program to communicate
2587280405Srpaulowith Lua.
2588280405SrpauloAll API functions and related types and constants
2589280405Srpauloare declared in the header file <a name="pdf-lua.h"><code>lua.h</code></a>.
2590280405Srpaulo
2591280405Srpaulo
2592280405Srpaulo<p>
2593280405SrpauloEven when we use the term "function",
2594280405Srpauloany facility in the API may be provided as a macro instead.
2595280405SrpauloExcept where stated otherwise,
2596280405Srpauloall such macros use each of their arguments exactly once
2597280405Srpaulo(except for the first argument, which is always a Lua state),
2598280405Srpauloand so do not generate any hidden side-effects.
2599280405Srpaulo
2600280405Srpaulo
2601280405Srpaulo<p>
2602280405SrpauloAs in most C&nbsp;libraries,
2603280405Srpaulothe Lua API functions do not check their arguments for validity or consistency.
2604280405SrpauloHowever, you can change this behavior by compiling Lua
2605280405Srpaulowith the macro <a name="pdf-LUA_USE_APICHECK"><code>LUA_USE_APICHECK</code></a> defined.
2606280405Srpaulo
2607280405Srpaulo
2608326344Simp<p>
2609326344SimpThe Lua library is fully reentrant:
2610326344Simpit has no global variables.
2611326344SimpIt keeps all information it needs in a dynamic structure,
2612326344Simpcalled the <em>Lua state</em>.
2613280405Srpaulo
2614326344Simp
2615326344Simp<p>
2616326344SimpEach Lua state has one or more threads,
2617326344Simpwhich correspond to independent, cooperative lines of execution.
2618326344SimpThe type <a href="#lua_State"><code>lua_State</code></a> (despite its name) refers to a thread.
2619326344Simp(Indirectly, through the thread, it also refers to the
2620326344SimpLua state associated to the thread.)
2621326344Simp
2622326344Simp
2623326344Simp<p>
2624326344SimpA pointer to a thread must be passed as the first argument to
2625326344Simpevery function in the library, except to <a href="#lua_newstate"><code>lua_newstate</code></a>,
2626326344Simpwhich creates a Lua state from scratch and returns a pointer
2627326344Simpto the <em>main thread</em> in the new state.
2628326344Simp
2629326344Simp
2630326344Simp
2631280405Srpaulo<h2>4.1 &ndash; <a name="4.1">The Stack</a></h2>
2632280405Srpaulo
2633280405Srpaulo<p>
2634280405SrpauloLua uses a <em>virtual stack</em> to pass values to and from C.
2635280405SrpauloEach element in this stack represents a Lua value
2636280405Srpaulo(<b>nil</b>, number, string, etc.).
2637326344SimpFunctions in the API can access this stack through the
2638326344SimpLua state parameter that they receive.
2639280405Srpaulo
2640280405Srpaulo
2641280405Srpaulo<p>
2642280405SrpauloWhenever Lua calls C, the called function gets a new stack,
2643280405Srpaulowhich is independent of previous stacks and of stacks of
2644280405SrpauloC&nbsp;functions that are still active.
2645280405SrpauloThis stack initially contains any arguments to the C&nbsp;function
2646326344Simpand it is where the C&nbsp;function can store temporary
2647326344SimpLua values and must push its results
2648280405Srpauloto be returned to the caller (see <a href="#lua_CFunction"><code>lua_CFunction</code></a>).
2649280405Srpaulo
2650280405Srpaulo
2651280405Srpaulo<p>
2652280405SrpauloFor convenience,
2653280405Srpaulomost query operations in the API do not follow a strict stack discipline.
2654280405SrpauloInstead, they can refer to any element in the stack
2655280405Srpauloby using an <em>index</em>:
2656280405SrpauloA positive index represents an absolute stack position
2657280405Srpaulo(starting at&nbsp;1);
2658280405Srpauloa negative index represents an offset relative to the top of the stack.
2659280405SrpauloMore specifically, if the stack has <em>n</em> elements,
2660280405Srpaulothen index&nbsp;1 represents the first element
2661280405Srpaulo(that is, the element that was pushed onto the stack first)
2662280405Srpauloand
2663280405Srpauloindex&nbsp;<em>n</em> represents the last element;
2664280405Srpauloindex&nbsp;-1 also represents the last element
2665280405Srpaulo(that is, the element at the&nbsp;top)
2666280405Srpauloand index <em>-n</em> represents the first element.
2667280405Srpaulo
2668280405Srpaulo
2669280405Srpaulo
2670280405Srpaulo
2671280405Srpaulo
2672280405Srpaulo<h2>4.2 &ndash; <a name="4.2">Stack Size</a></h2>
2673280405Srpaulo
2674280405Srpaulo<p>
2675280405SrpauloWhen you interact with the Lua API,
2676280405Srpauloyou are responsible for ensuring consistency.
2677280405SrpauloIn particular,
2678280405Srpaulo<em>you are responsible for controlling stack overflow</em>.
2679280405SrpauloYou can use the function <a href="#lua_checkstack"><code>lua_checkstack</code></a>
2680280405Srpauloto ensure that the stack has enough space for pushing new elements.
2681280405Srpaulo
2682280405Srpaulo
2683280405Srpaulo<p>
2684280405SrpauloWhenever Lua calls C,
2685280405Srpauloit ensures that the stack has space for
2686280405Srpauloat least <a name="pdf-LUA_MINSTACK"><code>LUA_MINSTACK</code></a> extra slots.
2687280405Srpaulo<code>LUA_MINSTACK</code> is defined as 20,
2688280405Srpauloso that usually you do not have to worry about stack space
2689280405Srpaulounless your code has loops pushing elements onto the stack.
2690280405Srpaulo
2691280405Srpaulo
2692280405Srpaulo<p>
2693280405SrpauloWhen you call a Lua function
2694280405Srpaulowithout a fixed number of results (see <a href="#lua_call"><code>lua_call</code></a>),
2695280405SrpauloLua ensures that the stack has enough space for all results,
2696280405Srpaulobut it does not ensure any extra space.
2697280405SrpauloSo, before pushing anything in the stack after such a call
2698280405Srpauloyou should use <a href="#lua_checkstack"><code>lua_checkstack</code></a>.
2699280405Srpaulo
2700280405Srpaulo
2701280405Srpaulo
2702280405Srpaulo
2703280405Srpaulo
2704280405Srpaulo<h2>4.3 &ndash; <a name="4.3">Valid and Acceptable Indices</a></h2>
2705280405Srpaulo
2706280405Srpaulo<p>
2707280405SrpauloAny function in the API that receives stack indices
2708280405Srpauloworks only with <em>valid indices</em> or <em>acceptable indices</em>.
2709280405Srpaulo
2710280405Srpaulo
2711280405Srpaulo<p>
2712280405SrpauloA <em>valid index</em> is an index that refers to a
2713326344Simpposition that stores a modifiable Lua value.
2714326344SimpIt comprises stack indices between&nbsp;1 and the stack top
2715326344Simp(<code>1 &le; abs(index) &le; top</code>)
2716280405Srpaulo
2717326344Simpplus <em>pseudo-indices</em>,
2718326344Simpwhich represent some positions that are accessible to C&nbsp;code
2719326344Simpbut that are not in the stack.
2720326344SimpPseudo-indices are used to access the registry (see <a href="#4.5">&sect;4.5</a>)
2721280405Srpauloand the upvalues of a C&nbsp;function (see <a href="#4.4">&sect;4.4</a>).
2722280405Srpaulo
2723280405Srpaulo
2724280405Srpaulo<p>
2725326344SimpFunctions that do not need a specific mutable position,
2726326344Simpbut only a value (e.g., query functions),
2727280405Srpaulocan be called with acceptable indices.
2728280405SrpauloAn <em>acceptable index</em> can be any valid index,
2729280405Srpaulobut it also can be any positive index after the stack top
2730280405Srpaulowithin the space allocated for the stack,
2731280405Srpaulothat is, indices up to the stack size.
2732280405Srpaulo(Note that 0 is never an acceptable index.)
2733280405SrpauloExcept when noted otherwise,
2734280405Srpaulofunctions in the API work with acceptable indices.
2735280405Srpaulo
2736280405Srpaulo
2737280405Srpaulo<p>
2738280405SrpauloAcceptable indices serve to avoid extra tests
2739280405Srpauloagainst the stack top when querying the stack.
2740280405SrpauloFor instance, a C&nbsp;function can query its third argument
2741280405Srpaulowithout the need to first check whether there is a third argument,
2742280405Srpaulothat is, without the need to check whether 3 is a valid index.
2743280405Srpaulo
2744280405Srpaulo
2745280405Srpaulo<p>
2746280405SrpauloFor functions that can be called with acceptable indices,
2747280405Srpauloany non-valid index is treated as if it
2748280405Srpaulocontains a value of a virtual type <a name="pdf-LUA_TNONE"><code>LUA_TNONE</code></a>,
2749280405Srpaulowhich behaves like a nil value.
2750280405Srpaulo
2751280405Srpaulo
2752280405Srpaulo
2753280405Srpaulo
2754280405Srpaulo
2755280405Srpaulo<h2>4.4 &ndash; <a name="4.4">C Closures</a></h2>
2756280405Srpaulo
2757280405Srpaulo<p>
2758280405SrpauloWhen a C&nbsp;function is created,
2759280405Srpauloit is possible to associate some values with it,
2760280405Srpaulothus creating a <em>C&nbsp;closure</em>
2761280405Srpaulo(see <a href="#lua_pushcclosure"><code>lua_pushcclosure</code></a>);
2762280405Srpaulothese values are called <em>upvalues</em> and are
2763280405Srpauloaccessible to the function whenever it is called.
2764280405Srpaulo
2765280405Srpaulo
2766280405Srpaulo<p>
2767280405SrpauloWhenever a C&nbsp;function is called,
2768280405Srpauloits upvalues are located at specific pseudo-indices.
2769280405SrpauloThese pseudo-indices are produced by the macro
2770280405Srpaulo<a href="#lua_upvalueindex"><code>lua_upvalueindex</code></a>.
2771326344SimpThe first upvalue associated with a function is at index
2772280405Srpaulo<code>lua_upvalueindex(1)</code>, and so on.
2773280405SrpauloAny access to <code>lua_upvalueindex(<em>n</em>)</code>,
2774280405Srpaulowhere <em>n</em> is greater than the number of upvalues of the
2775326344Simpcurrent function
2776326344Simp(but not greater than 256,
2777326344Simpwhich is one plus the maximum number of upvalues in a closure),
2778280405Srpauloproduces an acceptable but invalid index.
2779280405Srpaulo
2780280405Srpaulo
2781280405Srpaulo
2782280405Srpaulo
2783280405Srpaulo
2784280405Srpaulo<h2>4.5 &ndash; <a name="4.5">Registry</a></h2>
2785280405Srpaulo
2786280405Srpaulo<p>
2787280405SrpauloLua provides a <em>registry</em>,
2788280405Srpauloa predefined table that can be used by any C&nbsp;code to
2789280405Srpaulostore whatever Lua values it needs to store.
2790280405SrpauloThe registry table is always located at pseudo-index
2791326344Simp<a name="pdf-LUA_REGISTRYINDEX"><code>LUA_REGISTRYINDEX</code></a>.
2792280405SrpauloAny C&nbsp;library can store data into this table,
2793280405Srpaulobut it must take care to choose keys
2794280405Srpaulothat are different from those used
2795280405Srpauloby other libraries, to avoid collisions.
2796280405SrpauloTypically, you should use as key a string containing your library name,
2797280405Srpauloor a light userdata with the address of a C&nbsp;object in your code,
2798280405Srpauloor any Lua object created by your code.
2799280405SrpauloAs with variable names,
2800280405Srpaulostring keys starting with an underscore followed by
2801280405Srpaulouppercase letters are reserved for Lua.
2802280405Srpaulo
2803280405Srpaulo
2804280405Srpaulo<p>
2805280405SrpauloThe integer keys in the registry are used
2806280405Srpauloby the reference mechanism (see <a href="#luaL_ref"><code>luaL_ref</code></a>)
2807280405Srpauloand by some predefined values.
2808280405SrpauloTherefore, integer keys must not be used for other purposes.
2809280405Srpaulo
2810280405Srpaulo
2811280405Srpaulo<p>
2812280405SrpauloWhen you create a new Lua state,
2813280405Srpauloits registry comes with some predefined values.
2814280405SrpauloThese predefined values are indexed with integer keys
2815280405Srpaulodefined as constants in <code>lua.h</code>.
2816280405SrpauloThe following constants are defined:
2817280405Srpaulo
2818280405Srpaulo<ul>
2819280405Srpaulo<li><b><a name="pdf-LUA_RIDX_MAINTHREAD"><code>LUA_RIDX_MAINTHREAD</code></a>: </b> At this index the registry has
2820280405Srpaulothe main thread of the state.
2821280405Srpaulo(The main thread is the one created together with the state.)
2822280405Srpaulo</li>
2823280405Srpaulo
2824280405Srpaulo<li><b><a name="pdf-LUA_RIDX_GLOBALS"><code>LUA_RIDX_GLOBALS</code></a>: </b> At this index the registry has
2825280405Srpaulothe global environment.
2826280405Srpaulo</li>
2827280405Srpaulo</ul>
2828280405Srpaulo
2829280405Srpaulo
2830280405Srpaulo
2831280405Srpaulo
2832280405Srpaulo<h2>4.6 &ndash; <a name="4.6">Error Handling in C</a></h2>
2833280405Srpaulo
2834280405Srpaulo<p>
2835280405SrpauloInternally, Lua uses the C <code>longjmp</code> facility to handle errors.
2836280405Srpaulo(Lua will use exceptions if you compile it as C++;
2837280405Srpaulosearch for <code>LUAI_THROW</code> in the source code for details.)
2838280405SrpauloWhen Lua faces any error
2839326344Simp(such as a memory allocation error or a type error)
2840280405Srpauloit <em>raises</em> an error;
2841280405Srpaulothat is, it does a long jump.
2842280405SrpauloA <em>protected environment</em> uses <code>setjmp</code>
2843280405Srpauloto set a recovery point;
2844280405Srpauloany error jumps to the most recent active recovery point.
2845280405Srpaulo
2846280405Srpaulo
2847280405Srpaulo<p>
2848326344SimpInside a C&nbsp;function you can raise an error by calling <a href="#lua_error"><code>lua_error</code></a>.
2849326344Simp
2850326344Simp
2851326344Simp<p>
2852326344SimpMost functions in the API can raise an error,
2853326344Simpfor instance due to a memory allocation error.
2854326344SimpThe documentation for each function indicates whether
2855326344Simpit can raise errors.
2856326344Simp
2857326344Simp
2858326344Simp<p>
2859280405SrpauloIf an error happens outside any protected environment,
2860280405SrpauloLua calls a <em>panic function</em> (see <a href="#lua_atpanic"><code>lua_atpanic</code></a>)
2861280405Srpauloand then calls <code>abort</code>,
2862280405Srpaulothus exiting the host application.
2863280405SrpauloYour panic function can avoid this exit by
2864280405Srpaulonever returning
2865280405Srpaulo(e.g., doing a long jump to your own recovery point outside Lua).
2866280405Srpaulo
2867280405Srpaulo
2868280405Srpaulo<p>
2869326344SimpThe panic function,
2870326344Simpas its name implies,
2871326344Simpis a mechanism of last resort.
2872326344SimpPrograms should avoid it.
2873326344SimpAs a general rule,
2874326344Simpwhen a C&nbsp;function is called by Lua with a Lua state,
2875326344Simpit can do whatever it wants on that Lua state,
2876326344Simpas it should be already protected.
2877326344SimpHowever,
2878326344Simpwhen C code operates on other Lua states
2879344220Skevans(e.g., a Lua argument to the function,
2880326344Simpa Lua state stored in the registry, or
2881326344Simpthe result of <a href="#lua_newthread"><code>lua_newthread</code></a>),
2882326344Simpit should use them only in API calls that cannot raise errors.
2883326344Simp
2884326344Simp
2885326344Simp<p>
2886280405SrpauloThe panic function runs as if it were a message handler (see <a href="#2.3">&sect;2.3</a>);
2887326344Simpin particular, the error object is at the top of the stack.
2888280405SrpauloHowever, there is no guarantee about stack space.
2889280405SrpauloTo push anything on the stack,
2890280405Srpaulothe panic function must first check the available space (see <a href="#4.2">&sect;4.2</a>).
2891280405Srpaulo
2892280405Srpaulo
2893280405Srpaulo
2894280405Srpaulo
2895280405Srpaulo
2896280405Srpaulo<h2>4.7 &ndash; <a name="4.7">Handling Yields in C</a></h2>
2897280405Srpaulo
2898280405Srpaulo<p>
2899280405SrpauloInternally, Lua uses the C <code>longjmp</code> facility to yield a coroutine.
2900326344SimpTherefore, if a C&nbsp;function <code>foo</code> calls an API function
2901280405Srpauloand this API function yields
2902280405Srpaulo(directly or indirectly by calling another function that yields),
2903280405SrpauloLua cannot return to <code>foo</code> any more,
2904280405Srpaulobecause the <code>longjmp</code> removes its frame from the C stack.
2905280405Srpaulo
2906280405Srpaulo
2907280405Srpaulo<p>
2908280405SrpauloTo avoid this kind of problem,
2909280405SrpauloLua raises an error whenever it tries to yield across an API call,
2910280405Srpauloexcept for three functions:
2911280405Srpaulo<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>.
2912280405SrpauloAll those functions receive a <em>continuation function</em>
2913280405Srpaulo(as a parameter named <code>k</code>) to continue execution after a yield.
2914280405Srpaulo
2915280405Srpaulo
2916280405Srpaulo<p>
2917280405SrpauloWe need to set some terminology to explain continuations.
2918326344SimpWe have a C&nbsp;function called from Lua which we will call
2919280405Srpaulothe <em>original function</em>.
2920280405SrpauloThis original function then calls one of those three functions in the C API,
2921280405Srpaulowhich we will call the <em>callee function</em>,
2922280405Srpaulothat then yields the current thread.
2923280405Srpaulo(This can happen when the callee function is <a href="#lua_yieldk"><code>lua_yieldk</code></a>,
2924280405Srpauloor 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>
2925280405Srpauloand the function called by them yields.)
2926280405Srpaulo
2927280405Srpaulo
2928280405Srpaulo<p>
2929280405SrpauloSuppose the running thread yields while executing the callee function.
2930280405SrpauloAfter the thread resumes,
2931280405Srpauloit eventually will finish running the callee function.
2932280405SrpauloHowever,
2933280405Srpaulothe callee function cannot return to the original function,
2934280405Srpaulobecause its frame in the C stack was destroyed by the yield.
2935280405SrpauloInstead, Lua calls a <em>continuation function</em>,
2936280405Srpaulowhich was given as an argument to the callee function.
2937280405SrpauloAs the name implies,
2938280405Srpaulothe continuation function should continue the task
2939280405Srpauloof the original function.
2940280405Srpaulo
2941280405Srpaulo
2942280405Srpaulo<p>
2943280405SrpauloAs an illustration, consider the following function:
2944280405Srpaulo
2945280405Srpaulo<pre>
2946280405Srpaulo     int original_function (lua_State *L) {
2947280405Srpaulo       ...     /* code 1 */
2948280405Srpaulo       status = lua_pcall(L, n, m, h);  /* calls Lua */
2949280405Srpaulo       ...     /* code 2 */
2950280405Srpaulo     }
2951280405Srpaulo</pre><p>
2952280405SrpauloNow we want to allow
2953280405Srpaulothe Lua code being run by <a href="#lua_pcall"><code>lua_pcall</code></a> to yield.
2954280405SrpauloFirst, we can rewrite our function like here:
2955280405Srpaulo
2956280405Srpaulo<pre>
2957280405Srpaulo     int k (lua_State *L, int status, lua_KContext ctx) {
2958280405Srpaulo       ...  /* code 2 */
2959280405Srpaulo     }
2960280405Srpaulo     
2961280405Srpaulo     int original_function (lua_State *L) {
2962280405Srpaulo       ...     /* code 1 */
2963280405Srpaulo       return k(L, lua_pcall(L, n, m, h), ctx);
2964280405Srpaulo     }
2965280405Srpaulo</pre><p>
2966280405SrpauloIn the above code,
2967280405Srpaulothe new function <code>k</code> is a
2968280405Srpaulo<em>continuation function</em> (with type <a href="#lua_KFunction"><code>lua_KFunction</code></a>),
2969280405Srpaulowhich should do all the work that the original function
2970280405Srpaulowas doing after calling <a href="#lua_pcall"><code>lua_pcall</code></a>.
2971280405SrpauloNow, we must inform Lua that it must call <code>k</code> if the Lua code
2972280405Srpaulobeing executed by <a href="#lua_pcall"><code>lua_pcall</code></a> gets interrupted in some way
2973280405Srpaulo(errors or yielding),
2974280405Srpauloso we rewrite the code as here,
2975280405Srpauloreplacing <a href="#lua_pcall"><code>lua_pcall</code></a> by <a href="#lua_pcallk"><code>lua_pcallk</code></a>:
2976280405Srpaulo
2977280405Srpaulo<pre>
2978280405Srpaulo     int original_function (lua_State *L) {
2979280405Srpaulo       ...     /* code 1 */
2980280405Srpaulo       return k(L, lua_pcallk(L, n, m, h, ctx2, k), ctx1);
2981280405Srpaulo     }
2982280405Srpaulo</pre><p>
2983280405SrpauloNote the external, explicit call to the continuation:
2984280405SrpauloLua will call the continuation only if needed, that is,
2985280405Srpauloin case of errors or resuming after a yield.
2986280405SrpauloIf the called function returns normally without ever yielding,
2987280405Srpaulo<a href="#lua_pcallk"><code>lua_pcallk</code></a> (and <a href="#lua_callk"><code>lua_callk</code></a>) will also return normally.
2988280405Srpaulo(Of course, instead of calling the continuation in that case,
2989280405Srpauloyou can do the equivalent work directly inside the original function.)
2990280405Srpaulo
2991280405Srpaulo
2992280405Srpaulo<p>
2993280405SrpauloBesides the Lua state,
2994280405Srpaulothe continuation function has two other parameters:
2995280405Srpaulothe final status of the call plus the context value (<code>ctx</code>) that
2996280405Srpaulowas passed originally to <a href="#lua_pcallk"><code>lua_pcallk</code></a>.
2997280405Srpaulo(Lua does not use this context value;
2998280405Srpauloit only passes this value from the original function to the
2999280405Srpaulocontinuation function.)
3000280405SrpauloFor <a href="#lua_pcallk"><code>lua_pcallk</code></a>,
3001280405Srpaulothe status is the same value that would be returned by <a href="#lua_pcallk"><code>lua_pcallk</code></a>,
3002280405Srpauloexcept that it is <a href="#pdf-LUA_YIELD"><code>LUA_YIELD</code></a> when being executed after a yield
3003280405Srpaulo(instead of <a href="#pdf-LUA_OK"><code>LUA_OK</code></a>).
3004280405SrpauloFor <a href="#lua_yieldk"><code>lua_yieldk</code></a> and <a href="#lua_callk"><code>lua_callk</code></a>,
3005280405Srpaulothe status is always <a href="#pdf-LUA_YIELD"><code>LUA_YIELD</code></a> when Lua calls the continuation.
3006280405Srpaulo(For these two functions,
3007280405SrpauloLua will not call the continuation in case of errors,
3008280405Srpaulobecause they do not handle errors.)
3009280405SrpauloSimilarly, when using <a href="#lua_callk"><code>lua_callk</code></a>,
3010280405Srpauloyou should call the continuation function
3011280405Srpaulowith <a href="#pdf-LUA_OK"><code>LUA_OK</code></a> as the status.
3012280405Srpaulo(For <a href="#lua_yieldk"><code>lua_yieldk</code></a>, there is not much point in calling
3013280405Srpaulodirectly the continuation function,
3014280405Srpaulobecause <a href="#lua_yieldk"><code>lua_yieldk</code></a> usually does not return.)
3015280405Srpaulo
3016280405Srpaulo
3017280405Srpaulo<p>
3018280405SrpauloLua treats the continuation function as if it were the original function.
3019280405SrpauloThe continuation function receives the same Lua stack
3020280405Srpaulofrom the original function,
3021280405Srpauloin the same state it would be if the callee function had returned.
3022280405Srpaulo(For instance,
3023280405Srpauloafter a <a href="#lua_callk"><code>lua_callk</code></a> the function and its arguments are
3024280405Srpauloremoved from the stack and replaced by the results from the call.)
3025280405SrpauloIt also has the same upvalues.
3026280405SrpauloWhatever it returns is handled by Lua as if it were the return
3027280405Srpauloof the original function.
3028280405Srpaulo
3029280405Srpaulo
3030280405Srpaulo
3031280405Srpaulo
3032280405Srpaulo
3033280405Srpaulo<h2>4.8 &ndash; <a name="4.8">Functions and Types</a></h2>
3034280405Srpaulo
3035280405Srpaulo<p>
3036280405SrpauloHere we list all functions and types from the C&nbsp;API in
3037280405Srpauloalphabetical order.
3038280405SrpauloEach function has an indicator like this:
3039280405Srpaulo<span class="apii">[-o, +p, <em>x</em>]</span>
3040280405Srpaulo
3041280405Srpaulo
3042280405Srpaulo<p>
3043280405SrpauloThe first field, <code>o</code>,
3044280405Srpaulois how many elements the function pops from the stack.
3045280405SrpauloThe second field, <code>p</code>,
3046280405Srpaulois how many elements the function pushes onto the stack.
3047280405Srpaulo(Any function always pushes its results after popping its arguments.)
3048280405SrpauloA field in the form <code>x|y</code> means the function can push (or pop)
3049280405Srpaulo<code>x</code> or <code>y</code> elements,
3050280405Srpaulodepending on the situation;
3051280405Srpauloan interrogation mark '<code>?</code>' means that
3052280405Srpaulowe cannot know how many elements the function pops/pushes
3053280405Srpauloby looking only at its arguments
3054280405Srpaulo(e.g., they may depend on what is on the stack).
3055280405SrpauloThe third field, <code>x</code>,
3056280405Srpaulotells whether the function may raise errors:
3057280405Srpaulo'<code>-</code>' means the function never raises any error;
3058326344Simp'<code>m</code>' means the function may raise out-of-memory errors
3059326344Simpand errors running a <code>__gc</code> metamethod;
3060326344Simp'<code>e</code>' means the function may raise any errors
3061326344Simp(it can run arbitrary Lua code,
3062326344Simpeither directly or through metamethods);
3063280405Srpaulo'<code>v</code>' means the function may raise an error on purpose.
3064280405Srpaulo
3065280405Srpaulo
3066280405Srpaulo
3067280405Srpaulo<hr><h3><a name="lua_absindex"><code>lua_absindex</code></a></h3><p>
3068280405Srpaulo<span class="apii">[-0, +0, &ndash;]</span>
3069280405Srpaulo<pre>int lua_absindex (lua_State *L, int idx);</pre>
3070280405Srpaulo
3071280405Srpaulo<p>
3072326344SimpConverts the acceptable index <code>idx</code>
3073326344Simpinto an equivalent absolute index
3074280405Srpaulo(that is, one that does not depend on the stack top).
3075280405Srpaulo
3076280405Srpaulo
3077280405Srpaulo
3078280405Srpaulo
3079280405Srpaulo
3080280405Srpaulo<hr><h3><a name="lua_Alloc"><code>lua_Alloc</code></a></h3>
3081280405Srpaulo<pre>typedef void * (*lua_Alloc) (void *ud,
3082280405Srpaulo                             void *ptr,
3083280405Srpaulo                             size_t osize,
3084280405Srpaulo                             size_t nsize);</pre>
3085280405Srpaulo
3086280405Srpaulo<p>
3087280405SrpauloThe type of the memory-allocation function used by Lua states.
3088280405SrpauloThe allocator function must provide a
3089280405Srpaulofunctionality similar to <code>realloc</code>,
3090280405Srpaulobut not exactly the same.
3091280405SrpauloIts arguments are
3092280405Srpaulo<code>ud</code>, an opaque pointer passed to <a href="#lua_newstate"><code>lua_newstate</code></a>;
3093280405Srpaulo<code>ptr</code>, a pointer to the block being allocated/reallocated/freed;
3094280405Srpaulo<code>osize</code>, the original size of the block or some code about what
3095280405Srpaulois being allocated;
3096280405Srpauloand <code>nsize</code>, the new size of the block.
3097280405Srpaulo
3098280405Srpaulo
3099280405Srpaulo<p>
3100280405SrpauloWhen <code>ptr</code> is not <code>NULL</code>,
3101280405Srpaulo<code>osize</code> is the size of the block pointed by <code>ptr</code>,
3102280405Srpaulothat is, the size given when it was allocated or reallocated.
3103280405Srpaulo
3104280405Srpaulo
3105280405Srpaulo<p>
3106280405SrpauloWhen <code>ptr</code> is <code>NULL</code>,
3107280405Srpaulo<code>osize</code> encodes the kind of object that Lua is allocating.
3108280405Srpaulo<code>osize</code> is any of
3109280405Srpaulo<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>,
3110280405Srpaulo<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)
3111280405SrpauloLua is creating a new object of that type.
3112280405SrpauloWhen <code>osize</code> is some other value,
3113280405SrpauloLua is allocating memory for something else.
3114280405Srpaulo
3115280405Srpaulo
3116280405Srpaulo<p>
3117280405SrpauloLua assumes the following behavior from the allocator function:
3118280405Srpaulo
3119280405Srpaulo
3120280405Srpaulo<p>
3121280405SrpauloWhen <code>nsize</code> is zero,
3122280405Srpaulothe allocator must behave like <code>free</code>
3123280405Srpauloand return <code>NULL</code>.
3124280405Srpaulo
3125280405Srpaulo
3126280405Srpaulo<p>
3127280405SrpauloWhen <code>nsize</code> is not zero,
3128280405Srpaulothe allocator must behave like <code>realloc</code>.
3129280405SrpauloThe allocator returns <code>NULL</code>
3130280405Srpauloif and only if it cannot fulfill the request.
3131280405SrpauloLua assumes that the allocator never fails when
3132280405Srpaulo<code>osize &gt;= nsize</code>.
3133280405Srpaulo
3134280405Srpaulo
3135280405Srpaulo<p>
3136280405SrpauloHere is a simple implementation for the allocator function.
3137280405SrpauloIt is used in the auxiliary library by <a href="#luaL_newstate"><code>luaL_newstate</code></a>.
3138280405Srpaulo
3139280405Srpaulo<pre>
3140280405Srpaulo     static void *l_alloc (void *ud, void *ptr, size_t osize,
3141280405Srpaulo                                                size_t nsize) {
3142280405Srpaulo       (void)ud;  (void)osize;  /* not used */
3143280405Srpaulo       if (nsize == 0) {
3144280405Srpaulo         free(ptr);
3145280405Srpaulo         return NULL;
3146280405Srpaulo       }
3147280405Srpaulo       else
3148280405Srpaulo         return realloc(ptr, nsize);
3149280405Srpaulo     }
3150280405Srpaulo</pre><p>
3151280405SrpauloNote that Standard&nbsp;C ensures
3152280405Srpaulothat <code>free(NULL)</code> has no effect and that
3153280405Srpaulo<code>realloc(NULL,size)</code> is equivalent to <code>malloc(size)</code>.
3154280405SrpauloThis code assumes that <code>realloc</code> does not fail when shrinking a block.
3155280405Srpaulo(Although Standard&nbsp;C does not ensure this behavior,
3156280405Srpauloit seems to be a safe assumption.)
3157280405Srpaulo
3158280405Srpaulo
3159280405Srpaulo
3160280405Srpaulo
3161280405Srpaulo
3162280405Srpaulo<hr><h3><a name="lua_arith"><code>lua_arith</code></a></h3><p>
3163280405Srpaulo<span class="apii">[-(2|1), +1, <em>e</em>]</span>
3164280405Srpaulo<pre>void lua_arith (lua_State *L, int op);</pre>
3165280405Srpaulo
3166280405Srpaulo<p>
3167280405SrpauloPerforms an arithmetic or bitwise operation over the two values
3168280405Srpaulo(or one, in the case of negations)
3169280405Srpauloat the top of the stack,
3170280405Srpaulowith the value at the top being the second operand,
3171280405Srpaulopops these values, and pushes the result of the operation.
3172280405SrpauloThe function follows the semantics of the corresponding Lua operator
3173280405Srpaulo(that is, it may call metamethods).
3174280405Srpaulo
3175280405Srpaulo
3176280405Srpaulo<p>
3177280405SrpauloThe value of <code>op</code> must be one of the following constants:
3178280405Srpaulo
3179280405Srpaulo<ul>
3180280405Srpaulo
3181280405Srpaulo<li><b><a name="pdf-LUA_OPADD"><code>LUA_OPADD</code></a>: </b> performs addition (<code>+</code>)</li>
3182280405Srpaulo<li><b><a name="pdf-LUA_OPSUB"><code>LUA_OPSUB</code></a>: </b> performs subtraction (<code>-</code>)</li>
3183280405Srpaulo<li><b><a name="pdf-LUA_OPMUL"><code>LUA_OPMUL</code></a>: </b> performs multiplication (<code>*</code>)</li>
3184280405Srpaulo<li><b><a name="pdf-LUA_OPDIV"><code>LUA_OPDIV</code></a>: </b> performs float division (<code>/</code>)</li>
3185280405Srpaulo<li><b><a name="pdf-LUA_OPIDIV"><code>LUA_OPIDIV</code></a>: </b> performs floor division (<code>//</code>)</li>
3186280405Srpaulo<li><b><a name="pdf-LUA_OPMOD"><code>LUA_OPMOD</code></a>: </b> performs modulo (<code>%</code>)</li>
3187280405Srpaulo<li><b><a name="pdf-LUA_OPPOW"><code>LUA_OPPOW</code></a>: </b> performs exponentiation (<code>^</code>)</li>
3188280405Srpaulo<li><b><a name="pdf-LUA_OPUNM"><code>LUA_OPUNM</code></a>: </b> performs mathematical negation (unary <code>-</code>)</li>
3189326344Simp<li><b><a name="pdf-LUA_OPBNOT"><code>LUA_OPBNOT</code></a>: </b> performs bitwise NOT (<code>~</code>)</li>
3190326344Simp<li><b><a name="pdf-LUA_OPBAND"><code>LUA_OPBAND</code></a>: </b> performs bitwise AND (<code>&amp;</code>)</li>
3191326344Simp<li><b><a name="pdf-LUA_OPBOR"><code>LUA_OPBOR</code></a>: </b> performs bitwise OR (<code>|</code>)</li>
3192326344Simp<li><b><a name="pdf-LUA_OPBXOR"><code>LUA_OPBXOR</code></a>: </b> performs bitwise exclusive OR (<code>~</code>)</li>
3193280405Srpaulo<li><b><a name="pdf-LUA_OPSHL"><code>LUA_OPSHL</code></a>: </b> performs left shift (<code>&lt;&lt;</code>)</li>
3194280405Srpaulo<li><b><a name="pdf-LUA_OPSHR"><code>LUA_OPSHR</code></a>: </b> performs right shift (<code>&gt;&gt;</code>)</li>
3195280405Srpaulo
3196280405Srpaulo</ul>
3197280405Srpaulo
3198280405Srpaulo
3199280405Srpaulo
3200280405Srpaulo
3201280405Srpaulo<hr><h3><a name="lua_atpanic"><code>lua_atpanic</code></a></h3><p>
3202280405Srpaulo<span class="apii">[-0, +0, &ndash;]</span>
3203280405Srpaulo<pre>lua_CFunction lua_atpanic (lua_State *L, lua_CFunction panicf);</pre>
3204280405Srpaulo
3205280405Srpaulo<p>
3206280405SrpauloSets a new panic function and returns the old one (see <a href="#4.6">&sect;4.6</a>).
3207280405Srpaulo
3208280405Srpaulo
3209280405Srpaulo
3210280405Srpaulo
3211280405Srpaulo
3212280405Srpaulo<hr><h3><a name="lua_call"><code>lua_call</code></a></h3><p>
3213280405Srpaulo<span class="apii">[-(nargs+1), +nresults, <em>e</em>]</span>
3214280405Srpaulo<pre>void lua_call (lua_State *L, int nargs, int nresults);</pre>
3215280405Srpaulo
3216280405Srpaulo<p>
3217280405SrpauloCalls a function.
3218280405Srpaulo
3219280405Srpaulo
3220280405Srpaulo<p>
3221280405SrpauloTo call a function you must use the following protocol:
3222280405Srpaulofirst, the function to be called is pushed onto the stack;
3223280405Srpaulothen, the arguments to the function are pushed
3224280405Srpauloin direct order;
3225280405Srpaulothat is, the first argument is pushed first.
3226280405SrpauloFinally you call <a href="#lua_call"><code>lua_call</code></a>;
3227280405Srpaulo<code>nargs</code> is the number of arguments that you pushed onto the stack.
3228280405SrpauloAll arguments and the function value are popped from the stack
3229280405Srpaulowhen the function is called.
3230280405SrpauloThe function results are pushed onto the stack when the function returns.
3231280405SrpauloThe number of results is adjusted to <code>nresults</code>,
3232280405Srpaulounless <code>nresults</code> is <a name="pdf-LUA_MULTRET"><code>LUA_MULTRET</code></a>.
3233326344SimpIn this case, all results from the function are pushed;
3234326344SimpLua takes care that the returned values fit into the stack space,
3235326344Simpbut it does not ensure any extra space in the stack.
3236280405SrpauloThe function results are pushed onto the stack in direct order
3237280405Srpaulo(the first result is pushed first),
3238280405Srpauloso that after the call the last result is on the top of the stack.
3239280405Srpaulo
3240280405Srpaulo
3241280405Srpaulo<p>
3242280405SrpauloAny error inside the called function is propagated upwards
3243280405Srpaulo(with a <code>longjmp</code>).
3244280405Srpaulo
3245280405Srpaulo
3246280405Srpaulo<p>
3247280405SrpauloThe following example shows how the host program can do the
3248280405Srpauloequivalent to this Lua code:
3249280405Srpaulo
3250280405Srpaulo<pre>
3251280405Srpaulo     a = f("how", t.x, 14)
3252280405Srpaulo</pre><p>
3253280405SrpauloHere it is in&nbsp;C:
3254280405Srpaulo
3255280405Srpaulo<pre>
3256280405Srpaulo     lua_getglobal(L, "f");                  /* function to be called */
3257280405Srpaulo     lua_pushliteral(L, "how");                       /* 1st argument */
3258280405Srpaulo     lua_getglobal(L, "t");                    /* table to be indexed */
3259280405Srpaulo     lua_getfield(L, -1, "x");        /* push result of t.x (2nd arg) */
3260280405Srpaulo     lua_remove(L, -2);                  /* remove 't' from the stack */
3261280405Srpaulo     lua_pushinteger(L, 14);                          /* 3rd argument */
3262280405Srpaulo     lua_call(L, 3, 1);     /* call 'f' with 3 arguments and 1 result */
3263280405Srpaulo     lua_setglobal(L, "a");                         /* set global 'a' */
3264280405Srpaulo</pre><p>
3265280405SrpauloNote that the code above is <em>balanced</em>:
3266280405Srpauloat its end, the stack is back to its original configuration.
3267280405SrpauloThis is considered good programming practice.
3268280405Srpaulo
3269280405Srpaulo
3270280405Srpaulo
3271280405Srpaulo
3272280405Srpaulo
3273280405Srpaulo<hr><h3><a name="lua_callk"><code>lua_callk</code></a></h3><p>
3274280405Srpaulo<span class="apii">[-(nargs + 1), +nresults, <em>e</em>]</span>
3275280405Srpaulo<pre>void lua_callk (lua_State *L,
3276280405Srpaulo                int nargs,
3277280405Srpaulo                int nresults,
3278280405Srpaulo                lua_KContext ctx,
3279280405Srpaulo                lua_KFunction k);</pre>
3280280405Srpaulo
3281280405Srpaulo<p>
3282280405SrpauloThis function behaves exactly like <a href="#lua_call"><code>lua_call</code></a>,
3283280405Srpaulobut allows the called function to yield (see <a href="#4.7">&sect;4.7</a>).
3284280405Srpaulo
3285280405Srpaulo
3286280405Srpaulo
3287280405Srpaulo
3288280405Srpaulo
3289280405Srpaulo<hr><h3><a name="lua_CFunction"><code>lua_CFunction</code></a></h3>
3290280405Srpaulo<pre>typedef int (*lua_CFunction) (lua_State *L);</pre>
3291280405Srpaulo
3292280405Srpaulo<p>
3293280405SrpauloType for C&nbsp;functions.
3294280405Srpaulo
3295280405Srpaulo
3296280405Srpaulo<p>
3297280405SrpauloIn order to communicate properly with Lua,
3298280405Srpauloa C&nbsp;function must use the following protocol,
3299280405Srpaulowhich defines the way parameters and results are passed:
3300280405Srpauloa C&nbsp;function receives its arguments from Lua in its stack
3301280405Srpauloin direct order (the first argument is pushed first).
3302280405SrpauloSo, when the function starts,
3303280405Srpaulo<code>lua_gettop(L)</code> returns the number of arguments received by the function.
3304280405SrpauloThe first argument (if any) is at index 1
3305280405Srpauloand its last argument is at index <code>lua_gettop(L)</code>.
3306280405SrpauloTo return values to Lua, a C&nbsp;function just pushes them onto the stack,
3307280405Srpauloin direct order (the first result is pushed first),
3308280405Srpauloand returns the number of results.
3309280405SrpauloAny other value in the stack below the results will be properly
3310280405Srpaulodiscarded by Lua.
3311280405SrpauloLike a Lua function, a C&nbsp;function called by Lua can also return
3312280405Srpaulomany results.
3313280405Srpaulo
3314280405Srpaulo
3315280405Srpaulo<p>
3316280405SrpauloAs an example, the following function receives a variable number
3317326344Simpof numeric arguments and returns their average and their sum:
3318280405Srpaulo
3319280405Srpaulo<pre>
3320280405Srpaulo     static int foo (lua_State *L) {
3321280405Srpaulo       int n = lua_gettop(L);    /* number of arguments */
3322280405Srpaulo       lua_Number sum = 0.0;
3323280405Srpaulo       int i;
3324280405Srpaulo       for (i = 1; i &lt;= n; i++) {
3325280405Srpaulo         if (!lua_isnumber(L, i)) {
3326280405Srpaulo           lua_pushliteral(L, "incorrect argument");
3327280405Srpaulo           lua_error(L);
3328280405Srpaulo         }
3329280405Srpaulo         sum += lua_tonumber(L, i);
3330280405Srpaulo       }
3331280405Srpaulo       lua_pushnumber(L, sum/n);        /* first result */
3332280405Srpaulo       lua_pushnumber(L, sum);         /* second result */
3333280405Srpaulo       return 2;                   /* number of results */
3334280405Srpaulo     }
3335280405Srpaulo</pre>
3336280405Srpaulo
3337280405Srpaulo
3338280405Srpaulo
3339280405Srpaulo
3340280405Srpaulo<hr><h3><a name="lua_checkstack"><code>lua_checkstack</code></a></h3><p>
3341280405Srpaulo<span class="apii">[-0, +0, &ndash;]</span>
3342280405Srpaulo<pre>int lua_checkstack (lua_State *L, int n);</pre>
3343280405Srpaulo
3344280405Srpaulo<p>
3345326344SimpEnsures that the stack has space for at least <code>n</code> extra slots
3346326344Simp(that is, that you can safely push up to <code>n</code> values into it).
3347280405SrpauloIt returns false if it cannot fulfill the request,
3348280405Srpauloeither because it would cause the stack
3349280405Srpauloto be larger than a fixed maximum size
3350280405Srpaulo(typically at least several thousand elements) or
3351280405Srpaulobecause it cannot allocate memory for the extra space.
3352280405SrpauloThis function never shrinks the stack;
3353326344Simpif the stack already has space for the extra slots,
3354280405Srpauloit is left unchanged.
3355280405Srpaulo
3356280405Srpaulo
3357280405Srpaulo
3358280405Srpaulo
3359280405Srpaulo
3360280405Srpaulo<hr><h3><a name="lua_close"><code>lua_close</code></a></h3><p>
3361280405Srpaulo<span class="apii">[-0, +0, &ndash;]</span>
3362280405Srpaulo<pre>void lua_close (lua_State *L);</pre>
3363280405Srpaulo
3364280405Srpaulo<p>
3365280405SrpauloDestroys all objects in the given Lua state
3366280405Srpaulo(calling the corresponding garbage-collection metamethods, if any)
3367280405Srpauloand frees all dynamic memory used by this state.
3368344220SkevansIn several platforms, you may not need to call this function,
3369280405Srpaulobecause all resources are naturally released when the host program ends.
3370280405SrpauloOn the other hand, long-running programs that create multiple states,
3371280405Srpaulosuch as daemons or web servers,
3372280405Srpaulowill probably need to close states as soon as they are not needed.
3373280405Srpaulo
3374280405Srpaulo
3375280405Srpaulo
3376280405Srpaulo
3377280405Srpaulo
3378280405Srpaulo<hr><h3><a name="lua_compare"><code>lua_compare</code></a></h3><p>
3379280405Srpaulo<span class="apii">[-0, +0, <em>e</em>]</span>
3380280405Srpaulo<pre>int lua_compare (lua_State *L, int index1, int index2, int op);</pre>
3381280405Srpaulo
3382280405Srpaulo<p>
3383280405SrpauloCompares two Lua values.
3384280405SrpauloReturns 1 if the value at index <code>index1</code> satisfies <code>op</code>
3385280405Srpaulowhen compared with the value at index <code>index2</code>,
3386280405Srpaulofollowing the semantics of the corresponding Lua operator
3387280405Srpaulo(that is, it may call metamethods).
3388280405SrpauloOtherwise returns&nbsp;0.
3389280405SrpauloAlso returns&nbsp;0 if any of the indices is not valid.
3390280405Srpaulo
3391280405Srpaulo
3392280405Srpaulo<p>
3393280405SrpauloThe value of <code>op</code> must be one of the following constants:
3394280405Srpaulo
3395280405Srpaulo<ul>
3396280405Srpaulo
3397280405Srpaulo<li><b><a name="pdf-LUA_OPEQ"><code>LUA_OPEQ</code></a>: </b> compares for equality (<code>==</code>)</li>
3398280405Srpaulo<li><b><a name="pdf-LUA_OPLT"><code>LUA_OPLT</code></a>: </b> compares for less than (<code>&lt;</code>)</li>
3399280405Srpaulo<li><b><a name="pdf-LUA_OPLE"><code>LUA_OPLE</code></a>: </b> compares for less or equal (<code>&lt;=</code>)</li>
3400280405Srpaulo
3401280405Srpaulo</ul>
3402280405Srpaulo
3403280405Srpaulo
3404280405Srpaulo
3405280405Srpaulo
3406280405Srpaulo<hr><h3><a name="lua_concat"><code>lua_concat</code></a></h3><p>
3407280405Srpaulo<span class="apii">[-n, +1, <em>e</em>]</span>
3408280405Srpaulo<pre>void lua_concat (lua_State *L, int n);</pre>
3409280405Srpaulo
3410280405Srpaulo<p>
3411280405SrpauloConcatenates the <code>n</code> values at the top of the stack,
3412280405Srpaulopops them, and leaves the result at the top.
3413280405SrpauloIf <code>n</code>&nbsp;is&nbsp;1, the result is the single value on the stack
3414280405Srpaulo(that is, the function does nothing);
3415280405Srpauloif <code>n</code> is 0, the result is the empty string.
3416280405SrpauloConcatenation is performed following the usual semantics of Lua
3417280405Srpaulo(see <a href="#3.4.6">&sect;3.4.6</a>).
3418280405Srpaulo
3419280405Srpaulo
3420280405Srpaulo
3421280405Srpaulo
3422280405Srpaulo
3423280405Srpaulo<hr><h3><a name="lua_copy"><code>lua_copy</code></a></h3><p>
3424280405Srpaulo<span class="apii">[-0, +0, &ndash;]</span>
3425280405Srpaulo<pre>void lua_copy (lua_State *L, int fromidx, int toidx);</pre>
3426280405Srpaulo
3427280405Srpaulo<p>
3428280405SrpauloCopies the element at index <code>fromidx</code>
3429280405Srpaulointo the valid index <code>toidx</code>,
3430280405Srpauloreplacing the value at that position.
3431280405SrpauloValues at other positions are not affected.
3432280405Srpaulo
3433280405Srpaulo
3434280405Srpaulo
3435280405Srpaulo
3436280405Srpaulo
3437280405Srpaulo<hr><h3><a name="lua_createtable"><code>lua_createtable</code></a></h3><p>
3438326344Simp<span class="apii">[-0, +1, <em>m</em>]</span>
3439280405Srpaulo<pre>void lua_createtable (lua_State *L, int narr, int nrec);</pre>
3440280405Srpaulo
3441280405Srpaulo<p>
3442280405SrpauloCreates a new empty table and pushes it onto the stack.
3443280405SrpauloParameter <code>narr</code> is a hint for how many elements the table
3444280405Srpaulowill have as a sequence;
3445280405Srpauloparameter <code>nrec</code> is a hint for how many other elements
3446280405Srpaulothe table will have.
3447280405SrpauloLua may use these hints to preallocate memory for the new table.
3448326344SimpThis preallocation is useful for performance when you know in advance
3449280405Srpaulohow many elements the table will have.
3450280405SrpauloOtherwise you can use the function <a href="#lua_newtable"><code>lua_newtable</code></a>.
3451280405Srpaulo
3452280405Srpaulo
3453280405Srpaulo
3454280405Srpaulo
3455280405Srpaulo
3456280405Srpaulo<hr><h3><a name="lua_dump"><code>lua_dump</code></a></h3><p>
3457326344Simp<span class="apii">[-0, +0, &ndash;]</span>
3458280405Srpaulo<pre>int lua_dump (lua_State *L,
3459280405Srpaulo                        lua_Writer writer,
3460280405Srpaulo                        void *data,
3461280405Srpaulo                        int strip);</pre>
3462280405Srpaulo
3463280405Srpaulo<p>
3464280405SrpauloDumps a function as a binary chunk.
3465280405SrpauloReceives a Lua function on the top of the stack
3466280405Srpauloand produces a binary chunk that,
3467280405Srpauloif loaded again,
3468280405Srpauloresults in a function equivalent to the one dumped.
3469280405SrpauloAs it produces parts of the chunk,
3470280405Srpaulo<a href="#lua_dump"><code>lua_dump</code></a> calls function <code>writer</code> (see <a href="#lua_Writer"><code>lua_Writer</code></a>)
3471280405Srpaulowith the given <code>data</code>
3472280405Srpauloto write them.
3473280405Srpaulo
3474280405Srpaulo
3475280405Srpaulo<p>
3476280405SrpauloIf <code>strip</code> is true,
3477326344Simpthe binary representation may not include all debug information
3478326344Simpabout the function,
3479326344Simpto save space.
3480280405Srpaulo
3481280405Srpaulo
3482280405Srpaulo<p>
3483280405SrpauloThe value returned is the error code returned by the last
3484280405Srpaulocall to the writer;
3485280405Srpaulo0&nbsp;means no errors.
3486280405Srpaulo
3487280405Srpaulo
3488280405Srpaulo<p>
3489280405SrpauloThis function does not pop the Lua function from the stack.
3490280405Srpaulo
3491280405Srpaulo
3492280405Srpaulo
3493280405Srpaulo
3494280405Srpaulo
3495280405Srpaulo<hr><h3><a name="lua_error"><code>lua_error</code></a></h3><p>
3496280405Srpaulo<span class="apii">[-1, +0, <em>v</em>]</span>
3497280405Srpaulo<pre>int lua_error (lua_State *L);</pre>
3498280405Srpaulo
3499280405Srpaulo<p>
3500280405SrpauloGenerates a Lua error,
3501280405Srpaulousing the value at the top of the stack as the error object.
3502280405SrpauloThis function does a long jump,
3503280405Srpauloand therefore never returns
3504280405Srpaulo(see <a href="#luaL_error"><code>luaL_error</code></a>).
3505280405Srpaulo
3506280405Srpaulo
3507280405Srpaulo
3508280405Srpaulo
3509280405Srpaulo
3510280405Srpaulo<hr><h3><a name="lua_gc"><code>lua_gc</code></a></h3><p>
3511326344Simp<span class="apii">[-0, +0, <em>m</em>]</span>
3512280405Srpaulo<pre>int lua_gc (lua_State *L, int what, int data);</pre>
3513280405Srpaulo
3514280405Srpaulo<p>
3515280405SrpauloControls the garbage collector.
3516280405Srpaulo
3517280405Srpaulo
3518280405Srpaulo<p>
3519280405SrpauloThis function performs several tasks,
3520280405Srpauloaccording to the value of the parameter <code>what</code>:
3521280405Srpaulo
3522280405Srpaulo<ul>
3523280405Srpaulo
3524280405Srpaulo<li><b><code>LUA_GCSTOP</code>: </b>
3525280405Srpaulostops the garbage collector.
3526280405Srpaulo</li>
3527280405Srpaulo
3528280405Srpaulo<li><b><code>LUA_GCRESTART</code>: </b>
3529280405Srpaulorestarts the garbage collector.
3530280405Srpaulo</li>
3531280405Srpaulo
3532280405Srpaulo<li><b><code>LUA_GCCOLLECT</code>: </b>
3533280405Srpauloperforms a full garbage-collection cycle.
3534280405Srpaulo</li>
3535280405Srpaulo
3536280405Srpaulo<li><b><code>LUA_GCCOUNT</code>: </b>
3537280405Srpauloreturns the current amount of memory (in Kbytes) in use by Lua.
3538280405Srpaulo</li>
3539280405Srpaulo
3540280405Srpaulo<li><b><code>LUA_GCCOUNTB</code>: </b>
3541280405Srpauloreturns the remainder of dividing the current amount of bytes of
3542280405Srpaulomemory in use by Lua by 1024.
3543280405Srpaulo</li>
3544280405Srpaulo
3545280405Srpaulo<li><b><code>LUA_GCSTEP</code>: </b>
3546280405Srpauloperforms an incremental step of garbage collection.
3547280405Srpaulo</li>
3548280405Srpaulo
3549280405Srpaulo<li><b><code>LUA_GCSETPAUSE</code>: </b>
3550280405Srpaulosets <code>data</code> as the new value
3551280405Srpaulofor the <em>pause</em> of the collector (see <a href="#2.5">&sect;2.5</a>)
3552280405Srpauloand returns the previous value of the pause.
3553280405Srpaulo</li>
3554280405Srpaulo
3555280405Srpaulo<li><b><code>LUA_GCSETSTEPMUL</code>: </b>
3556280405Srpaulosets <code>data</code> as the new value for the <em>step multiplier</em> of
3557280405Srpaulothe collector (see <a href="#2.5">&sect;2.5</a>)
3558280405Srpauloand returns the previous value of the step multiplier.
3559280405Srpaulo</li>
3560280405Srpaulo
3561280405Srpaulo<li><b><code>LUA_GCISRUNNING</code>: </b>
3562280405Srpauloreturns a boolean that tells whether the collector is running
3563280405Srpaulo(i.e., not stopped).
3564280405Srpaulo</li>
3565280405Srpaulo
3566280405Srpaulo</ul>
3567280405Srpaulo
3568280405Srpaulo<p>
3569280405SrpauloFor more details about these options,
3570280405Srpaulosee <a href="#pdf-collectgarbage"><code>collectgarbage</code></a>.
3571280405Srpaulo
3572280405Srpaulo
3573280405Srpaulo
3574280405Srpaulo
3575280405Srpaulo
3576280405Srpaulo<hr><h3><a name="lua_getallocf"><code>lua_getallocf</code></a></h3><p>
3577280405Srpaulo<span class="apii">[-0, +0, &ndash;]</span>
3578280405Srpaulo<pre>lua_Alloc lua_getallocf (lua_State *L, void **ud);</pre>
3579280405Srpaulo
3580280405Srpaulo<p>
3581280405SrpauloReturns the memory-allocation function of a given state.
3582280405SrpauloIf <code>ud</code> is not <code>NULL</code>, Lua stores in <code>*ud</code> the
3583280405Srpauloopaque pointer given when the memory-allocator function was set.
3584280405Srpaulo
3585280405Srpaulo
3586280405Srpaulo
3587280405Srpaulo
3588280405Srpaulo
3589280405Srpaulo<hr><h3><a name="lua_getfield"><code>lua_getfield</code></a></h3><p>
3590280405Srpaulo<span class="apii">[-0, +1, <em>e</em>]</span>
3591280405Srpaulo<pre>int lua_getfield (lua_State *L, int index, const char *k);</pre>
3592280405Srpaulo
3593280405Srpaulo<p>
3594280405SrpauloPushes onto the stack the value <code>t[k]</code>,
3595280405Srpaulowhere <code>t</code> is the value at the given index.
3596280405SrpauloAs in Lua, this function may trigger a metamethod
3597280405Srpaulofor the "index" event (see <a href="#2.4">&sect;2.4</a>).
3598280405Srpaulo
3599280405Srpaulo
3600280405Srpaulo<p>
3601280405SrpauloReturns the type of the pushed value.
3602280405Srpaulo
3603280405Srpaulo
3604280405Srpaulo
3605280405Srpaulo
3606280405Srpaulo
3607280405Srpaulo<hr><h3><a name="lua_getextraspace"><code>lua_getextraspace</code></a></h3><p>
3608280405Srpaulo<span class="apii">[-0, +0, &ndash;]</span>
3609280405Srpaulo<pre>void *lua_getextraspace (lua_State *L);</pre>
3610280405Srpaulo
3611280405Srpaulo<p>
3612280405SrpauloReturns a pointer to a raw memory area associated with the
3613280405Srpaulogiven Lua state.
3614280405SrpauloThe application can use this area for any purpose;
3615280405SrpauloLua does not use it for anything.
3616280405Srpaulo
3617280405Srpaulo
3618280405Srpaulo<p>
3619280405SrpauloEach new thread has this area initialized with a copy
3620280405Srpauloof the area of the main thread.
3621280405Srpaulo
3622280405Srpaulo
3623280405Srpaulo<p>
3624280405SrpauloBy default, this area has the size of a pointer to void,
3625280405Srpaulobut you can recompile Lua with a different size for this area.
3626280405Srpaulo(See <code>LUA_EXTRASPACE</code> in <code>luaconf.h</code>.)
3627280405Srpaulo
3628280405Srpaulo
3629280405Srpaulo
3630280405Srpaulo
3631280405Srpaulo
3632280405Srpaulo<hr><h3><a name="lua_getglobal"><code>lua_getglobal</code></a></h3><p>
3633280405Srpaulo<span class="apii">[-0, +1, <em>e</em>]</span>
3634280405Srpaulo<pre>int lua_getglobal (lua_State *L, const char *name);</pre>
3635280405Srpaulo
3636280405Srpaulo<p>
3637280405SrpauloPushes onto the stack the value of the global <code>name</code>.
3638280405SrpauloReturns the type of that value.
3639280405Srpaulo
3640280405Srpaulo
3641280405Srpaulo
3642280405Srpaulo
3643280405Srpaulo
3644280405Srpaulo<hr><h3><a name="lua_geti"><code>lua_geti</code></a></h3><p>
3645280405Srpaulo<span class="apii">[-0, +1, <em>e</em>]</span>
3646280405Srpaulo<pre>int lua_geti (lua_State *L, int index, lua_Integer i);</pre>
3647280405Srpaulo
3648280405Srpaulo<p>
3649280405SrpauloPushes onto the stack the value <code>t[i]</code>,
3650280405Srpaulowhere <code>t</code> is the value at the given index.
3651280405SrpauloAs in Lua, this function may trigger a metamethod
3652280405Srpaulofor the "index" event (see <a href="#2.4">&sect;2.4</a>).
3653280405Srpaulo
3654280405Srpaulo
3655280405Srpaulo<p>
3656280405SrpauloReturns the type of the pushed value.
3657280405Srpaulo
3658280405Srpaulo
3659280405Srpaulo
3660280405Srpaulo
3661280405Srpaulo
3662280405Srpaulo<hr><h3><a name="lua_getmetatable"><code>lua_getmetatable</code></a></h3><p>
3663280405Srpaulo<span class="apii">[-0, +(0|1), &ndash;]</span>
3664280405Srpaulo<pre>int lua_getmetatable (lua_State *L, int index);</pre>
3665280405Srpaulo
3666280405Srpaulo<p>
3667280405SrpauloIf the value at the given index has a metatable,
3668280405Srpaulothe function pushes that metatable onto the stack and returns&nbsp;1.
3669280405SrpauloOtherwise,
3670280405Srpaulothe function returns&nbsp;0 and pushes nothing on the stack.
3671280405Srpaulo
3672280405Srpaulo
3673280405Srpaulo
3674280405Srpaulo
3675280405Srpaulo
3676280405Srpaulo<hr><h3><a name="lua_gettable"><code>lua_gettable</code></a></h3><p>
3677280405Srpaulo<span class="apii">[-1, +1, <em>e</em>]</span>
3678280405Srpaulo<pre>int lua_gettable (lua_State *L, int index);</pre>
3679280405Srpaulo
3680280405Srpaulo<p>
3681280405SrpauloPushes onto the stack the value <code>t[k]</code>,
3682280405Srpaulowhere <code>t</code> is the value at the given index
3683280405Srpauloand <code>k</code> is the value at the top of the stack.
3684280405Srpaulo
3685280405Srpaulo
3686280405Srpaulo<p>
3687280405SrpauloThis function pops the key from the stack,
3688280405Srpaulopushing the resulting value in its place.
3689280405SrpauloAs in Lua, this function may trigger a metamethod
3690280405Srpaulofor the "index" event (see <a href="#2.4">&sect;2.4</a>).
3691280405Srpaulo
3692280405Srpaulo
3693280405Srpaulo<p>
3694280405SrpauloReturns the type of the pushed value.
3695280405Srpaulo
3696280405Srpaulo
3697280405Srpaulo
3698280405Srpaulo
3699280405Srpaulo
3700280405Srpaulo<hr><h3><a name="lua_gettop"><code>lua_gettop</code></a></h3><p>
3701280405Srpaulo<span class="apii">[-0, +0, &ndash;]</span>
3702280405Srpaulo<pre>int lua_gettop (lua_State *L);</pre>
3703280405Srpaulo
3704280405Srpaulo<p>
3705280405SrpauloReturns the index of the top element in the stack.
3706280405SrpauloBecause indices start at&nbsp;1,
3707280405Srpaulothis result is equal to the number of elements in the stack;
3708280405Srpauloin particular, 0&nbsp;means an empty stack.
3709280405Srpaulo
3710280405Srpaulo
3711280405Srpaulo
3712280405Srpaulo
3713280405Srpaulo
3714280405Srpaulo<hr><h3><a name="lua_getuservalue"><code>lua_getuservalue</code></a></h3><p>
3715280405Srpaulo<span class="apii">[-0, +1, &ndash;]</span>
3716280405Srpaulo<pre>int lua_getuservalue (lua_State *L, int index);</pre>
3717280405Srpaulo
3718280405Srpaulo<p>
3719326344SimpPushes onto the stack the Lua value associated with the full userdata
3720280405Srpauloat the given index.
3721280405Srpaulo
3722280405Srpaulo
3723280405Srpaulo<p>
3724280405SrpauloReturns the type of the pushed value.
3725280405Srpaulo
3726280405Srpaulo
3727280405Srpaulo
3728280405Srpaulo
3729280405Srpaulo
3730280405Srpaulo<hr><h3><a name="lua_insert"><code>lua_insert</code></a></h3><p>
3731280405Srpaulo<span class="apii">[-1, +1, &ndash;]</span>
3732280405Srpaulo<pre>void lua_insert (lua_State *L, int index);</pre>
3733280405Srpaulo
3734280405Srpaulo<p>
3735280405SrpauloMoves the top element into the given valid index,
3736280405Srpauloshifting up the elements above this index to open space.
3737280405SrpauloThis function cannot be called with a pseudo-index,
3738280405Srpaulobecause a pseudo-index is not an actual stack position.
3739280405Srpaulo
3740280405Srpaulo
3741280405Srpaulo
3742280405Srpaulo
3743280405Srpaulo
3744280405Srpaulo<hr><h3><a name="lua_Integer"><code>lua_Integer</code></a></h3>
3745280405Srpaulo<pre>typedef ... lua_Integer;</pre>
3746280405Srpaulo
3747280405Srpaulo<p>
3748280405SrpauloThe type of integers in Lua.
3749280405Srpaulo
3750280405Srpaulo
3751280405Srpaulo<p>
3752280405SrpauloBy default this type is <code>long long</code>,
3753280405Srpaulo(usually a 64-bit two-complement integer),
3754280405Srpaulobut that can be changed to <code>long</code> or <code>int</code>
3755280405Srpaulo(usually a 32-bit two-complement integer).
3756326344Simp(See <code>LUA_INT_TYPE</code> in <code>luaconf.h</code>.)
3757280405Srpaulo
3758280405Srpaulo
3759280405Srpaulo<p>
3760280405SrpauloLua also defines the constants
3761280405Srpaulo<a name="pdf-LUA_MININTEGER"><code>LUA_MININTEGER</code></a> and <a name="pdf-LUA_MAXINTEGER"><code>LUA_MAXINTEGER</code></a>,
3762280405Srpaulowith the minimum and the maximum values that fit in this type.
3763280405Srpaulo
3764280405Srpaulo
3765280405Srpaulo
3766280405Srpaulo
3767280405Srpaulo
3768280405Srpaulo<hr><h3><a name="lua_isboolean"><code>lua_isboolean</code></a></h3><p>
3769280405Srpaulo<span class="apii">[-0, +0, &ndash;]</span>
3770280405Srpaulo<pre>int lua_isboolean (lua_State *L, int index);</pre>
3771280405Srpaulo
3772280405Srpaulo<p>
3773280405SrpauloReturns 1 if the value at the given index is a boolean,
3774280405Srpauloand 0&nbsp;otherwise.
3775280405Srpaulo
3776280405Srpaulo
3777280405Srpaulo
3778280405Srpaulo
3779280405Srpaulo
3780280405Srpaulo<hr><h3><a name="lua_iscfunction"><code>lua_iscfunction</code></a></h3><p>
3781280405Srpaulo<span class="apii">[-0, +0, &ndash;]</span>
3782280405Srpaulo<pre>int lua_iscfunction (lua_State *L, int index);</pre>
3783280405Srpaulo
3784280405Srpaulo<p>
3785280405SrpauloReturns 1 if the value at the given index is a C&nbsp;function,
3786280405Srpauloand 0&nbsp;otherwise.
3787280405Srpaulo
3788280405Srpaulo
3789280405Srpaulo
3790280405Srpaulo
3791280405Srpaulo
3792280405Srpaulo<hr><h3><a name="lua_isfunction"><code>lua_isfunction</code></a></h3><p>
3793280405Srpaulo<span class="apii">[-0, +0, &ndash;]</span>
3794280405Srpaulo<pre>int lua_isfunction (lua_State *L, int index);</pre>
3795280405Srpaulo
3796280405Srpaulo<p>
3797280405SrpauloReturns 1 if the value at the given index is a function
3798280405Srpaulo(either C or Lua), and 0&nbsp;otherwise.
3799280405Srpaulo
3800280405Srpaulo
3801280405Srpaulo
3802280405Srpaulo
3803280405Srpaulo
3804280405Srpaulo<hr><h3><a name="lua_isinteger"><code>lua_isinteger</code></a></h3><p>
3805280405Srpaulo<span class="apii">[-0, +0, &ndash;]</span>
3806280405Srpaulo<pre>int lua_isinteger (lua_State *L, int index);</pre>
3807280405Srpaulo
3808280405Srpaulo<p>
3809280405SrpauloReturns 1 if the value at the given index is an integer
3810280405Srpaulo(that is, the value is a number and is represented as an integer),
3811280405Srpauloand 0&nbsp;otherwise.
3812280405Srpaulo
3813280405Srpaulo
3814280405Srpaulo
3815280405Srpaulo
3816280405Srpaulo
3817280405Srpaulo<hr><h3><a name="lua_islightuserdata"><code>lua_islightuserdata</code></a></h3><p>
3818280405Srpaulo<span class="apii">[-0, +0, &ndash;]</span>
3819280405Srpaulo<pre>int lua_islightuserdata (lua_State *L, int index);</pre>
3820280405Srpaulo
3821280405Srpaulo<p>
3822280405SrpauloReturns 1 if the value at the given index is a light userdata,
3823280405Srpauloand 0&nbsp;otherwise.
3824280405Srpaulo
3825280405Srpaulo
3826280405Srpaulo
3827280405Srpaulo
3828280405Srpaulo
3829280405Srpaulo<hr><h3><a name="lua_isnil"><code>lua_isnil</code></a></h3><p>
3830280405Srpaulo<span class="apii">[-0, +0, &ndash;]</span>
3831280405Srpaulo<pre>int lua_isnil (lua_State *L, int index);</pre>
3832280405Srpaulo
3833280405Srpaulo<p>
3834280405SrpauloReturns 1 if the value at the given index is <b>nil</b>,
3835280405Srpauloand 0&nbsp;otherwise.
3836280405Srpaulo
3837280405Srpaulo
3838280405Srpaulo
3839280405Srpaulo
3840280405Srpaulo
3841280405Srpaulo<hr><h3><a name="lua_isnone"><code>lua_isnone</code></a></h3><p>
3842280405Srpaulo<span class="apii">[-0, +0, &ndash;]</span>
3843280405Srpaulo<pre>int lua_isnone (lua_State *L, int index);</pre>
3844280405Srpaulo
3845280405Srpaulo<p>
3846280405SrpauloReturns 1 if the given index is not valid,
3847280405Srpauloand 0&nbsp;otherwise.
3848280405Srpaulo
3849280405Srpaulo
3850280405Srpaulo
3851280405Srpaulo
3852280405Srpaulo
3853280405Srpaulo<hr><h3><a name="lua_isnoneornil"><code>lua_isnoneornil</code></a></h3><p>
3854280405Srpaulo<span class="apii">[-0, +0, &ndash;]</span>
3855280405Srpaulo<pre>int lua_isnoneornil (lua_State *L, int index);</pre>
3856280405Srpaulo
3857280405Srpaulo<p>
3858280405SrpauloReturns 1 if the given index is not valid
3859280405Srpauloor if the value at this index is <b>nil</b>,
3860280405Srpauloand 0&nbsp;otherwise.
3861280405Srpaulo
3862280405Srpaulo
3863280405Srpaulo
3864280405Srpaulo
3865280405Srpaulo
3866280405Srpaulo<hr><h3><a name="lua_isnumber"><code>lua_isnumber</code></a></h3><p>
3867280405Srpaulo<span class="apii">[-0, +0, &ndash;]</span>
3868280405Srpaulo<pre>int lua_isnumber (lua_State *L, int index);</pre>
3869280405Srpaulo
3870280405Srpaulo<p>
3871280405SrpauloReturns 1 if the value at the given index is a number
3872280405Srpauloor a string convertible to a number,
3873280405Srpauloand 0&nbsp;otherwise.
3874280405Srpaulo
3875280405Srpaulo
3876280405Srpaulo
3877280405Srpaulo
3878280405Srpaulo
3879280405Srpaulo<hr><h3><a name="lua_isstring"><code>lua_isstring</code></a></h3><p>
3880280405Srpaulo<span class="apii">[-0, +0, &ndash;]</span>
3881280405Srpaulo<pre>int lua_isstring (lua_State *L, int index);</pre>
3882280405Srpaulo
3883280405Srpaulo<p>
3884280405SrpauloReturns 1 if the value at the given index is a string
3885280405Srpauloor a number (which is always convertible to a string),
3886280405Srpauloand 0&nbsp;otherwise.
3887280405Srpaulo
3888280405Srpaulo
3889280405Srpaulo
3890280405Srpaulo
3891280405Srpaulo
3892280405Srpaulo<hr><h3><a name="lua_istable"><code>lua_istable</code></a></h3><p>
3893280405Srpaulo<span class="apii">[-0, +0, &ndash;]</span>
3894280405Srpaulo<pre>int lua_istable (lua_State *L, int index);</pre>
3895280405Srpaulo
3896280405Srpaulo<p>
3897280405SrpauloReturns 1 if the value at the given index is a table,
3898280405Srpauloand 0&nbsp;otherwise.
3899280405Srpaulo
3900280405Srpaulo
3901280405Srpaulo
3902280405Srpaulo
3903280405Srpaulo
3904280405Srpaulo<hr><h3><a name="lua_isthread"><code>lua_isthread</code></a></h3><p>
3905280405Srpaulo<span class="apii">[-0, +0, &ndash;]</span>
3906280405Srpaulo<pre>int lua_isthread (lua_State *L, int index);</pre>
3907280405Srpaulo
3908280405Srpaulo<p>
3909280405SrpauloReturns 1 if the value at the given index is a thread,
3910280405Srpauloand 0&nbsp;otherwise.
3911280405Srpaulo
3912280405Srpaulo
3913280405Srpaulo
3914280405Srpaulo
3915280405Srpaulo
3916280405Srpaulo<hr><h3><a name="lua_isuserdata"><code>lua_isuserdata</code></a></h3><p>
3917280405Srpaulo<span class="apii">[-0, +0, &ndash;]</span>
3918280405Srpaulo<pre>int lua_isuserdata (lua_State *L, int index);</pre>
3919280405Srpaulo
3920280405Srpaulo<p>
3921280405SrpauloReturns 1 if the value at the given index is a userdata
3922280405Srpaulo(either full or light), and 0&nbsp;otherwise.
3923280405Srpaulo
3924280405Srpaulo
3925280405Srpaulo
3926280405Srpaulo
3927280405Srpaulo
3928280405Srpaulo<hr><h3><a name="lua_isyieldable"><code>lua_isyieldable</code></a></h3><p>
3929280405Srpaulo<span class="apii">[-0, +0, &ndash;]</span>
3930280405Srpaulo<pre>int lua_isyieldable (lua_State *L);</pre>
3931280405Srpaulo
3932280405Srpaulo<p>
3933280405SrpauloReturns 1 if the given coroutine can yield,
3934280405Srpauloand 0&nbsp;otherwise.
3935280405Srpaulo
3936280405Srpaulo
3937280405Srpaulo
3938280405Srpaulo
3939280405Srpaulo
3940280405Srpaulo<hr><h3><a name="lua_KContext"><code>lua_KContext</code></a></h3>
3941280405Srpaulo<pre>typedef ... lua_KContext;</pre>
3942280405Srpaulo
3943280405Srpaulo<p>
3944280405SrpauloThe type for continuation-function contexts.
3945326344SimpIt must be a numeric type.
3946280405SrpauloThis type is defined as <code>intptr_t</code>
3947280405Srpaulowhen <code>intptr_t</code> is available,
3948280405Srpauloso that it can store pointers too.
3949280405SrpauloOtherwise, it is defined as <code>ptrdiff_t</code>.
3950280405Srpaulo
3951280405Srpaulo
3952280405Srpaulo
3953280405Srpaulo
3954280405Srpaulo
3955280405Srpaulo<hr><h3><a name="lua_KFunction"><code>lua_KFunction</code></a></h3>
3956280405Srpaulo<pre>typedef int (*lua_KFunction) (lua_State *L, int status, lua_KContext ctx);</pre>
3957280405Srpaulo
3958280405Srpaulo<p>
3959280405SrpauloType for continuation functions (see <a href="#4.7">&sect;4.7</a>).
3960280405Srpaulo
3961280405Srpaulo
3962280405Srpaulo
3963280405Srpaulo
3964280405Srpaulo
3965280405Srpaulo<hr><h3><a name="lua_len"><code>lua_len</code></a></h3><p>
3966280405Srpaulo<span class="apii">[-0, +1, <em>e</em>]</span>
3967280405Srpaulo<pre>void lua_len (lua_State *L, int index);</pre>
3968280405Srpaulo
3969280405Srpaulo<p>
3970280405SrpauloReturns the length of the value at the given index.
3971280405SrpauloIt is equivalent to the '<code>#</code>' operator in Lua (see <a href="#3.4.7">&sect;3.4.7</a>) and
3972280405Srpaulomay trigger a metamethod for the "length" event (see <a href="#2.4">&sect;2.4</a>).
3973280405SrpauloThe result is pushed on the stack.
3974280405Srpaulo
3975280405Srpaulo
3976280405Srpaulo
3977280405Srpaulo
3978280405Srpaulo
3979280405Srpaulo<hr><h3><a name="lua_load"><code>lua_load</code></a></h3><p>
3980280405Srpaulo<span class="apii">[-0, +1, &ndash;]</span>
3981280405Srpaulo<pre>int lua_load (lua_State *L,
3982280405Srpaulo              lua_Reader reader,
3983280405Srpaulo              void *data,
3984280405Srpaulo              const char *chunkname,
3985280405Srpaulo              const char *mode);</pre>
3986280405Srpaulo
3987280405Srpaulo<p>
3988280405SrpauloLoads a Lua chunk without running it.
3989280405SrpauloIf there are no errors,
3990280405Srpaulo<code>lua_load</code> pushes the compiled chunk as a Lua
3991280405Srpaulofunction on top of the stack.
3992280405SrpauloOtherwise, it pushes an error message.
3993280405Srpaulo
3994280405Srpaulo
3995280405Srpaulo<p>
3996280405SrpauloThe return values of <code>lua_load</code> are:
3997280405Srpaulo
3998280405Srpaulo<ul>
3999280405Srpaulo
4000280405Srpaulo<li><b><a href="#pdf-LUA_OK"><code>LUA_OK</code></a>: </b> no errors;</li>
4001280405Srpaulo
4002280405Srpaulo<li><b><a name="pdf-LUA_ERRSYNTAX"><code>LUA_ERRSYNTAX</code></a>: </b>
4003280405Srpaulosyntax error during precompilation;</li>
4004280405Srpaulo
4005280405Srpaulo<li><b><a href="#pdf-LUA_ERRMEM"><code>LUA_ERRMEM</code></a>: </b>
4006326344Simpmemory allocation (out-of-memory) error;</li>
4007280405Srpaulo
4008280405Srpaulo<li><b><a href="#pdf-LUA_ERRGCMM"><code>LUA_ERRGCMM</code></a>: </b>
4009280405Srpauloerror while running a <code>__gc</code> metamethod.
4010280405Srpaulo(This error has no relation with the chunk being loaded.
4011280405SrpauloIt is generated by the garbage collector.)
4012280405Srpaulo</li>
4013280405Srpaulo
4014280405Srpaulo</ul>
4015280405Srpaulo
4016280405Srpaulo<p>
4017280405SrpauloThe <code>lua_load</code> function uses a user-supplied <code>reader</code> function
4018280405Srpauloto read the chunk (see <a href="#lua_Reader"><code>lua_Reader</code></a>).
4019280405SrpauloThe <code>data</code> argument is an opaque value passed to the reader function.
4020280405Srpaulo
4021280405Srpaulo
4022280405Srpaulo<p>
4023280405SrpauloThe <code>chunkname</code> argument gives a name to the chunk,
4024280405Srpaulowhich is used for error messages and in debug information (see <a href="#4.9">&sect;4.9</a>).
4025280405Srpaulo
4026280405Srpaulo
4027280405Srpaulo<p>
4028280405Srpaulo<code>lua_load</code> automatically detects whether the chunk is text or binary
4029280405Srpauloand loads it accordingly (see program <code>luac</code>).
4030280405SrpauloThe string <code>mode</code> works as in function <a href="#pdf-load"><code>load</code></a>,
4031280405Srpaulowith the addition that
4032280405Srpauloa <code>NULL</code> value is equivalent to the string "<code>bt</code>".
4033280405Srpaulo
4034280405Srpaulo
4035280405Srpaulo<p>
4036280405Srpaulo<code>lua_load</code> uses the stack internally,
4037280405Srpauloso the reader function must always leave the stack
4038280405Srpaulounmodified when returning.
4039280405Srpaulo
4040280405Srpaulo
4041280405Srpaulo<p>
4042280405SrpauloIf the resulting function has upvalues,
4043280405Srpauloits first upvalue is set to the value of the global environment
4044280405Srpaulostored at index <code>LUA_RIDX_GLOBALS</code> in the registry (see <a href="#4.5">&sect;4.5</a>).
4045280405SrpauloWhen loading main chunks,
4046280405Srpaulothis upvalue will be the <code>_ENV</code> variable (see <a href="#2.2">&sect;2.2</a>).
4047280405SrpauloOther upvalues are initialized with <b>nil</b>.
4048280405Srpaulo
4049280405Srpaulo
4050280405Srpaulo
4051280405Srpaulo
4052280405Srpaulo
4053280405Srpaulo<hr><h3><a name="lua_newstate"><code>lua_newstate</code></a></h3><p>
4054280405Srpaulo<span class="apii">[-0, +0, &ndash;]</span>
4055280405Srpaulo<pre>lua_State *lua_newstate (lua_Alloc f, void *ud);</pre>
4056280405Srpaulo
4057280405Srpaulo<p>
4058280405SrpauloCreates a new thread running in a new, independent state.
4059280405SrpauloReturns <code>NULL</code> if it cannot create the thread or the state
4060280405Srpaulo(due to lack of memory).
4061280405SrpauloThe argument <code>f</code> is the allocator function;
4062326344SimpLua does all memory allocation for this state
4063326344Simpthrough this function (see <a href="#lua_Alloc"><code>lua_Alloc</code></a>).
4064280405SrpauloThe second argument, <code>ud</code>, is an opaque pointer that Lua
4065280405Srpaulopasses to the allocator in every call.
4066280405Srpaulo
4067280405Srpaulo
4068280405Srpaulo
4069280405Srpaulo
4070280405Srpaulo
4071280405Srpaulo<hr><h3><a name="lua_newtable"><code>lua_newtable</code></a></h3><p>
4072326344Simp<span class="apii">[-0, +1, <em>m</em>]</span>
4073280405Srpaulo<pre>void lua_newtable (lua_State *L);</pre>
4074280405Srpaulo
4075280405Srpaulo<p>
4076280405SrpauloCreates a new empty table and pushes it onto the stack.
4077280405SrpauloIt is equivalent to <code>lua_createtable(L, 0, 0)</code>.
4078280405Srpaulo
4079280405Srpaulo
4080280405Srpaulo
4081280405Srpaulo
4082280405Srpaulo
4083280405Srpaulo<hr><h3><a name="lua_newthread"><code>lua_newthread</code></a></h3><p>
4084326344Simp<span class="apii">[-0, +1, <em>m</em>]</span>
4085280405Srpaulo<pre>lua_State *lua_newthread (lua_State *L);</pre>
4086280405Srpaulo
4087280405Srpaulo<p>
4088280405SrpauloCreates a new thread, pushes it on the stack,
4089280405Srpauloand returns a pointer to a <a href="#lua_State"><code>lua_State</code></a> that represents this new thread.
4090280405SrpauloThe new thread returned by this function shares with the original thread
4091280405Srpauloits global environment,
4092280405Srpaulobut has an independent execution stack.
4093280405Srpaulo
4094280405Srpaulo
4095280405Srpaulo<p>
4096280405SrpauloThere is no explicit function to close or to destroy a thread.
4097280405SrpauloThreads are subject to garbage collection,
4098280405Srpaulolike any Lua object.
4099280405Srpaulo
4100280405Srpaulo
4101280405Srpaulo
4102280405Srpaulo
4103280405Srpaulo
4104280405Srpaulo<hr><h3><a name="lua_newuserdata"><code>lua_newuserdata</code></a></h3><p>
4105326344Simp<span class="apii">[-0, +1, <em>m</em>]</span>
4106280405Srpaulo<pre>void *lua_newuserdata (lua_State *L, size_t size);</pre>
4107280405Srpaulo
4108280405Srpaulo<p>
4109280405SrpauloThis function allocates a new block of memory with the given size,
4110280405Srpaulopushes onto the stack a new full userdata with the block address,
4111280405Srpauloand returns this address.
4112280405SrpauloThe host program can freely use this memory.
4113280405Srpaulo
4114280405Srpaulo
4115280405Srpaulo
4116280405Srpaulo
4117280405Srpaulo
4118280405Srpaulo<hr><h3><a name="lua_next"><code>lua_next</code></a></h3><p>
4119280405Srpaulo<span class="apii">[-1, +(2|0), <em>e</em>]</span>
4120280405Srpaulo<pre>int lua_next (lua_State *L, int index);</pre>
4121280405Srpaulo
4122280405Srpaulo<p>
4123280405SrpauloPops a key from the stack,
4124280405Srpauloand pushes a key&ndash;value pair from the table at the given index
4125280405Srpaulo(the "next" pair after the given key).
4126280405SrpauloIf there are no more elements in the table,
4127280405Srpaulothen <a href="#lua_next"><code>lua_next</code></a> returns 0 (and pushes nothing).
4128280405Srpaulo
4129280405Srpaulo
4130280405Srpaulo<p>
4131280405SrpauloA typical traversal looks like this:
4132280405Srpaulo
4133280405Srpaulo<pre>
4134280405Srpaulo     /* table is in the stack at index 't' */
4135280405Srpaulo     lua_pushnil(L);  /* first key */
4136280405Srpaulo     while (lua_next(L, t) != 0) {
4137280405Srpaulo       /* uses 'key' (at index -2) and 'value' (at index -1) */
4138280405Srpaulo       printf("%s - %s\n",
4139280405Srpaulo              lua_typename(L, lua_type(L, -2)),
4140280405Srpaulo              lua_typename(L, lua_type(L, -1)));
4141280405Srpaulo       /* removes 'value'; keeps 'key' for next iteration */
4142280405Srpaulo       lua_pop(L, 1);
4143280405Srpaulo     }
4144280405Srpaulo</pre>
4145280405Srpaulo
4146280405Srpaulo<p>
4147280405SrpauloWhile traversing a table,
4148280405Srpaulodo not call <a href="#lua_tolstring"><code>lua_tolstring</code></a> directly on a key,
4149280405Srpaulounless you know that the key is actually a string.
4150280405SrpauloRecall that <a href="#lua_tolstring"><code>lua_tolstring</code></a> may change
4151280405Srpaulothe value at the given index;
4152280405Srpaulothis confuses the next call to <a href="#lua_next"><code>lua_next</code></a>.
4153280405Srpaulo
4154280405Srpaulo
4155280405Srpaulo<p>
4156280405SrpauloSee function <a href="#pdf-next"><code>next</code></a> for the caveats of modifying
4157280405Srpaulothe table during its traversal.
4158280405Srpaulo
4159280405Srpaulo
4160280405Srpaulo
4161280405Srpaulo
4162280405Srpaulo
4163280405Srpaulo<hr><h3><a name="lua_Number"><code>lua_Number</code></a></h3>
4164326344Simp<pre>typedef ... lua_Number;</pre>
4165280405Srpaulo
4166280405Srpaulo<p>
4167280405SrpauloThe type of floats in Lua.
4168280405Srpaulo
4169280405Srpaulo
4170280405Srpaulo<p>
4171280405SrpauloBy default this type is double,
4172326344Simpbut that can be changed to a single float or a long double.
4173326344Simp(See <code>LUA_FLOAT_TYPE</code> in <code>luaconf.h</code>.)
4174280405Srpaulo
4175280405Srpaulo
4176280405Srpaulo
4177280405Srpaulo
4178280405Srpaulo
4179280405Srpaulo<hr><h3><a name="lua_numbertointeger"><code>lua_numbertointeger</code></a></h3>
4180280405Srpaulo<pre>int lua_numbertointeger (lua_Number n, lua_Integer *p);</pre>
4181280405Srpaulo
4182280405Srpaulo<p>
4183280405SrpauloConverts a Lua float to a Lua integer.
4184280405SrpauloThis macro assumes that <code>n</code> has an integral value.
4185280405SrpauloIf that value is within the range of Lua integers,
4186280405Srpauloit is converted to an integer and assigned to <code>*p</code>.
4187280405SrpauloThe macro results in a boolean indicating whether the
4188280405Srpauloconversion was successful.
4189280405Srpaulo(Note that this range test can be tricky to do
4190280405Srpaulocorrectly without this macro,
4191280405Srpaulodue to roundings.)
4192280405Srpaulo
4193280405Srpaulo
4194280405Srpaulo<p>
4195280405SrpauloThis macro may evaluate its arguments more than once.
4196280405Srpaulo
4197280405Srpaulo
4198280405Srpaulo
4199280405Srpaulo
4200280405Srpaulo
4201280405Srpaulo<hr><h3><a name="lua_pcall"><code>lua_pcall</code></a></h3><p>
4202280405Srpaulo<span class="apii">[-(nargs + 1), +(nresults|1), &ndash;]</span>
4203280405Srpaulo<pre>int lua_pcall (lua_State *L, int nargs, int nresults, int msgh);</pre>
4204280405Srpaulo
4205280405Srpaulo<p>
4206280405SrpauloCalls a function in protected mode.
4207280405Srpaulo
4208280405Srpaulo
4209280405Srpaulo<p>
4210280405SrpauloBoth <code>nargs</code> and <code>nresults</code> have the same meaning as
4211280405Srpauloin <a href="#lua_call"><code>lua_call</code></a>.
4212280405SrpauloIf there are no errors during the call,
4213280405Srpaulo<a href="#lua_pcall"><code>lua_pcall</code></a> behaves exactly like <a href="#lua_call"><code>lua_call</code></a>.
4214280405SrpauloHowever, if there is any error,
4215280405Srpaulo<a href="#lua_pcall"><code>lua_pcall</code></a> catches it,
4216326344Simppushes a single value on the stack (the error object),
4217280405Srpauloand returns an error code.
4218280405SrpauloLike <a href="#lua_call"><code>lua_call</code></a>,
4219280405Srpaulo<a href="#lua_pcall"><code>lua_pcall</code></a> always removes the function
4220280405Srpauloand its arguments from the stack.
4221280405Srpaulo
4222280405Srpaulo
4223280405Srpaulo<p>
4224280405SrpauloIf <code>msgh</code> is 0,
4225326344Simpthen the error object returned on the stack
4226326344Simpis exactly the original error object.
4227280405SrpauloOtherwise, <code>msgh</code> is the stack index of a
4228280405Srpaulo<em>message handler</em>.
4229326344Simp(This index cannot be a pseudo-index.)
4230280405SrpauloIn case of runtime errors,
4231326344Simpthis function will be called with the error object
4232326344Simpand its return value will be the object
4233280405Srpauloreturned on the stack by <a href="#lua_pcall"><code>lua_pcall</code></a>.
4234280405Srpaulo
4235280405Srpaulo
4236280405Srpaulo<p>
4237280405SrpauloTypically, the message handler is used to add more debug
4238326344Simpinformation to the error object, such as a stack traceback.
4239280405SrpauloSuch information cannot be gathered after the return of <a href="#lua_pcall"><code>lua_pcall</code></a>,
4240280405Srpaulosince by then the stack has unwound.
4241280405Srpaulo
4242280405Srpaulo
4243280405Srpaulo<p>
4244280405SrpauloThe <a href="#lua_pcall"><code>lua_pcall</code></a> function returns one of the following constants
4245280405Srpaulo(defined in <code>lua.h</code>):
4246280405Srpaulo
4247280405Srpaulo<ul>
4248280405Srpaulo
4249280405Srpaulo<li><b><a name="pdf-LUA_OK"><code>LUA_OK</code></a> (0): </b>
4250280405Srpaulosuccess.</li>
4251280405Srpaulo
4252280405Srpaulo<li><b><a name="pdf-LUA_ERRRUN"><code>LUA_ERRRUN</code></a>: </b>
4253280405Srpauloa runtime error.
4254280405Srpaulo</li>
4255280405Srpaulo
4256280405Srpaulo<li><b><a name="pdf-LUA_ERRMEM"><code>LUA_ERRMEM</code></a>: </b>
4257280405Srpaulomemory allocation error.
4258280405SrpauloFor such errors, Lua does not call the message handler.
4259280405Srpaulo</li>
4260280405Srpaulo
4261280405Srpaulo<li><b><a name="pdf-LUA_ERRERR"><code>LUA_ERRERR</code></a>: </b>
4262280405Srpauloerror while running the message handler.
4263280405Srpaulo</li>
4264280405Srpaulo
4265280405Srpaulo<li><b><a name="pdf-LUA_ERRGCMM"><code>LUA_ERRGCMM</code></a>: </b>
4266280405Srpauloerror while running a <code>__gc</code> metamethod.
4267326344SimpFor such errors, Lua does not call the message handler
4268326344Simp(as this kind of error typically has no relation
4269326344Simpwith the function being called).
4270280405Srpaulo</li>
4271280405Srpaulo
4272280405Srpaulo</ul>
4273280405Srpaulo
4274280405Srpaulo
4275280405Srpaulo
4276280405Srpaulo
4277280405Srpaulo<hr><h3><a name="lua_pcallk"><code>lua_pcallk</code></a></h3><p>
4278280405Srpaulo<span class="apii">[-(nargs + 1), +(nresults|1), &ndash;]</span>
4279280405Srpaulo<pre>int lua_pcallk (lua_State *L,
4280280405Srpaulo                int nargs,
4281280405Srpaulo                int nresults,
4282280405Srpaulo                int msgh,
4283280405Srpaulo                lua_KContext ctx,
4284280405Srpaulo                lua_KFunction k);</pre>
4285280405Srpaulo
4286280405Srpaulo<p>
4287280405SrpauloThis function behaves exactly like <a href="#lua_pcall"><code>lua_pcall</code></a>,
4288280405Srpaulobut allows the called function to yield (see <a href="#4.7">&sect;4.7</a>).
4289280405Srpaulo
4290280405Srpaulo
4291280405Srpaulo
4292280405Srpaulo
4293280405Srpaulo
4294280405Srpaulo<hr><h3><a name="lua_pop"><code>lua_pop</code></a></h3><p>
4295280405Srpaulo<span class="apii">[-n, +0, &ndash;]</span>
4296280405Srpaulo<pre>void lua_pop (lua_State *L, int n);</pre>
4297280405Srpaulo
4298280405Srpaulo<p>
4299280405SrpauloPops <code>n</code> elements from the stack.
4300280405Srpaulo
4301280405Srpaulo
4302280405Srpaulo
4303280405Srpaulo
4304280405Srpaulo
4305280405Srpaulo<hr><h3><a name="lua_pushboolean"><code>lua_pushboolean</code></a></h3><p>
4306280405Srpaulo<span class="apii">[-0, +1, &ndash;]</span>
4307280405Srpaulo<pre>void lua_pushboolean (lua_State *L, int b);</pre>
4308280405Srpaulo
4309280405Srpaulo<p>
4310280405SrpauloPushes a boolean value with value <code>b</code> onto the stack.
4311280405Srpaulo
4312280405Srpaulo
4313280405Srpaulo
4314280405Srpaulo
4315280405Srpaulo
4316280405Srpaulo<hr><h3><a name="lua_pushcclosure"><code>lua_pushcclosure</code></a></h3><p>
4317326344Simp<span class="apii">[-n, +1, <em>m</em>]</span>
4318280405Srpaulo<pre>void lua_pushcclosure (lua_State *L, lua_CFunction fn, int n);</pre>
4319280405Srpaulo
4320280405Srpaulo<p>
4321280405SrpauloPushes a new C&nbsp;closure onto the stack.
4322280405Srpaulo
4323280405Srpaulo
4324280405Srpaulo<p>
4325280405SrpauloWhen a C&nbsp;function is created,
4326280405Srpauloit is possible to associate some values with it,
4327280405Srpaulothus creating a C&nbsp;closure (see <a href="#4.4">&sect;4.4</a>);
4328280405Srpaulothese values are then accessible to the function whenever it is called.
4329280405SrpauloTo associate values with a C&nbsp;function,
4330280405Srpaulofirst these values must be pushed onto the stack
4331280405Srpaulo(when there are multiple values, the first value is pushed first).
4332280405SrpauloThen <a href="#lua_pushcclosure"><code>lua_pushcclosure</code></a>
4333280405Srpaulois called to create and push the C&nbsp;function onto the stack,
4334280405Srpaulowith the argument <code>n</code> telling how many values will be
4335280405Srpauloassociated with the function.
4336280405Srpaulo<a href="#lua_pushcclosure"><code>lua_pushcclosure</code></a> also pops these values from the stack.
4337280405Srpaulo
4338280405Srpaulo
4339280405Srpaulo<p>
4340280405SrpauloThe maximum value for <code>n</code> is 255.
4341280405Srpaulo
4342280405Srpaulo
4343280405Srpaulo<p>
4344280405SrpauloWhen <code>n</code> is zero,
4345326344Simpthis function creates a <em>light C&nbsp;function</em>,
4346280405Srpaulowhich is just a pointer to the C&nbsp;function.
4347280405SrpauloIn that case, it never raises a memory error.
4348280405Srpaulo
4349280405Srpaulo
4350280405Srpaulo
4351280405Srpaulo
4352280405Srpaulo
4353280405Srpaulo<hr><h3><a name="lua_pushcfunction"><code>lua_pushcfunction</code></a></h3><p>
4354280405Srpaulo<span class="apii">[-0, +1, &ndash;]</span>
4355280405Srpaulo<pre>void lua_pushcfunction (lua_State *L, lua_CFunction f);</pre>
4356280405Srpaulo
4357280405Srpaulo<p>
4358280405SrpauloPushes a C&nbsp;function onto the stack.
4359326344SimpThis function receives a pointer to a C&nbsp;function
4360280405Srpauloand pushes onto the stack a Lua value of type <code>function</code> that,
4361280405Srpaulowhen called, invokes the corresponding C&nbsp;function.
4362280405Srpaulo
4363280405Srpaulo
4364280405Srpaulo<p>
4365326344SimpAny function to be callable by Lua must
4366280405Srpaulofollow the correct protocol to receive its parameters
4367280405Srpauloand return its results (see <a href="#lua_CFunction"><code>lua_CFunction</code></a>).
4368280405Srpaulo
4369280405Srpaulo
4370280405Srpaulo
4371280405Srpaulo
4372280405Srpaulo
4373280405Srpaulo<hr><h3><a name="lua_pushfstring"><code>lua_pushfstring</code></a></h3><p>
4374280405Srpaulo<span class="apii">[-0, +1, <em>e</em>]</span>
4375280405Srpaulo<pre>const char *lua_pushfstring (lua_State *L, const char *fmt, ...);</pre>
4376280405Srpaulo
4377280405Srpaulo<p>
4378280405SrpauloPushes onto the stack a formatted string
4379280405Srpauloand returns a pointer to this string.
4380280405SrpauloIt is similar to the ISO&nbsp;C function <code>sprintf</code>,
4381280405Srpaulobut has some important differences:
4382280405Srpaulo
4383280405Srpaulo<ul>
4384280405Srpaulo
4385280405Srpaulo<li>
4386280405SrpauloYou do not have to allocate space for the result:
4387280405Srpaulothe result is a Lua string and Lua takes care of memory allocation
4388280405Srpaulo(and deallocation, through garbage collection).
4389280405Srpaulo</li>
4390280405Srpaulo
4391280405Srpaulo<li>
4392280405SrpauloThe conversion specifiers are quite restricted.
4393280405SrpauloThere are no flags, widths, or precisions.
4394280405SrpauloThe conversion specifiers can only be
4395280405Srpaulo'<code>%%</code>' (inserts the character '<code>%</code>'),
4396280405Srpaulo'<code>%s</code>' (inserts a zero-terminated string, with no size restrictions),
4397280405Srpaulo'<code>%f</code>' (inserts a <a href="#lua_Number"><code>lua_Number</code></a>),
4398326344Simp'<code>%I</code>' (inserts a <a href="#lua_Integer"><code>lua_Integer</code></a>),
4399280405Srpaulo'<code>%p</code>' (inserts a pointer as a hexadecimal numeral),
4400280405Srpaulo'<code>%d</code>' (inserts an <code>int</code>),
4401280405Srpaulo'<code>%c</code>' (inserts an <code>int</code> as a one-byte character), and
4402280405Srpaulo'<code>%U</code>' (inserts a <code>long int</code> as a UTF-8 byte sequence).
4403280405Srpaulo</li>
4404280405Srpaulo
4405280405Srpaulo</ul>
4406280405Srpaulo
4407326344Simp<p>
4408326344SimpUnlike other push functions,
4409326344Simpthis function checks for the stack space it needs,
4410326344Simpincluding the slot for its result.
4411280405Srpaulo
4412280405Srpaulo
4413280405Srpaulo
4414326344Simp
4415326344Simp
4416280405Srpaulo<hr><h3><a name="lua_pushglobaltable"><code>lua_pushglobaltable</code></a></h3><p>
4417280405Srpaulo<span class="apii">[-0, +1, &ndash;]</span>
4418280405Srpaulo<pre>void lua_pushglobaltable (lua_State *L);</pre>
4419280405Srpaulo
4420280405Srpaulo<p>
4421280405SrpauloPushes the global environment onto the stack.
4422280405Srpaulo
4423280405Srpaulo
4424280405Srpaulo
4425280405Srpaulo
4426280405Srpaulo
4427280405Srpaulo<hr><h3><a name="lua_pushinteger"><code>lua_pushinteger</code></a></h3><p>
4428280405Srpaulo<span class="apii">[-0, +1, &ndash;]</span>
4429280405Srpaulo<pre>void lua_pushinteger (lua_State *L, lua_Integer n);</pre>
4430280405Srpaulo
4431280405Srpaulo<p>
4432280405SrpauloPushes an integer with value <code>n</code> onto the stack.
4433280405Srpaulo
4434280405Srpaulo
4435280405Srpaulo
4436280405Srpaulo
4437280405Srpaulo
4438280405Srpaulo<hr><h3><a name="lua_pushlightuserdata"><code>lua_pushlightuserdata</code></a></h3><p>
4439280405Srpaulo<span class="apii">[-0, +1, &ndash;]</span>
4440280405Srpaulo<pre>void lua_pushlightuserdata (lua_State *L, void *p);</pre>
4441280405Srpaulo
4442280405Srpaulo<p>
4443280405SrpauloPushes a light userdata onto the stack.
4444280405Srpaulo
4445280405Srpaulo
4446280405Srpaulo<p>
4447280405SrpauloUserdata represent C&nbsp;values in Lua.
4448280405SrpauloA <em>light userdata</em> represents a pointer, a <code>void*</code>.
4449280405SrpauloIt is a value (like a number):
4450280405Srpauloyou do not create it, it has no individual metatable,
4451280405Srpauloand it is not collected (as it was never created).
4452280405SrpauloA light userdata is equal to "any"
4453280405Srpaulolight userdata with the same C&nbsp;address.
4454280405Srpaulo
4455280405Srpaulo
4456280405Srpaulo
4457280405Srpaulo
4458280405Srpaulo
4459280405Srpaulo<hr><h3><a name="lua_pushliteral"><code>lua_pushliteral</code></a></h3><p>
4460326344Simp<span class="apii">[-0, +1, <em>m</em>]</span>
4461280405Srpaulo<pre>const char *lua_pushliteral (lua_State *L, const char *s);</pre>
4462280405Srpaulo
4463280405Srpaulo<p>
4464326344SimpThis macro is equivalent to <a href="#lua_pushstring"><code>lua_pushstring</code></a>,
4465326344Simpbut should be used only when <code>s</code> is a literal string.
4466280405Srpaulo
4467280405Srpaulo
4468280405Srpaulo
4469280405Srpaulo
4470280405Srpaulo
4471280405Srpaulo<hr><h3><a name="lua_pushlstring"><code>lua_pushlstring</code></a></h3><p>
4472326344Simp<span class="apii">[-0, +1, <em>m</em>]</span>
4473280405Srpaulo<pre>const char *lua_pushlstring (lua_State *L, const char *s, size_t len);</pre>
4474280405Srpaulo
4475280405Srpaulo<p>
4476280405SrpauloPushes the string pointed to by <code>s</code> with size <code>len</code>
4477280405Srpauloonto the stack.
4478280405SrpauloLua makes (or reuses) an internal copy of the given string,
4479280405Srpauloso the memory at <code>s</code> can be freed or reused immediately after
4480280405Srpaulothe function returns.
4481280405SrpauloThe string can contain any binary data,
4482280405Srpauloincluding embedded zeros.
4483280405Srpaulo
4484280405Srpaulo
4485280405Srpaulo<p>
4486280405SrpauloReturns a pointer to the internal copy of the string.
4487280405Srpaulo
4488280405Srpaulo
4489280405Srpaulo
4490280405Srpaulo
4491280405Srpaulo
4492280405Srpaulo<hr><h3><a name="lua_pushnil"><code>lua_pushnil</code></a></h3><p>
4493280405Srpaulo<span class="apii">[-0, +1, &ndash;]</span>
4494280405Srpaulo<pre>void lua_pushnil (lua_State *L);</pre>
4495280405Srpaulo
4496280405Srpaulo<p>
4497280405SrpauloPushes a nil value onto the stack.
4498280405Srpaulo
4499280405Srpaulo
4500280405Srpaulo
4501280405Srpaulo
4502280405Srpaulo
4503280405Srpaulo<hr><h3><a name="lua_pushnumber"><code>lua_pushnumber</code></a></h3><p>
4504280405Srpaulo<span class="apii">[-0, +1, &ndash;]</span>
4505280405Srpaulo<pre>void lua_pushnumber (lua_State *L, lua_Number n);</pre>
4506280405Srpaulo
4507280405Srpaulo<p>
4508280405SrpauloPushes a float with value <code>n</code> onto the stack.
4509280405Srpaulo
4510280405Srpaulo
4511280405Srpaulo
4512280405Srpaulo
4513280405Srpaulo
4514280405Srpaulo<hr><h3><a name="lua_pushstring"><code>lua_pushstring</code></a></h3><p>
4515326344Simp<span class="apii">[-0, +1, <em>m</em>]</span>
4516280405Srpaulo<pre>const char *lua_pushstring (lua_State *L, const char *s);</pre>
4517280405Srpaulo
4518280405Srpaulo<p>
4519280405SrpauloPushes the zero-terminated string pointed to by <code>s</code>
4520280405Srpauloonto the stack.
4521280405SrpauloLua makes (or reuses) an internal copy of the given string,
4522280405Srpauloso the memory at <code>s</code> can be freed or reused immediately after
4523280405Srpaulothe function returns.
4524280405Srpaulo
4525280405Srpaulo
4526280405Srpaulo<p>
4527280405SrpauloReturns a pointer to the internal copy of the string.
4528280405Srpaulo
4529280405Srpaulo
4530280405Srpaulo<p>
4531280405SrpauloIf <code>s</code> is <code>NULL</code>, pushes <b>nil</b> and returns <code>NULL</code>.
4532280405Srpaulo
4533280405Srpaulo
4534280405Srpaulo
4535280405Srpaulo
4536280405Srpaulo
4537280405Srpaulo<hr><h3><a name="lua_pushthread"><code>lua_pushthread</code></a></h3><p>
4538280405Srpaulo<span class="apii">[-0, +1, &ndash;]</span>
4539280405Srpaulo<pre>int lua_pushthread (lua_State *L);</pre>
4540280405Srpaulo
4541280405Srpaulo<p>
4542280405SrpauloPushes the thread represented by <code>L</code> onto the stack.
4543280405SrpauloReturns 1 if this thread is the main thread of its state.
4544280405Srpaulo
4545280405Srpaulo
4546280405Srpaulo
4547280405Srpaulo
4548280405Srpaulo
4549280405Srpaulo<hr><h3><a name="lua_pushvalue"><code>lua_pushvalue</code></a></h3><p>
4550280405Srpaulo<span class="apii">[-0, +1, &ndash;]</span>
4551280405Srpaulo<pre>void lua_pushvalue (lua_State *L, int index);</pre>
4552280405Srpaulo
4553280405Srpaulo<p>
4554280405SrpauloPushes a copy of the element at the given index
4555280405Srpauloonto the stack.
4556280405Srpaulo
4557280405Srpaulo
4558280405Srpaulo
4559280405Srpaulo
4560280405Srpaulo
4561280405Srpaulo<hr><h3><a name="lua_pushvfstring"><code>lua_pushvfstring</code></a></h3><p>
4562326344Simp<span class="apii">[-0, +1, <em>m</em>]</span>
4563280405Srpaulo<pre>const char *lua_pushvfstring (lua_State *L,
4564280405Srpaulo                              const char *fmt,
4565280405Srpaulo                              va_list argp);</pre>
4566280405Srpaulo
4567280405Srpaulo<p>
4568280405SrpauloEquivalent to <a href="#lua_pushfstring"><code>lua_pushfstring</code></a>, except that it receives a <code>va_list</code>
4569280405Srpauloinstead of a variable number of arguments.
4570280405Srpaulo
4571280405Srpaulo
4572280405Srpaulo
4573280405Srpaulo
4574280405Srpaulo
4575280405Srpaulo<hr><h3><a name="lua_rawequal"><code>lua_rawequal</code></a></h3><p>
4576280405Srpaulo<span class="apii">[-0, +0, &ndash;]</span>
4577280405Srpaulo<pre>int lua_rawequal (lua_State *L, int index1, int index2);</pre>
4578280405Srpaulo
4579280405Srpaulo<p>
4580280405SrpauloReturns 1 if the two values in indices <code>index1</code> and
4581280405Srpaulo<code>index2</code> are primitively equal
4582326344Simp(that is, without calling the <code>__eq</code> metamethod).
4583280405SrpauloOtherwise returns&nbsp;0.
4584280405SrpauloAlso returns&nbsp;0 if any of the indices are not valid.
4585280405Srpaulo
4586280405Srpaulo
4587280405Srpaulo
4588280405Srpaulo
4589280405Srpaulo
4590280405Srpaulo<hr><h3><a name="lua_rawget"><code>lua_rawget</code></a></h3><p>
4591280405Srpaulo<span class="apii">[-1, +1, &ndash;]</span>
4592280405Srpaulo<pre>int lua_rawget (lua_State *L, int index);</pre>
4593280405Srpaulo
4594280405Srpaulo<p>
4595280405SrpauloSimilar to <a href="#lua_gettable"><code>lua_gettable</code></a>, but does a raw access
4596280405Srpaulo(i.e., without metamethods).
4597280405Srpaulo
4598280405Srpaulo
4599280405Srpaulo
4600280405Srpaulo
4601280405Srpaulo
4602280405Srpaulo<hr><h3><a name="lua_rawgeti"><code>lua_rawgeti</code></a></h3><p>
4603280405Srpaulo<span class="apii">[-0, +1, &ndash;]</span>
4604280405Srpaulo<pre>int lua_rawgeti (lua_State *L, int index, lua_Integer n);</pre>
4605280405Srpaulo
4606280405Srpaulo<p>
4607280405SrpauloPushes onto the stack the value <code>t[n]</code>,
4608280405Srpaulowhere <code>t</code> is the table at the given index.
4609326344SimpThe access is raw,
4610326344Simpthat is, it does not invoke the <code>__index</code> metamethod.
4611280405Srpaulo
4612280405Srpaulo
4613280405Srpaulo<p>
4614280405SrpauloReturns the type of the pushed value.
4615280405Srpaulo
4616280405Srpaulo
4617280405Srpaulo
4618280405Srpaulo
4619280405Srpaulo
4620280405Srpaulo<hr><h3><a name="lua_rawgetp"><code>lua_rawgetp</code></a></h3><p>
4621280405Srpaulo<span class="apii">[-0, +1, &ndash;]</span>
4622280405Srpaulo<pre>int lua_rawgetp (lua_State *L, int index, const void *p);</pre>
4623280405Srpaulo
4624280405Srpaulo<p>
4625280405SrpauloPushes onto the stack the value <code>t[k]</code>,
4626280405Srpaulowhere <code>t</code> is the table at the given index and
4627280405Srpaulo<code>k</code> is the pointer <code>p</code> represented as a light userdata.
4628280405SrpauloThe access is raw;
4629326344Simpthat is, it does not invoke the <code>__index</code> metamethod.
4630280405Srpaulo
4631280405Srpaulo
4632280405Srpaulo<p>
4633280405SrpauloReturns the type of the pushed value.
4634280405Srpaulo
4635280405Srpaulo
4636280405Srpaulo
4637280405Srpaulo
4638280405Srpaulo
4639280405Srpaulo<hr><h3><a name="lua_rawlen"><code>lua_rawlen</code></a></h3><p>
4640280405Srpaulo<span class="apii">[-0, +0, &ndash;]</span>
4641280405Srpaulo<pre>size_t lua_rawlen (lua_State *L, int index);</pre>
4642280405Srpaulo
4643280405Srpaulo<p>
4644280405SrpauloReturns the raw "length" of the value at the given index:
4645280405Srpaulofor strings, this is the string length;
4646280405Srpaulofor tables, this is the result of the length operator ('<code>#</code>')
4647280405Srpaulowith no metamethods;
4648280405Srpaulofor userdata, this is the size of the block of memory allocated
4649280405Srpaulofor the userdata;
4650280405Srpaulofor other values, it is&nbsp;0.
4651280405Srpaulo
4652280405Srpaulo
4653280405Srpaulo
4654280405Srpaulo
4655280405Srpaulo
4656280405Srpaulo<hr><h3><a name="lua_rawset"><code>lua_rawset</code></a></h3><p>
4657326344Simp<span class="apii">[-2, +0, <em>m</em>]</span>
4658280405Srpaulo<pre>void lua_rawset (lua_State *L, int index);</pre>
4659280405Srpaulo
4660280405Srpaulo<p>
4661280405SrpauloSimilar to <a href="#lua_settable"><code>lua_settable</code></a>, but does a raw assignment
4662280405Srpaulo(i.e., without metamethods).
4663280405Srpaulo
4664280405Srpaulo
4665280405Srpaulo
4666280405Srpaulo
4667280405Srpaulo
4668280405Srpaulo<hr><h3><a name="lua_rawseti"><code>lua_rawseti</code></a></h3><p>
4669326344Simp<span class="apii">[-1, +0, <em>m</em>]</span>
4670280405Srpaulo<pre>void lua_rawseti (lua_State *L, int index, lua_Integer i);</pre>
4671280405Srpaulo
4672280405Srpaulo<p>
4673280405SrpauloDoes the equivalent of <code>t[i] = v</code>,
4674280405Srpaulowhere <code>t</code> is the table at the given index
4675280405Srpauloand <code>v</code> is the value at the top of the stack.
4676280405Srpaulo
4677280405Srpaulo
4678280405Srpaulo<p>
4679280405SrpauloThis function pops the value from the stack.
4680326344SimpThe assignment is raw,
4681326344Simpthat is, it does not invoke the <code>__newindex</code> metamethod.
4682280405Srpaulo
4683280405Srpaulo
4684280405Srpaulo
4685280405Srpaulo
4686280405Srpaulo
4687280405Srpaulo<hr><h3><a name="lua_rawsetp"><code>lua_rawsetp</code></a></h3><p>
4688326344Simp<span class="apii">[-1, +0, <em>m</em>]</span>
4689280405Srpaulo<pre>void lua_rawsetp (lua_State *L, int index, const void *p);</pre>
4690280405Srpaulo
4691280405Srpaulo<p>
4692326344SimpDoes the equivalent of <code>t[p] = v</code>,
4693280405Srpaulowhere <code>t</code> is the table at the given index,
4694326344Simp<code>p</code> is encoded as a light userdata,
4695280405Srpauloand <code>v</code> is the value at the top of the stack.
4696280405Srpaulo
4697280405Srpaulo
4698280405Srpaulo<p>
4699280405SrpauloThis function pops the value from the stack.
4700326344SimpThe assignment is raw,
4701326344Simpthat is, it does not invoke <code>__newindex</code> metamethod.
4702280405Srpaulo
4703280405Srpaulo
4704280405Srpaulo
4705280405Srpaulo
4706280405Srpaulo
4707280405Srpaulo<hr><h3><a name="lua_Reader"><code>lua_Reader</code></a></h3>
4708280405Srpaulo<pre>typedef const char * (*lua_Reader) (lua_State *L,
4709280405Srpaulo                                    void *data,
4710280405Srpaulo                                    size_t *size);</pre>
4711280405Srpaulo
4712280405Srpaulo<p>
4713280405SrpauloThe reader function used by <a href="#lua_load"><code>lua_load</code></a>.
4714280405SrpauloEvery time it needs another piece of the chunk,
4715280405Srpaulo<a href="#lua_load"><code>lua_load</code></a> calls the reader,
4716280405Srpaulopassing along its <code>data</code> parameter.
4717280405SrpauloThe reader must return a pointer to a block of memory
4718280405Srpaulowith a new piece of the chunk
4719280405Srpauloand set <code>size</code> to the block size.
4720280405SrpauloThe block must exist until the reader function is called again.
4721280405SrpauloTo signal the end of the chunk,
4722280405Srpaulothe reader must return <code>NULL</code> or set <code>size</code> to zero.
4723280405SrpauloThe reader function may return pieces of any size greater than zero.
4724280405Srpaulo
4725280405Srpaulo
4726280405Srpaulo
4727280405Srpaulo
4728280405Srpaulo
4729280405Srpaulo<hr><h3><a name="lua_register"><code>lua_register</code></a></h3><p>
4730280405Srpaulo<span class="apii">[-0, +0, <em>e</em>]</span>
4731280405Srpaulo<pre>void lua_register (lua_State *L, const char *name, lua_CFunction f);</pre>
4732280405Srpaulo
4733280405Srpaulo<p>
4734326344SimpSets the C&nbsp;function <code>f</code> as the new value of global <code>name</code>.
4735280405SrpauloIt is defined as a macro:
4736280405Srpaulo
4737280405Srpaulo<pre>
4738280405Srpaulo     #define lua_register(L,n,f) \
4739280405Srpaulo            (lua_pushcfunction(L, f), lua_setglobal(L, n))
4740280405Srpaulo</pre>
4741280405Srpaulo
4742280405Srpaulo
4743280405Srpaulo
4744280405Srpaulo
4745280405Srpaulo<hr><h3><a name="lua_remove"><code>lua_remove</code></a></h3><p>
4746280405Srpaulo<span class="apii">[-1, +0, &ndash;]</span>
4747280405Srpaulo<pre>void lua_remove (lua_State *L, int index);</pre>
4748280405Srpaulo
4749280405Srpaulo<p>
4750280405SrpauloRemoves the element at the given valid index,
4751280405Srpauloshifting down the elements above this index to fill the gap.
4752280405SrpauloThis function cannot be called with a pseudo-index,
4753280405Srpaulobecause a pseudo-index is not an actual stack position.
4754280405Srpaulo
4755280405Srpaulo
4756280405Srpaulo
4757280405Srpaulo
4758280405Srpaulo
4759280405Srpaulo<hr><h3><a name="lua_replace"><code>lua_replace</code></a></h3><p>
4760280405Srpaulo<span class="apii">[-1, +0, &ndash;]</span>
4761280405Srpaulo<pre>void lua_replace (lua_State *L, int index);</pre>
4762280405Srpaulo
4763280405Srpaulo<p>
4764280405SrpauloMoves the top element into the given valid index
4765280405Srpaulowithout shifting any element
4766326344Simp(therefore replacing the value at that given index),
4767280405Srpauloand then pops the top element.
4768280405Srpaulo
4769280405Srpaulo
4770280405Srpaulo
4771280405Srpaulo
4772280405Srpaulo
4773280405Srpaulo<hr><h3><a name="lua_resume"><code>lua_resume</code></a></h3><p>
4774280405Srpaulo<span class="apii">[-?, +?, &ndash;]</span>
4775280405Srpaulo<pre>int lua_resume (lua_State *L, lua_State *from, int nargs);</pre>
4776280405Srpaulo
4777280405Srpaulo<p>
4778326344SimpStarts and resumes a coroutine in the given thread <code>L</code>.
4779280405Srpaulo
4780280405Srpaulo
4781280405Srpaulo<p>
4782280405SrpauloTo start a coroutine,
4783280405Srpauloyou push onto the thread stack the main function plus any arguments;
4784280405Srpaulothen you call <a href="#lua_resume"><code>lua_resume</code></a>,
4785280405Srpaulowith <code>nargs</code> being the number of arguments.
4786280405SrpauloThis call returns when the coroutine suspends or finishes its execution.
4787280405SrpauloWhen it returns, the stack contains all values passed to <a href="#lua_yield"><code>lua_yield</code></a>,
4788280405Srpauloor all values returned by the body function.
4789280405Srpaulo<a href="#lua_resume"><code>lua_resume</code></a> returns
4790280405Srpaulo<a href="#pdf-LUA_YIELD"><code>LUA_YIELD</code></a> if the coroutine yields,
4791280405Srpaulo<a href="#pdf-LUA_OK"><code>LUA_OK</code></a> if the coroutine finishes its execution
4792280405Srpaulowithout errors,
4793280405Srpauloor an error code in case of errors (see <a href="#lua_pcall"><code>lua_pcall</code></a>).
4794280405Srpaulo
4795280405Srpaulo
4796280405Srpaulo<p>
4797280405SrpauloIn case of errors,
4798280405Srpaulothe stack is not unwound,
4799280405Srpauloso you can use the debug API over it.
4800326344SimpThe error object is on the top of the stack.
4801280405Srpaulo
4802280405Srpaulo
4803280405Srpaulo<p>
4804280405SrpauloTo resume a coroutine,
4805280405Srpauloyou remove any results from the last <a href="#lua_yield"><code>lua_yield</code></a>,
4806280405Srpauloput on its stack only the values to
4807280405Srpaulobe passed as results from <code>yield</code>,
4808280405Srpauloand then call <a href="#lua_resume"><code>lua_resume</code></a>.
4809280405Srpaulo
4810280405Srpaulo
4811280405Srpaulo<p>
4812280405SrpauloThe parameter <code>from</code> represents the coroutine that is resuming <code>L</code>.
4813280405SrpauloIf there is no such coroutine,
4814280405Srpaulothis parameter can be <code>NULL</code>.
4815280405Srpaulo
4816280405Srpaulo
4817280405Srpaulo
4818280405Srpaulo
4819280405Srpaulo
4820280405Srpaulo<hr><h3><a name="lua_rotate"><code>lua_rotate</code></a></h3><p>
4821280405Srpaulo<span class="apii">[-0, +0, &ndash;]</span>
4822280405Srpaulo<pre>void lua_rotate (lua_State *L, int idx, int n);</pre>
4823280405Srpaulo
4824280405Srpaulo<p>
4825326344SimpRotates the stack elements between the valid index <code>idx</code>
4826326344Simpand the top of the stack.
4827326344SimpThe elements are rotated <code>n</code> positions in the direction of the top,
4828326344Simpfor a positive <code>n</code>,
4829280405Srpauloor <code>-n</code> positions in the direction of the bottom,
4830280405Srpaulofor a negative <code>n</code>.
4831280405SrpauloThe absolute value of <code>n</code> must not be greater than the size
4832280405Srpauloof the slice being rotated.
4833326344SimpThis function cannot be called with a pseudo-index,
4834326344Simpbecause a pseudo-index is not an actual stack position.
4835280405Srpaulo
4836280405Srpaulo
4837280405Srpaulo
4838280405Srpaulo
4839280405Srpaulo
4840280405Srpaulo<hr><h3><a name="lua_setallocf"><code>lua_setallocf</code></a></h3><p>
4841280405Srpaulo<span class="apii">[-0, +0, &ndash;]</span>
4842280405Srpaulo<pre>void lua_setallocf (lua_State *L, lua_Alloc f, void *ud);</pre>
4843280405Srpaulo
4844280405Srpaulo<p>
4845280405SrpauloChanges the allocator function of a given state to <code>f</code>
4846280405Srpaulowith user data <code>ud</code>.
4847280405Srpaulo
4848280405Srpaulo
4849280405Srpaulo
4850280405Srpaulo
4851280405Srpaulo
4852280405Srpaulo<hr><h3><a name="lua_setfield"><code>lua_setfield</code></a></h3><p>
4853280405Srpaulo<span class="apii">[-1, +0, <em>e</em>]</span>
4854280405Srpaulo<pre>void lua_setfield (lua_State *L, int index, const char *k);</pre>
4855280405Srpaulo
4856280405Srpaulo<p>
4857280405SrpauloDoes the equivalent to <code>t[k] = v</code>,
4858280405Srpaulowhere <code>t</code> is the value at the given index
4859280405Srpauloand <code>v</code> is the value at the top of the stack.
4860280405Srpaulo
4861280405Srpaulo
4862280405Srpaulo<p>
4863280405SrpauloThis function pops the value from the stack.
4864280405SrpauloAs in Lua, this function may trigger a metamethod
4865280405Srpaulofor the "newindex" event (see <a href="#2.4">&sect;2.4</a>).
4866280405Srpaulo
4867280405Srpaulo
4868280405Srpaulo
4869280405Srpaulo
4870280405Srpaulo
4871280405Srpaulo<hr><h3><a name="lua_setglobal"><code>lua_setglobal</code></a></h3><p>
4872280405Srpaulo<span class="apii">[-1, +0, <em>e</em>]</span>
4873280405Srpaulo<pre>void lua_setglobal (lua_State *L, const char *name);</pre>
4874280405Srpaulo
4875280405Srpaulo<p>
4876280405SrpauloPops a value from the stack and
4877280405Srpaulosets it as the new value of global <code>name</code>.
4878280405Srpaulo
4879280405Srpaulo
4880280405Srpaulo
4881280405Srpaulo
4882280405Srpaulo
4883280405Srpaulo<hr><h3><a name="lua_seti"><code>lua_seti</code></a></h3><p>
4884280405Srpaulo<span class="apii">[-1, +0, <em>e</em>]</span>
4885280405Srpaulo<pre>void lua_seti (lua_State *L, int index, lua_Integer n);</pre>
4886280405Srpaulo
4887280405Srpaulo<p>
4888280405SrpauloDoes the equivalent to <code>t[n] = v</code>,
4889280405Srpaulowhere <code>t</code> is the value at the given index
4890280405Srpauloand <code>v</code> is the value at the top of the stack.
4891280405Srpaulo
4892280405Srpaulo
4893280405Srpaulo<p>
4894280405SrpauloThis function pops the value from the stack.
4895280405SrpauloAs in Lua, this function may trigger a metamethod
4896280405Srpaulofor the "newindex" event (see <a href="#2.4">&sect;2.4</a>).
4897280405Srpaulo
4898280405Srpaulo
4899280405Srpaulo
4900280405Srpaulo
4901280405Srpaulo
4902280405Srpaulo<hr><h3><a name="lua_setmetatable"><code>lua_setmetatable</code></a></h3><p>
4903280405Srpaulo<span class="apii">[-1, +0, &ndash;]</span>
4904280405Srpaulo<pre>void lua_setmetatable (lua_State *L, int index);</pre>
4905280405Srpaulo
4906280405Srpaulo<p>
4907280405SrpauloPops a table from the stack and
4908280405Srpaulosets it as the new metatable for the value at the given index.
4909280405Srpaulo
4910280405Srpaulo
4911280405Srpaulo
4912280405Srpaulo
4913280405Srpaulo
4914280405Srpaulo<hr><h3><a name="lua_settable"><code>lua_settable</code></a></h3><p>
4915280405Srpaulo<span class="apii">[-2, +0, <em>e</em>]</span>
4916280405Srpaulo<pre>void lua_settable (lua_State *L, int index);</pre>
4917280405Srpaulo
4918280405Srpaulo<p>
4919280405SrpauloDoes the equivalent to <code>t[k] = v</code>,
4920280405Srpaulowhere <code>t</code> is the value at the given index,
4921280405Srpaulo<code>v</code> is the value at the top of the stack,
4922280405Srpauloand <code>k</code> is the value just below the top.
4923280405Srpaulo
4924280405Srpaulo
4925280405Srpaulo<p>
4926280405SrpauloThis function pops both the key and the value from the stack.
4927280405SrpauloAs in Lua, this function may trigger a metamethod
4928280405Srpaulofor the "newindex" event (see <a href="#2.4">&sect;2.4</a>).
4929280405Srpaulo
4930280405Srpaulo
4931280405Srpaulo
4932280405Srpaulo
4933280405Srpaulo
4934280405Srpaulo<hr><h3><a name="lua_settop"><code>lua_settop</code></a></h3><p>
4935280405Srpaulo<span class="apii">[-?, +?, &ndash;]</span>
4936280405Srpaulo<pre>void lua_settop (lua_State *L, int index);</pre>
4937280405Srpaulo
4938280405Srpaulo<p>
4939280405SrpauloAccepts any index, or&nbsp;0,
4940280405Srpauloand sets the stack top to this index.
4941280405SrpauloIf the new top is larger than the old one,
4942280405Srpaulothen the new elements are filled with <b>nil</b>.
4943280405SrpauloIf <code>index</code> is&nbsp;0, then all stack elements are removed.
4944280405Srpaulo
4945280405Srpaulo
4946280405Srpaulo
4947280405Srpaulo
4948280405Srpaulo
4949280405Srpaulo<hr><h3><a name="lua_setuservalue"><code>lua_setuservalue</code></a></h3><p>
4950280405Srpaulo<span class="apii">[-1, +0, &ndash;]</span>
4951280405Srpaulo<pre>void lua_setuservalue (lua_State *L, int index);</pre>
4952280405Srpaulo
4953280405Srpaulo<p>
4954280405SrpauloPops a value from the stack and sets it as
4955326344Simpthe new value associated to the full userdata at the given index.
4956280405Srpaulo
4957280405Srpaulo
4958280405Srpaulo
4959280405Srpaulo
4960280405Srpaulo
4961280405Srpaulo<hr><h3><a name="lua_State"><code>lua_State</code></a></h3>
4962280405Srpaulo<pre>typedef struct lua_State lua_State;</pre>
4963280405Srpaulo
4964280405Srpaulo<p>
4965280405SrpauloAn opaque structure that points to a thread and indirectly
4966280405Srpaulo(through the thread) to the whole state of a Lua interpreter.
4967280405SrpauloThe Lua library is fully reentrant:
4968280405Srpauloit has no global variables.
4969280405SrpauloAll information about a state is accessible through this structure.
4970280405Srpaulo
4971280405Srpaulo
4972280405Srpaulo<p>
4973280405SrpauloA pointer to this structure must be passed as the first argument to
4974280405Srpauloevery function in the library, except to <a href="#lua_newstate"><code>lua_newstate</code></a>,
4975280405Srpaulowhich creates a Lua state from scratch.
4976280405Srpaulo
4977280405Srpaulo
4978280405Srpaulo
4979280405Srpaulo
4980280405Srpaulo
4981280405Srpaulo<hr><h3><a name="lua_status"><code>lua_status</code></a></h3><p>
4982280405Srpaulo<span class="apii">[-0, +0, &ndash;]</span>
4983280405Srpaulo<pre>int lua_status (lua_State *L);</pre>
4984280405Srpaulo
4985280405Srpaulo<p>
4986280405SrpauloReturns the status of the thread <code>L</code>.
4987280405Srpaulo
4988280405Srpaulo
4989280405Srpaulo<p>
4990280405SrpauloThe status can be 0 (<a href="#pdf-LUA_OK"><code>LUA_OK</code></a>) for a normal thread,
4991280405Srpauloan error code if the thread finished the execution
4992280405Srpauloof a <a href="#lua_resume"><code>lua_resume</code></a> with an error,
4993280405Srpauloor <a name="pdf-LUA_YIELD"><code>LUA_YIELD</code></a> if the thread is suspended.
4994280405Srpaulo
4995280405Srpaulo
4996280405Srpaulo<p>
4997280405SrpauloYou can only call functions in threads with status <a href="#pdf-LUA_OK"><code>LUA_OK</code></a>.
4998280405SrpauloYou can resume threads with status <a href="#pdf-LUA_OK"><code>LUA_OK</code></a>
4999280405Srpaulo(to start a new coroutine) or <a href="#pdf-LUA_YIELD"><code>LUA_YIELD</code></a>
5000280405Srpaulo(to resume a coroutine).
5001280405Srpaulo
5002280405Srpaulo
5003280405Srpaulo
5004280405Srpaulo
5005280405Srpaulo
5006280405Srpaulo<hr><h3><a name="lua_stringtonumber"><code>lua_stringtonumber</code></a></h3><p>
5007280405Srpaulo<span class="apii">[-0, +1, &ndash;]</span>
5008280405Srpaulo<pre>size_t lua_stringtonumber (lua_State *L, const char *s);</pre>
5009280405Srpaulo
5010280405Srpaulo<p>
5011280405SrpauloConverts the zero-terminated string <code>s</code> to a number,
5012280405Srpaulopushes that number into the stack,
5013280405Srpauloand returns the total size of the string,
5014280405Srpaulothat is, its length plus one.
5015280405SrpauloThe conversion can result in an integer or a float,
5016280405Srpauloaccording to the lexical conventions of Lua (see <a href="#3.1">&sect;3.1</a>).
5017280405SrpauloThe string may have leading and trailing spaces and a sign.
5018280405SrpauloIf the string is not a valid numeral,
5019280405Srpauloreturns 0 and pushes nothing.
5020280405Srpaulo(Note that the result can be used as a boolean,
5021280405Srpaulotrue if the conversion succeeds.)
5022280405Srpaulo
5023280405Srpaulo
5024280405Srpaulo
5025280405Srpaulo
5026280405Srpaulo
5027280405Srpaulo<hr><h3><a name="lua_toboolean"><code>lua_toboolean</code></a></h3><p>
5028280405Srpaulo<span class="apii">[-0, +0, &ndash;]</span>
5029280405Srpaulo<pre>int lua_toboolean (lua_State *L, int index);</pre>
5030280405Srpaulo
5031280405Srpaulo<p>
5032280405SrpauloConverts the Lua value at the given index to a C&nbsp;boolean
5033280405Srpaulovalue (0&nbsp;or&nbsp;1).
5034280405SrpauloLike all tests in Lua,
5035280405Srpaulo<a href="#lua_toboolean"><code>lua_toboolean</code></a> returns true for any Lua value
5036280405Srpaulodifferent from <b>false</b> and <b>nil</b>;
5037280405Srpaulootherwise it returns false.
5038280405Srpaulo(If you want to accept only actual boolean values,
5039280405Srpaulouse <a href="#lua_isboolean"><code>lua_isboolean</code></a> to test the value's type.)
5040280405Srpaulo
5041280405Srpaulo
5042280405Srpaulo
5043280405Srpaulo
5044280405Srpaulo
5045280405Srpaulo<hr><h3><a name="lua_tocfunction"><code>lua_tocfunction</code></a></h3><p>
5046280405Srpaulo<span class="apii">[-0, +0, &ndash;]</span>
5047280405Srpaulo<pre>lua_CFunction lua_tocfunction (lua_State *L, int index);</pre>
5048280405Srpaulo
5049280405Srpaulo<p>
5050280405SrpauloConverts a value at the given index to a C&nbsp;function.
5051280405SrpauloThat value must be a C&nbsp;function;
5052280405Srpaulootherwise, returns <code>NULL</code>.
5053280405Srpaulo
5054280405Srpaulo
5055280405Srpaulo
5056280405Srpaulo
5057280405Srpaulo
5058280405Srpaulo<hr><h3><a name="lua_tointeger"><code>lua_tointeger</code></a></h3><p>
5059280405Srpaulo<span class="apii">[-0, +0, &ndash;]</span>
5060280405Srpaulo<pre>lua_Integer lua_tointeger (lua_State *L, int index);</pre>
5061280405Srpaulo
5062280405Srpaulo<p>
5063280405SrpauloEquivalent to <a href="#lua_tointegerx"><code>lua_tointegerx</code></a> with <code>isnum</code> equal to <code>NULL</code>.
5064280405Srpaulo
5065280405Srpaulo
5066280405Srpaulo
5067280405Srpaulo
5068280405Srpaulo
5069280405Srpaulo<hr><h3><a name="lua_tointegerx"><code>lua_tointegerx</code></a></h3><p>
5070280405Srpaulo<span class="apii">[-0, +0, &ndash;]</span>
5071280405Srpaulo<pre>lua_Integer lua_tointegerx (lua_State *L, int index, int *isnum);</pre>
5072280405Srpaulo
5073280405Srpaulo<p>
5074280405SrpauloConverts the Lua value at the given index
5075280405Srpauloto the signed integral type <a href="#lua_Integer"><code>lua_Integer</code></a>.
5076280405SrpauloThe Lua value must be an integer,
5077280405Srpauloor a number or string convertible to an integer (see <a href="#3.4.3">&sect;3.4.3</a>);
5078280405Srpaulootherwise, <code>lua_tointegerx</code> returns&nbsp;0.
5079280405Srpaulo
5080280405Srpaulo
5081280405Srpaulo<p>
5082280405SrpauloIf <code>isnum</code> is not <code>NULL</code>,
5083280405Srpauloits referent is assigned a boolean value that
5084280405Srpauloindicates whether the operation succeeded.
5085280405Srpaulo
5086280405Srpaulo
5087280405Srpaulo
5088280405Srpaulo
5089280405Srpaulo
5090280405Srpaulo<hr><h3><a name="lua_tolstring"><code>lua_tolstring</code></a></h3><p>
5091326344Simp<span class="apii">[-0, +0, <em>m</em>]</span>
5092280405Srpaulo<pre>const char *lua_tolstring (lua_State *L, int index, size_t *len);</pre>
5093280405Srpaulo
5094280405Srpaulo<p>
5095280405SrpauloConverts the Lua value at the given index to a C&nbsp;string.
5096280405SrpauloIf <code>len</code> is not <code>NULL</code>,
5097326344Simpit sets <code>*len</code> with the string length.
5098280405SrpauloThe Lua value must be a string or a number;
5099280405Srpaulootherwise, the function returns <code>NULL</code>.
5100280405SrpauloIf the value is a number,
5101280405Srpaulothen <code>lua_tolstring</code> also
5102280405Srpaulo<em>changes the actual value in the stack to a string</em>.
5103280405Srpaulo(This change confuses <a href="#lua_next"><code>lua_next</code></a>
5104280405Srpaulowhen <code>lua_tolstring</code> is applied to keys during a table traversal.)
5105280405Srpaulo
5106280405Srpaulo
5107280405Srpaulo<p>
5108326344Simp<code>lua_tolstring</code> returns a pointer
5109280405Srpauloto a string inside the Lua state.
5110280405SrpauloThis string always has a zero ('<code>\0</code>')
5111280405Srpauloafter its last character (as in&nbsp;C),
5112280405Srpaulobut can contain other zeros in its body.
5113280405Srpaulo
5114280405Srpaulo
5115280405Srpaulo<p>
5116280405SrpauloBecause Lua has garbage collection,
5117280405Srpaulothere is no guarantee that the pointer returned by <code>lua_tolstring</code>
5118280405Srpaulowill be valid after the corresponding Lua value is removed from the stack.
5119280405Srpaulo
5120280405Srpaulo
5121280405Srpaulo
5122280405Srpaulo
5123280405Srpaulo
5124280405Srpaulo<hr><h3><a name="lua_tonumber"><code>lua_tonumber</code></a></h3><p>
5125280405Srpaulo<span class="apii">[-0, +0, &ndash;]</span>
5126280405Srpaulo<pre>lua_Number lua_tonumber (lua_State *L, int index);</pre>
5127280405Srpaulo
5128280405Srpaulo<p>
5129280405SrpauloEquivalent to <a href="#lua_tonumberx"><code>lua_tonumberx</code></a> with <code>isnum</code> equal to <code>NULL</code>.
5130280405Srpaulo
5131280405Srpaulo
5132280405Srpaulo
5133280405Srpaulo
5134280405Srpaulo
5135280405Srpaulo<hr><h3><a name="lua_tonumberx"><code>lua_tonumberx</code></a></h3><p>
5136280405Srpaulo<span class="apii">[-0, +0, &ndash;]</span>
5137280405Srpaulo<pre>lua_Number lua_tonumberx (lua_State *L, int index, int *isnum);</pre>
5138280405Srpaulo
5139280405Srpaulo<p>
5140280405SrpauloConverts the Lua value at the given index
5141280405Srpauloto the C&nbsp;type <a href="#lua_Number"><code>lua_Number</code></a> (see <a href="#lua_Number"><code>lua_Number</code></a>).
5142280405SrpauloThe Lua value must be a number or a string convertible to a number
5143280405Srpaulo(see <a href="#3.4.3">&sect;3.4.3</a>);
5144280405Srpaulootherwise, <a href="#lua_tonumberx"><code>lua_tonumberx</code></a> returns&nbsp;0.
5145280405Srpaulo
5146280405Srpaulo
5147280405Srpaulo<p>
5148280405SrpauloIf <code>isnum</code> is not <code>NULL</code>,
5149280405Srpauloits referent is assigned a boolean value that
5150280405Srpauloindicates whether the operation succeeded.
5151280405Srpaulo
5152280405Srpaulo
5153280405Srpaulo
5154280405Srpaulo
5155280405Srpaulo
5156280405Srpaulo<hr><h3><a name="lua_topointer"><code>lua_topointer</code></a></h3><p>
5157280405Srpaulo<span class="apii">[-0, +0, &ndash;]</span>
5158280405Srpaulo<pre>const void *lua_topointer (lua_State *L, int index);</pre>
5159280405Srpaulo
5160280405Srpaulo<p>
5161280405SrpauloConverts the value at the given index to a generic
5162280405SrpauloC&nbsp;pointer (<code>void*</code>).
5163280405SrpauloThe value can be a userdata, a table, a thread, or a function;
5164280405Srpaulootherwise, <code>lua_topointer</code> returns <code>NULL</code>.
5165280405SrpauloDifferent objects will give different pointers.
5166280405SrpauloThere is no way to convert the pointer back to its original value.
5167280405Srpaulo
5168280405Srpaulo
5169280405Srpaulo<p>
5170326344SimpTypically this function is used only for hashing and debug information.
5171280405Srpaulo
5172280405Srpaulo
5173280405Srpaulo
5174280405Srpaulo
5175280405Srpaulo
5176280405Srpaulo<hr><h3><a name="lua_tostring"><code>lua_tostring</code></a></h3><p>
5177326344Simp<span class="apii">[-0, +0, <em>m</em>]</span>
5178280405Srpaulo<pre>const char *lua_tostring (lua_State *L, int index);</pre>
5179280405Srpaulo
5180280405Srpaulo<p>
5181280405SrpauloEquivalent to <a href="#lua_tolstring"><code>lua_tolstring</code></a> with <code>len</code> equal to <code>NULL</code>.
5182280405Srpaulo
5183280405Srpaulo
5184280405Srpaulo
5185280405Srpaulo
5186280405Srpaulo
5187280405Srpaulo<hr><h3><a name="lua_tothread"><code>lua_tothread</code></a></h3><p>
5188280405Srpaulo<span class="apii">[-0, +0, &ndash;]</span>
5189280405Srpaulo<pre>lua_State *lua_tothread (lua_State *L, int index);</pre>
5190280405Srpaulo
5191280405Srpaulo<p>
5192280405SrpauloConverts the value at the given index to a Lua thread
5193280405Srpaulo(represented as <code>lua_State*</code>).
5194280405SrpauloThis value must be a thread;
5195280405Srpaulootherwise, the function returns <code>NULL</code>.
5196280405Srpaulo
5197280405Srpaulo
5198280405Srpaulo
5199280405Srpaulo
5200280405Srpaulo
5201280405Srpaulo<hr><h3><a name="lua_touserdata"><code>lua_touserdata</code></a></h3><p>
5202280405Srpaulo<span class="apii">[-0, +0, &ndash;]</span>
5203280405Srpaulo<pre>void *lua_touserdata (lua_State *L, int index);</pre>
5204280405Srpaulo
5205280405Srpaulo<p>
5206280405SrpauloIf the value at the given index is a full userdata,
5207280405Srpauloreturns its block address.
5208280405SrpauloIf the value is a light userdata,
5209280405Srpauloreturns its pointer.
5210280405SrpauloOtherwise, returns <code>NULL</code>.
5211280405Srpaulo
5212280405Srpaulo
5213280405Srpaulo
5214280405Srpaulo
5215280405Srpaulo
5216280405Srpaulo<hr><h3><a name="lua_type"><code>lua_type</code></a></h3><p>
5217280405Srpaulo<span class="apii">[-0, +0, &ndash;]</span>
5218280405Srpaulo<pre>int lua_type (lua_State *L, int index);</pre>
5219280405Srpaulo
5220280405Srpaulo<p>
5221280405SrpauloReturns the type of the value in the given valid index,
5222280405Srpauloor <code>LUA_TNONE</code> for a non-valid (but acceptable) index.
5223280405SrpauloThe types returned by <a href="#lua_type"><code>lua_type</code></a> are coded by the following constants
5224280405Srpaulodefined in <code>lua.h</code>:
5225326344Simp<a name="pdf-LUA_TNIL"><code>LUA_TNIL</code></a> (0),
5226280405Srpaulo<a name="pdf-LUA_TNUMBER"><code>LUA_TNUMBER</code></a>,
5227280405Srpaulo<a name="pdf-LUA_TBOOLEAN"><code>LUA_TBOOLEAN</code></a>,
5228280405Srpaulo<a name="pdf-LUA_TSTRING"><code>LUA_TSTRING</code></a>,
5229280405Srpaulo<a name="pdf-LUA_TTABLE"><code>LUA_TTABLE</code></a>,
5230280405Srpaulo<a name="pdf-LUA_TFUNCTION"><code>LUA_TFUNCTION</code></a>,
5231280405Srpaulo<a name="pdf-LUA_TUSERDATA"><code>LUA_TUSERDATA</code></a>,
5232280405Srpaulo<a name="pdf-LUA_TTHREAD"><code>LUA_TTHREAD</code></a>,
5233280405Srpauloand
5234280405Srpaulo<a name="pdf-LUA_TLIGHTUSERDATA"><code>LUA_TLIGHTUSERDATA</code></a>.
5235280405Srpaulo
5236280405Srpaulo
5237280405Srpaulo
5238280405Srpaulo
5239280405Srpaulo
5240280405Srpaulo<hr><h3><a name="lua_typename"><code>lua_typename</code></a></h3><p>
5241280405Srpaulo<span class="apii">[-0, +0, &ndash;]</span>
5242280405Srpaulo<pre>const char *lua_typename (lua_State *L, int tp);</pre>
5243280405Srpaulo
5244280405Srpaulo<p>
5245280405SrpauloReturns the name of the type encoded by the value <code>tp</code>,
5246280405Srpaulowhich must be one the values returned by <a href="#lua_type"><code>lua_type</code></a>.
5247280405Srpaulo
5248280405Srpaulo
5249280405Srpaulo
5250280405Srpaulo
5251280405Srpaulo
5252280405Srpaulo<hr><h3><a name="lua_Unsigned"><code>lua_Unsigned</code></a></h3>
5253280405Srpaulo<pre>typedef ... lua_Unsigned;</pre>
5254280405Srpaulo
5255280405Srpaulo<p>
5256280405SrpauloThe unsigned version of <a href="#lua_Integer"><code>lua_Integer</code></a>.
5257280405Srpaulo
5258280405Srpaulo
5259280405Srpaulo
5260280405Srpaulo
5261280405Srpaulo
5262280405Srpaulo<hr><h3><a name="lua_upvalueindex"><code>lua_upvalueindex</code></a></h3><p>
5263280405Srpaulo<span class="apii">[-0, +0, &ndash;]</span>
5264280405Srpaulo<pre>int lua_upvalueindex (int i);</pre>
5265280405Srpaulo
5266280405Srpaulo<p>
5267280405SrpauloReturns the pseudo-index that represents the <code>i</code>-th upvalue of
5268280405Srpaulothe running function (see <a href="#4.4">&sect;4.4</a>).
5269280405Srpaulo
5270280405Srpaulo
5271280405Srpaulo
5272280405Srpaulo
5273280405Srpaulo
5274280405Srpaulo<hr><h3><a name="lua_version"><code>lua_version</code></a></h3><p>
5275326344Simp<span class="apii">[-0, +0, &ndash;]</span>
5276280405Srpaulo<pre>const lua_Number *lua_version (lua_State *L);</pre>
5277280405Srpaulo
5278280405Srpaulo<p>
5279326344SimpReturns the address of the version number
5280326344Simp(a C static variable)
5281326344Simpstored in the Lua core.
5282280405SrpauloWhen called with a valid <a href="#lua_State"><code>lua_State</code></a>,
5283280405Srpauloreturns the address of the version used to create that state.
5284280405SrpauloWhen called with <code>NULL</code>,
5285280405Srpauloreturns the address of the version running the call.
5286280405Srpaulo
5287280405Srpaulo
5288280405Srpaulo
5289280405Srpaulo
5290280405Srpaulo
5291280405Srpaulo<hr><h3><a name="lua_Writer"><code>lua_Writer</code></a></h3>
5292280405Srpaulo<pre>typedef int (*lua_Writer) (lua_State *L,
5293280405Srpaulo                           const void* p,
5294280405Srpaulo                           size_t sz,
5295280405Srpaulo                           void* ud);</pre>
5296280405Srpaulo
5297280405Srpaulo<p>
5298280405SrpauloThe type of the writer function used by <a href="#lua_dump"><code>lua_dump</code></a>.
5299280405SrpauloEvery time it produces another piece of chunk,
5300280405Srpaulo<a href="#lua_dump"><code>lua_dump</code></a> calls the writer,
5301280405Srpaulopassing along the buffer to be written (<code>p</code>),
5302280405Srpauloits size (<code>sz</code>),
5303280405Srpauloand the <code>data</code> parameter supplied to <a href="#lua_dump"><code>lua_dump</code></a>.
5304280405Srpaulo
5305280405Srpaulo
5306280405Srpaulo<p>
5307280405SrpauloThe writer returns an error code:
5308280405Srpaulo0&nbsp;means no errors;
5309280405Srpauloany other value means an error and stops <a href="#lua_dump"><code>lua_dump</code></a> from
5310280405Srpaulocalling the writer again.
5311280405Srpaulo
5312280405Srpaulo
5313280405Srpaulo
5314280405Srpaulo
5315280405Srpaulo
5316280405Srpaulo<hr><h3><a name="lua_xmove"><code>lua_xmove</code></a></h3><p>
5317280405Srpaulo<span class="apii">[-?, +?, &ndash;]</span>
5318280405Srpaulo<pre>void lua_xmove (lua_State *from, lua_State *to, int n);</pre>
5319280405Srpaulo
5320280405Srpaulo<p>
5321280405SrpauloExchange values between different threads of the same state.
5322280405Srpaulo
5323280405Srpaulo
5324280405Srpaulo<p>
5325280405SrpauloThis function pops <code>n</code> values from the stack <code>from</code>,
5326280405Srpauloand pushes them onto the stack <code>to</code>.
5327280405Srpaulo
5328280405Srpaulo
5329280405Srpaulo
5330280405Srpaulo
5331280405Srpaulo
5332280405Srpaulo<hr><h3><a name="lua_yield"><code>lua_yield</code></a></h3><p>
5333280405Srpaulo<span class="apii">[-?, +?, <em>e</em>]</span>
5334280405Srpaulo<pre>int lua_yield (lua_State *L, int nresults);</pre>
5335280405Srpaulo
5336280405Srpaulo<p>
5337280405SrpauloThis function is equivalent to <a href="#lua_yieldk"><code>lua_yieldk</code></a>,
5338280405Srpaulobut it has no continuation (see <a href="#4.7">&sect;4.7</a>).
5339280405SrpauloTherefore, when the thread resumes,
5340280405Srpauloit continues the function that called
5341280405Srpaulothe function calling <code>lua_yield</code>.
5342280405Srpaulo
5343280405Srpaulo
5344280405Srpaulo
5345280405Srpaulo
5346280405Srpaulo
5347280405Srpaulo<hr><h3><a name="lua_yieldk"><code>lua_yieldk</code></a></h3><p>
5348280405Srpaulo<span class="apii">[-?, +?, <em>e</em>]</span>
5349280405Srpaulo<pre>int lua_yieldk (lua_State *L,
5350280405Srpaulo                int nresults,
5351280405Srpaulo                lua_KContext ctx,
5352280405Srpaulo                lua_KFunction k);</pre>
5353280405Srpaulo
5354280405Srpaulo<p>
5355280405SrpauloYields a coroutine (thread).
5356280405Srpaulo
5357280405Srpaulo
5358280405Srpaulo<p>
5359280405SrpauloWhen a C&nbsp;function calls <a href="#lua_yieldk"><code>lua_yieldk</code></a>,
5360280405Srpaulothe running coroutine suspends its execution,
5361280405Srpauloand the call to <a href="#lua_resume"><code>lua_resume</code></a> that started this coroutine returns.
5362280405SrpauloThe parameter <code>nresults</code> is the number of values from the stack
5363280405Srpaulothat will be passed as results to <a href="#lua_resume"><code>lua_resume</code></a>.
5364280405Srpaulo
5365280405Srpaulo
5366280405Srpaulo<p>
5367280405SrpauloWhen the coroutine is resumed again,
5368280405SrpauloLua calls the given continuation function <code>k</code> to continue
5369326344Simpthe execution of the C&nbsp;function that yielded (see <a href="#4.7">&sect;4.7</a>).
5370280405SrpauloThis continuation function receives the same stack
5371280405Srpaulofrom the previous function,
5372280405Srpaulowith the <code>n</code> results removed and
5373280405Srpauloreplaced by the arguments passed to <a href="#lua_resume"><code>lua_resume</code></a>.
5374280405SrpauloMoreover,
5375280405Srpaulothe continuation function receives the value <code>ctx</code>
5376280405Srpaulothat was passed to <a href="#lua_yieldk"><code>lua_yieldk</code></a>.
5377280405Srpaulo
5378280405Srpaulo
5379280405Srpaulo<p>
5380280405SrpauloUsually, this function does not return;
5381280405Srpaulowhen the coroutine eventually resumes,
5382280405Srpauloit continues executing the continuation function.
5383280405SrpauloHowever, there is one special case,
5384280405Srpaulowhich is when this function is called
5385326344Simpfrom inside a line or a count hook (see <a href="#4.9">&sect;4.9</a>).
5386280405SrpauloIn that case, <code>lua_yieldk</code> should be called with no continuation
5387326344Simp(probably in the form of <a href="#lua_yield"><code>lua_yield</code></a>) and no results,
5388280405Srpauloand the hook should return immediately after the call.
5389280405SrpauloLua will yield and,
5390280405Srpaulowhen the coroutine resumes again,
5391280405Srpauloit will continue the normal execution
5392280405Srpauloof the (Lua) function that triggered the hook.
5393280405Srpaulo
5394280405Srpaulo
5395280405Srpaulo<p>
5396280405SrpauloThis function can raise an error if it is called from a thread
5397280405Srpaulowith a pending C call with no continuation function,
5398280405Srpauloor it is called from a thread that is not running inside a resume
5399280405Srpaulo(e.g., the main thread).
5400280405Srpaulo
5401280405Srpaulo
5402280405Srpaulo
5403280405Srpaulo
5404280405Srpaulo
5405280405Srpaulo
5406280405Srpaulo
5407280405Srpaulo<h2>4.9 &ndash; <a name="4.9">The Debug Interface</a></h2>
5408280405Srpaulo
5409280405Srpaulo<p>
5410280405SrpauloLua has no built-in debugging facilities.
5411280405SrpauloInstead, it offers a special interface
5412280405Srpauloby means of functions and <em>hooks</em>.
5413280405SrpauloThis interface allows the construction of different
5414280405Srpaulokinds of debuggers, profilers, and other tools
5415280405Srpaulothat need "inside information" from the interpreter.
5416280405Srpaulo
5417280405Srpaulo
5418280405Srpaulo
5419280405Srpaulo<hr><h3><a name="lua_Debug"><code>lua_Debug</code></a></h3>
5420280405Srpaulo<pre>typedef struct lua_Debug {
5421280405Srpaulo  int event;
5422280405Srpaulo  const char *name;           /* (n) */
5423280405Srpaulo  const char *namewhat;       /* (n) */
5424280405Srpaulo  const char *what;           /* (S) */
5425280405Srpaulo  const char *source;         /* (S) */
5426280405Srpaulo  int currentline;            /* (l) */
5427280405Srpaulo  int linedefined;            /* (S) */
5428280405Srpaulo  int lastlinedefined;        /* (S) */
5429280405Srpaulo  unsigned char nups;         /* (u) number of upvalues */
5430280405Srpaulo  unsigned char nparams;      /* (u) number of parameters */
5431280405Srpaulo  char isvararg;              /* (u) */
5432280405Srpaulo  char istailcall;            /* (t) */
5433280405Srpaulo  char short_src[LUA_IDSIZE]; /* (S) */
5434280405Srpaulo  /* private part */
5435280405Srpaulo  <em>other fields</em>
5436280405Srpaulo} lua_Debug;</pre>
5437280405Srpaulo
5438280405Srpaulo<p>
5439280405SrpauloA structure used to carry different pieces of
5440280405Srpauloinformation about a function or an activation record.
5441280405Srpaulo<a href="#lua_getstack"><code>lua_getstack</code></a> fills only the private part
5442280405Srpauloof this structure, for later use.
5443280405SrpauloTo fill the other fields of <a href="#lua_Debug"><code>lua_Debug</code></a> with useful information,
5444280405Srpaulocall <a href="#lua_getinfo"><code>lua_getinfo</code></a>.
5445280405Srpaulo
5446280405Srpaulo
5447280405Srpaulo<p>
5448280405SrpauloThe fields of <a href="#lua_Debug"><code>lua_Debug</code></a> have the following meaning:
5449280405Srpaulo
5450280405Srpaulo<ul>
5451280405Srpaulo
5452280405Srpaulo<li><b><code>source</code>: </b>
5453280405Srpaulothe name of the chunk that created the function.
5454280405SrpauloIf <code>source</code> starts with a '<code>@</code>',
5455280405Srpauloit means that the function was defined in a file where
5456280405Srpaulothe file name follows the '<code>@</code>'.
5457280405SrpauloIf <code>source</code> starts with a '<code>=</code>',
5458280405Srpaulothe remainder of its contents describe the source in a user-dependent manner.
5459280405SrpauloOtherwise,
5460280405Srpaulothe function was defined in a string where
5461280405Srpaulo<code>source</code> is that string.
5462280405Srpaulo</li>
5463280405Srpaulo
5464280405Srpaulo<li><b><code>short_src</code>: </b>
5465280405Srpauloa "printable" version of <code>source</code>, to be used in error messages.
5466280405Srpaulo</li>
5467280405Srpaulo
5468280405Srpaulo<li><b><code>linedefined</code>: </b>
5469280405Srpaulothe line number where the definition of the function starts.
5470280405Srpaulo</li>
5471280405Srpaulo
5472280405Srpaulo<li><b><code>lastlinedefined</code>: </b>
5473280405Srpaulothe line number where the definition of the function ends.
5474280405Srpaulo</li>
5475280405Srpaulo
5476280405Srpaulo<li><b><code>what</code>: </b>
5477280405Srpaulothe string <code>"Lua"</code> if the function is a Lua function,
5478280405Srpaulo<code>"C"</code> if it is a C&nbsp;function,
5479280405Srpaulo<code>"main"</code> if it is the main part of a chunk.
5480280405Srpaulo</li>
5481280405Srpaulo
5482280405Srpaulo<li><b><code>currentline</code>: </b>
5483280405Srpaulothe current line where the given function is executing.
5484280405SrpauloWhen no line information is available,
5485280405Srpaulo<code>currentline</code> is set to -1.
5486280405Srpaulo</li>
5487280405Srpaulo
5488280405Srpaulo<li><b><code>name</code>: </b>
5489280405Srpauloa reasonable name for the given function.
5490280405SrpauloBecause functions in Lua are first-class values,
5491280405Srpaulothey do not have a fixed name:
5492280405Srpaulosome functions can be the value of multiple global variables,
5493280405Srpaulowhile others can be stored only in a table field.
5494280405SrpauloThe <code>lua_getinfo</code> function checks how the function was
5495280405Srpaulocalled to find a suitable name.
5496280405SrpauloIf it cannot find a name,
5497280405Srpaulothen <code>name</code> is set to <code>NULL</code>.
5498280405Srpaulo</li>
5499280405Srpaulo
5500280405Srpaulo<li><b><code>namewhat</code>: </b>
5501280405Srpauloexplains the <code>name</code> field.
5502280405SrpauloThe value of <code>namewhat</code> can be
5503280405Srpaulo<code>"global"</code>, <code>"local"</code>, <code>"method"</code>,
5504280405Srpaulo<code>"field"</code>, <code>"upvalue"</code>, or <code>""</code> (the empty string),
5505280405Srpauloaccording to how the function was called.
5506280405Srpaulo(Lua uses the empty string when no other option seems to apply.)
5507280405Srpaulo</li>
5508280405Srpaulo
5509280405Srpaulo<li><b><code>istailcall</code>: </b>
5510280405Srpaulotrue if this function invocation was called by a tail call.
5511280405SrpauloIn this case, the caller of this level is not in the stack.
5512280405Srpaulo</li>
5513280405Srpaulo
5514280405Srpaulo<li><b><code>nups</code>: </b>
5515280405Srpaulothe number of upvalues of the function.
5516280405Srpaulo</li>
5517280405Srpaulo
5518280405Srpaulo<li><b><code>nparams</code>: </b>
5519280405Srpaulothe number of fixed parameters of the function
5520280405Srpaulo(always 0&nbsp;for C&nbsp;functions).
5521280405Srpaulo</li>
5522280405Srpaulo
5523280405Srpaulo<li><b><code>isvararg</code>: </b>
5524280405Srpaulotrue if the function is a vararg function
5525280405Srpaulo(always true for C&nbsp;functions).
5526280405Srpaulo</li>
5527280405Srpaulo
5528280405Srpaulo</ul>
5529280405Srpaulo
5530280405Srpaulo
5531280405Srpaulo
5532280405Srpaulo
5533280405Srpaulo<hr><h3><a name="lua_gethook"><code>lua_gethook</code></a></h3><p>
5534280405Srpaulo<span class="apii">[-0, +0, &ndash;]</span>
5535280405Srpaulo<pre>lua_Hook lua_gethook (lua_State *L);</pre>
5536280405Srpaulo
5537280405Srpaulo<p>
5538280405SrpauloReturns the current hook function.
5539280405Srpaulo
5540280405Srpaulo
5541280405Srpaulo
5542280405Srpaulo
5543280405Srpaulo
5544280405Srpaulo<hr><h3><a name="lua_gethookcount"><code>lua_gethookcount</code></a></h3><p>
5545280405Srpaulo<span class="apii">[-0, +0, &ndash;]</span>
5546280405Srpaulo<pre>int lua_gethookcount (lua_State *L);</pre>
5547280405Srpaulo
5548280405Srpaulo<p>
5549280405SrpauloReturns the current hook count.
5550280405Srpaulo
5551280405Srpaulo
5552280405Srpaulo
5553280405Srpaulo
5554280405Srpaulo
5555280405Srpaulo<hr><h3><a name="lua_gethookmask"><code>lua_gethookmask</code></a></h3><p>
5556280405Srpaulo<span class="apii">[-0, +0, &ndash;]</span>
5557280405Srpaulo<pre>int lua_gethookmask (lua_State *L);</pre>
5558280405Srpaulo
5559280405Srpaulo<p>
5560280405SrpauloReturns the current hook mask.
5561280405Srpaulo
5562280405Srpaulo
5563280405Srpaulo
5564280405Srpaulo
5565280405Srpaulo
5566280405Srpaulo<hr><h3><a name="lua_getinfo"><code>lua_getinfo</code></a></h3><p>
5567280405Srpaulo<span class="apii">[-(0|1), +(0|1|2), <em>e</em>]</span>
5568280405Srpaulo<pre>int lua_getinfo (lua_State *L, const char *what, lua_Debug *ar);</pre>
5569280405Srpaulo
5570280405Srpaulo<p>
5571280405SrpauloGets information about a specific function or function invocation.
5572280405Srpaulo
5573280405Srpaulo
5574280405Srpaulo<p>
5575280405SrpauloTo get information about a function invocation,
5576280405Srpaulothe parameter <code>ar</code> must be a valid activation record that was
5577280405Srpaulofilled by a previous call to <a href="#lua_getstack"><code>lua_getstack</code></a> or
5578280405Srpaulogiven as argument to a hook (see <a href="#lua_Hook"><code>lua_Hook</code></a>).
5579280405Srpaulo
5580280405Srpaulo
5581280405Srpaulo<p>
5582344220SkevansTo get information about a function, you push it onto the stack
5583280405Srpauloand start the <code>what</code> string with the character '<code>&gt;</code>'.
5584280405Srpaulo(In that case,
5585280405Srpaulo<code>lua_getinfo</code> pops the function from the top of the stack.)
5586280405SrpauloFor instance, to know in which line a function <code>f</code> was defined,
5587280405Srpauloyou can write the following code:
5588280405Srpaulo
5589280405Srpaulo<pre>
5590280405Srpaulo     lua_Debug ar;
5591280405Srpaulo     lua_getglobal(L, "f");  /* get global 'f' */
5592280405Srpaulo     lua_getinfo(L, "&gt;S", &amp;ar);
5593280405Srpaulo     printf("%d\n", ar.linedefined);
5594280405Srpaulo</pre>
5595280405Srpaulo
5596280405Srpaulo<p>
5597280405SrpauloEach character in the string <code>what</code>
5598280405Srpauloselects some fields of the structure <code>ar</code> to be filled or
5599280405Srpauloa value to be pushed on the stack:
5600280405Srpaulo
5601280405Srpaulo<ul>
5602280405Srpaulo
5603280405Srpaulo<li><b>'<code>n</code>': </b> fills in the field <code>name</code> and <code>namewhat</code>;
5604280405Srpaulo</li>
5605280405Srpaulo
5606280405Srpaulo<li><b>'<code>S</code>': </b>
5607280405Srpaulofills in the fields <code>source</code>, <code>short_src</code>,
5608280405Srpaulo<code>linedefined</code>, <code>lastlinedefined</code>, and <code>what</code>;
5609280405Srpaulo</li>
5610280405Srpaulo
5611280405Srpaulo<li><b>'<code>l</code>': </b> fills in the field <code>currentline</code>;
5612280405Srpaulo</li>
5613280405Srpaulo
5614280405Srpaulo<li><b>'<code>t</code>': </b> fills in the field <code>istailcall</code>;
5615280405Srpaulo</li>
5616280405Srpaulo
5617280405Srpaulo<li><b>'<code>u</code>': </b> fills in the fields
5618280405Srpaulo<code>nups</code>, <code>nparams</code>, and <code>isvararg</code>;
5619280405Srpaulo</li>
5620280405Srpaulo
5621280405Srpaulo<li><b>'<code>f</code>': </b>
5622280405Srpaulopushes onto the stack the function that is
5623280405Srpaulorunning at the given level;
5624280405Srpaulo</li>
5625280405Srpaulo
5626280405Srpaulo<li><b>'<code>L</code>': </b>
5627280405Srpaulopushes onto the stack a table whose indices are the
5628280405Srpaulonumbers of the lines that are valid on the function.
5629280405Srpaulo(A <em>valid line</em> is a line with some associated code,
5630280405Srpaulothat is, a line where you can put a break point.
5631280405SrpauloNon-valid lines include empty lines and comments.)
5632280405Srpaulo
5633280405Srpaulo
5634280405Srpaulo<p>
5635280405SrpauloIf this option is given together with option '<code>f</code>',
5636280405Srpauloits table is pushed after the function.
5637280405Srpaulo</li>
5638280405Srpaulo
5639280405Srpaulo</ul>
5640280405Srpaulo
5641280405Srpaulo<p>
5642280405SrpauloThis function returns 0 on error
5643280405Srpaulo(for instance, an invalid option in <code>what</code>).
5644280405Srpaulo
5645280405Srpaulo
5646280405Srpaulo
5647280405Srpaulo
5648280405Srpaulo
5649280405Srpaulo<hr><h3><a name="lua_getlocal"><code>lua_getlocal</code></a></h3><p>
5650280405Srpaulo<span class="apii">[-0, +(0|1), &ndash;]</span>
5651280405Srpaulo<pre>const char *lua_getlocal (lua_State *L, const lua_Debug *ar, int n);</pre>
5652280405Srpaulo
5653280405Srpaulo<p>
5654280405SrpauloGets information about a local variable of
5655280405Srpauloa given activation record or a given function.
5656280405Srpaulo
5657280405Srpaulo
5658280405Srpaulo<p>
5659280405SrpauloIn the first case,
5660280405Srpaulothe parameter <code>ar</code> must be a valid activation record that was
5661280405Srpaulofilled by a previous call to <a href="#lua_getstack"><code>lua_getstack</code></a> or
5662280405Srpaulogiven as argument to a hook (see <a href="#lua_Hook"><code>lua_Hook</code></a>).
5663280405SrpauloThe index <code>n</code> selects which local variable to inspect;
5664280405Srpaulosee <a href="#pdf-debug.getlocal"><code>debug.getlocal</code></a> for details about variable indices
5665280405Srpauloand names.
5666280405Srpaulo
5667280405Srpaulo
5668280405Srpaulo<p>
5669280405Srpaulo<a href="#lua_getlocal"><code>lua_getlocal</code></a> pushes the variable's value onto the stack
5670280405Srpauloand returns its name.
5671280405Srpaulo
5672280405Srpaulo
5673280405Srpaulo<p>
5674280405SrpauloIn the second case, <code>ar</code> must be <code>NULL</code> and the function
5675280405Srpauloto be inspected must be at the top of the stack.
5676280405SrpauloIn this case, only parameters of Lua functions are visible
5677280405Srpaulo(as there is no information about what variables are active)
5678280405Srpauloand no values are pushed onto the stack.
5679280405Srpaulo
5680280405Srpaulo
5681280405Srpaulo<p>
5682280405SrpauloReturns <code>NULL</code> (and pushes nothing)
5683280405Srpaulowhen the index is greater than
5684280405Srpaulothe number of active local variables.
5685280405Srpaulo
5686280405Srpaulo
5687280405Srpaulo
5688280405Srpaulo
5689280405Srpaulo
5690280405Srpaulo<hr><h3><a name="lua_getstack"><code>lua_getstack</code></a></h3><p>
5691280405Srpaulo<span class="apii">[-0, +0, &ndash;]</span>
5692280405Srpaulo<pre>int lua_getstack (lua_State *L, int level, lua_Debug *ar);</pre>
5693280405Srpaulo
5694280405Srpaulo<p>
5695280405SrpauloGets information about the interpreter runtime stack.
5696280405Srpaulo
5697280405Srpaulo
5698280405Srpaulo<p>
5699280405SrpauloThis function fills parts of a <a href="#lua_Debug"><code>lua_Debug</code></a> structure with
5700280405Srpauloan identification of the <em>activation record</em>
5701280405Srpauloof the function executing at a given level.
5702280405SrpauloLevel&nbsp;0 is the current running function,
5703280405Srpaulowhereas level <em>n+1</em> is the function that has called level <em>n</em>
5704280405Srpaulo(except for tail calls, which do not count on the stack).
5705280405SrpauloWhen there are no errors, <a href="#lua_getstack"><code>lua_getstack</code></a> returns 1;
5706280405Srpaulowhen called with a level greater than the stack depth,
5707280405Srpauloit returns 0.
5708280405Srpaulo
5709280405Srpaulo
5710280405Srpaulo
5711280405Srpaulo
5712280405Srpaulo
5713280405Srpaulo<hr><h3><a name="lua_getupvalue"><code>lua_getupvalue</code></a></h3><p>
5714280405Srpaulo<span class="apii">[-0, +(0|1), &ndash;]</span>
5715280405Srpaulo<pre>const char *lua_getupvalue (lua_State *L, int funcindex, int n);</pre>
5716280405Srpaulo
5717280405Srpaulo<p>
5718326344SimpGets information about the <code>n</code>-th upvalue
5719326344Simpof the closure at index <code>funcindex</code>.
5720326344SimpIt pushes the upvalue's value onto the stack
5721280405Srpauloand returns its name.
5722326344SimpReturns <code>NULL</code> (and pushes nothing)
5723326344Simpwhen the index <code>n</code> is greater than the number of upvalues.
5724280405Srpaulo
5725280405Srpaulo
5726280405Srpaulo<p>
5727280405SrpauloFor C&nbsp;functions, this function uses the empty string <code>""</code>
5728280405Srpauloas a name for all upvalues.
5729326344Simp(For Lua functions,
5730326344Simpupvalues are the external local variables that the function uses,
5731326344Simpand that are consequently included in its closure.)
5732280405Srpaulo
5733280405Srpaulo
5734326344Simp<p>
5735326344SimpUpvalues have no particular order,
5736326344Simpas they are active through the whole function.
5737326344SimpThey are numbered in an arbitrary order.
5738280405Srpaulo
5739280405Srpaulo
5740280405Srpaulo
5741326344Simp
5742326344Simp
5743280405Srpaulo<hr><h3><a name="lua_Hook"><code>lua_Hook</code></a></h3>
5744280405Srpaulo<pre>typedef void (*lua_Hook) (lua_State *L, lua_Debug *ar);</pre>
5745280405Srpaulo
5746280405Srpaulo<p>
5747280405SrpauloType for debugging hook functions.
5748280405Srpaulo
5749280405Srpaulo
5750280405Srpaulo<p>
5751280405SrpauloWhenever a hook is called, its <code>ar</code> argument has its field
5752280405Srpaulo<code>event</code> set to the specific event that triggered the hook.
5753280405SrpauloLua identifies these events with the following constants:
5754280405Srpaulo<a name="pdf-LUA_HOOKCALL"><code>LUA_HOOKCALL</code></a>, <a name="pdf-LUA_HOOKRET"><code>LUA_HOOKRET</code></a>,
5755280405Srpaulo<a name="pdf-LUA_HOOKTAILCALL"><code>LUA_HOOKTAILCALL</code></a>, <a name="pdf-LUA_HOOKLINE"><code>LUA_HOOKLINE</code></a>,
5756280405Srpauloand <a name="pdf-LUA_HOOKCOUNT"><code>LUA_HOOKCOUNT</code></a>.
5757280405SrpauloMoreover, for line events, the field <code>currentline</code> is also set.
5758280405SrpauloTo get the value of any other field in <code>ar</code>,
5759280405Srpaulothe hook must call <a href="#lua_getinfo"><code>lua_getinfo</code></a>.
5760280405Srpaulo
5761280405Srpaulo
5762280405Srpaulo<p>
5763280405SrpauloFor call events, <code>event</code> can be <code>LUA_HOOKCALL</code>,
5764280405Srpaulothe normal value, or <code>LUA_HOOKTAILCALL</code>, for a tail call;
5765280405Srpauloin this case, there will be no corresponding return event.
5766280405Srpaulo
5767280405Srpaulo
5768280405Srpaulo<p>
5769280405SrpauloWhile Lua is running a hook, it disables other calls to hooks.
5770280405SrpauloTherefore, if a hook calls back Lua to execute a function or a chunk,
5771280405Srpaulothis execution occurs without any calls to hooks.
5772280405Srpaulo
5773280405Srpaulo
5774280405Srpaulo<p>
5775280405SrpauloHook functions cannot have continuations,
5776280405Srpaulothat is, they cannot call <a href="#lua_yieldk"><code>lua_yieldk</code></a>,
5777280405Srpaulo<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>.
5778280405Srpaulo
5779280405Srpaulo
5780280405Srpaulo<p>
5781280405SrpauloHook functions can yield under the following conditions:
5782326344SimpOnly count and line events can yield;
5783326344Simpto yield, a hook function must finish its execution
5784326344Simpcalling <a href="#lua_yield"><code>lua_yield</code></a> with <code>nresults</code> equal to zero
5785326344Simp(that is, with no values).
5786280405Srpaulo
5787280405Srpaulo
5788280405Srpaulo
5789280405Srpaulo
5790280405Srpaulo
5791280405Srpaulo<hr><h3><a name="lua_sethook"><code>lua_sethook</code></a></h3><p>
5792280405Srpaulo<span class="apii">[-0, +0, &ndash;]</span>
5793280405Srpaulo<pre>void lua_sethook (lua_State *L, lua_Hook f, int mask, int count);</pre>
5794280405Srpaulo
5795280405Srpaulo<p>
5796280405SrpauloSets the debugging hook function.
5797280405Srpaulo
5798280405Srpaulo
5799280405Srpaulo<p>
5800280405SrpauloArgument <code>f</code> is the hook function.
5801280405Srpaulo<code>mask</code> specifies on which events the hook will be called:
5802326344Simpit is formed by a bitwise OR of the constants
5803280405Srpaulo<a name="pdf-LUA_MASKCALL"><code>LUA_MASKCALL</code></a>,
5804280405Srpaulo<a name="pdf-LUA_MASKRET"><code>LUA_MASKRET</code></a>,
5805280405Srpaulo<a name="pdf-LUA_MASKLINE"><code>LUA_MASKLINE</code></a>,
5806280405Srpauloand <a name="pdf-LUA_MASKCOUNT"><code>LUA_MASKCOUNT</code></a>.
5807280405SrpauloThe <code>count</code> argument is only meaningful when the mask
5808280405Srpauloincludes <code>LUA_MASKCOUNT</code>.
5809280405SrpauloFor each event, the hook is called as explained below:
5810280405Srpaulo
5811280405Srpaulo<ul>
5812280405Srpaulo
5813280405Srpaulo<li><b>The call hook: </b> is called when the interpreter calls a function.
5814280405SrpauloThe hook is called just after Lua enters the new function,
5815280405Srpaulobefore the function gets its arguments.
5816280405Srpaulo</li>
5817280405Srpaulo
5818280405Srpaulo<li><b>The return hook: </b> is called when the interpreter returns from a function.
5819280405SrpauloThe hook is called just before Lua leaves the function.
5820280405SrpauloThere is no standard way to access the values
5821280405Srpauloto be returned by the function.
5822280405Srpaulo</li>
5823280405Srpaulo
5824280405Srpaulo<li><b>The line hook: </b> is called when the interpreter is about to
5825280405Srpaulostart the execution of a new line of code,
5826280405Srpauloor when it jumps back in the code (even to the same line).
5827280405Srpaulo(This event only happens while Lua is executing a Lua function.)
5828280405Srpaulo</li>
5829280405Srpaulo
5830280405Srpaulo<li><b>The count hook: </b> is called after the interpreter executes every
5831280405Srpaulo<code>count</code> instructions.
5832280405Srpaulo(This event only happens while Lua is executing a Lua function.)
5833280405Srpaulo</li>
5834280405Srpaulo
5835280405Srpaulo</ul>
5836280405Srpaulo
5837280405Srpaulo<p>
5838280405SrpauloA hook is disabled by setting <code>mask</code> to zero.
5839280405Srpaulo
5840280405Srpaulo
5841280405Srpaulo
5842280405Srpaulo
5843280405Srpaulo
5844280405Srpaulo<hr><h3><a name="lua_setlocal"><code>lua_setlocal</code></a></h3><p>
5845280405Srpaulo<span class="apii">[-(0|1), +0, &ndash;]</span>
5846280405Srpaulo<pre>const char *lua_setlocal (lua_State *L, const lua_Debug *ar, int n);</pre>
5847280405Srpaulo
5848280405Srpaulo<p>
5849280405SrpauloSets the value of a local variable of a given activation record.
5850326344SimpIt assigns the value at the top of the stack
5851280405Srpauloto the variable and returns its name.
5852280405SrpauloIt also pops the value from the stack.
5853280405Srpaulo
5854280405Srpaulo
5855280405Srpaulo<p>
5856280405SrpauloReturns <code>NULL</code> (and pops nothing)
5857280405Srpaulowhen the index is greater than
5858280405Srpaulothe number of active local variables.
5859280405Srpaulo
5860280405Srpaulo
5861326344Simp<p>
5862326344SimpParameters <code>ar</code> and <code>n</code> are as in function <a href="#lua_getlocal"><code>lua_getlocal</code></a>.
5863280405Srpaulo
5864280405Srpaulo
5865280405Srpaulo
5866326344Simp
5867326344Simp
5868280405Srpaulo<hr><h3><a name="lua_setupvalue"><code>lua_setupvalue</code></a></h3><p>
5869280405Srpaulo<span class="apii">[-(0|1), +0, &ndash;]</span>
5870280405Srpaulo<pre>const char *lua_setupvalue (lua_State *L, int funcindex, int n);</pre>
5871280405Srpaulo
5872280405Srpaulo<p>
5873280405SrpauloSets the value of a closure's upvalue.
5874280405SrpauloIt assigns the value at the top of the stack
5875280405Srpauloto the upvalue and returns its name.
5876280405SrpauloIt also pops the value from the stack.
5877280405Srpaulo
5878280405Srpaulo
5879280405Srpaulo<p>
5880280405SrpauloReturns <code>NULL</code> (and pops nothing)
5881326344Simpwhen the index <code>n</code> is greater than the number of upvalues.
5882280405Srpaulo
5883280405Srpaulo
5884326344Simp<p>
5885326344SimpParameters <code>funcindex</code> and <code>n</code> are as in function <a href="#lua_getupvalue"><code>lua_getupvalue</code></a>.
5886280405Srpaulo
5887280405Srpaulo
5888280405Srpaulo
5889326344Simp
5890326344Simp
5891280405Srpaulo<hr><h3><a name="lua_upvalueid"><code>lua_upvalueid</code></a></h3><p>
5892280405Srpaulo<span class="apii">[-0, +0, &ndash;]</span>
5893280405Srpaulo<pre>void *lua_upvalueid (lua_State *L, int funcindex, int n);</pre>
5894280405Srpaulo
5895280405Srpaulo<p>
5896280405SrpauloReturns a unique identifier for the upvalue numbered <code>n</code>
5897280405Srpaulofrom the closure at index <code>funcindex</code>.
5898280405Srpaulo
5899280405Srpaulo
5900280405Srpaulo<p>
5901280405SrpauloThese unique identifiers allow a program to check whether different
5902280405Srpauloclosures share upvalues.
5903280405SrpauloLua closures that share an upvalue
5904280405Srpaulo(that is, that access a same external local variable)
5905280405Srpaulowill return identical ids for those upvalue indices.
5906280405Srpaulo
5907280405Srpaulo
5908326344Simp<p>
5909326344SimpParameters <code>funcindex</code> and <code>n</code> are as in function <a href="#lua_getupvalue"><code>lua_getupvalue</code></a>,
5910326344Simpbut <code>n</code> cannot be greater than the number of upvalues.
5911280405Srpaulo
5912280405Srpaulo
5913280405Srpaulo
5914326344Simp
5915326344Simp
5916280405Srpaulo<hr><h3><a name="lua_upvaluejoin"><code>lua_upvaluejoin</code></a></h3><p>
5917280405Srpaulo<span class="apii">[-0, +0, &ndash;]</span>
5918280405Srpaulo<pre>void lua_upvaluejoin (lua_State *L, int funcindex1, int n1,
5919280405Srpaulo                                    int funcindex2, int n2);</pre>
5920280405Srpaulo
5921280405Srpaulo<p>
5922280405SrpauloMake the <code>n1</code>-th upvalue of the Lua closure at index <code>funcindex1</code>
5923280405Srpaulorefer to the <code>n2</code>-th upvalue of the Lua closure at index <code>funcindex2</code>.
5924280405Srpaulo
5925280405Srpaulo
5926280405Srpaulo
5927280405Srpaulo
5928280405Srpaulo
5929280405Srpaulo
5930280405Srpaulo
5931280405Srpaulo<h1>5 &ndash; <a name="5">The Auxiliary Library</a></h1>
5932280405Srpaulo
5933280405Srpaulo<p>
5934280405Srpaulo
5935280405SrpauloThe <em>auxiliary library</em> provides several convenient functions
5936280405Srpauloto interface C with Lua.
5937280405SrpauloWhile the basic API provides the primitive functions for all
5938280405Srpaulointeractions between C and Lua,
5939280405Srpaulothe auxiliary library provides higher-level functions for some
5940280405Srpaulocommon tasks.
5941280405Srpaulo
5942280405Srpaulo
5943280405Srpaulo<p>
5944280405SrpauloAll functions and types from the auxiliary library
5945280405Srpauloare defined in header file <code>lauxlib.h</code> and
5946280405Srpaulohave a prefix <code>luaL_</code>.
5947280405Srpaulo
5948280405Srpaulo
5949280405Srpaulo<p>
5950280405SrpauloAll functions in the auxiliary library are built on
5951280405Srpaulotop of the basic API,
5952280405Srpauloand so they provide nothing that cannot be done with that API.
5953280405SrpauloNevertheless, the use of the auxiliary library ensures
5954280405Srpaulomore consistency to your code.
5955280405Srpaulo
5956280405Srpaulo
5957280405Srpaulo<p>
5958280405SrpauloSeveral functions in the auxiliary library use internally some
5959280405Srpauloextra stack slots.
5960280405SrpauloWhen a function in the auxiliary library uses less than five slots,
5961280405Srpauloit does not check the stack size;
5962280405Srpauloit simply assumes that there are enough slots.
5963280405Srpaulo
5964280405Srpaulo
5965280405Srpaulo<p>
5966280405SrpauloSeveral functions in the auxiliary library are used to
5967280405Srpaulocheck C&nbsp;function arguments.
5968280405SrpauloBecause the error message is formatted for arguments
5969280405Srpaulo(e.g., "<code>bad argument #1</code>"),
5970280405Srpauloyou should not use these functions for other stack values.
5971280405Srpaulo
5972280405Srpaulo
5973280405Srpaulo<p>
5974280405SrpauloFunctions called <code>luaL_check*</code>
5975280405Srpauloalways raise an error if the check is not satisfied.
5976280405Srpaulo
5977280405Srpaulo
5978280405Srpaulo
5979280405Srpaulo<h2>5.1 &ndash; <a name="5.1">Functions and Types</a></h2>
5980280405Srpaulo
5981280405Srpaulo<p>
5982280405SrpauloHere we list all functions and types from the auxiliary library
5983280405Srpauloin alphabetical order.
5984280405Srpaulo
5985280405Srpaulo
5986280405Srpaulo
5987280405Srpaulo<hr><h3><a name="luaL_addchar"><code>luaL_addchar</code></a></h3><p>
5988326344Simp<span class="apii">[-?, +?, <em>m</em>]</span>
5989280405Srpaulo<pre>void luaL_addchar (luaL_Buffer *B, char c);</pre>
5990280405Srpaulo
5991280405Srpaulo<p>
5992280405SrpauloAdds the byte <code>c</code> to the buffer <code>B</code>
5993280405Srpaulo(see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>).
5994280405Srpaulo
5995280405Srpaulo
5996280405Srpaulo
5997280405Srpaulo
5998280405Srpaulo
5999280405Srpaulo<hr><h3><a name="luaL_addlstring"><code>luaL_addlstring</code></a></h3><p>
6000326344Simp<span class="apii">[-?, +?, <em>m</em>]</span>
6001280405Srpaulo<pre>void luaL_addlstring (luaL_Buffer *B, const char *s, size_t l);</pre>
6002280405Srpaulo
6003280405Srpaulo<p>
6004280405SrpauloAdds the string pointed to by <code>s</code> with length <code>l</code> to
6005280405Srpaulothe buffer <code>B</code>
6006280405Srpaulo(see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>).
6007280405SrpauloThe string can contain embedded zeros.
6008280405Srpaulo
6009280405Srpaulo
6010280405Srpaulo
6011280405Srpaulo
6012280405Srpaulo
6013280405Srpaulo<hr><h3><a name="luaL_addsize"><code>luaL_addsize</code></a></h3><p>
6014326344Simp<span class="apii">[-?, +?, &ndash;]</span>
6015280405Srpaulo<pre>void luaL_addsize (luaL_Buffer *B, size_t n);</pre>
6016280405Srpaulo
6017280405Srpaulo<p>
6018280405SrpauloAdds to the buffer <code>B</code> (see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>)
6019280405Srpauloa string of length <code>n</code> previously copied to the
6020280405Srpaulobuffer area (see <a href="#luaL_prepbuffer"><code>luaL_prepbuffer</code></a>).
6021280405Srpaulo
6022280405Srpaulo
6023280405Srpaulo
6024280405Srpaulo
6025280405Srpaulo
6026280405Srpaulo<hr><h3><a name="luaL_addstring"><code>luaL_addstring</code></a></h3><p>
6027326344Simp<span class="apii">[-?, +?, <em>m</em>]</span>
6028280405Srpaulo<pre>void luaL_addstring (luaL_Buffer *B, const char *s);</pre>
6029280405Srpaulo
6030280405Srpaulo<p>
6031280405SrpauloAdds the zero-terminated string pointed to by <code>s</code>
6032280405Srpauloto the buffer <code>B</code>
6033280405Srpaulo(see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>).
6034280405Srpaulo
6035280405Srpaulo
6036280405Srpaulo
6037280405Srpaulo
6038280405Srpaulo
6039280405Srpaulo<hr><h3><a name="luaL_addvalue"><code>luaL_addvalue</code></a></h3><p>
6040326344Simp<span class="apii">[-1, +?, <em>m</em>]</span>
6041280405Srpaulo<pre>void luaL_addvalue (luaL_Buffer *B);</pre>
6042280405Srpaulo
6043280405Srpaulo<p>
6044280405SrpauloAdds the value at the top of the stack
6045280405Srpauloto the buffer <code>B</code>
6046280405Srpaulo(see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>).
6047280405SrpauloPops the value.
6048280405Srpaulo
6049280405Srpaulo
6050280405Srpaulo<p>
6051280405SrpauloThis is the only function on string buffers that can (and must)
6052280405Srpaulobe called with an extra element on the stack,
6053280405Srpaulowhich is the value to be added to the buffer.
6054280405Srpaulo
6055280405Srpaulo
6056280405Srpaulo
6057280405Srpaulo
6058280405Srpaulo
6059280405Srpaulo<hr><h3><a name="luaL_argcheck"><code>luaL_argcheck</code></a></h3><p>
6060280405Srpaulo<span class="apii">[-0, +0, <em>v</em>]</span>
6061280405Srpaulo<pre>void luaL_argcheck (lua_State *L,
6062280405Srpaulo                    int cond,
6063280405Srpaulo                    int arg,
6064280405Srpaulo                    const char *extramsg);</pre>
6065280405Srpaulo
6066280405Srpaulo<p>
6067280405SrpauloChecks whether <code>cond</code> is true.
6068280405SrpauloIf it is not, raises an error with a standard message (see <a href="#luaL_argerror"><code>luaL_argerror</code></a>).
6069280405Srpaulo
6070280405Srpaulo
6071280405Srpaulo
6072280405Srpaulo
6073280405Srpaulo
6074280405Srpaulo<hr><h3><a name="luaL_argerror"><code>luaL_argerror</code></a></h3><p>
6075280405Srpaulo<span class="apii">[-0, +0, <em>v</em>]</span>
6076280405Srpaulo<pre>int luaL_argerror (lua_State *L, int arg, const char *extramsg);</pre>
6077280405Srpaulo
6078280405Srpaulo<p>
6079280405SrpauloRaises an error reporting a problem with argument <code>arg</code>
6080326344Simpof the C&nbsp;function that called it,
6081280405Srpaulousing a standard message
6082280405Srpaulothat includes <code>extramsg</code> as a comment:
6083280405Srpaulo
6084280405Srpaulo<pre>
6085280405Srpaulo     bad argument #<em>arg</em> to '<em>funcname</em>' (<em>extramsg</em>)
6086280405Srpaulo</pre><p>
6087280405SrpauloThis function never returns.
6088280405Srpaulo
6089280405Srpaulo
6090280405Srpaulo
6091280405Srpaulo
6092280405Srpaulo
6093280405Srpaulo<hr><h3><a name="luaL_Buffer"><code>luaL_Buffer</code></a></h3>
6094280405Srpaulo<pre>typedef struct luaL_Buffer luaL_Buffer;</pre>
6095280405Srpaulo
6096280405Srpaulo<p>
6097280405SrpauloType for a <em>string buffer</em>.
6098280405Srpaulo
6099280405Srpaulo
6100280405Srpaulo<p>
6101280405SrpauloA string buffer allows C&nbsp;code to build Lua strings piecemeal.
6102280405SrpauloIts pattern of use is as follows:
6103280405Srpaulo
6104280405Srpaulo<ul>
6105280405Srpaulo
6106280405Srpaulo<li>First declare a variable <code>b</code> of type <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>.</li>
6107280405Srpaulo
6108280405Srpaulo<li>Then initialize it with a call <code>luaL_buffinit(L, &amp;b)</code>.</li>
6109280405Srpaulo
6110280405Srpaulo<li>
6111280405SrpauloThen add string pieces to the buffer calling any of
6112280405Srpaulothe <code>luaL_add*</code> functions.
6113280405Srpaulo</li>
6114280405Srpaulo
6115280405Srpaulo<li>
6116280405SrpauloFinish by calling <code>luaL_pushresult(&amp;b)</code>.
6117280405SrpauloThis call leaves the final string on the top of the stack.
6118280405Srpaulo</li>
6119280405Srpaulo
6120280405Srpaulo</ul>
6121280405Srpaulo
6122280405Srpaulo<p>
6123280405SrpauloIf you know beforehand the total size of the resulting string,
6124280405Srpauloyou can use the buffer like this:
6125280405Srpaulo
6126280405Srpaulo<ul>
6127280405Srpaulo
6128280405Srpaulo<li>First declare a variable <code>b</code> of type <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>.</li>
6129280405Srpaulo
6130280405Srpaulo<li>Then initialize it and preallocate a space of
6131280405Srpaulosize <code>sz</code> with a call <code>luaL_buffinitsize(L, &amp;b, sz)</code>.</li>
6132280405Srpaulo
6133280405Srpaulo<li>Then copy the string into that space.</li>
6134280405Srpaulo
6135280405Srpaulo<li>
6136280405SrpauloFinish by calling <code>luaL_pushresultsize(&amp;b, sz)</code>,
6137280405Srpaulowhere <code>sz</code> is the total size of the resulting string
6138280405Srpaulocopied into that space.
6139280405Srpaulo</li>
6140280405Srpaulo
6141280405Srpaulo</ul>
6142280405Srpaulo
6143280405Srpaulo<p>
6144280405SrpauloDuring its normal operation,
6145280405Srpauloa string buffer uses a variable number of stack slots.
6146280405SrpauloSo, while using a buffer, you cannot assume that you know where
6147280405Srpaulothe top of the stack is.
6148280405SrpauloYou can use the stack between successive calls to buffer operations
6149280405Srpauloas long as that use is balanced;
6150280405Srpaulothat is,
6151280405Srpaulowhen you call a buffer operation,
6152280405Srpaulothe stack is at the same level
6153280405Srpauloit was immediately after the previous buffer operation.
6154280405Srpaulo(The only exception to this rule is <a href="#luaL_addvalue"><code>luaL_addvalue</code></a>.)
6155280405SrpauloAfter calling <a href="#luaL_pushresult"><code>luaL_pushresult</code></a> the stack is back to its
6156280405Srpaulolevel when the buffer was initialized,
6157280405Srpauloplus the final string on its top.
6158280405Srpaulo
6159280405Srpaulo
6160280405Srpaulo
6161280405Srpaulo
6162280405Srpaulo
6163280405Srpaulo<hr><h3><a name="luaL_buffinit"><code>luaL_buffinit</code></a></h3><p>
6164280405Srpaulo<span class="apii">[-0, +0, &ndash;]</span>
6165280405Srpaulo<pre>void luaL_buffinit (lua_State *L, luaL_Buffer *B);</pre>
6166280405Srpaulo
6167280405Srpaulo<p>
6168280405SrpauloInitializes a buffer <code>B</code>.
6169280405SrpauloThis function does not allocate any space;
6170280405Srpaulothe buffer must be declared as a variable
6171280405Srpaulo(see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>).
6172280405Srpaulo
6173280405Srpaulo
6174280405Srpaulo
6175280405Srpaulo
6176280405Srpaulo
6177280405Srpaulo<hr><h3><a name="luaL_buffinitsize"><code>luaL_buffinitsize</code></a></h3><p>
6178326344Simp<span class="apii">[-?, +?, <em>m</em>]</span>
6179280405Srpaulo<pre>char *luaL_buffinitsize (lua_State *L, luaL_Buffer *B, size_t sz);</pre>
6180280405Srpaulo
6181280405Srpaulo<p>
6182280405SrpauloEquivalent to the sequence
6183280405Srpaulo<a href="#luaL_buffinit"><code>luaL_buffinit</code></a>, <a href="#luaL_prepbuffsize"><code>luaL_prepbuffsize</code></a>.
6184280405Srpaulo
6185280405Srpaulo
6186280405Srpaulo
6187280405Srpaulo
6188280405Srpaulo
6189280405Srpaulo<hr><h3><a name="luaL_callmeta"><code>luaL_callmeta</code></a></h3><p>
6190280405Srpaulo<span class="apii">[-0, +(0|1), <em>e</em>]</span>
6191280405Srpaulo<pre>int luaL_callmeta (lua_State *L, int obj, const char *e);</pre>
6192280405Srpaulo
6193280405Srpaulo<p>
6194280405SrpauloCalls a metamethod.
6195280405Srpaulo
6196280405Srpaulo
6197280405Srpaulo<p>
6198280405SrpauloIf the object at index <code>obj</code> has a metatable and this
6199280405Srpaulometatable has a field <code>e</code>,
6200280405Srpaulothis function calls this field passing the object as its only argument.
6201280405SrpauloIn this case this function returns true and pushes onto the
6202280405Srpaulostack the value returned by the call.
6203280405SrpauloIf there is no metatable or no metamethod,
6204280405Srpaulothis function returns false (without pushing any value on the stack).
6205280405Srpaulo
6206280405Srpaulo
6207280405Srpaulo
6208280405Srpaulo
6209280405Srpaulo
6210280405Srpaulo<hr><h3><a name="luaL_checkany"><code>luaL_checkany</code></a></h3><p>
6211280405Srpaulo<span class="apii">[-0, +0, <em>v</em>]</span>
6212280405Srpaulo<pre>void luaL_checkany (lua_State *L, int arg);</pre>
6213280405Srpaulo
6214280405Srpaulo<p>
6215280405SrpauloChecks whether the function has an argument
6216280405Srpauloof any type (including <b>nil</b>) at position <code>arg</code>.
6217280405Srpaulo
6218280405Srpaulo
6219280405Srpaulo
6220280405Srpaulo
6221280405Srpaulo
6222280405Srpaulo<hr><h3><a name="luaL_checkinteger"><code>luaL_checkinteger</code></a></h3><p>
6223280405Srpaulo<span class="apii">[-0, +0, <em>v</em>]</span>
6224280405Srpaulo<pre>lua_Integer luaL_checkinteger (lua_State *L, int arg);</pre>
6225280405Srpaulo
6226280405Srpaulo<p>
6227280405SrpauloChecks whether the function argument <code>arg</code> is an integer
6228280405Srpaulo(or can be converted to an integer)
6229280405Srpauloand returns this integer cast to a <a href="#lua_Integer"><code>lua_Integer</code></a>.
6230280405Srpaulo
6231280405Srpaulo
6232280405Srpaulo
6233280405Srpaulo
6234280405Srpaulo
6235280405Srpaulo<hr><h3><a name="luaL_checklstring"><code>luaL_checklstring</code></a></h3><p>
6236280405Srpaulo<span class="apii">[-0, +0, <em>v</em>]</span>
6237280405Srpaulo<pre>const char *luaL_checklstring (lua_State *L, int arg, size_t *l);</pre>
6238280405Srpaulo
6239280405Srpaulo<p>
6240280405SrpauloChecks whether the function argument <code>arg</code> is a string
6241280405Srpauloand returns this string;
6242280405Srpauloif <code>l</code> is not <code>NULL</code> fills <code>*l</code>
6243280405Srpaulowith the string's length.
6244280405Srpaulo
6245280405Srpaulo
6246280405Srpaulo<p>
6247280405SrpauloThis function uses <a href="#lua_tolstring"><code>lua_tolstring</code></a> to get its result,
6248280405Srpauloso all conversions and caveats of that function apply here.
6249280405Srpaulo
6250280405Srpaulo
6251280405Srpaulo
6252280405Srpaulo
6253280405Srpaulo
6254280405Srpaulo<hr><h3><a name="luaL_checknumber"><code>luaL_checknumber</code></a></h3><p>
6255280405Srpaulo<span class="apii">[-0, +0, <em>v</em>]</span>
6256280405Srpaulo<pre>lua_Number luaL_checknumber (lua_State *L, int arg);</pre>
6257280405Srpaulo
6258280405Srpaulo<p>
6259280405SrpauloChecks whether the function argument <code>arg</code> is a number
6260280405Srpauloand returns this number.
6261280405Srpaulo
6262280405Srpaulo
6263280405Srpaulo
6264280405Srpaulo
6265280405Srpaulo
6266280405Srpaulo<hr><h3><a name="luaL_checkoption"><code>luaL_checkoption</code></a></h3><p>
6267280405Srpaulo<span class="apii">[-0, +0, <em>v</em>]</span>
6268280405Srpaulo<pre>int luaL_checkoption (lua_State *L,
6269280405Srpaulo                      int arg,
6270280405Srpaulo                      const char *def,
6271280405Srpaulo                      const char *const lst[]);</pre>
6272280405Srpaulo
6273280405Srpaulo<p>
6274280405SrpauloChecks whether the function argument <code>arg</code> is a string and
6275280405Srpaulosearches for this string in the array <code>lst</code>
6276280405Srpaulo(which must be NULL-terminated).
6277280405SrpauloReturns the index in the array where the string was found.
6278280405SrpauloRaises an error if the argument is not a string or
6279280405Srpauloif the string cannot be found.
6280280405Srpaulo
6281280405Srpaulo
6282280405Srpaulo<p>
6283280405SrpauloIf <code>def</code> is not <code>NULL</code>,
6284280405Srpaulothe function uses <code>def</code> as a default value when
6285280405Srpaulothere is no argument <code>arg</code> or when this argument is <b>nil</b>.
6286280405Srpaulo
6287280405Srpaulo
6288280405Srpaulo<p>
6289280405SrpauloThis is a useful function for mapping strings to C&nbsp;enums.
6290280405Srpaulo(The usual convention in Lua libraries is
6291280405Srpauloto use strings instead of numbers to select options.)
6292280405Srpaulo
6293280405Srpaulo
6294280405Srpaulo
6295280405Srpaulo
6296280405Srpaulo
6297280405Srpaulo<hr><h3><a name="luaL_checkstack"><code>luaL_checkstack</code></a></h3><p>
6298280405Srpaulo<span class="apii">[-0, +0, <em>v</em>]</span>
6299280405Srpaulo<pre>void luaL_checkstack (lua_State *L, int sz, const char *msg);</pre>
6300280405Srpaulo
6301280405Srpaulo<p>
6302280405SrpauloGrows the stack size to <code>top + sz</code> elements,
6303280405Srpauloraising an error if the stack cannot grow to that size.
6304280405Srpaulo<code>msg</code> is an additional text to go into the error message
6305280405Srpaulo(or <code>NULL</code> for no additional text).
6306280405Srpaulo
6307280405Srpaulo
6308280405Srpaulo
6309280405Srpaulo
6310280405Srpaulo
6311280405Srpaulo<hr><h3><a name="luaL_checkstring"><code>luaL_checkstring</code></a></h3><p>
6312280405Srpaulo<span class="apii">[-0, +0, <em>v</em>]</span>
6313280405Srpaulo<pre>const char *luaL_checkstring (lua_State *L, int arg);</pre>
6314280405Srpaulo
6315280405Srpaulo<p>
6316280405SrpauloChecks whether the function argument <code>arg</code> is a string
6317280405Srpauloand returns this string.
6318280405Srpaulo
6319280405Srpaulo
6320280405Srpaulo<p>
6321280405SrpauloThis function uses <a href="#lua_tolstring"><code>lua_tolstring</code></a> to get its result,
6322280405Srpauloso all conversions and caveats of that function apply here.
6323280405Srpaulo
6324280405Srpaulo
6325280405Srpaulo
6326280405Srpaulo
6327280405Srpaulo
6328280405Srpaulo<hr><h3><a name="luaL_checktype"><code>luaL_checktype</code></a></h3><p>
6329280405Srpaulo<span class="apii">[-0, +0, <em>v</em>]</span>
6330280405Srpaulo<pre>void luaL_checktype (lua_State *L, int arg, int t);</pre>
6331280405Srpaulo
6332280405Srpaulo<p>
6333280405SrpauloChecks whether the function argument <code>arg</code> has type <code>t</code>.
6334280405SrpauloSee <a href="#lua_type"><code>lua_type</code></a> for the encoding of types for <code>t</code>.
6335280405Srpaulo
6336280405Srpaulo
6337280405Srpaulo
6338280405Srpaulo
6339280405Srpaulo
6340280405Srpaulo<hr><h3><a name="luaL_checkudata"><code>luaL_checkudata</code></a></h3><p>
6341280405Srpaulo<span class="apii">[-0, +0, <em>v</em>]</span>
6342280405Srpaulo<pre>void *luaL_checkudata (lua_State *L, int arg, const char *tname);</pre>
6343280405Srpaulo
6344280405Srpaulo<p>
6345280405SrpauloChecks whether the function argument <code>arg</code> is a userdata
6346280405Srpauloof the type <code>tname</code> (see <a href="#luaL_newmetatable"><code>luaL_newmetatable</code></a>) and
6347280405Srpauloreturns the userdata address (see <a href="#lua_touserdata"><code>lua_touserdata</code></a>).
6348280405Srpaulo
6349280405Srpaulo
6350280405Srpaulo
6351280405Srpaulo
6352280405Srpaulo
6353280405Srpaulo<hr><h3><a name="luaL_checkversion"><code>luaL_checkversion</code></a></h3><p>
6354326344Simp<span class="apii">[-0, +0, <em>v</em>]</span>
6355280405Srpaulo<pre>void luaL_checkversion (lua_State *L);</pre>
6356280405Srpaulo
6357280405Srpaulo<p>
6358280405SrpauloChecks whether the core running the call,
6359280405Srpaulothe core that created the Lua state,
6360280405Srpauloand the code making the call are all using the same version of Lua.
6361280405SrpauloAlso checks whether the core running the call
6362280405Srpauloand the core that created the Lua state
6363280405Srpauloare using the same address space.
6364280405Srpaulo
6365280405Srpaulo
6366280405Srpaulo
6367280405Srpaulo
6368280405Srpaulo
6369280405Srpaulo<hr><h3><a name="luaL_dofile"><code>luaL_dofile</code></a></h3><p>
6370280405Srpaulo<span class="apii">[-0, +?, <em>e</em>]</span>
6371280405Srpaulo<pre>int luaL_dofile (lua_State *L, const char *filename);</pre>
6372280405Srpaulo
6373280405Srpaulo<p>
6374280405SrpauloLoads and runs the given file.
6375280405SrpauloIt is defined as the following macro:
6376280405Srpaulo
6377280405Srpaulo<pre>
6378280405Srpaulo     (luaL_loadfile(L, filename) || lua_pcall(L, 0, LUA_MULTRET, 0))
6379280405Srpaulo</pre><p>
6380280405SrpauloIt returns false if there are no errors
6381280405Srpauloor true in case of errors.
6382280405Srpaulo
6383280405Srpaulo
6384280405Srpaulo
6385280405Srpaulo
6386280405Srpaulo
6387280405Srpaulo<hr><h3><a name="luaL_dostring"><code>luaL_dostring</code></a></h3><p>
6388280405Srpaulo<span class="apii">[-0, +?, &ndash;]</span>
6389280405Srpaulo<pre>int luaL_dostring (lua_State *L, const char *str);</pre>
6390280405Srpaulo
6391280405Srpaulo<p>
6392280405SrpauloLoads and runs the given string.
6393280405SrpauloIt is defined as the following macro:
6394280405Srpaulo
6395280405Srpaulo<pre>
6396280405Srpaulo     (luaL_loadstring(L, str) || lua_pcall(L, 0, LUA_MULTRET, 0))
6397280405Srpaulo</pre><p>
6398280405SrpauloIt returns false if there are no errors
6399280405Srpauloor true in case of errors.
6400280405Srpaulo
6401280405Srpaulo
6402280405Srpaulo
6403280405Srpaulo
6404280405Srpaulo
6405280405Srpaulo<hr><h3><a name="luaL_error"><code>luaL_error</code></a></h3><p>
6406280405Srpaulo<span class="apii">[-0, +0, <em>v</em>]</span>
6407280405Srpaulo<pre>int luaL_error (lua_State *L, const char *fmt, ...);</pre>
6408280405Srpaulo
6409280405Srpaulo<p>
6410280405SrpauloRaises an error.
6411280405SrpauloThe error message format is given by <code>fmt</code>
6412280405Srpauloplus any extra arguments,
6413280405Srpaulofollowing the same rules of <a href="#lua_pushfstring"><code>lua_pushfstring</code></a>.
6414280405SrpauloIt also adds at the beginning of the message the file name and
6415280405Srpaulothe line number where the error occurred,
6416280405Srpauloif this information is available.
6417280405Srpaulo
6418280405Srpaulo
6419280405Srpaulo<p>
6420280405SrpauloThis function never returns,
6421280405Srpaulobut it is an idiom to use it in C&nbsp;functions
6422280405Srpauloas <code>return luaL_error(<em>args</em>)</code>.
6423280405Srpaulo
6424280405Srpaulo
6425280405Srpaulo
6426280405Srpaulo
6427280405Srpaulo
6428280405Srpaulo<hr><h3><a name="luaL_execresult"><code>luaL_execresult</code></a></h3><p>
6429326344Simp<span class="apii">[-0, +3, <em>m</em>]</span>
6430280405Srpaulo<pre>int luaL_execresult (lua_State *L, int stat);</pre>
6431280405Srpaulo
6432280405Srpaulo<p>
6433280405SrpauloThis function produces the return values for
6434280405Srpauloprocess-related functions in the standard library
6435280405Srpaulo(<a href="#pdf-os.execute"><code>os.execute</code></a> and <a href="#pdf-io.close"><code>io.close</code></a>).
6436280405Srpaulo
6437280405Srpaulo
6438280405Srpaulo
6439280405Srpaulo
6440280405Srpaulo
6441280405Srpaulo<hr><h3><a name="luaL_fileresult"><code>luaL_fileresult</code></a></h3><p>
6442326344Simp<span class="apii">[-0, +(1|3), <em>m</em>]</span>
6443280405Srpaulo<pre>int luaL_fileresult (lua_State *L, int stat, const char *fname);</pre>
6444280405Srpaulo
6445280405Srpaulo<p>
6446280405SrpauloThis function produces the return values for
6447280405Srpaulofile-related functions in the standard library
6448280405Srpaulo(<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.).
6449280405Srpaulo
6450280405Srpaulo
6451280405Srpaulo
6452280405Srpaulo
6453280405Srpaulo
6454280405Srpaulo<hr><h3><a name="luaL_getmetafield"><code>luaL_getmetafield</code></a></h3><p>
6455326344Simp<span class="apii">[-0, +(0|1), <em>m</em>]</span>
6456280405Srpaulo<pre>int luaL_getmetafield (lua_State *L, int obj, const char *e);</pre>
6457280405Srpaulo
6458280405Srpaulo<p>
6459280405SrpauloPushes onto the stack the field <code>e</code> from the metatable
6460344220Skevansof the object at index <code>obj</code> and returns the type of the pushed value.
6461280405SrpauloIf the object does not have a metatable,
6462280405Srpauloor if the metatable does not have this field,
6463280405Srpaulopushes nothing and returns <code>LUA_TNIL</code>.
6464280405Srpaulo
6465280405Srpaulo
6466280405Srpaulo
6467280405Srpaulo
6468280405Srpaulo
6469280405Srpaulo<hr><h3><a name="luaL_getmetatable"><code>luaL_getmetatable</code></a></h3><p>
6470326344Simp<span class="apii">[-0, +1, <em>m</em>]</span>
6471280405Srpaulo<pre>int luaL_getmetatable (lua_State *L, const char *tname);</pre>
6472280405Srpaulo
6473280405Srpaulo<p>
6474280405SrpauloPushes onto the stack the metatable associated with name <code>tname</code>
6475326344Simpin the registry (see <a href="#luaL_newmetatable"><code>luaL_newmetatable</code></a>)
6476326344Simp(<b>nil</b> if there is no metatable associated with that name).
6477326344SimpReturns the type of the pushed value.
6478280405Srpaulo
6479280405Srpaulo
6480280405Srpaulo
6481280405Srpaulo
6482280405Srpaulo
6483280405Srpaulo<hr><h3><a name="luaL_getsubtable"><code>luaL_getsubtable</code></a></h3><p>
6484280405Srpaulo<span class="apii">[-0, +1, <em>e</em>]</span>
6485280405Srpaulo<pre>int luaL_getsubtable (lua_State *L, int idx, const char *fname);</pre>
6486280405Srpaulo
6487280405Srpaulo<p>
6488280405SrpauloEnsures that the value <code>t[fname]</code>,
6489280405Srpaulowhere <code>t</code> is the value at index <code>idx</code>,
6490280405Srpaulois a table,
6491280405Srpauloand pushes that table onto the stack.
6492280405SrpauloReturns true if it finds a previous table there
6493280405Srpauloand false if it creates a new table.
6494280405Srpaulo
6495280405Srpaulo
6496280405Srpaulo
6497280405Srpaulo
6498280405Srpaulo
6499280405Srpaulo<hr><h3><a name="luaL_gsub"><code>luaL_gsub</code></a></h3><p>
6500326344Simp<span class="apii">[-0, +1, <em>m</em>]</span>
6501280405Srpaulo<pre>const char *luaL_gsub (lua_State *L,
6502280405Srpaulo                       const char *s,
6503280405Srpaulo                       const char *p,
6504280405Srpaulo                       const char *r);</pre>
6505280405Srpaulo
6506280405Srpaulo<p>
6507280405SrpauloCreates a copy of string <code>s</code> by replacing
6508280405Srpauloany occurrence of the string <code>p</code>
6509280405Srpaulowith the string <code>r</code>.
6510280405SrpauloPushes the resulting string on the stack and returns it.
6511280405Srpaulo
6512280405Srpaulo
6513280405Srpaulo
6514280405Srpaulo
6515280405Srpaulo
6516280405Srpaulo<hr><h3><a name="luaL_len"><code>luaL_len</code></a></h3><p>
6517280405Srpaulo<span class="apii">[-0, +0, <em>e</em>]</span>
6518280405Srpaulo<pre>lua_Integer luaL_len (lua_State *L, int index);</pre>
6519280405Srpaulo
6520280405Srpaulo<p>
6521280405SrpauloReturns the "length" of the value at the given index
6522280405Srpauloas a number;
6523280405Srpauloit is equivalent to the '<code>#</code>' operator in Lua (see <a href="#3.4.7">&sect;3.4.7</a>).
6524280405SrpauloRaises an error if the result of the operation is not an integer.
6525280405Srpaulo(This case only can happen through metamethods.)
6526280405Srpaulo
6527280405Srpaulo
6528280405Srpaulo
6529280405Srpaulo
6530280405Srpaulo
6531280405Srpaulo<hr><h3><a name="luaL_loadbuffer"><code>luaL_loadbuffer</code></a></h3><p>
6532280405Srpaulo<span class="apii">[-0, +1, &ndash;]</span>
6533280405Srpaulo<pre>int luaL_loadbuffer (lua_State *L,
6534280405Srpaulo                     const char *buff,
6535280405Srpaulo                     size_t sz,
6536280405Srpaulo                     const char *name);</pre>
6537280405Srpaulo
6538280405Srpaulo<p>
6539280405SrpauloEquivalent to <a href="#luaL_loadbufferx"><code>luaL_loadbufferx</code></a> with <code>mode</code> equal to <code>NULL</code>.
6540280405Srpaulo
6541280405Srpaulo
6542280405Srpaulo
6543280405Srpaulo
6544280405Srpaulo
6545280405Srpaulo<hr><h3><a name="luaL_loadbufferx"><code>luaL_loadbufferx</code></a></h3><p>
6546280405Srpaulo<span class="apii">[-0, +1, &ndash;]</span>
6547280405Srpaulo<pre>int luaL_loadbufferx (lua_State *L,
6548280405Srpaulo                      const char *buff,
6549280405Srpaulo                      size_t sz,
6550280405Srpaulo                      const char *name,
6551280405Srpaulo                      const char *mode);</pre>
6552280405Srpaulo
6553280405Srpaulo<p>
6554280405SrpauloLoads a buffer as a Lua chunk.
6555280405SrpauloThis function uses <a href="#lua_load"><code>lua_load</code></a> to load the chunk in the
6556280405Srpaulobuffer pointed to by <code>buff</code> with size <code>sz</code>.
6557280405Srpaulo
6558280405Srpaulo
6559280405Srpaulo<p>
6560280405SrpauloThis function returns the same results as <a href="#lua_load"><code>lua_load</code></a>.
6561280405Srpaulo<code>name</code> is the chunk name,
6562280405Srpauloused for debug information and error messages.
6563280405SrpauloThe string <code>mode</code> works as in function <a href="#lua_load"><code>lua_load</code></a>.
6564280405Srpaulo
6565280405Srpaulo
6566280405Srpaulo
6567280405Srpaulo
6568280405Srpaulo
6569280405Srpaulo<hr><h3><a name="luaL_loadfile"><code>luaL_loadfile</code></a></h3><p>
6570326344Simp<span class="apii">[-0, +1, <em>m</em>]</span>
6571280405Srpaulo<pre>int luaL_loadfile (lua_State *L, const char *filename);</pre>
6572280405Srpaulo
6573280405Srpaulo<p>
6574280405SrpauloEquivalent to <a href="#luaL_loadfilex"><code>luaL_loadfilex</code></a> with <code>mode</code> equal to <code>NULL</code>.
6575280405Srpaulo
6576280405Srpaulo
6577280405Srpaulo
6578280405Srpaulo
6579280405Srpaulo
6580280405Srpaulo<hr><h3><a name="luaL_loadfilex"><code>luaL_loadfilex</code></a></h3><p>
6581326344Simp<span class="apii">[-0, +1, <em>m</em>]</span>
6582280405Srpaulo<pre>int luaL_loadfilex (lua_State *L, const char *filename,
6583280405Srpaulo                                            const char *mode);</pre>
6584280405Srpaulo
6585280405Srpaulo<p>
6586280405SrpauloLoads a file as a Lua chunk.
6587280405SrpauloThis function uses <a href="#lua_load"><code>lua_load</code></a> to load the chunk in the file
6588280405Srpaulonamed <code>filename</code>.
6589280405SrpauloIf <code>filename</code> is <code>NULL</code>,
6590280405Srpaulothen it loads from the standard input.
6591280405SrpauloThe first line in the file is ignored if it starts with a <code>#</code>.
6592280405Srpaulo
6593280405Srpaulo
6594280405Srpaulo<p>
6595280405SrpauloThe string <code>mode</code> works as in function <a href="#lua_load"><code>lua_load</code></a>.
6596280405Srpaulo
6597280405Srpaulo
6598280405Srpaulo<p>
6599280405SrpauloThis function returns the same results as <a href="#lua_load"><code>lua_load</code></a>,
6600280405Srpaulobut it has an extra error code <a name="pdf-LUA_ERRFILE"><code>LUA_ERRFILE</code></a>
6601326344Simpfor file-related errors
6602326344Simp(e.g., it cannot open or read the file).
6603280405Srpaulo
6604280405Srpaulo
6605280405Srpaulo<p>
6606280405SrpauloAs <a href="#lua_load"><code>lua_load</code></a>, this function only loads the chunk;
6607280405Srpauloit does not run it.
6608280405Srpaulo
6609280405Srpaulo
6610280405Srpaulo
6611280405Srpaulo
6612280405Srpaulo
6613280405Srpaulo<hr><h3><a name="luaL_loadstring"><code>luaL_loadstring</code></a></h3><p>
6614280405Srpaulo<span class="apii">[-0, +1, &ndash;]</span>
6615280405Srpaulo<pre>int luaL_loadstring (lua_State *L, const char *s);</pre>
6616280405Srpaulo
6617280405Srpaulo<p>
6618280405SrpauloLoads a string as a Lua chunk.
6619280405SrpauloThis function uses <a href="#lua_load"><code>lua_load</code></a> to load the chunk in
6620280405Srpaulothe zero-terminated string <code>s</code>.
6621280405Srpaulo
6622280405Srpaulo
6623280405Srpaulo<p>
6624280405SrpauloThis function returns the same results as <a href="#lua_load"><code>lua_load</code></a>.
6625280405Srpaulo
6626280405Srpaulo
6627280405Srpaulo<p>
6628280405SrpauloAlso as <a href="#lua_load"><code>lua_load</code></a>, this function only loads the chunk;
6629280405Srpauloit does not run it.
6630280405Srpaulo
6631280405Srpaulo
6632280405Srpaulo
6633280405Srpaulo
6634280405Srpaulo
6635280405Srpaulo<hr><h3><a name="luaL_newlib"><code>luaL_newlib</code></a></h3><p>
6636326344Simp<span class="apii">[-0, +1, <em>m</em>]</span>
6637280405Srpaulo<pre>void luaL_newlib (lua_State *L, const luaL_Reg l[]);</pre>
6638280405Srpaulo
6639280405Srpaulo<p>
6640280405SrpauloCreates a new table and registers there
6641280405Srpaulothe functions in list <code>l</code>.
6642280405Srpaulo
6643280405Srpaulo
6644280405Srpaulo<p>
6645280405SrpauloIt is implemented as the following macro:
6646280405Srpaulo
6647280405Srpaulo<pre>
6648280405Srpaulo     (luaL_newlibtable(L,l), luaL_setfuncs(L,l,0))
6649280405Srpaulo</pre><p>
6650280405SrpauloThe array <code>l</code> must be the actual array,
6651280405Srpaulonot a pointer to it.
6652280405Srpaulo
6653280405Srpaulo
6654280405Srpaulo
6655280405Srpaulo
6656280405Srpaulo
6657280405Srpaulo<hr><h3><a name="luaL_newlibtable"><code>luaL_newlibtable</code></a></h3><p>
6658326344Simp<span class="apii">[-0, +1, <em>m</em>]</span>
6659280405Srpaulo<pre>void luaL_newlibtable (lua_State *L, const luaL_Reg l[]);</pre>
6660280405Srpaulo
6661280405Srpaulo<p>
6662280405SrpauloCreates a new table with a size optimized
6663280405Srpauloto store all entries in the array <code>l</code>
6664280405Srpaulo(but does not actually store them).
6665280405SrpauloIt is intended to be used in conjunction with <a href="#luaL_setfuncs"><code>luaL_setfuncs</code></a>
6666280405Srpaulo(see <a href="#luaL_newlib"><code>luaL_newlib</code></a>).
6667280405Srpaulo
6668280405Srpaulo
6669280405Srpaulo<p>
6670280405SrpauloIt is implemented as a macro.
6671280405SrpauloThe array <code>l</code> must be the actual array,
6672280405Srpaulonot a pointer to it.
6673280405Srpaulo
6674280405Srpaulo
6675280405Srpaulo
6676280405Srpaulo
6677280405Srpaulo
6678280405Srpaulo<hr><h3><a name="luaL_newmetatable"><code>luaL_newmetatable</code></a></h3><p>
6679326344Simp<span class="apii">[-0, +1, <em>m</em>]</span>
6680280405Srpaulo<pre>int luaL_newmetatable (lua_State *L, const char *tname);</pre>
6681280405Srpaulo
6682280405Srpaulo<p>
6683280405SrpauloIf the registry already has the key <code>tname</code>,
6684280405Srpauloreturns 0.
6685280405SrpauloOtherwise,
6686280405Srpaulocreates a new table to be used as a metatable for userdata,
6687280405Srpauloadds to this new table the pair <code>__name = tname</code>,
6688280405Srpauloadds to the registry the pair <code>[tname] = new table</code>,
6689280405Srpauloand returns 1.
6690280405Srpaulo(The entry <code>__name</code> is used by some error-reporting functions.)
6691280405Srpaulo
6692280405Srpaulo
6693280405Srpaulo<p>
6694280405SrpauloIn both cases pushes onto the stack the final value associated
6695280405Srpaulowith <code>tname</code> in the registry.
6696280405Srpaulo
6697280405Srpaulo
6698280405Srpaulo
6699280405Srpaulo
6700280405Srpaulo
6701280405Srpaulo<hr><h3><a name="luaL_newstate"><code>luaL_newstate</code></a></h3><p>
6702280405Srpaulo<span class="apii">[-0, +0, &ndash;]</span>
6703280405Srpaulo<pre>lua_State *luaL_newstate (void);</pre>
6704280405Srpaulo
6705280405Srpaulo<p>
6706280405SrpauloCreates a new Lua state.
6707280405SrpauloIt calls <a href="#lua_newstate"><code>lua_newstate</code></a> with an
6708280405Srpauloallocator based on the standard&nbsp;C <code>realloc</code> function
6709280405Srpauloand then sets a panic function (see <a href="#4.6">&sect;4.6</a>) that prints
6710280405Srpauloan error message to the standard error output in case of fatal
6711280405Srpauloerrors.
6712280405Srpaulo
6713280405Srpaulo
6714280405Srpaulo<p>
6715280405SrpauloReturns the new state,
6716280405Srpauloor <code>NULL</code> if there is a memory allocation error.
6717280405Srpaulo
6718280405Srpaulo
6719280405Srpaulo
6720280405Srpaulo
6721280405Srpaulo
6722280405Srpaulo<hr><h3><a name="luaL_openlibs"><code>luaL_openlibs</code></a></h3><p>
6723280405Srpaulo<span class="apii">[-0, +0, <em>e</em>]</span>
6724280405Srpaulo<pre>void luaL_openlibs (lua_State *L);</pre>
6725280405Srpaulo
6726280405Srpaulo<p>
6727280405SrpauloOpens all standard Lua libraries into the given state.
6728280405Srpaulo
6729280405Srpaulo
6730280405Srpaulo
6731280405Srpaulo
6732280405Srpaulo
6733326344Simp<hr><h3><a name="luaL_opt"><code>luaL_opt</code></a></h3><p>
6734326344Simp<span class="apii">[-0, +0, <em>e</em>]</span>
6735326344Simp<pre>T luaL_opt (L, func, arg, dflt);</pre>
6736326344Simp
6737326344Simp<p>
6738326344SimpThis macro is defined as follows:
6739326344Simp
6740326344Simp<pre>
6741326344Simp     (lua_isnoneornil(L,(arg)) ? (dflt) : func(L,(arg)))
6742326344Simp</pre><p>
6743326344SimpIn words, if the argument <code>arg</code> is nil or absent,
6744326344Simpthe macro results in the default <code>dflt</code>.
6745326344SimpOtherwise, it results in the result of calling <code>func</code>
6746326344Simpwith the state <code>L</code> and the argument index <code>arg</code> as
6747344220Skevansarguments.
6748326344SimpNote that it evaluates the expression <code>dflt</code> only if needed.
6749326344Simp
6750326344Simp
6751326344Simp
6752326344Simp
6753326344Simp
6754280405Srpaulo<hr><h3><a name="luaL_optinteger"><code>luaL_optinteger</code></a></h3><p>
6755280405Srpaulo<span class="apii">[-0, +0, <em>v</em>]</span>
6756280405Srpaulo<pre>lua_Integer luaL_optinteger (lua_State *L,
6757280405Srpaulo                             int arg,
6758280405Srpaulo                             lua_Integer d);</pre>
6759280405Srpaulo
6760280405Srpaulo<p>
6761280405SrpauloIf the function argument <code>arg</code> is an integer
6762280405Srpaulo(or convertible to an integer),
6763280405Srpauloreturns this integer.
6764280405SrpauloIf this argument is absent or is <b>nil</b>,
6765280405Srpauloreturns <code>d</code>.
6766280405SrpauloOtherwise, raises an error.
6767280405Srpaulo
6768280405Srpaulo
6769280405Srpaulo
6770280405Srpaulo
6771280405Srpaulo
6772280405Srpaulo<hr><h3><a name="luaL_optlstring"><code>luaL_optlstring</code></a></h3><p>
6773280405Srpaulo<span class="apii">[-0, +0, <em>v</em>]</span>
6774280405Srpaulo<pre>const char *luaL_optlstring (lua_State *L,
6775280405Srpaulo                             int arg,
6776280405Srpaulo                             const char *d,
6777280405Srpaulo                             size_t *l);</pre>
6778280405Srpaulo
6779280405Srpaulo<p>
6780280405SrpauloIf the function argument <code>arg</code> is a string,
6781280405Srpauloreturns this string.
6782280405SrpauloIf this argument is absent or is <b>nil</b>,
6783280405Srpauloreturns <code>d</code>.
6784280405SrpauloOtherwise, raises an error.
6785280405Srpaulo
6786280405Srpaulo
6787280405Srpaulo<p>
6788280405SrpauloIf <code>l</code> is not <code>NULL</code>,
6789280405Srpaulofills the position <code>*l</code> with the result's length.
6790326344SimpIf the result is <code>NULL</code>
6791326344Simp(only possible when returning <code>d</code> and <code>d == NULL</code>),
6792326344Simpits length is considered zero.
6793280405Srpaulo
6794280405Srpaulo
6795326344Simp<p>
6796326344SimpThis function uses <a href="#lua_tolstring"><code>lua_tolstring</code></a> to get its result,
6797326344Simpso all conversions and caveats of that function apply here.
6798280405Srpaulo
6799280405Srpaulo
6800280405Srpaulo
6801326344Simp
6802326344Simp
6803280405Srpaulo<hr><h3><a name="luaL_optnumber"><code>luaL_optnumber</code></a></h3><p>
6804280405Srpaulo<span class="apii">[-0, +0, <em>v</em>]</span>
6805280405Srpaulo<pre>lua_Number luaL_optnumber (lua_State *L, int arg, lua_Number d);</pre>
6806280405Srpaulo
6807280405Srpaulo<p>
6808280405SrpauloIf the function argument <code>arg</code> is a number,
6809280405Srpauloreturns this number.
6810280405SrpauloIf this argument is absent or is <b>nil</b>,
6811280405Srpauloreturns <code>d</code>.
6812280405SrpauloOtherwise, raises an error.
6813280405Srpaulo
6814280405Srpaulo
6815280405Srpaulo
6816280405Srpaulo
6817280405Srpaulo
6818280405Srpaulo<hr><h3><a name="luaL_optstring"><code>luaL_optstring</code></a></h3><p>
6819280405Srpaulo<span class="apii">[-0, +0, <em>v</em>]</span>
6820280405Srpaulo<pre>const char *luaL_optstring (lua_State *L,
6821280405Srpaulo                            int arg,
6822280405Srpaulo                            const char *d);</pre>
6823280405Srpaulo
6824280405Srpaulo<p>
6825280405SrpauloIf the function argument <code>arg</code> is a string,
6826280405Srpauloreturns this string.
6827280405SrpauloIf this argument is absent or is <b>nil</b>,
6828280405Srpauloreturns <code>d</code>.
6829280405SrpauloOtherwise, raises an error.
6830280405Srpaulo
6831280405Srpaulo
6832280405Srpaulo
6833280405Srpaulo
6834280405Srpaulo
6835280405Srpaulo<hr><h3><a name="luaL_prepbuffer"><code>luaL_prepbuffer</code></a></h3><p>
6836326344Simp<span class="apii">[-?, +?, <em>m</em>]</span>
6837280405Srpaulo<pre>char *luaL_prepbuffer (luaL_Buffer *B);</pre>
6838280405Srpaulo
6839280405Srpaulo<p>
6840280405SrpauloEquivalent to <a href="#luaL_prepbuffsize"><code>luaL_prepbuffsize</code></a>
6841280405Srpaulowith the predefined size <a name="pdf-LUAL_BUFFERSIZE"><code>LUAL_BUFFERSIZE</code></a>.
6842280405Srpaulo
6843280405Srpaulo
6844280405Srpaulo
6845280405Srpaulo
6846280405Srpaulo
6847280405Srpaulo<hr><h3><a name="luaL_prepbuffsize"><code>luaL_prepbuffsize</code></a></h3><p>
6848326344Simp<span class="apii">[-?, +?, <em>m</em>]</span>
6849280405Srpaulo<pre>char *luaL_prepbuffsize (luaL_Buffer *B, size_t sz);</pre>
6850280405Srpaulo
6851280405Srpaulo<p>
6852280405SrpauloReturns an address to a space of size <code>sz</code>
6853280405Srpaulowhere you can copy a string to be added to buffer <code>B</code>
6854280405Srpaulo(see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>).
6855280405SrpauloAfter copying the string into this space you must call
6856280405Srpaulo<a href="#luaL_addsize"><code>luaL_addsize</code></a> with the size of the string to actually add
6857280405Srpauloit to the buffer.
6858280405Srpaulo
6859280405Srpaulo
6860280405Srpaulo
6861280405Srpaulo
6862280405Srpaulo
6863280405Srpaulo<hr><h3><a name="luaL_pushresult"><code>luaL_pushresult</code></a></h3><p>
6864326344Simp<span class="apii">[-?, +1, <em>m</em>]</span>
6865280405Srpaulo<pre>void luaL_pushresult (luaL_Buffer *B);</pre>
6866280405Srpaulo
6867280405Srpaulo<p>
6868280405SrpauloFinishes the use of buffer <code>B</code> leaving the final string on
6869280405Srpaulothe top of the stack.
6870280405Srpaulo
6871280405Srpaulo
6872280405Srpaulo
6873280405Srpaulo
6874280405Srpaulo
6875280405Srpaulo<hr><h3><a name="luaL_pushresultsize"><code>luaL_pushresultsize</code></a></h3><p>
6876326344Simp<span class="apii">[-?, +1, <em>m</em>]</span>
6877280405Srpaulo<pre>void luaL_pushresultsize (luaL_Buffer *B, size_t sz);</pre>
6878280405Srpaulo
6879280405Srpaulo<p>
6880280405SrpauloEquivalent to the sequence <a href="#luaL_addsize"><code>luaL_addsize</code></a>, <a href="#luaL_pushresult"><code>luaL_pushresult</code></a>.
6881280405Srpaulo
6882280405Srpaulo
6883280405Srpaulo
6884280405Srpaulo
6885280405Srpaulo
6886280405Srpaulo<hr><h3><a name="luaL_ref"><code>luaL_ref</code></a></h3><p>
6887326344Simp<span class="apii">[-1, +0, <em>m</em>]</span>
6888280405Srpaulo<pre>int luaL_ref (lua_State *L, int t);</pre>
6889280405Srpaulo
6890280405Srpaulo<p>
6891280405SrpauloCreates and returns a <em>reference</em>,
6892280405Srpauloin the table at index <code>t</code>,
6893280405Srpaulofor the object at the top of the stack (and pops the object).
6894280405Srpaulo
6895280405Srpaulo
6896280405Srpaulo<p>
6897280405SrpauloA reference is a unique integer key.
6898280405SrpauloAs long as you do not manually add integer keys into table <code>t</code>,
6899280405Srpaulo<a href="#luaL_ref"><code>luaL_ref</code></a> ensures the uniqueness of the key it returns.
6900280405SrpauloYou can retrieve an object referred by reference <code>r</code>
6901280405Srpauloby calling <code>lua_rawgeti(L, t, r)</code>.
6902280405SrpauloFunction <a href="#luaL_unref"><code>luaL_unref</code></a> frees a reference and its associated object.
6903280405Srpaulo
6904280405Srpaulo
6905280405Srpaulo<p>
6906280405SrpauloIf the object at the top of the stack is <b>nil</b>,
6907280405Srpaulo<a href="#luaL_ref"><code>luaL_ref</code></a> returns the constant <a name="pdf-LUA_REFNIL"><code>LUA_REFNIL</code></a>.
6908280405SrpauloThe constant <a name="pdf-LUA_NOREF"><code>LUA_NOREF</code></a> is guaranteed to be different
6909280405Srpaulofrom any reference returned by <a href="#luaL_ref"><code>luaL_ref</code></a>.
6910280405Srpaulo
6911280405Srpaulo
6912280405Srpaulo
6913280405Srpaulo
6914280405Srpaulo
6915280405Srpaulo<hr><h3><a name="luaL_Reg"><code>luaL_Reg</code></a></h3>
6916280405Srpaulo<pre>typedef struct luaL_Reg {
6917280405Srpaulo  const char *name;
6918280405Srpaulo  lua_CFunction func;
6919280405Srpaulo} luaL_Reg;</pre>
6920280405Srpaulo
6921280405Srpaulo<p>
6922280405SrpauloType for arrays of functions to be registered by
6923280405Srpaulo<a href="#luaL_setfuncs"><code>luaL_setfuncs</code></a>.
6924280405Srpaulo<code>name</code> is the function name and <code>func</code> is a pointer to
6925280405Srpaulothe function.
6926280405SrpauloAny array of <a href="#luaL_Reg"><code>luaL_Reg</code></a> must end with a sentinel entry
6927280405Srpauloin which both <code>name</code> and <code>func</code> are <code>NULL</code>.
6928280405Srpaulo
6929280405Srpaulo
6930280405Srpaulo
6931280405Srpaulo
6932280405Srpaulo
6933280405Srpaulo<hr><h3><a name="luaL_requiref"><code>luaL_requiref</code></a></h3><p>
6934280405Srpaulo<span class="apii">[-0, +1, <em>e</em>]</span>
6935280405Srpaulo<pre>void luaL_requiref (lua_State *L, const char *modname,
6936280405Srpaulo                    lua_CFunction openf, int glb);</pre>
6937280405Srpaulo
6938280405Srpaulo<p>
6939280405SrpauloIf <code>modname</code> is not already present in <a href="#pdf-package.loaded"><code>package.loaded</code></a>,
6940280405Srpaulocalls function <code>openf</code> with string <code>modname</code> as an argument
6941280405Srpauloand sets the call result in <code>package.loaded[modname]</code>,
6942280405Srpauloas if that function has been called through <a href="#pdf-require"><code>require</code></a>.
6943280405Srpaulo
6944280405Srpaulo
6945280405Srpaulo<p>
6946280405SrpauloIf <code>glb</code> is true,
6947280405Srpauloalso stores the module into global <code>modname</code>.
6948280405Srpaulo
6949280405Srpaulo
6950280405Srpaulo<p>
6951280405SrpauloLeaves a copy of the module on the stack.
6952280405Srpaulo
6953280405Srpaulo
6954280405Srpaulo
6955280405Srpaulo
6956280405Srpaulo
6957280405Srpaulo<hr><h3><a name="luaL_setfuncs"><code>luaL_setfuncs</code></a></h3><p>
6958326344Simp<span class="apii">[-nup, +0, <em>m</em>]</span>
6959280405Srpaulo<pre>void luaL_setfuncs (lua_State *L, const luaL_Reg *l, int nup);</pre>
6960280405Srpaulo
6961280405Srpaulo<p>
6962280405SrpauloRegisters all functions in the array <code>l</code>
6963280405Srpaulo(see <a href="#luaL_Reg"><code>luaL_Reg</code></a>) into the table on the top of the stack
6964280405Srpaulo(below optional upvalues, see next).
6965280405Srpaulo
6966280405Srpaulo
6967280405Srpaulo<p>
6968280405SrpauloWhen <code>nup</code> is not zero,
6969280405Srpauloall functions are created sharing <code>nup</code> upvalues,
6970280405Srpaulowhich must be previously pushed on the stack
6971280405Srpauloon top of the library table.
6972280405SrpauloThese values are popped from the stack after the registration.
6973280405Srpaulo
6974280405Srpaulo
6975280405Srpaulo
6976280405Srpaulo
6977280405Srpaulo
6978280405Srpaulo<hr><h3><a name="luaL_setmetatable"><code>luaL_setmetatable</code></a></h3><p>
6979280405Srpaulo<span class="apii">[-0, +0, &ndash;]</span>
6980280405Srpaulo<pre>void luaL_setmetatable (lua_State *L, const char *tname);</pre>
6981280405Srpaulo
6982280405Srpaulo<p>
6983280405SrpauloSets the metatable of the object at the top of the stack
6984280405Srpauloas the metatable associated with name <code>tname</code>
6985280405Srpauloin the registry (see <a href="#luaL_newmetatable"><code>luaL_newmetatable</code></a>).
6986280405Srpaulo
6987280405Srpaulo
6988280405Srpaulo
6989280405Srpaulo
6990280405Srpaulo
6991280405Srpaulo<hr><h3><a name="luaL_Stream"><code>luaL_Stream</code></a></h3>
6992280405Srpaulo<pre>typedef struct luaL_Stream {
6993280405Srpaulo  FILE *f;
6994280405Srpaulo  lua_CFunction closef;
6995280405Srpaulo} luaL_Stream;</pre>
6996280405Srpaulo
6997280405Srpaulo<p>
6998280405SrpauloThe standard representation for file handles,
6999280405Srpaulowhich is used by the standard I/O library.
7000280405Srpaulo
7001280405Srpaulo
7002280405Srpaulo<p>
7003280405SrpauloA file handle is implemented as a full userdata,
7004280405Srpaulowith a metatable called <code>LUA_FILEHANDLE</code>
7005280405Srpaulo(where <code>LUA_FILEHANDLE</code> is a macro with the actual metatable's name).
7006280405SrpauloThe metatable is created by the I/O library
7007280405Srpaulo(see <a href="#luaL_newmetatable"><code>luaL_newmetatable</code></a>).
7008280405Srpaulo
7009280405Srpaulo
7010280405Srpaulo<p>
7011280405SrpauloThis userdata must start with the structure <code>luaL_Stream</code>;
7012280405Srpauloit can contain other data after this initial structure.
7013280405SrpauloField <code>f</code> points to the corresponding C stream
7014280405Srpaulo(or it can be <code>NULL</code> to indicate an incompletely created handle).
7015280405SrpauloField <code>closef</code> points to a Lua function
7016280405Srpaulothat will be called to close the stream
7017280405Srpaulowhen the handle is closed or collected;
7018280405Srpaulothis function receives the file handle as its sole argument and
7019280405Srpaulomust return either <b>true</b> (in case of success)
7020280405Srpauloor <b>nil</b> plus an error message (in case of error).
7021280405SrpauloOnce Lua calls this field,
7022326344Simpit changes the field value to <code>NULL</code>
7023280405Srpauloto signal that the handle is closed.
7024280405Srpaulo
7025280405Srpaulo
7026280405Srpaulo
7027280405Srpaulo
7028280405Srpaulo
7029280405Srpaulo<hr><h3><a name="luaL_testudata"><code>luaL_testudata</code></a></h3><p>
7030326344Simp<span class="apii">[-0, +0, <em>m</em>]</span>
7031280405Srpaulo<pre>void *luaL_testudata (lua_State *L, int arg, const char *tname);</pre>
7032280405Srpaulo
7033280405Srpaulo<p>
7034280405SrpauloThis function works like <a href="#luaL_checkudata"><code>luaL_checkudata</code></a>,
7035280405Srpauloexcept that, when the test fails,
7036280405Srpauloit returns <code>NULL</code> instead of raising an error.
7037280405Srpaulo
7038280405Srpaulo
7039280405Srpaulo
7040280405Srpaulo
7041280405Srpaulo
7042280405Srpaulo<hr><h3><a name="luaL_tolstring"><code>luaL_tolstring</code></a></h3><p>
7043280405Srpaulo<span class="apii">[-0, +1, <em>e</em>]</span>
7044280405Srpaulo<pre>const char *luaL_tolstring (lua_State *L, int idx, size_t *len);</pre>
7045280405Srpaulo
7046280405Srpaulo<p>
7047280405SrpauloConverts any Lua value at the given index to a C&nbsp;string
7048280405Srpauloin a reasonable format.
7049280405SrpauloThe resulting string is pushed onto the stack and also
7050280405Srpauloreturned by the function.
7051280405SrpauloIf <code>len</code> is not <code>NULL</code>,
7052280405Srpaulothe function also sets <code>*len</code> with the string length.
7053280405Srpaulo
7054280405Srpaulo
7055280405Srpaulo<p>
7056326344SimpIf the value has a metatable with a <code>__tostring</code> field,
7057280405Srpaulothen <code>luaL_tolstring</code> calls the corresponding metamethod
7058280405Srpaulowith the value as argument,
7059280405Srpauloand uses the result of the call as its result.
7060280405Srpaulo
7061280405Srpaulo
7062280405Srpaulo
7063280405Srpaulo
7064280405Srpaulo
7065280405Srpaulo<hr><h3><a name="luaL_traceback"><code>luaL_traceback</code></a></h3><p>
7066326344Simp<span class="apii">[-0, +1, <em>m</em>]</span>
7067280405Srpaulo<pre>void luaL_traceback (lua_State *L, lua_State *L1, const char *msg,
7068280405Srpaulo                     int level);</pre>
7069280405Srpaulo
7070280405Srpaulo<p>
7071280405SrpauloCreates and pushes a traceback of the stack <code>L1</code>.
7072280405SrpauloIf <code>msg</code> is not <code>NULL</code> it is appended
7073280405Srpauloat the beginning of the traceback.
7074280405SrpauloThe <code>level</code> parameter tells at which level
7075280405Srpauloto start the traceback.
7076280405Srpaulo
7077280405Srpaulo
7078280405Srpaulo
7079280405Srpaulo
7080280405Srpaulo
7081280405Srpaulo<hr><h3><a name="luaL_typename"><code>luaL_typename</code></a></h3><p>
7082280405Srpaulo<span class="apii">[-0, +0, &ndash;]</span>
7083280405Srpaulo<pre>const char *luaL_typename (lua_State *L, int index);</pre>
7084280405Srpaulo
7085280405Srpaulo<p>
7086280405SrpauloReturns the name of the type of the value at the given index.
7087280405Srpaulo
7088280405Srpaulo
7089280405Srpaulo
7090280405Srpaulo
7091280405Srpaulo
7092280405Srpaulo<hr><h3><a name="luaL_unref"><code>luaL_unref</code></a></h3><p>
7093280405Srpaulo<span class="apii">[-0, +0, &ndash;]</span>
7094280405Srpaulo<pre>void luaL_unref (lua_State *L, int t, int ref);</pre>
7095280405Srpaulo
7096280405Srpaulo<p>
7097280405SrpauloReleases reference <code>ref</code> from the table at index <code>t</code>
7098280405Srpaulo(see <a href="#luaL_ref"><code>luaL_ref</code></a>).
7099280405SrpauloThe entry is removed from the table,
7100280405Srpauloso that the referred object can be collected.
7101280405SrpauloThe reference <code>ref</code> is also freed to be used again.
7102280405Srpaulo
7103280405Srpaulo
7104280405Srpaulo<p>
7105280405SrpauloIf <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>,
7106280405Srpaulo<a href="#luaL_unref"><code>luaL_unref</code></a> does nothing.
7107280405Srpaulo
7108280405Srpaulo
7109280405Srpaulo
7110280405Srpaulo
7111280405Srpaulo
7112280405Srpaulo<hr><h3><a name="luaL_where"><code>luaL_where</code></a></h3><p>
7113326344Simp<span class="apii">[-0, +1, <em>m</em>]</span>
7114280405Srpaulo<pre>void luaL_where (lua_State *L, int lvl);</pre>
7115280405Srpaulo
7116280405Srpaulo<p>
7117280405SrpauloPushes onto the stack a string identifying the current position
7118280405Srpauloof the control at level <code>lvl</code> in the call stack.
7119280405SrpauloTypically this string has the following format:
7120280405Srpaulo
7121280405Srpaulo<pre>
7122280405Srpaulo     <em>chunkname</em>:<em>currentline</em>:
7123280405Srpaulo</pre><p>
7124280405SrpauloLevel&nbsp;0 is the running function,
7125280405Srpaulolevel&nbsp;1 is the function that called the running function,
7126280405Srpauloetc.
7127280405Srpaulo
7128280405Srpaulo
7129280405Srpaulo<p>
7130280405SrpauloThis function is used to build a prefix for error messages.
7131280405Srpaulo
7132280405Srpaulo
7133280405Srpaulo
7134280405Srpaulo
7135280405Srpaulo
7136280405Srpaulo
7137280405Srpaulo
7138280405Srpaulo<h1>6 &ndash; <a name="6">Standard Libraries</a></h1>
7139280405Srpaulo
7140280405Srpaulo<p>
7141280405SrpauloThe standard Lua libraries provide useful functions
7142280405Srpaulothat are implemented directly through the C&nbsp;API.
7143280405SrpauloSome of these functions provide essential services to the language
7144280405Srpaulo(e.g., <a href="#pdf-type"><code>type</code></a> and <a href="#pdf-getmetatable"><code>getmetatable</code></a>);
7145280405Srpauloothers provide access to "outside" services (e.g., I/O);
7146280405Srpauloand others could be implemented in Lua itself,
7147280405Srpaulobut are quite useful or have critical performance requirements that
7148280405Srpaulodeserve an implementation in C (e.g., <a href="#pdf-table.sort"><code>table.sort</code></a>).
7149280405Srpaulo
7150280405Srpaulo
7151280405Srpaulo<p>
7152280405SrpauloAll libraries are implemented through the official C&nbsp;API
7153280405Srpauloand are provided as separate C&nbsp;modules.
7154280405SrpauloCurrently, Lua has the following standard libraries:
7155280405Srpaulo
7156280405Srpaulo<ul>
7157280405Srpaulo
7158280405Srpaulo<li>basic library (<a href="#6.1">&sect;6.1</a>);</li>
7159280405Srpaulo
7160280405Srpaulo<li>coroutine library (<a href="#6.2">&sect;6.2</a>);</li>
7161280405Srpaulo
7162280405Srpaulo<li>package library (<a href="#6.3">&sect;6.3</a>);</li>
7163280405Srpaulo
7164280405Srpaulo<li>string manipulation (<a href="#6.4">&sect;6.4</a>);</li>
7165280405Srpaulo
7166280405Srpaulo<li>basic UTF-8 support (<a href="#6.5">&sect;6.5</a>);</li>
7167280405Srpaulo
7168280405Srpaulo<li>table manipulation (<a href="#6.6">&sect;6.6</a>);</li>
7169280405Srpaulo
7170280405Srpaulo<li>mathematical functions (<a href="#6.7">&sect;6.7</a>) (sin, log, etc.);</li>
7171280405Srpaulo
7172280405Srpaulo<li>input and output (<a href="#6.8">&sect;6.8</a>);</li>
7173280405Srpaulo
7174280405Srpaulo<li>operating system facilities (<a href="#6.9">&sect;6.9</a>);</li>
7175280405Srpaulo
7176280405Srpaulo<li>debug facilities (<a href="#6.10">&sect;6.10</a>).</li>
7177280405Srpaulo
7178280405Srpaulo</ul><p>
7179280405SrpauloExcept for the basic and the package libraries,
7180280405Srpauloeach library provides all its functions as fields of a global table
7181280405Srpauloor as methods of its objects.
7182280405Srpaulo
7183280405Srpaulo
7184280405Srpaulo<p>
7185280405SrpauloTo have access to these libraries,
7186280405Srpaulothe C&nbsp;host program should call the <a href="#luaL_openlibs"><code>luaL_openlibs</code></a> function,
7187280405Srpaulowhich opens all standard libraries.
7188280405SrpauloAlternatively,
7189280405Srpaulothe host program can open them individually by using
7190280405Srpaulo<a href="#luaL_requiref"><code>luaL_requiref</code></a> to call
7191280405Srpaulo<a name="pdf-luaopen_base"><code>luaopen_base</code></a> (for the basic library),
7192280405Srpaulo<a name="pdf-luaopen_package"><code>luaopen_package</code></a> (for the package library),
7193280405Srpaulo<a name="pdf-luaopen_coroutine"><code>luaopen_coroutine</code></a> (for the coroutine library),
7194280405Srpaulo<a name="pdf-luaopen_string"><code>luaopen_string</code></a> (for the string library),
7195280405Srpaulo<a name="pdf-luaopen_utf8"><code>luaopen_utf8</code></a> (for the UTF8 library),
7196280405Srpaulo<a name="pdf-luaopen_table"><code>luaopen_table</code></a> (for the table library),
7197280405Srpaulo<a name="pdf-luaopen_math"><code>luaopen_math</code></a> (for the mathematical library),
7198280405Srpaulo<a name="pdf-luaopen_io"><code>luaopen_io</code></a> (for the I/O library),
7199280405Srpaulo<a name="pdf-luaopen_os"><code>luaopen_os</code></a> (for the operating system library),
7200280405Srpauloand <a name="pdf-luaopen_debug"><code>luaopen_debug</code></a> (for the debug library).
7201280405SrpauloThese functions are declared in <a name="pdf-lualib.h"><code>lualib.h</code></a>.
7202280405Srpaulo
7203280405Srpaulo
7204280405Srpaulo
7205280405Srpaulo<h2>6.1 &ndash; <a name="6.1">Basic Functions</a></h2>
7206280405Srpaulo
7207280405Srpaulo<p>
7208280405SrpauloThe basic library provides core functions to Lua.
7209280405SrpauloIf you do not include this library in your application,
7210280405Srpauloyou should check carefully whether you need to provide
7211280405Srpauloimplementations for some of its facilities.
7212280405Srpaulo
7213280405Srpaulo
7214280405Srpaulo<p>
7215280405Srpaulo<hr><h3><a name="pdf-assert"><code>assert (v [, message])</code></a></h3>
7216280405Srpaulo
7217280405Srpaulo
7218280405Srpaulo<p>
7219280405SrpauloCalls <a href="#pdf-error"><code>error</code></a> if
7220280405Srpaulothe value of its argument <code>v</code> is false (i.e., <b>nil</b> or <b>false</b>);
7221280405Srpaulootherwise, returns all its arguments.
7222280405SrpauloIn case of error,
7223280405Srpaulo<code>message</code> is the error object;
7224280405Srpaulowhen absent, it defaults to "<code>assertion failed!</code>"
7225280405Srpaulo
7226280405Srpaulo
7227280405Srpaulo
7228280405Srpaulo
7229280405Srpaulo<p>
7230280405Srpaulo<hr><h3><a name="pdf-collectgarbage"><code>collectgarbage ([opt [, arg]])</code></a></h3>
7231280405Srpaulo
7232280405Srpaulo
7233280405Srpaulo<p>
7234280405SrpauloThis function is a generic interface to the garbage collector.
7235280405SrpauloIt performs different functions according to its first argument, <code>opt</code>:
7236280405Srpaulo
7237280405Srpaulo<ul>
7238280405Srpaulo
7239280405Srpaulo<li><b>"<code>collect</code>": </b>
7240280405Srpauloperforms a full garbage-collection cycle.
7241280405SrpauloThis is the default option.
7242280405Srpaulo</li>
7243280405Srpaulo
7244280405Srpaulo<li><b>"<code>stop</code>": </b>
7245280405Srpaulostops automatic execution of the garbage collector.
7246280405SrpauloThe collector will run only when explicitly invoked,
7247280405Srpaulountil a call to restart it.
7248280405Srpaulo</li>
7249280405Srpaulo
7250280405Srpaulo<li><b>"<code>restart</code>": </b>
7251280405Srpaulorestarts automatic execution of the garbage collector.
7252280405Srpaulo</li>
7253280405Srpaulo
7254280405Srpaulo<li><b>"<code>count</code>": </b>
7255280405Srpauloreturns the total memory in use by Lua in Kbytes.
7256280405SrpauloThe value has a fractional part,
7257280405Srpauloso that it multiplied by 1024
7258280405Srpaulogives the exact number of bytes in use by Lua
7259280405Srpaulo(except for overflows).
7260280405Srpaulo</li>
7261280405Srpaulo
7262280405Srpaulo<li><b>"<code>step</code>": </b>
7263280405Srpauloperforms a garbage-collection step.
7264280405SrpauloThe step "size" is controlled by <code>arg</code>.
7265280405SrpauloWith a zero value,
7266280405Srpaulothe collector will perform one basic (indivisible) step.
7267280405SrpauloFor non-zero values,
7268280405Srpaulothe collector will perform as if that amount of memory
7269280405Srpaulo(in KBytes) had been allocated by Lua.
7270280405SrpauloReturns <b>true</b> if the step finished a collection cycle.
7271280405Srpaulo</li>
7272280405Srpaulo
7273280405Srpaulo<li><b>"<code>setpause</code>": </b>
7274280405Srpaulosets <code>arg</code> as the new value for the <em>pause</em> of
7275280405Srpaulothe collector (see <a href="#2.5">&sect;2.5</a>).
7276280405SrpauloReturns the previous value for <em>pause</em>.
7277280405Srpaulo</li>
7278280405Srpaulo
7279280405Srpaulo<li><b>"<code>setstepmul</code>": </b>
7280280405Srpaulosets <code>arg</code> as the new value for the <em>step multiplier</em> of
7281280405Srpaulothe collector (see <a href="#2.5">&sect;2.5</a>).
7282280405SrpauloReturns the previous value for <em>step</em>.
7283280405Srpaulo</li>
7284280405Srpaulo
7285280405Srpaulo<li><b>"<code>isrunning</code>": </b>
7286280405Srpauloreturns a boolean that tells whether the collector is running
7287280405Srpaulo(i.e., not stopped).
7288280405Srpaulo</li>
7289280405Srpaulo
7290280405Srpaulo</ul>
7291280405Srpaulo
7292280405Srpaulo
7293280405Srpaulo
7294280405Srpaulo<p>
7295280405Srpaulo<hr><h3><a name="pdf-dofile"><code>dofile ([filename])</code></a></h3>
7296280405SrpauloOpens the named file and executes its contents as a Lua chunk.
7297280405SrpauloWhen called without arguments,
7298280405Srpaulo<code>dofile</code> executes the contents of the standard input (<code>stdin</code>).
7299280405SrpauloReturns all values returned by the chunk.
7300280405SrpauloIn case of errors, <code>dofile</code> propagates the error
7301280405Srpauloto its caller (that is, <code>dofile</code> does not run in protected mode).
7302280405Srpaulo
7303280405Srpaulo
7304280405Srpaulo
7305280405Srpaulo
7306280405Srpaulo<p>
7307280405Srpaulo<hr><h3><a name="pdf-error"><code>error (message [, level])</code></a></h3>
7308280405SrpauloTerminates the last protected function called
7309280405Srpauloand returns <code>message</code> as the error object.
7310280405SrpauloFunction <code>error</code> never returns.
7311280405Srpaulo
7312280405Srpaulo
7313280405Srpaulo<p>
7314280405SrpauloUsually, <code>error</code> adds some information about the error position
7315280405Srpauloat the beginning of the message, if the message is a string.
7316280405SrpauloThe <code>level</code> argument specifies how to get the error position.
7317280405SrpauloWith level&nbsp;1 (the default), the error position is where the
7318280405Srpaulo<code>error</code> function was called.
7319280405SrpauloLevel&nbsp;2 points the error to where the function
7320280405Srpaulothat called <code>error</code> was called; and so on.
7321280405SrpauloPassing a level&nbsp;0 avoids the addition of error position information
7322280405Srpauloto the message.
7323280405Srpaulo
7324280405Srpaulo
7325280405Srpaulo
7326280405Srpaulo
7327280405Srpaulo<p>
7328280405Srpaulo<hr><h3><a name="pdf-_G"><code>_G</code></a></h3>
7329280405SrpauloA global variable (not a function) that
7330280405Srpauloholds the global environment (see <a href="#2.2">&sect;2.2</a>).
7331280405SrpauloLua itself does not use this variable;
7332280405Srpaulochanging its value does not affect any environment,
7333280405Srpaulonor vice versa.
7334280405Srpaulo
7335280405Srpaulo
7336280405Srpaulo
7337280405Srpaulo
7338280405Srpaulo<p>
7339280405Srpaulo<hr><h3><a name="pdf-getmetatable"><code>getmetatable (object)</code></a></h3>
7340280405Srpaulo
7341280405Srpaulo
7342280405Srpaulo<p>
7343280405SrpauloIf <code>object</code> does not have a metatable, returns <b>nil</b>.
7344280405SrpauloOtherwise,
7345326344Simpif the object's metatable has a <code>__metatable</code> field,
7346280405Srpauloreturns the associated value.
7347280405SrpauloOtherwise, returns the metatable of the given object.
7348280405Srpaulo
7349280405Srpaulo
7350280405Srpaulo
7351280405Srpaulo
7352280405Srpaulo<p>
7353280405Srpaulo<hr><h3><a name="pdf-ipairs"><code>ipairs (t)</code></a></h3>
7354280405Srpaulo
7355280405Srpaulo
7356280405Srpaulo<p>
7357280405SrpauloReturns three values (an iterator function, the table <code>t</code>, and 0)
7358280405Srpauloso that the construction
7359280405Srpaulo
7360280405Srpaulo<pre>
7361280405Srpaulo     for i,v in ipairs(t) do <em>body</em> end
7362280405Srpaulo</pre><p>
7363280405Srpaulowill iterate over the key&ndash;value pairs
7364280405Srpaulo(<code>1,t[1]</code>), (<code>2,t[2]</code>), ...,
7365280405Srpauloup to the first nil value.
7366280405Srpaulo
7367280405Srpaulo
7368280405Srpaulo
7369280405Srpaulo
7370280405Srpaulo<p>
7371280405Srpaulo<hr><h3><a name="pdf-load"><code>load (chunk [, chunkname [, mode [, env]]])</code></a></h3>
7372280405Srpaulo
7373280405Srpaulo
7374280405Srpaulo<p>
7375280405SrpauloLoads a chunk.
7376280405Srpaulo
7377280405Srpaulo
7378280405Srpaulo<p>
7379280405SrpauloIf <code>chunk</code> is a string, the chunk is this string.
7380280405SrpauloIf <code>chunk</code> is a function,
7381280405Srpaulo<code>load</code> calls it repeatedly to get the chunk pieces.
7382280405SrpauloEach call to <code>chunk</code> must return a string that concatenates
7383280405Srpaulowith previous results.
7384280405SrpauloA return of an empty string, <b>nil</b>, or no value signals the end of the chunk.
7385280405Srpaulo
7386280405Srpaulo
7387280405Srpaulo<p>
7388280405SrpauloIf there are no syntactic errors,
7389280405Srpauloreturns the compiled chunk as a function;
7390280405Srpaulootherwise, returns <b>nil</b> plus the error message.
7391280405Srpaulo
7392280405Srpaulo
7393280405Srpaulo<p>
7394280405SrpauloIf the resulting function has upvalues,
7395280405Srpaulothe first upvalue is set to the value of <code>env</code>,
7396280405Srpauloif that parameter is given,
7397280405Srpauloor to the value of the global environment.
7398280405SrpauloOther upvalues are initialized with <b>nil</b>.
7399280405Srpaulo(When you load a main chunk,
7400280405Srpaulothe resulting function will always have exactly one upvalue,
7401280405Srpaulothe <code>_ENV</code> variable (see <a href="#2.2">&sect;2.2</a>).
7402280405SrpauloHowever,
7403280405Srpaulowhen you load a binary chunk created from a function (see <a href="#pdf-string.dump"><code>string.dump</code></a>),
7404280405Srpaulothe resulting function can have an arbitrary number of upvalues.)
7405280405SrpauloAll upvalues are fresh, that is,
7406280405Srpaulothey are not shared with any other function.
7407280405Srpaulo
7408280405Srpaulo
7409280405Srpaulo<p>
7410280405Srpaulo<code>chunkname</code> is used as the name of the chunk for error messages
7411280405Srpauloand debug information (see <a href="#4.9">&sect;4.9</a>).
7412280405SrpauloWhen absent,
7413280405Srpauloit defaults to <code>chunk</code>, if <code>chunk</code> is a string,
7414280405Srpauloor to "<code>=(load)</code>" otherwise.
7415280405Srpaulo
7416280405Srpaulo
7417280405Srpaulo<p>
7418280405SrpauloThe string <code>mode</code> controls whether the chunk can be text or binary
7419280405Srpaulo(that is, a precompiled chunk).
7420280405SrpauloIt may be the string "<code>b</code>" (only binary chunks),
7421280405Srpaulo"<code>t</code>" (only text chunks),
7422280405Srpauloor "<code>bt</code>" (both binary and text).
7423280405SrpauloThe default is "<code>bt</code>".
7424280405Srpaulo
7425280405Srpaulo
7426280405Srpaulo<p>
7427280405SrpauloLua does not check the consistency of binary chunks.
7428280405SrpauloMaliciously crafted binary chunks can crash
7429280405Srpaulothe interpreter.
7430280405Srpaulo
7431280405Srpaulo
7432280405Srpaulo
7433280405Srpaulo
7434280405Srpaulo<p>
7435280405Srpaulo<hr><h3><a name="pdf-loadfile"><code>loadfile ([filename [, mode [, env]]])</code></a></h3>
7436280405Srpaulo
7437280405Srpaulo
7438280405Srpaulo<p>
7439280405SrpauloSimilar to <a href="#pdf-load"><code>load</code></a>,
7440280405Srpaulobut gets the chunk from file <code>filename</code>
7441280405Srpauloor from the standard input,
7442280405Srpauloif no file name is given.
7443280405Srpaulo
7444280405Srpaulo
7445280405Srpaulo
7446280405Srpaulo
7447280405Srpaulo<p>
7448280405Srpaulo<hr><h3><a name="pdf-next"><code>next (table [, index])</code></a></h3>
7449280405Srpaulo
7450280405Srpaulo
7451280405Srpaulo<p>
7452280405SrpauloAllows a program to traverse all fields of a table.
7453280405SrpauloIts first argument is a table and its second argument
7454280405Srpaulois an index in this table.
7455280405Srpaulo<code>next</code> returns the next index of the table
7456280405Srpauloand its associated value.
7457280405SrpauloWhen called with <b>nil</b> as its second argument,
7458280405Srpaulo<code>next</code> returns an initial index
7459280405Srpauloand its associated value.
7460280405SrpauloWhen called with the last index,
7461280405Srpauloor with <b>nil</b> in an empty table,
7462280405Srpaulo<code>next</code> returns <b>nil</b>.
7463280405SrpauloIf the second argument is absent, then it is interpreted as <b>nil</b>.
7464280405SrpauloIn particular,
7465280405Srpauloyou can use <code>next(t)</code> to check whether a table is empty.
7466280405Srpaulo
7467280405Srpaulo
7468280405Srpaulo<p>
7469280405SrpauloThe order in which the indices are enumerated is not specified,
7470280405Srpaulo<em>even for numeric indices</em>.
7471326344Simp(To traverse a table in numerical order,
7472280405Srpaulouse a numerical <b>for</b>.)
7473280405Srpaulo
7474280405Srpaulo
7475280405Srpaulo<p>
7476280405SrpauloThe behavior of <code>next</code> is undefined if,
7477280405Srpauloduring the traversal,
7478280405Srpauloyou assign any value to a non-existent field in the table.
7479280405SrpauloYou may however modify existing fields.
7480280405SrpauloIn particular, you may clear existing fields.
7481280405Srpaulo
7482280405Srpaulo
7483280405Srpaulo
7484280405Srpaulo
7485280405Srpaulo<p>
7486280405Srpaulo<hr><h3><a name="pdf-pairs"><code>pairs (t)</code></a></h3>
7487280405Srpaulo
7488280405Srpaulo
7489280405Srpaulo<p>
7490280405SrpauloIf <code>t</code> has a metamethod <code>__pairs</code>,
7491280405Srpaulocalls it with <code>t</code> as argument and returns the first three
7492280405Srpauloresults from the call.
7493280405Srpaulo
7494280405Srpaulo
7495280405Srpaulo<p>
7496280405SrpauloOtherwise,
7497280405Srpauloreturns three values: the <a href="#pdf-next"><code>next</code></a> function, the table <code>t</code>, and <b>nil</b>,
7498280405Srpauloso that the construction
7499280405Srpaulo
7500280405Srpaulo<pre>
7501280405Srpaulo     for k,v in pairs(t) do <em>body</em> end
7502280405Srpaulo</pre><p>
7503280405Srpaulowill iterate over all key&ndash;value pairs of table <code>t</code>.
7504280405Srpaulo
7505280405Srpaulo
7506280405Srpaulo<p>
7507280405SrpauloSee function <a href="#pdf-next"><code>next</code></a> for the caveats of modifying
7508280405Srpaulothe table during its traversal.
7509280405Srpaulo
7510280405Srpaulo
7511280405Srpaulo
7512280405Srpaulo
7513280405Srpaulo<p>
7514280405Srpaulo<hr><h3><a name="pdf-pcall"><code>pcall (f [, arg1, &middot;&middot;&middot;])</code></a></h3>
7515280405Srpaulo
7516280405Srpaulo
7517280405Srpaulo<p>
7518280405SrpauloCalls function <code>f</code> with
7519280405Srpaulothe given arguments in <em>protected mode</em>.
7520280405SrpauloThis means that any error inside&nbsp;<code>f</code> is not propagated;
7521280405Srpauloinstead, <code>pcall</code> catches the error
7522280405Srpauloand returns a status code.
7523280405SrpauloIts first result is the status code (a boolean),
7524280405Srpaulowhich is true if the call succeeds without errors.
7525280405SrpauloIn such case, <code>pcall</code> also returns all results from the call,
7526280405Srpauloafter this first result.
7527280405SrpauloIn case of any error, <code>pcall</code> returns <b>false</b> plus the error message.
7528280405Srpaulo
7529280405Srpaulo
7530280405Srpaulo
7531280405Srpaulo
7532280405Srpaulo<p>
7533280405Srpaulo<hr><h3><a name="pdf-print"><code>print (&middot;&middot;&middot;)</code></a></h3>
7534280405SrpauloReceives any number of arguments
7535280405Srpauloand prints their values to <code>stdout</code>,
7536280405Srpaulousing the <a href="#pdf-tostring"><code>tostring</code></a> function to convert each argument to a string.
7537280405Srpaulo<code>print</code> is not intended for formatted output,
7538280405Srpaulobut only as a quick way to show a value,
7539280405Srpaulofor instance for debugging.
7540280405SrpauloFor complete control over the output,
7541280405Srpaulouse <a href="#pdf-string.format"><code>string.format</code></a> and <a href="#pdf-io.write"><code>io.write</code></a>.
7542280405Srpaulo
7543280405Srpaulo
7544280405Srpaulo
7545280405Srpaulo
7546280405Srpaulo<p>
7547280405Srpaulo<hr><h3><a name="pdf-rawequal"><code>rawequal (v1, v2)</code></a></h3>
7548280405SrpauloChecks whether <code>v1</code> is equal to <code>v2</code>,
7549326344Simpwithout invoking the <code>__eq</code> metamethod.
7550280405SrpauloReturns a boolean.
7551280405Srpaulo
7552280405Srpaulo
7553280405Srpaulo
7554280405Srpaulo
7555280405Srpaulo<p>
7556280405Srpaulo<hr><h3><a name="pdf-rawget"><code>rawget (table, index)</code></a></h3>
7557280405SrpauloGets the real value of <code>table[index]</code>,
7558326344Simpwithout invoking the <code>__index</code> metamethod.
7559280405Srpaulo<code>table</code> must be a table;
7560280405Srpaulo<code>index</code> may be any value.
7561280405Srpaulo
7562280405Srpaulo
7563280405Srpaulo
7564280405Srpaulo
7565280405Srpaulo<p>
7566280405Srpaulo<hr><h3><a name="pdf-rawlen"><code>rawlen (v)</code></a></h3>
7567280405SrpauloReturns the length of the object <code>v</code>,
7568280405Srpaulowhich must be a table or a string,
7569326344Simpwithout invoking the <code>__len</code> metamethod.
7570280405SrpauloReturns an integer.
7571280405Srpaulo
7572280405Srpaulo
7573280405Srpaulo
7574280405Srpaulo
7575280405Srpaulo<p>
7576280405Srpaulo<hr><h3><a name="pdf-rawset"><code>rawset (table, index, value)</code></a></h3>
7577280405SrpauloSets the real value of <code>table[index]</code> to <code>value</code>,
7578326344Simpwithout invoking the <code>__newindex</code> metamethod.
7579280405Srpaulo<code>table</code> must be a table,
7580280405Srpaulo<code>index</code> any value different from <b>nil</b> and NaN,
7581280405Srpauloand <code>value</code> any Lua value.
7582280405Srpaulo
7583280405Srpaulo
7584280405Srpaulo<p>
7585280405SrpauloThis function returns <code>table</code>.
7586280405Srpaulo
7587280405Srpaulo
7588280405Srpaulo
7589280405Srpaulo
7590280405Srpaulo<p>
7591280405Srpaulo<hr><h3><a name="pdf-select"><code>select (index, &middot;&middot;&middot;)</code></a></h3>
7592280405Srpaulo
7593280405Srpaulo
7594280405Srpaulo<p>
7595280405SrpauloIf <code>index</code> is a number,
7596280405Srpauloreturns all arguments after argument number <code>index</code>;
7597280405Srpauloa negative number indexes from the end (-1 is the last argument).
7598280405SrpauloOtherwise, <code>index</code> must be the string <code>"#"</code>,
7599280405Srpauloand <code>select</code> returns the total number of extra arguments it received.
7600280405Srpaulo
7601280405Srpaulo
7602280405Srpaulo
7603280405Srpaulo
7604280405Srpaulo<p>
7605280405Srpaulo<hr><h3><a name="pdf-setmetatable"><code>setmetatable (table, metatable)</code></a></h3>
7606280405Srpaulo
7607280405Srpaulo
7608280405Srpaulo<p>
7609280405SrpauloSets the metatable for the given table.
7610326344Simp(To change the metatable of other types from Lua code,
7611326344Simpyou must use the debug library (<a href="#6.10">&sect;6.10</a>).)
7612280405SrpauloIf <code>metatable</code> is <b>nil</b>,
7613280405Srpauloremoves the metatable of the given table.
7614326344SimpIf the original metatable has a <code>__metatable</code> field,
7615280405Srpauloraises an error.
7616280405Srpaulo
7617280405Srpaulo
7618280405Srpaulo<p>
7619280405SrpauloThis function returns <code>table</code>.
7620280405Srpaulo
7621280405Srpaulo
7622280405Srpaulo
7623280405Srpaulo
7624280405Srpaulo<p>
7625280405Srpaulo<hr><h3><a name="pdf-tonumber"><code>tonumber (e [, base])</code></a></h3>
7626280405Srpaulo
7627280405Srpaulo
7628280405Srpaulo<p>
7629280405SrpauloWhen called with no <code>base</code>,
7630280405Srpaulo<code>tonumber</code> tries to convert its argument to a number.
7631280405SrpauloIf the argument is already a number or
7632280405Srpauloa string convertible to a number,
7633280405Srpaulothen <code>tonumber</code> returns this number;
7634280405Srpaulootherwise, it returns <b>nil</b>.
7635280405Srpaulo
7636280405Srpaulo
7637280405Srpaulo<p>
7638280405SrpauloThe conversion of strings can result in integers or floats,
7639280405Srpauloaccording to the lexical conventions of Lua (see <a href="#3.1">&sect;3.1</a>).
7640280405Srpaulo(The string may have leading and trailing spaces and a sign.)
7641280405Srpaulo
7642280405Srpaulo
7643280405Srpaulo<p>
7644280405SrpauloWhen called with <code>base</code>,
7645280405Srpaulothen <code>e</code> must be a string to be interpreted as
7646280405Srpauloan integer numeral in that base.
7647280405SrpauloThe base may be any integer between 2 and 36, inclusive.
7648280405SrpauloIn bases above&nbsp;10, the letter '<code>A</code>' (in either upper or lower case)
7649280405Srpaulorepresents&nbsp;10, '<code>B</code>' represents&nbsp;11, and so forth,
7650280405Srpaulowith '<code>Z</code>' representing 35.
7651280405SrpauloIf the string <code>e</code> is not a valid numeral in the given base,
7652280405Srpaulothe function returns <b>nil</b>.
7653280405Srpaulo
7654280405Srpaulo
7655280405Srpaulo
7656280405Srpaulo
7657280405Srpaulo<p>
7658280405Srpaulo<hr><h3><a name="pdf-tostring"><code>tostring (v)</code></a></h3>
7659280405SrpauloReceives a value of any type and
7660280405Srpauloconverts it to a string in a human-readable format.
7661280405Srpaulo(For complete control of how numbers are converted,
7662280405Srpaulouse <a href="#pdf-string.format"><code>string.format</code></a>.)
7663280405Srpaulo
7664280405Srpaulo
7665280405Srpaulo<p>
7666326344SimpIf the metatable of <code>v</code> has a <code>__tostring</code> field,
7667280405Srpaulothen <code>tostring</code> calls the corresponding value
7668280405Srpaulowith <code>v</code> as argument,
7669280405Srpauloand uses the result of the call as its result.
7670280405Srpaulo
7671280405Srpaulo
7672280405Srpaulo
7673280405Srpaulo
7674280405Srpaulo<p>
7675280405Srpaulo<hr><h3><a name="pdf-type"><code>type (v)</code></a></h3>
7676280405SrpauloReturns the type of its only argument, coded as a string.
7677280405SrpauloThe possible results of this function are
7678280405Srpaulo"<code>nil</code>" (a string, not the value <b>nil</b>),
7679280405Srpaulo"<code>number</code>",
7680280405Srpaulo"<code>string</code>",
7681280405Srpaulo"<code>boolean</code>",
7682280405Srpaulo"<code>table</code>",
7683280405Srpaulo"<code>function</code>",
7684280405Srpaulo"<code>thread</code>",
7685280405Srpauloand "<code>userdata</code>".
7686280405Srpaulo
7687280405Srpaulo
7688280405Srpaulo
7689280405Srpaulo
7690280405Srpaulo<p>
7691280405Srpaulo<hr><h3><a name="pdf-_VERSION"><code>_VERSION</code></a></h3>
7692326344Simp
7693326344Simp
7694326344Simp<p>
7695280405SrpauloA global variable (not a function) that
7696326344Simpholds a string containing the running Lua version.
7697280405SrpauloThe current value of this variable is "<code>Lua 5.3</code>".
7698280405Srpaulo
7699280405Srpaulo
7700280405Srpaulo
7701280405Srpaulo
7702280405Srpaulo<p>
7703280405Srpaulo<hr><h3><a name="pdf-xpcall"><code>xpcall (f, msgh [, arg1, &middot;&middot;&middot;])</code></a></h3>
7704280405Srpaulo
7705280405Srpaulo
7706280405Srpaulo<p>
7707280405SrpauloThis function is similar to <a href="#pdf-pcall"><code>pcall</code></a>,
7708280405Srpauloexcept that it sets a new message handler <code>msgh</code>.
7709280405Srpaulo
7710280405Srpaulo
7711280405Srpaulo
7712280405Srpaulo
7713280405Srpaulo
7714280405Srpaulo
7715280405Srpaulo
7716280405Srpaulo<h2>6.2 &ndash; <a name="6.2">Coroutine Manipulation</a></h2>
7717280405Srpaulo
7718280405Srpaulo<p>
7719326344SimpThis library comprises the operations to manipulate coroutines,
7720326344Simpwhich come inside the table <a name="pdf-coroutine"><code>coroutine</code></a>.
7721280405SrpauloSee <a href="#2.6">&sect;2.6</a> for a general description of coroutines.
7722280405Srpaulo
7723280405Srpaulo
7724280405Srpaulo<p>
7725280405Srpaulo<hr><h3><a name="pdf-coroutine.create"><code>coroutine.create (f)</code></a></h3>
7726280405Srpaulo
7727280405Srpaulo
7728280405Srpaulo<p>
7729280405SrpauloCreates a new coroutine, with body <code>f</code>.
7730326344Simp<code>f</code> must be a function.
7731280405SrpauloReturns this new coroutine,
7732280405Srpauloan object with type <code>"thread"</code>.
7733280405Srpaulo
7734280405Srpaulo
7735280405Srpaulo
7736280405Srpaulo
7737280405Srpaulo<p>
7738280405Srpaulo<hr><h3><a name="pdf-coroutine.isyieldable"><code>coroutine.isyieldable ()</code></a></h3>
7739280405Srpaulo
7740280405Srpaulo
7741280405Srpaulo<p>
7742280405SrpauloReturns true when the running coroutine can yield.
7743280405Srpaulo
7744280405Srpaulo
7745280405Srpaulo<p>
7746280405SrpauloA running coroutine is yieldable if it is not the main thread and
7747326344Simpit is not inside a non-yieldable C&nbsp;function.
7748280405Srpaulo
7749280405Srpaulo
7750280405Srpaulo
7751280405Srpaulo
7752280405Srpaulo<p>
7753280405Srpaulo<hr><h3><a name="pdf-coroutine.resume"><code>coroutine.resume (co [, val1, &middot;&middot;&middot;])</code></a></h3>
7754280405Srpaulo
7755280405Srpaulo
7756280405Srpaulo<p>
7757280405SrpauloStarts or continues the execution of coroutine <code>co</code>.
7758280405SrpauloThe first time you resume a coroutine,
7759280405Srpauloit starts running its body.
7760280405SrpauloThe values <code>val1</code>, ... are passed
7761280405Srpauloas the arguments to the body function.
7762280405SrpauloIf the coroutine has yielded,
7763280405Srpaulo<code>resume</code> restarts it;
7764280405Srpaulothe values <code>val1</code>, ... are passed
7765280405Srpauloas the results from the yield.
7766280405Srpaulo
7767280405Srpaulo
7768280405Srpaulo<p>
7769280405SrpauloIf the coroutine runs without any errors,
7770280405Srpaulo<code>resume</code> returns <b>true</b> plus any values passed to <code>yield</code>
7771280405Srpaulo(when the coroutine yields) or any values returned by the body function
7772280405Srpaulo(when the coroutine terminates).
7773280405SrpauloIf there is any error,
7774280405Srpaulo<code>resume</code> returns <b>false</b> plus the error message.
7775280405Srpaulo
7776280405Srpaulo
7777280405Srpaulo
7778280405Srpaulo
7779280405Srpaulo<p>
7780280405Srpaulo<hr><h3><a name="pdf-coroutine.running"><code>coroutine.running ()</code></a></h3>
7781280405Srpaulo
7782280405Srpaulo
7783280405Srpaulo<p>
7784280405SrpauloReturns the running coroutine plus a boolean,
7785280405Srpaulotrue when the running coroutine is the main one.
7786280405Srpaulo
7787280405Srpaulo
7788280405Srpaulo
7789280405Srpaulo
7790280405Srpaulo<p>
7791280405Srpaulo<hr><h3><a name="pdf-coroutine.status"><code>coroutine.status (co)</code></a></h3>
7792280405Srpaulo
7793280405Srpaulo
7794280405Srpaulo<p>
7795280405SrpauloReturns the status of coroutine <code>co</code>, as a string:
7796280405Srpaulo<code>"running"</code>,
7797280405Srpauloif the coroutine is running (that is, it called <code>status</code>);
7798280405Srpaulo<code>"suspended"</code>, if the coroutine is suspended in a call to <code>yield</code>,
7799280405Srpauloor if it has not started running yet;
7800280405Srpaulo<code>"normal"</code> if the coroutine is active but not running
7801280405Srpaulo(that is, it has resumed another coroutine);
7802280405Srpauloand <code>"dead"</code> if the coroutine has finished its body function,
7803280405Srpauloor if it has stopped with an error.
7804280405Srpaulo
7805280405Srpaulo
7806280405Srpaulo
7807280405Srpaulo
7808280405Srpaulo<p>
7809280405Srpaulo<hr><h3><a name="pdf-coroutine.wrap"><code>coroutine.wrap (f)</code></a></h3>
7810280405Srpaulo
7811280405Srpaulo
7812280405Srpaulo<p>
7813280405SrpauloCreates a new coroutine, with body <code>f</code>.
7814326344Simp<code>f</code> must be a function.
7815280405SrpauloReturns a function that resumes the coroutine each time it is called.
7816280405SrpauloAny arguments passed to the function behave as the
7817280405Srpauloextra arguments to <code>resume</code>.
7818280405SrpauloReturns the same values returned by <code>resume</code>,
7819280405Srpauloexcept the first boolean.
7820280405SrpauloIn case of error, propagates the error.
7821280405Srpaulo
7822280405Srpaulo
7823280405Srpaulo
7824280405Srpaulo
7825280405Srpaulo<p>
7826280405Srpaulo<hr><h3><a name="pdf-coroutine.yield"><code>coroutine.yield (&middot;&middot;&middot;)</code></a></h3>
7827280405Srpaulo
7828280405Srpaulo
7829280405Srpaulo<p>
7830280405SrpauloSuspends the execution of the calling coroutine.
7831280405SrpauloAny arguments to <code>yield</code> are passed as extra results to <code>resume</code>.
7832280405Srpaulo
7833280405Srpaulo
7834280405Srpaulo
7835280405Srpaulo
7836280405Srpaulo
7837280405Srpaulo
7838280405Srpaulo
7839280405Srpaulo<h2>6.3 &ndash; <a name="6.3">Modules</a></h2>
7840280405Srpaulo
7841280405Srpaulo<p>
7842280405SrpauloThe package library provides basic
7843280405Srpaulofacilities for loading modules in Lua.
7844280405SrpauloIt exports one function directly in the global environment:
7845280405Srpaulo<a href="#pdf-require"><code>require</code></a>.
7846280405SrpauloEverything else is exported in a table <a name="pdf-package"><code>package</code></a>.
7847280405Srpaulo
7848280405Srpaulo
7849280405Srpaulo<p>
7850280405Srpaulo<hr><h3><a name="pdf-require"><code>require (modname)</code></a></h3>
7851280405Srpaulo
7852280405Srpaulo
7853280405Srpaulo<p>
7854280405SrpauloLoads the given module.
7855280405SrpauloThe function starts by looking into the <a href="#pdf-package.loaded"><code>package.loaded</code></a> table
7856280405Srpauloto determine whether <code>modname</code> is already loaded.
7857280405SrpauloIf it is, then <code>require</code> returns the value stored
7858280405Srpauloat <code>package.loaded[modname]</code>.
7859280405SrpauloOtherwise, it tries to find a <em>loader</em> for the module.
7860280405Srpaulo
7861280405Srpaulo
7862280405Srpaulo<p>
7863280405SrpauloTo find a loader,
7864280405Srpaulo<code>require</code> is guided by the <a href="#pdf-package.searchers"><code>package.searchers</code></a> sequence.
7865280405SrpauloBy changing this sequence,
7866280405Srpaulowe can change how <code>require</code> looks for a module.
7867280405SrpauloThe following explanation is based on the default configuration
7868280405Srpaulofor <a href="#pdf-package.searchers"><code>package.searchers</code></a>.
7869280405Srpaulo
7870280405Srpaulo
7871280405Srpaulo<p>
7872280405SrpauloFirst <code>require</code> queries <code>package.preload[modname]</code>.
7873280405SrpauloIf it has a value,
7874280405Srpaulothis value (which must be a function) is the loader.
7875280405SrpauloOtherwise <code>require</code> searches for a Lua loader using the
7876280405Srpaulopath stored in <a href="#pdf-package.path"><code>package.path</code></a>.
7877280405SrpauloIf that also fails, it searches for a C&nbsp;loader using the
7878280405Srpaulopath stored in <a href="#pdf-package.cpath"><code>package.cpath</code></a>.
7879280405SrpauloIf that also fails,
7880280405Srpauloit tries an <em>all-in-one</em> loader (see <a href="#pdf-package.searchers"><code>package.searchers</code></a>).
7881280405Srpaulo
7882280405Srpaulo
7883280405Srpaulo<p>
7884280405SrpauloOnce a loader is found,
7885280405Srpaulo<code>require</code> calls the loader with two arguments:
7886280405Srpaulo<code>modname</code> and an extra value dependent on how it got the loader.
7887280405Srpaulo(If the loader came from a file,
7888280405Srpaulothis extra value is the file name.)
7889280405SrpauloIf the loader returns any non-nil value,
7890280405Srpaulo<code>require</code> assigns the returned value to <code>package.loaded[modname]</code>.
7891280405SrpauloIf the loader does not return a non-nil value and
7892280405Srpaulohas not assigned any value to <code>package.loaded[modname]</code>,
7893280405Srpaulothen <code>require</code> assigns <b>true</b> to this entry.
7894280405SrpauloIn any case, <code>require</code> returns the
7895280405Srpaulofinal value of <code>package.loaded[modname]</code>.
7896280405Srpaulo
7897280405Srpaulo
7898280405Srpaulo<p>
7899280405SrpauloIf there is any error loading or running the module,
7900280405Srpauloor if it cannot find any loader for the module,
7901280405Srpaulothen <code>require</code> raises an error.
7902280405Srpaulo
7903280405Srpaulo
7904280405Srpaulo
7905280405Srpaulo
7906280405Srpaulo<p>
7907280405Srpaulo<hr><h3><a name="pdf-package.config"><code>package.config</code></a></h3>
7908280405Srpaulo
7909280405Srpaulo
7910280405Srpaulo<p>
7911280405SrpauloA string describing some compile-time configurations for packages.
7912280405SrpauloThis string is a sequence of lines:
7913280405Srpaulo
7914280405Srpaulo<ul>
7915280405Srpaulo
7916280405Srpaulo<li>The first line is the directory separator string.
7917280405SrpauloDefault is '<code>\</code>' for Windows and '<code>/</code>' for all other systems.</li>
7918280405Srpaulo
7919280405Srpaulo<li>The second line is the character that separates templates in a path.
7920280405SrpauloDefault is '<code>;</code>'.</li>
7921280405Srpaulo
7922280405Srpaulo<li>The third line is the string that marks the
7923280405Srpaulosubstitution points in a template.
7924280405SrpauloDefault is '<code>?</code>'.</li>
7925280405Srpaulo
7926280405Srpaulo<li>The fourth line is a string that, in a path in Windows,
7927280405Srpaulois replaced by the executable's directory.
7928280405SrpauloDefault is '<code>!</code>'.</li>
7929280405Srpaulo
7930280405Srpaulo<li>The fifth line is a mark to ignore all text after it
7931280405Srpaulowhen building the <code>luaopen_</code> function name.
7932280405SrpauloDefault is '<code>-</code>'.</li>
7933280405Srpaulo
7934280405Srpaulo</ul>
7935280405Srpaulo
7936280405Srpaulo
7937280405Srpaulo
7938280405Srpaulo<p>
7939280405Srpaulo<hr><h3><a name="pdf-package.cpath"><code>package.cpath</code></a></h3>
7940280405Srpaulo
7941280405Srpaulo
7942280405Srpaulo<p>
7943280405SrpauloThe path used by <a href="#pdf-require"><code>require</code></a> to search for a C&nbsp;loader.
7944280405Srpaulo
7945280405Srpaulo
7946280405Srpaulo<p>
7947280405SrpauloLua initializes the C&nbsp;path <a href="#pdf-package.cpath"><code>package.cpath</code></a> in the same way
7948280405Srpauloit initializes the Lua path <a href="#pdf-package.path"><code>package.path</code></a>,
7949326344Simpusing the environment variable <a name="pdf-LUA_CPATH_5_3"><code>LUA_CPATH_5_3</code></a>,
7950326344Simpor the environment variable <a name="pdf-LUA_CPATH"><code>LUA_CPATH</code></a>,
7951280405Srpauloor a default path defined in <code>luaconf.h</code>.
7952280405Srpaulo
7953280405Srpaulo
7954280405Srpaulo
7955280405Srpaulo
7956280405Srpaulo<p>
7957280405Srpaulo<hr><h3><a name="pdf-package.loaded"><code>package.loaded</code></a></h3>
7958280405Srpaulo
7959280405Srpaulo
7960280405Srpaulo<p>
7961280405SrpauloA table used by <a href="#pdf-require"><code>require</code></a> to control which
7962280405Srpaulomodules are already loaded.
7963280405SrpauloWhen you require a module <code>modname</code> and
7964280405Srpaulo<code>package.loaded[modname]</code> is not false,
7965280405Srpaulo<a href="#pdf-require"><code>require</code></a> simply returns the value stored there.
7966280405Srpaulo
7967280405Srpaulo
7968280405Srpaulo<p>
7969280405SrpauloThis variable is only a reference to the real table;
7970280405Srpauloassignments to this variable do not change the
7971280405Srpaulotable used by <a href="#pdf-require"><code>require</code></a>.
7972280405Srpaulo
7973280405Srpaulo
7974280405Srpaulo
7975280405Srpaulo
7976280405Srpaulo<p>
7977280405Srpaulo<hr><h3><a name="pdf-package.loadlib"><code>package.loadlib (libname, funcname)</code></a></h3>
7978280405Srpaulo
7979280405Srpaulo
7980280405Srpaulo<p>
7981280405SrpauloDynamically links the host program with the C&nbsp;library <code>libname</code>.
7982280405Srpaulo
7983280405Srpaulo
7984280405Srpaulo<p>
7985280405SrpauloIf <code>funcname</code> is "<code>*</code>",
7986280405Srpaulothen it only links with the library,
7987280405Srpaulomaking the symbols exported by the library
7988280405Srpauloavailable to other dynamically linked libraries.
7989280405SrpauloOtherwise,
7990280405Srpauloit looks for a function <code>funcname</code> inside the library
7991280405Srpauloand returns this function as a C&nbsp;function.
7992280405SrpauloSo, <code>funcname</code> must follow the <a href="#lua_CFunction"><code>lua_CFunction</code></a> prototype
7993280405Srpaulo(see <a href="#lua_CFunction"><code>lua_CFunction</code></a>).
7994280405Srpaulo
7995280405Srpaulo
7996280405Srpaulo<p>
7997280405SrpauloThis is a low-level function.
7998280405SrpauloIt completely bypasses the package and module system.
7999280405SrpauloUnlike <a href="#pdf-require"><code>require</code></a>,
8000280405Srpauloit does not perform any path searching and
8001280405Srpaulodoes not automatically adds extensions.
8002280405Srpaulo<code>libname</code> must be the complete file name of the C&nbsp;library,
8003280405Srpauloincluding if necessary a path and an extension.
8004280405Srpaulo<code>funcname</code> must be the exact name exported by the C&nbsp;library
8005280405Srpaulo(which may depend on the C&nbsp;compiler and linker used).
8006280405Srpaulo
8007280405Srpaulo
8008280405Srpaulo<p>
8009280405SrpauloThis function is not supported by Standard&nbsp;C.
8010280405SrpauloAs such, it is only available on some platforms
8011280405Srpaulo(Windows, Linux, Mac OS X, Solaris, BSD,
8012280405Srpauloplus other Unix systems that support the <code>dlfcn</code> standard).
8013280405Srpaulo
8014280405Srpaulo
8015280405Srpaulo
8016280405Srpaulo
8017280405Srpaulo<p>
8018280405Srpaulo<hr><h3><a name="pdf-package.path"><code>package.path</code></a></h3>
8019280405Srpaulo
8020280405Srpaulo
8021280405Srpaulo<p>
8022280405SrpauloThe path used by <a href="#pdf-require"><code>require</code></a> to search for a Lua loader.
8023280405Srpaulo
8024280405Srpaulo
8025280405Srpaulo<p>
8026280405SrpauloAt start-up, Lua initializes this variable with
8027280405Srpaulothe value of the environment variable <a name="pdf-LUA_PATH_5_3"><code>LUA_PATH_5_3</code></a> or
8028280405Srpaulothe environment variable <a name="pdf-LUA_PATH"><code>LUA_PATH</code></a> or
8029280405Srpaulowith a default path defined in <code>luaconf.h</code>,
8030280405Srpauloif those environment variables are not defined.
8031280405SrpauloAny "<code>;;</code>" in the value of the environment variable
8032280405Srpaulois replaced by the default path.
8033280405Srpaulo
8034280405Srpaulo
8035280405Srpaulo
8036280405Srpaulo
8037280405Srpaulo<p>
8038280405Srpaulo<hr><h3><a name="pdf-package.preload"><code>package.preload</code></a></h3>
8039280405Srpaulo
8040280405Srpaulo
8041280405Srpaulo<p>
8042280405SrpauloA table to store loaders for specific modules
8043280405Srpaulo(see <a href="#pdf-require"><code>require</code></a>).
8044280405Srpaulo
8045280405Srpaulo
8046280405Srpaulo<p>
8047280405SrpauloThis variable is only a reference to the real table;
8048280405Srpauloassignments to this variable do not change the
8049280405Srpaulotable used by <a href="#pdf-require"><code>require</code></a>.
8050280405Srpaulo
8051280405Srpaulo
8052280405Srpaulo
8053280405Srpaulo
8054280405Srpaulo<p>
8055280405Srpaulo<hr><h3><a name="pdf-package.searchers"><code>package.searchers</code></a></h3>
8056280405Srpaulo
8057280405Srpaulo
8058280405Srpaulo<p>
8059280405SrpauloA table used by <a href="#pdf-require"><code>require</code></a> to control how to load modules.
8060280405Srpaulo
8061280405Srpaulo
8062280405Srpaulo<p>
8063280405SrpauloEach entry in this table is a <em>searcher function</em>.
8064280405SrpauloWhen looking for a module,
8065280405Srpaulo<a href="#pdf-require"><code>require</code></a> calls each of these searchers in ascending order,
8066280405Srpaulowith the module name (the argument given to <a href="#pdf-require"><code>require</code></a>) as its
8067280405Srpaulosole parameter.
8068280405SrpauloThe function can return another function (the module <em>loader</em>)
8069280405Srpauloplus an extra value that will be passed to that loader,
8070280405Srpauloor a string explaining why it did not find that module
8071280405Srpaulo(or <b>nil</b> if it has nothing to say).
8072280405Srpaulo
8073280405Srpaulo
8074280405Srpaulo<p>
8075280405SrpauloLua initializes this table with four searcher functions.
8076280405Srpaulo
8077280405Srpaulo
8078280405Srpaulo<p>
8079280405SrpauloThe first searcher simply looks for a loader in the
8080280405Srpaulo<a href="#pdf-package.preload"><code>package.preload</code></a> table.
8081280405Srpaulo
8082280405Srpaulo
8083280405Srpaulo<p>
8084280405SrpauloThe second searcher looks for a loader as a Lua library,
8085280405Srpaulousing the path stored at <a href="#pdf-package.path"><code>package.path</code></a>.
8086280405SrpauloThe search is done as described in function <a href="#pdf-package.searchpath"><code>package.searchpath</code></a>.
8087280405Srpaulo
8088280405Srpaulo
8089280405Srpaulo<p>
8090280405SrpauloThe third searcher looks for a loader as a C&nbsp;library,
8091280405Srpaulousing the path given by the variable <a href="#pdf-package.cpath"><code>package.cpath</code></a>.
8092280405SrpauloAgain,
8093280405Srpaulothe search is done as described in function <a href="#pdf-package.searchpath"><code>package.searchpath</code></a>.
8094280405SrpauloFor instance,
8095280405Srpauloif the C&nbsp;path is the string
8096280405Srpaulo
8097280405Srpaulo<pre>
8098280405Srpaulo     "./?.so;./?.dll;/usr/local/?/init.so"
8099280405Srpaulo</pre><p>
8100280405Srpaulothe searcher for module <code>foo</code>
8101280405Srpaulowill try to open the files <code>./foo.so</code>, <code>./foo.dll</code>,
8102280405Srpauloand <code>/usr/local/foo/init.so</code>, in that order.
8103280405SrpauloOnce it finds a C&nbsp;library,
8104280405Srpaulothis searcher first uses a dynamic link facility to link the
8105280405Srpauloapplication with the library.
8106280405SrpauloThen it tries to find a C&nbsp;function inside the library to
8107280405Srpaulobe used as the loader.
8108280405SrpauloThe name of this C&nbsp;function is the string "<code>luaopen_</code>"
8109280405Srpauloconcatenated with a copy of the module name where each dot
8110280405Srpaulois replaced by an underscore.
8111280405SrpauloMoreover, if the module name has a hyphen,
8112280405Srpauloits suffix after (and including) the first hyphen is removed.
8113280405SrpauloFor instance, if the module name is <code>a.b.c-v2.1</code>,
8114280405Srpaulothe function name will be <code>luaopen_a_b_c</code>.
8115280405Srpaulo
8116280405Srpaulo
8117280405Srpaulo<p>
8118280405SrpauloThe fourth searcher tries an <em>all-in-one loader</em>.
8119280405SrpauloIt searches the C&nbsp;path for a library for
8120280405Srpaulothe root name of the given module.
8121280405SrpauloFor instance, when requiring <code>a.b.c</code>,
8122280405Srpauloit will search for a C&nbsp;library for <code>a</code>.
8123280405SrpauloIf found, it looks into it for an open function for
8124280405Srpaulothe submodule;
8125280405Srpauloin our example, that would be <code>luaopen_a_b_c</code>.
8126280405SrpauloWith this facility, a package can pack several C&nbsp;submodules
8127280405Srpaulointo one single library,
8128280405Srpaulowith each submodule keeping its original open function.
8129280405Srpaulo
8130280405Srpaulo
8131280405Srpaulo<p>
8132280405SrpauloAll searchers except the first one (preload) return as the extra value
8133280405Srpaulothe file name where the module was found,
8134280405Srpauloas returned by <a href="#pdf-package.searchpath"><code>package.searchpath</code></a>.
8135280405SrpauloThe first searcher returns no extra value.
8136280405Srpaulo
8137280405Srpaulo
8138280405Srpaulo
8139280405Srpaulo
8140280405Srpaulo<p>
8141280405Srpaulo<hr><h3><a name="pdf-package.searchpath"><code>package.searchpath (name, path [, sep [, rep]])</code></a></h3>
8142280405Srpaulo
8143280405Srpaulo
8144280405Srpaulo<p>
8145280405SrpauloSearches for the given <code>name</code> in the given <code>path</code>.
8146280405Srpaulo
8147280405Srpaulo
8148280405Srpaulo<p>
8149280405SrpauloA path is a string containing a sequence of
8150280405Srpaulo<em>templates</em> separated by semicolons.
8151280405SrpauloFor each template,
8152280405Srpaulothe function replaces each interrogation mark (if any)
8153280405Srpauloin the template with a copy of <code>name</code>
8154280405Srpaulowherein all occurrences of <code>sep</code>
8155280405Srpaulo(a dot, by default)
8156280405Srpaulowere replaced by <code>rep</code>
8157280405Srpaulo(the system's directory separator, by default),
8158280405Srpauloand then tries to open the resulting file name.
8159280405Srpaulo
8160280405Srpaulo
8161280405Srpaulo<p>
8162280405SrpauloFor instance, if the path is the string
8163280405Srpaulo
8164280405Srpaulo<pre>
8165280405Srpaulo     "./?.lua;./?.lc;/usr/local/?/init.lua"
8166280405Srpaulo</pre><p>
8167280405Srpaulothe search for the name <code>foo.a</code>
8168280405Srpaulowill try to open the files
8169280405Srpaulo<code>./foo/a.lua</code>, <code>./foo/a.lc</code>, and
8170280405Srpaulo<code>/usr/local/foo/a/init.lua</code>, in that order.
8171280405Srpaulo
8172280405Srpaulo
8173280405Srpaulo<p>
8174280405SrpauloReturns the resulting name of the first file that it can
8175280405Srpauloopen in read mode (after closing the file),
8176280405Srpauloor <b>nil</b> plus an error message if none succeeds.
8177280405Srpaulo(This error message lists all file names it tried to open.)
8178280405Srpaulo
8179280405Srpaulo
8180280405Srpaulo
8181280405Srpaulo
8182280405Srpaulo
8183280405Srpaulo
8184280405Srpaulo
8185280405Srpaulo<h2>6.4 &ndash; <a name="6.4">String Manipulation</a></h2>
8186280405Srpaulo
8187280405Srpaulo<p>
8188280405SrpauloThis library provides generic functions for string manipulation,
8189280405Srpaulosuch as finding and extracting substrings, and pattern matching.
8190280405SrpauloWhen indexing a string in Lua, the first character is at position&nbsp;1
8191280405Srpaulo(not at&nbsp;0, as in C).
8192280405SrpauloIndices are allowed to be negative and are interpreted as indexing backwards,
8193280405Srpaulofrom the end of the string.
8194280405SrpauloThus, the last character is at position -1, and so on.
8195280405Srpaulo
8196280405Srpaulo
8197280405Srpaulo<p>
8198280405SrpauloThe string library provides all its functions inside the table
8199280405Srpaulo<a name="pdf-string"><code>string</code></a>.
8200280405SrpauloIt also sets a metatable for strings
8201280405Srpaulowhere the <code>__index</code> field points to the <code>string</code> table.
8202280405SrpauloTherefore, you can use the string functions in object-oriented style.
8203280405SrpauloFor instance, <code>string.byte(s,i)</code>
8204280405Srpaulocan be written as <code>s:byte(i)</code>.
8205280405Srpaulo
8206280405Srpaulo
8207280405Srpaulo<p>
8208280405SrpauloThe string library assumes one-byte character encodings.
8209280405Srpaulo
8210280405Srpaulo
8211280405Srpaulo<p>
8212280405Srpaulo<hr><h3><a name="pdf-string.byte"><code>string.byte (s [, i [, j]])</code></a></h3>
8213326344SimpReturns the internal numeric codes of the characters <code>s[i]</code>,
8214280405Srpaulo<code>s[i+1]</code>, ..., <code>s[j]</code>.
8215280405SrpauloThe default value for <code>i</code> is&nbsp;1;
8216280405Srpaulothe default value for <code>j</code> is&nbsp;<code>i</code>.
8217280405SrpauloThese indices are corrected
8218280405Srpaulofollowing the same rules of function <a href="#pdf-string.sub"><code>string.sub</code></a>.
8219280405Srpaulo
8220280405Srpaulo
8221280405Srpaulo<p>
8222326344SimpNumeric codes are not necessarily portable across platforms.
8223280405Srpaulo
8224280405Srpaulo
8225280405Srpaulo
8226280405Srpaulo
8227280405Srpaulo<p>
8228280405Srpaulo<hr><h3><a name="pdf-string.char"><code>string.char (&middot;&middot;&middot;)</code></a></h3>
8229280405SrpauloReceives zero or more integers.
8230280405SrpauloReturns a string with length equal to the number of arguments,
8231326344Simpin which each character has the internal numeric code equal
8232280405Srpauloto its corresponding argument.
8233280405Srpaulo
8234280405Srpaulo
8235280405Srpaulo<p>
8236326344SimpNumeric codes are not necessarily portable across platforms.
8237280405Srpaulo
8238280405Srpaulo
8239280405Srpaulo
8240280405Srpaulo
8241280405Srpaulo<p>
8242280405Srpaulo<hr><h3><a name="pdf-string.dump"><code>string.dump (function [, strip])</code></a></h3>
8243280405Srpaulo
8244280405Srpaulo
8245280405Srpaulo<p>
8246280405SrpauloReturns a string containing a binary representation
8247280405Srpaulo(a <em>binary chunk</em>)
8248280405Srpauloof the given function,
8249280405Srpauloso that a later <a href="#pdf-load"><code>load</code></a> on this string returns
8250280405Srpauloa copy of the function (but with new upvalues).
8251280405SrpauloIf <code>strip</code> is a true value,
8252326344Simpthe binary representation may not include all debug information
8253326344Simpabout the function,
8254326344Simpto save space.
8255280405Srpaulo
8256280405Srpaulo
8257280405Srpaulo<p>
8258280405SrpauloFunctions with upvalues have only their number of upvalues saved.
8259280405SrpauloWhen (re)loaded,
8260280405Srpaulothose upvalues receive fresh instances containing <b>nil</b>.
8261280405Srpaulo(You can use the debug library to serialize
8262280405Srpauloand reload the upvalues of a function
8263280405Srpauloin a way adequate to your needs.)
8264280405Srpaulo
8265280405Srpaulo
8266280405Srpaulo
8267280405Srpaulo
8268280405Srpaulo<p>
8269280405Srpaulo<hr><h3><a name="pdf-string.find"><code>string.find (s, pattern [, init [, plain]])</code></a></h3>
8270280405Srpaulo
8271280405Srpaulo
8272280405Srpaulo<p>
8273280405SrpauloLooks for the first match of
8274280405Srpaulo<code>pattern</code> (see <a href="#6.4.1">&sect;6.4.1</a>) in the string <code>s</code>.
8275280405SrpauloIf it finds a match, then <code>find</code> returns the indices of&nbsp;<code>s</code>
8276280405Srpaulowhere this occurrence starts and ends;
8277280405Srpaulootherwise, it returns <b>nil</b>.
8278326344SimpA third, optional numeric argument <code>init</code> specifies
8279280405Srpaulowhere to start the search;
8280280405Srpauloits default value is&nbsp;1 and can be negative.
8281280405SrpauloA value of <b>true</b> as a fourth, optional argument <code>plain</code>
8282280405Srpauloturns off the pattern matching facilities,
8283280405Srpauloso the function does a plain "find substring" operation,
8284280405Srpaulowith no characters in <code>pattern</code> being considered magic.
8285280405SrpauloNote that if <code>plain</code> is given, then <code>init</code> must be given as well.
8286280405Srpaulo
8287280405Srpaulo
8288280405Srpaulo<p>
8289280405SrpauloIf the pattern has captures,
8290280405Srpaulothen in a successful match
8291280405Srpaulothe captured values are also returned,
8292280405Srpauloafter the two indices.
8293280405Srpaulo
8294280405Srpaulo
8295280405Srpaulo
8296280405Srpaulo
8297280405Srpaulo<p>
8298280405Srpaulo<hr><h3><a name="pdf-string.format"><code>string.format (formatstring, &middot;&middot;&middot;)</code></a></h3>
8299280405Srpaulo
8300280405Srpaulo
8301280405Srpaulo<p>
8302280405SrpauloReturns a formatted version of its variable number of arguments
8303280405Srpaulofollowing the description given in its first argument (which must be a string).
8304280405SrpauloThe format string follows the same rules as the ISO&nbsp;C function <code>sprintf</code>.
8305280405SrpauloThe only differences are that the options/modifiers
8306280405Srpaulo<code>*</code>, <code>h</code>, <code>L</code>, <code>l</code>, <code>n</code>,
8307280405Srpauloand <code>p</code> are not supported
8308280405Srpauloand that there is an extra option, <code>q</code>.
8309326344Simp
8310326344Simp
8311326344Simp<p>
8312280405SrpauloThe <code>q</code> option formats a string between double quotes,
8313280405Srpaulousing escape sequences when necessary to ensure that
8314280405Srpauloit can safely be read back by the Lua interpreter.
8315280405SrpauloFor instance, the call
8316280405Srpaulo
8317280405Srpaulo<pre>
8318280405Srpaulo     string.format('%q', 'a string with "quotes" and \n new line')
8319280405Srpaulo</pre><p>
8320280405Srpaulomay produce the string:
8321280405Srpaulo
8322280405Srpaulo<pre>
8323280405Srpaulo     "a string with \"quotes\" and \
8324280405Srpaulo      new line"
8325280405Srpaulo</pre>
8326280405Srpaulo
8327280405Srpaulo<p>
8328280405SrpauloOptions
8329326344Simp<code>A</code>, <code>a</code>, <code>E</code>, <code>e</code>, <code>f</code>,
8330280405Srpaulo<code>G</code>, and <code>g</code> all expect a number as argument.
8331280405SrpauloOptions <code>c</code>, <code>d</code>,
8332280405Srpaulo<code>i</code>, <code>o</code>, <code>u</code>, <code>X</code>, and <code>x</code>
8333280405Srpauloexpect an integer.
8334326344SimpWhen Lua is compiled with a C89 compiler,
8335326344Simpoptions <code>A</code> and <code>a</code> (hexadecimal floats)
8336326344Simpdo not support any modifier (flags, width, length).
8337326344Simp
8338326344Simp
8339326344Simp<p>
8340326344SimpOption <code>s</code> expects a string;
8341326344Simpif its argument is not a string,
8342280405Srpauloit is converted to one following the same rules of <a href="#pdf-tostring"><code>tostring</code></a>.
8343326344SimpIf the option has any modifier (flags, width, length),
8344326344Simpthe string argument should not contain embedded zeros.
8345280405Srpaulo
8346280405Srpaulo
8347280405Srpaulo
8348280405Srpaulo
8349280405Srpaulo<p>
8350280405Srpaulo<hr><h3><a name="pdf-string.gmatch"><code>string.gmatch (s, pattern)</code></a></h3>
8351280405SrpauloReturns an iterator function that,
8352280405Srpauloeach time it is called,
8353280405Srpauloreturns the next captures from <code>pattern</code> (see <a href="#6.4.1">&sect;6.4.1</a>)
8354280405Srpauloover the string <code>s</code>.
8355280405SrpauloIf <code>pattern</code> specifies no captures,
8356280405Srpaulothen the whole match is produced in each call.
8357280405Srpaulo
8358280405Srpaulo
8359280405Srpaulo<p>
8360280405SrpauloAs an example, the following loop
8361280405Srpaulowill iterate over all the words from string <code>s</code>,
8362280405Srpauloprinting one per line:
8363280405Srpaulo
8364280405Srpaulo<pre>
8365280405Srpaulo     s = "hello world from Lua"
8366280405Srpaulo     for w in string.gmatch(s, "%a+") do
8367280405Srpaulo       print(w)
8368280405Srpaulo     end
8369280405Srpaulo</pre><p>
8370280405SrpauloThe next example collects all pairs <code>key=value</code> from the
8371280405Srpaulogiven string into a table:
8372280405Srpaulo
8373280405Srpaulo<pre>
8374280405Srpaulo     t = {}
8375280405Srpaulo     s = "from=world, to=Lua"
8376280405Srpaulo     for k, v in string.gmatch(s, "(%w+)=(%w+)") do
8377280405Srpaulo       t[k] = v
8378280405Srpaulo     end
8379280405Srpaulo</pre>
8380280405Srpaulo
8381280405Srpaulo<p>
8382280405SrpauloFor this function, a caret '<code>^</code>' at the start of a pattern does not
8383280405Srpaulowork as an anchor, as this would prevent the iteration.
8384280405Srpaulo
8385280405Srpaulo
8386280405Srpaulo
8387280405Srpaulo
8388280405Srpaulo<p>
8389280405Srpaulo<hr><h3><a name="pdf-string.gsub"><code>string.gsub (s, pattern, repl [, n])</code></a></h3>
8390280405SrpauloReturns a copy of <code>s</code>
8391280405Srpauloin which all (or the first <code>n</code>, if given)
8392280405Srpaulooccurrences of the <code>pattern</code> (see <a href="#6.4.1">&sect;6.4.1</a>) have been
8393280405Srpauloreplaced by a replacement string specified by <code>repl</code>,
8394280405Srpaulowhich can be a string, a table, or a function.
8395280405Srpaulo<code>gsub</code> also returns, as its second value,
8396280405Srpaulothe total number of matches that occurred.
8397280405SrpauloThe name <code>gsub</code> comes from <em>Global SUBstitution</em>.
8398280405Srpaulo
8399280405Srpaulo
8400280405Srpaulo<p>
8401280405SrpauloIf <code>repl</code> is a string, then its value is used for replacement.
8402280405SrpauloThe character&nbsp;<code>%</code> works as an escape character:
8403280405Srpauloany sequence in <code>repl</code> of the form <code>%<em>d</em></code>,
8404280405Srpaulowith <em>d</em> between 1 and 9,
8405280405Srpaulostands for the value of the <em>d</em>-th captured substring.
8406280405SrpauloThe sequence <code>%0</code> stands for the whole match.
8407280405SrpauloThe sequence <code>%%</code> stands for a single&nbsp;<code>%</code>.
8408280405Srpaulo
8409280405Srpaulo
8410280405Srpaulo<p>
8411280405SrpauloIf <code>repl</code> is a table, then the table is queried for every match,
8412280405Srpaulousing the first capture as the key.
8413280405Srpaulo
8414280405Srpaulo
8415280405Srpaulo<p>
8416280405SrpauloIf <code>repl</code> is a function, then this function is called every time a
8417280405Srpaulomatch occurs, with all captured substrings passed as arguments,
8418280405Srpauloin order.
8419280405Srpaulo
8420280405Srpaulo
8421280405Srpaulo<p>
8422280405SrpauloIn any case,
8423280405Srpauloif the pattern specifies no captures,
8424280405Srpaulothen it behaves as if the whole pattern was inside a capture.
8425280405Srpaulo
8426280405Srpaulo
8427280405Srpaulo<p>
8428280405SrpauloIf the value returned by the table query or by the function call
8429280405Srpaulois a string or a number,
8430280405Srpaulothen it is used as the replacement string;
8431280405Srpaulootherwise, if it is <b>false</b> or <b>nil</b>,
8432280405Srpaulothen there is no replacement
8433280405Srpaulo(that is, the original match is kept in the string).
8434280405Srpaulo
8435280405Srpaulo
8436280405Srpaulo<p>
8437280405SrpauloHere are some examples:
8438280405Srpaulo
8439280405Srpaulo<pre>
8440280405Srpaulo     x = string.gsub("hello world", "(%w+)", "%1 %1")
8441280405Srpaulo     --&gt; x="hello hello world world"
8442280405Srpaulo     
8443280405Srpaulo     x = string.gsub("hello world", "%w+", "%0 %0", 1)
8444280405Srpaulo     --&gt; x="hello hello world"
8445280405Srpaulo     
8446280405Srpaulo     x = string.gsub("hello world from Lua", "(%w+)%s*(%w+)", "%2 %1")
8447280405Srpaulo     --&gt; x="world hello Lua from"
8448280405Srpaulo     
8449280405Srpaulo     x = string.gsub("home = $HOME, user = $USER", "%$(%w+)", os.getenv)
8450280405Srpaulo     --&gt; x="home = /home/roberto, user = roberto"
8451280405Srpaulo     
8452280405Srpaulo     x = string.gsub("4+5 = $return 4+5$", "%$(.-)%$", function (s)
8453280405Srpaulo           return load(s)()
8454280405Srpaulo         end)
8455280405Srpaulo     --&gt; x="4+5 = 9"
8456280405Srpaulo     
8457280405Srpaulo     local t = {name="lua", version="5.3"}
8458280405Srpaulo     x = string.gsub("$name-$version.tar.gz", "%$(%w+)", t)
8459280405Srpaulo     --&gt; x="lua-5.3.tar.gz"
8460280405Srpaulo</pre>
8461280405Srpaulo
8462280405Srpaulo
8463280405Srpaulo
8464280405Srpaulo<p>
8465280405Srpaulo<hr><h3><a name="pdf-string.len"><code>string.len (s)</code></a></h3>
8466280405SrpauloReceives a string and returns its length.
8467280405SrpauloThe empty string <code>""</code> has length 0.
8468280405SrpauloEmbedded zeros are counted,
8469280405Srpauloso <code>"a\000bc\000"</code> has length 5.
8470280405Srpaulo
8471280405Srpaulo
8472280405Srpaulo
8473280405Srpaulo
8474280405Srpaulo<p>
8475280405Srpaulo<hr><h3><a name="pdf-string.lower"><code>string.lower (s)</code></a></h3>
8476280405SrpauloReceives a string and returns a copy of this string with all
8477280405Srpaulouppercase letters changed to lowercase.
8478280405SrpauloAll other characters are left unchanged.
8479280405SrpauloThe definition of what an uppercase letter is depends on the current locale.
8480280405Srpaulo
8481280405Srpaulo
8482280405Srpaulo
8483280405Srpaulo
8484280405Srpaulo<p>
8485280405Srpaulo<hr><h3><a name="pdf-string.match"><code>string.match (s, pattern [, init])</code></a></h3>
8486280405SrpauloLooks for the first <em>match</em> of
8487280405Srpaulo<code>pattern</code> (see <a href="#6.4.1">&sect;6.4.1</a>) in the string <code>s</code>.
8488280405SrpauloIf it finds one, then <code>match</code> returns
8489280405Srpaulothe captures from the pattern;
8490280405Srpaulootherwise it returns <b>nil</b>.
8491280405SrpauloIf <code>pattern</code> specifies no captures,
8492280405Srpaulothen the whole match is returned.
8493326344SimpA third, optional numeric argument <code>init</code> specifies
8494280405Srpaulowhere to start the search;
8495280405Srpauloits default value is&nbsp;1 and can be negative.
8496280405Srpaulo
8497280405Srpaulo
8498280405Srpaulo
8499280405Srpaulo
8500280405Srpaulo<p>
8501280405Srpaulo<hr><h3><a name="pdf-string.pack"><code>string.pack (fmt, v1, v2, &middot;&middot;&middot;)</code></a></h3>
8502280405Srpaulo
8503280405Srpaulo
8504280405Srpaulo<p>
8505280405SrpauloReturns a binary string containing the values <code>v1</code>, <code>v2</code>, etc.
8506280405Srpaulopacked (that is, serialized in binary form)
8507326344Simpaccording to the format string <code>fmt</code> (see <a href="#6.4.2">&sect;6.4.2</a>).
8508280405Srpaulo
8509280405Srpaulo
8510280405Srpaulo
8511280405Srpaulo
8512280405Srpaulo<p>
8513280405Srpaulo<hr><h3><a name="pdf-string.packsize"><code>string.packsize (fmt)</code></a></h3>
8514280405Srpaulo
8515280405Srpaulo
8516280405Srpaulo<p>
8517280405SrpauloReturns the size of a string resulting from <a href="#pdf-string.pack"><code>string.pack</code></a>
8518280405Srpaulowith the given format.
8519280405SrpauloThe format string cannot have the variable-length options
8520280405Srpaulo'<code>s</code>' or '<code>z</code>' (see <a href="#6.4.2">&sect;6.4.2</a>).
8521280405Srpaulo
8522280405Srpaulo
8523280405Srpaulo
8524280405Srpaulo
8525280405Srpaulo<p>
8526280405Srpaulo<hr><h3><a name="pdf-string.rep"><code>string.rep (s, n [, sep])</code></a></h3>
8527280405SrpauloReturns a string that is the concatenation of <code>n</code> copies of
8528280405Srpaulothe string <code>s</code> separated by the string <code>sep</code>.
8529280405SrpauloThe default value for <code>sep</code> is the empty string
8530280405Srpaulo(that is, no separator).
8531280405SrpauloReturns the empty string if <code>n</code> is not positive.
8532280405Srpaulo
8533280405Srpaulo
8534326344Simp<p>
8535326344Simp(Note that it is very easy to exhaust the memory of your machine
8536326344Simpwith a single call to this function.)
8537280405Srpaulo
8538280405Srpaulo
8539326344Simp
8540326344Simp
8541280405Srpaulo<p>
8542280405Srpaulo<hr><h3><a name="pdf-string.reverse"><code>string.reverse (s)</code></a></h3>
8543280405SrpauloReturns a string that is the string <code>s</code> reversed.
8544280405Srpaulo
8545280405Srpaulo
8546280405Srpaulo
8547280405Srpaulo
8548280405Srpaulo<p>
8549280405Srpaulo<hr><h3><a name="pdf-string.sub"><code>string.sub (s, i [, j])</code></a></h3>
8550280405SrpauloReturns the substring of <code>s</code> that
8551280405Srpaulostarts at <code>i</code>  and continues until <code>j</code>;
8552280405Srpaulo<code>i</code> and <code>j</code> can be negative.
8553280405SrpauloIf <code>j</code> is absent, then it is assumed to be equal to -1
8554280405Srpaulo(which is the same as the string length).
8555280405SrpauloIn particular,
8556280405Srpaulothe call <code>string.sub(s,1,j)</code> returns a prefix of <code>s</code>
8557280405Srpaulowith length <code>j</code>,
8558326344Simpand <code>string.sub(s, -i)</code> (for a positive <code>i</code>)
8559326344Simpreturns a suffix of <code>s</code>
8560280405Srpaulowith length <code>i</code>.
8561280405Srpaulo
8562280405Srpaulo
8563280405Srpaulo<p>
8564280405SrpauloIf, after the translation of negative indices,
8565280405Srpaulo<code>i</code> is less than 1,
8566280405Srpauloit is corrected to 1.
8567280405SrpauloIf <code>j</code> is greater than the string length,
8568280405Srpauloit is corrected to that length.
8569280405SrpauloIf, after these corrections,
8570280405Srpaulo<code>i</code> is greater than <code>j</code>,
8571280405Srpaulothe function returns the empty string.
8572280405Srpaulo
8573280405Srpaulo
8574280405Srpaulo
8575280405Srpaulo
8576280405Srpaulo<p>
8577280405Srpaulo<hr><h3><a name="pdf-string.unpack"><code>string.unpack (fmt, s [, pos])</code></a></h3>
8578280405Srpaulo
8579280405Srpaulo
8580280405Srpaulo<p>
8581280405SrpauloReturns the values packed in string <code>s</code> (see <a href="#pdf-string.pack"><code>string.pack</code></a>)
8582280405Srpauloaccording to the format string <code>fmt</code> (see <a href="#6.4.2">&sect;6.4.2</a>).
8583280405SrpauloAn optional <code>pos</code> marks where
8584280405Srpauloto start reading in <code>s</code> (default is 1).
8585280405SrpauloAfter the read values,
8586280405Srpaulothis function also returns the index of the first unread byte in <code>s</code>.
8587280405Srpaulo
8588280405Srpaulo
8589280405Srpaulo
8590280405Srpaulo
8591280405Srpaulo<p>
8592280405Srpaulo<hr><h3><a name="pdf-string.upper"><code>string.upper (s)</code></a></h3>
8593280405SrpauloReceives a string and returns a copy of this string with all
8594280405Srpaulolowercase letters changed to uppercase.
8595280405SrpauloAll other characters are left unchanged.
8596280405SrpauloThe definition of what a lowercase letter is depends on the current locale.
8597280405Srpaulo
8598280405Srpaulo
8599280405Srpaulo
8600280405Srpaulo
8601280405Srpaulo
8602280405Srpaulo<h3>6.4.1 &ndash; <a name="6.4.1">Patterns</a></h3>
8603280405Srpaulo
8604280405Srpaulo<p>
8605280405SrpauloPatterns in Lua are described by regular strings,
8606280405Srpaulowhich are interpreted as patterns by the pattern-matching functions
8607280405Srpaulo<a href="#pdf-string.find"><code>string.find</code></a>,
8608280405Srpaulo<a href="#pdf-string.gmatch"><code>string.gmatch</code></a>,
8609280405Srpaulo<a href="#pdf-string.gsub"><code>string.gsub</code></a>,
8610280405Srpauloand <a href="#pdf-string.match"><code>string.match</code></a>.
8611280405SrpauloThis section describes the syntax and the meaning
8612280405Srpaulo(that is, what they match) of these strings.
8613280405Srpaulo
8614280405Srpaulo
8615280405Srpaulo
8616280405Srpaulo<h4>Character Class:</h4><p>
8617280405SrpauloA <em>character class</em> is used to represent a set of characters.
8618280405SrpauloThe following combinations are allowed in describing a character class:
8619280405Srpaulo
8620280405Srpaulo<ul>
8621280405Srpaulo
8622280405Srpaulo<li><b><em>x</em>: </b>
8623280405Srpaulo(where <em>x</em> is not one of the <em>magic characters</em>
8624280405Srpaulo<code>^$()%.[]*+-?</code>)
8625280405Srpaulorepresents the character <em>x</em> itself.
8626280405Srpaulo</li>
8627280405Srpaulo
8628280405Srpaulo<li><b><code>.</code>: </b> (a dot) represents all characters.</li>
8629280405Srpaulo
8630280405Srpaulo<li><b><code>%a</code>: </b> represents all letters.</li>
8631280405Srpaulo
8632280405Srpaulo<li><b><code>%c</code>: </b> represents all control characters.</li>
8633280405Srpaulo
8634280405Srpaulo<li><b><code>%d</code>: </b> represents all digits.</li>
8635280405Srpaulo
8636280405Srpaulo<li><b><code>%g</code>: </b> represents all printable characters except space.</li>
8637280405Srpaulo
8638280405Srpaulo<li><b><code>%l</code>: </b> represents all lowercase letters.</li>
8639280405Srpaulo
8640280405Srpaulo<li><b><code>%p</code>: </b> represents all punctuation characters.</li>
8641280405Srpaulo
8642280405Srpaulo<li><b><code>%s</code>: </b> represents all space characters.</li>
8643280405Srpaulo
8644280405Srpaulo<li><b><code>%u</code>: </b> represents all uppercase letters.</li>
8645280405Srpaulo
8646280405Srpaulo<li><b><code>%w</code>: </b> represents all alphanumeric characters.</li>
8647280405Srpaulo
8648280405Srpaulo<li><b><code>%x</code>: </b> represents all hexadecimal digits.</li>
8649280405Srpaulo
8650280405Srpaulo<li><b><code>%<em>x</em></code>: </b> (where <em>x</em> is any non-alphanumeric character)
8651280405Srpaulorepresents the character <em>x</em>.
8652280405SrpauloThis is the standard way to escape the magic characters.
8653280405SrpauloAny non-alphanumeric character
8654326344Simp(including all punctuation characters, even the non-magical)
8655280405Srpaulocan be preceded by a '<code>%</code>'
8656280405Srpaulowhen used to represent itself in a pattern.
8657280405Srpaulo</li>
8658280405Srpaulo
8659280405Srpaulo<li><b><code>[<em>set</em>]</code>: </b>
8660280405Srpaulorepresents the class which is the union of all
8661280405Srpaulocharacters in <em>set</em>.
8662280405SrpauloA range of characters can be specified by
8663280405Srpauloseparating the end characters of the range,
8664280405Srpauloin ascending order, with a '<code>-</code>'.
8665280405SrpauloAll classes <code>%</code><em>x</em> described above can also be used as
8666280405Srpaulocomponents in <em>set</em>.
8667280405SrpauloAll other characters in <em>set</em> represent themselves.
8668280405SrpauloFor example, <code>[%w_]</code> (or <code>[_%w]</code>)
8669280405Srpaulorepresents all alphanumeric characters plus the underscore,
8670280405Srpaulo<code>[0-7]</code> represents the octal digits,
8671280405Srpauloand <code>[0-7%l%-]</code> represents the octal digits plus
8672280405Srpaulothe lowercase letters plus the '<code>-</code>' character.
8673280405Srpaulo
8674280405Srpaulo
8675280405Srpaulo<p>
8676326344SimpYou can put a closing square bracket in a set
8677326344Simpby positioning it as the first character in the set.
8678344220SkevansYou can put a hyphen in a set
8679326344Simpby positioning it as the first or the last character in the set.
8680326344Simp(You can also use an escape for both cases.)
8681326344Simp
8682326344Simp
8683326344Simp<p>
8684280405SrpauloThe interaction between ranges and classes is not defined.
8685280405SrpauloTherefore, patterns like <code>[%a-z]</code> or <code>[a-%%]</code>
8686280405Srpaulohave no meaning.
8687280405Srpaulo</li>
8688280405Srpaulo
8689280405Srpaulo<li><b><code>[^<em>set</em>]</code>: </b>
8690280405Srpaulorepresents the complement of <em>set</em>,
8691280405Srpaulowhere <em>set</em> is interpreted as above.
8692280405Srpaulo</li>
8693280405Srpaulo
8694280405Srpaulo</ul><p>
8695280405SrpauloFor all classes represented by single letters (<code>%a</code>, <code>%c</code>, etc.),
8696280405Srpaulothe corresponding uppercase letter represents the complement of the class.
8697280405SrpauloFor instance, <code>%S</code> represents all non-space characters.
8698280405Srpaulo
8699280405Srpaulo
8700280405Srpaulo<p>
8701280405SrpauloThe definitions of letter, space, and other character groups
8702280405Srpaulodepend on the current locale.
8703280405SrpauloIn particular, the class <code>[a-z]</code> may not be equivalent to <code>%l</code>.
8704280405Srpaulo
8705280405Srpaulo
8706280405Srpaulo
8707280405Srpaulo
8708280405Srpaulo
8709280405Srpaulo<h4>Pattern Item:</h4><p>
8710280405SrpauloA <em>pattern item</em> can be
8711280405Srpaulo
8712280405Srpaulo<ul>
8713280405Srpaulo
8714280405Srpaulo<li>
8715280405Srpauloa single character class,
8716280405Srpaulowhich matches any single character in the class;
8717280405Srpaulo</li>
8718280405Srpaulo
8719280405Srpaulo<li>
8720280405Srpauloa single character class followed by '<code>*</code>',
8721280405Srpaulowhich matches zero or more repetitions of characters in the class.
8722280405SrpauloThese repetition items will always match the longest possible sequence;
8723280405Srpaulo</li>
8724280405Srpaulo
8725280405Srpaulo<li>
8726280405Srpauloa single character class followed by '<code>+</code>',
8727280405Srpaulowhich matches one or more repetitions of characters in the class.
8728280405SrpauloThese repetition items will always match the longest possible sequence;
8729280405Srpaulo</li>
8730280405Srpaulo
8731280405Srpaulo<li>
8732280405Srpauloa single character class followed by '<code>-</code>',
8733280405Srpaulowhich also matches zero or more repetitions of characters in the class.
8734280405SrpauloUnlike '<code>*</code>',
8735280405Srpaulothese repetition items will always match the shortest possible sequence;
8736280405Srpaulo</li>
8737280405Srpaulo
8738280405Srpaulo<li>
8739280405Srpauloa single character class followed by '<code>?</code>',
8740280405Srpaulowhich matches zero or one occurrence of a character in the class.
8741280405SrpauloIt always matches one occurrence if possible;
8742280405Srpaulo</li>
8743280405Srpaulo
8744280405Srpaulo<li>
8745280405Srpaulo<code>%<em>n</em></code>, for <em>n</em> between 1 and 9;
8746280405Srpaulosuch item matches a substring equal to the <em>n</em>-th captured string
8747280405Srpaulo(see below);
8748280405Srpaulo</li>
8749280405Srpaulo
8750280405Srpaulo<li>
8751280405Srpaulo<code>%b<em>xy</em></code>, where <em>x</em> and <em>y</em> are two distinct characters;
8752280405Srpaulosuch item matches strings that start with&nbsp;<em>x</em>, end with&nbsp;<em>y</em>,
8753280405Srpauloand where the <em>x</em> and <em>y</em> are <em>balanced</em>.
8754280405SrpauloThis means that, if one reads the string from left to right,
8755280405Srpaulocounting <em>+1</em> for an <em>x</em> and <em>-1</em> for a <em>y</em>,
8756280405Srpaulothe ending <em>y</em> is the first <em>y</em> where the count reaches 0.
8757280405SrpauloFor instance, the item <code>%b()</code> matches expressions with
8758280405Srpaulobalanced parentheses.
8759280405Srpaulo</li>
8760280405Srpaulo
8761280405Srpaulo<li>
8762280405Srpaulo<code>%f[<em>set</em>]</code>, a <em>frontier pattern</em>;
8763280405Srpaulosuch item matches an empty string at any position such that
8764280405Srpaulothe next character belongs to <em>set</em>
8765280405Srpauloand the previous character does not belong to <em>set</em>.
8766280405SrpauloThe set <em>set</em> is interpreted as previously described.
8767280405SrpauloThe beginning and the end of the subject are handled as if
8768280405Srpaulothey were the character '<code>\0</code>'.
8769280405Srpaulo</li>
8770280405Srpaulo
8771280405Srpaulo</ul>
8772280405Srpaulo
8773280405Srpaulo
8774280405Srpaulo
8775280405Srpaulo
8776280405Srpaulo<h4>Pattern:</h4><p>
8777280405SrpauloA <em>pattern</em> is a sequence of pattern items.
8778280405SrpauloA caret '<code>^</code>' at the beginning of a pattern anchors the match at the
8779280405Srpaulobeginning of the subject string.
8780280405SrpauloA '<code>$</code>' at the end of a pattern anchors the match at the
8781280405Srpauloend of the subject string.
8782280405SrpauloAt other positions,
8783280405Srpaulo'<code>^</code>' and '<code>$</code>' have no special meaning and represent themselves.
8784280405Srpaulo
8785280405Srpaulo
8786280405Srpaulo
8787280405Srpaulo
8788280405Srpaulo
8789280405Srpaulo<h4>Captures:</h4><p>
8790280405SrpauloA pattern can contain sub-patterns enclosed in parentheses;
8791280405Srpaulothey describe <em>captures</em>.
8792280405SrpauloWhen a match succeeds, the substrings of the subject string
8793280405Srpaulothat match captures are stored (<em>captured</em>) for future use.
8794280405SrpauloCaptures are numbered according to their left parentheses.
8795280405SrpauloFor instance, in the pattern <code>"(a*(.)%w(%s*))"</code>,
8796280405Srpaulothe part of the string matching <code>"a*(.)%w(%s*)"</code> is
8797280405Srpaulostored as the first capture (and therefore has number&nbsp;1);
8798280405Srpaulothe character matching "<code>.</code>" is captured with number&nbsp;2,
8799280405Srpauloand the part matching "<code>%s*</code>" has number&nbsp;3.
8800280405Srpaulo
8801280405Srpaulo
8802280405Srpaulo<p>
8803280405SrpauloAs a special case, the empty capture <code>()</code> captures
8804280405Srpaulothe current string position (a number).
8805280405SrpauloFor instance, if we apply the pattern <code>"()aa()"</code> on the
8806280405Srpaulostring <code>"flaaap"</code>, there will be two captures: 3&nbsp;and&nbsp;5.
8807280405Srpaulo
8808280405Srpaulo
8809280405Srpaulo
8810280405Srpaulo
8811280405Srpaulo
8812280405Srpaulo
8813280405Srpaulo
8814280405Srpaulo<h3>6.4.2 &ndash; <a name="6.4.2">Format Strings for Pack and Unpack</a></h3>
8815280405Srpaulo
8816280405Srpaulo<p>
8817280405SrpauloThe first argument to <a href="#pdf-string.pack"><code>string.pack</code></a>,
8818280405Srpaulo<a href="#pdf-string.packsize"><code>string.packsize</code></a>, and <a href="#pdf-string.unpack"><code>string.unpack</code></a>
8819280405Srpaulois a format string,
8820280405Srpaulowhich describes the layout of the structure being created or read.
8821280405Srpaulo
8822280405Srpaulo
8823280405Srpaulo<p>
8824280405SrpauloA format string is a sequence of conversion options.
8825280405SrpauloThe conversion options are as follows:
8826280405Srpaulo
8827280405Srpaulo<ul>
8828280405Srpaulo<li><b><code>&lt;</code>: </b>sets little endian</li>
8829280405Srpaulo<li><b><code>&gt;</code>: </b>sets big endian</li>
8830280405Srpaulo<li><b><code>=</code>: </b>sets native endian</li>
8831280405Srpaulo<li><b><code>![<em>n</em>]</code>: </b>sets maximum alignment to <code>n</code>
8832280405Srpaulo(default is native alignment)</li>
8833280405Srpaulo<li><b><code>b</code>: </b>a signed byte (<code>char</code>)</li>
8834280405Srpaulo<li><b><code>B</code>: </b>an unsigned byte (<code>char</code>)</li>
8835280405Srpaulo<li><b><code>h</code>: </b>a signed <code>short</code> (native size)</li>
8836280405Srpaulo<li><b><code>H</code>: </b>an unsigned <code>short</code> (native size)</li>
8837280405Srpaulo<li><b><code>l</code>: </b>a signed <code>long</code> (native size)</li>
8838280405Srpaulo<li><b><code>L</code>: </b>an unsigned <code>long</code> (native size)</li>
8839280405Srpaulo<li><b><code>j</code>: </b>a <code>lua_Integer</code></li>
8840280405Srpaulo<li><b><code>J</code>: </b>a <code>lua_Unsigned</code></li>
8841280405Srpaulo<li><b><code>T</code>: </b>a <code>size_t</code> (native size)</li>
8842280405Srpaulo<li><b><code>i[<em>n</em>]</code>: </b>a signed <code>int</code> with <code>n</code> bytes
8843280405Srpaulo(default is native size)</li>
8844280405Srpaulo<li><b><code>I[<em>n</em>]</code>: </b>an unsigned <code>int</code> with <code>n</code> bytes
8845280405Srpaulo(default is native size)</li>
8846280405Srpaulo<li><b><code>f</code>: </b>a <code>float</code> (native size)</li>
8847280405Srpaulo<li><b><code>d</code>: </b>a <code>double</code> (native size)</li>
8848280405Srpaulo<li><b><code>n</code>: </b>a <code>lua_Number</code></li>
8849280405Srpaulo<li><b><code>c<em>n</em></code>: </b>a fixed-sized string with <code>n</code> bytes</li>
8850280405Srpaulo<li><b><code>z</code>: </b>a zero-terminated string</li>
8851280405Srpaulo<li><b><code>s[<em>n</em>]</code>: </b>a string preceded by its length
8852280405Srpaulocoded as an unsigned integer with <code>n</code> bytes
8853280405Srpaulo(default is a <code>size_t</code>)</li>
8854280405Srpaulo<li><b><code>x</code>: </b>one byte of padding</li>
8855280405Srpaulo<li><b><code>X<em>op</em></code>: </b>an empty item that aligns
8856280405Srpauloaccording to option <code>op</code>
8857280405Srpaulo(which is otherwise ignored)</li>
8858280405Srpaulo<li><b>'<code> </code>': </b>(empty space) ignored</li>
8859280405Srpaulo</ul><p>
8860280405Srpaulo(A "<code>[<em>n</em>]</code>" means an optional integral numeral.)
8861280405SrpauloExcept for padding, spaces, and configurations
8862280405Srpaulo(options "<code>xX &lt;=&gt;!</code>"),
8863280405Srpauloeach option corresponds to an argument (in <a href="#pdf-string.pack"><code>string.pack</code></a>)
8864280405Srpauloor a result (in <a href="#pdf-string.unpack"><code>string.unpack</code></a>).
8865280405Srpaulo
8866280405Srpaulo
8867280405Srpaulo<p>
8868280405SrpauloFor 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>",
8869280405Srpaulo<code>n</code> can be any integer between 1 and 16.
8870280405SrpauloAll integral options check overflows;
8871280405Srpaulo<a href="#pdf-string.pack"><code>string.pack</code></a> checks whether the given value fits in the given size;
8872280405Srpaulo<a href="#pdf-string.unpack"><code>string.unpack</code></a> checks whether the read value fits in a Lua integer.
8873280405Srpaulo
8874280405Srpaulo
8875280405Srpaulo<p>
8876280405SrpauloAny format string starts as if prefixed by "<code>!1=</code>",
8877280405Srpaulothat is,
8878280405Srpaulowith maximum alignment of 1 (no alignment)
8879280405Srpauloand native endianness.
8880280405Srpaulo
8881280405Srpaulo
8882280405Srpaulo<p>
8883280405SrpauloAlignment works as follows:
8884280405SrpauloFor each option,
8885280405Srpaulothe format gets extra padding until the data starts
8886280405Srpauloat an offset that is a multiple of the minimum between the
8887280405Srpaulooption size and the maximum alignment;
8888280405Srpaulothis minimum must be a power of 2.
8889280405SrpauloOptions "<code>c</code>" and "<code>z</code>" are not aligned;
8890280405Srpaulooption "<code>s</code>" follows the alignment of its starting integer.
8891280405Srpaulo
8892280405Srpaulo
8893280405Srpaulo<p>
8894280405SrpauloAll padding is filled with zeros by <a href="#pdf-string.pack"><code>string.pack</code></a>
8895280405Srpaulo(and ignored by <a href="#pdf-string.unpack"><code>string.unpack</code></a>).
8896280405Srpaulo
8897280405Srpaulo
8898280405Srpaulo
8899280405Srpaulo
8900280405Srpaulo
8901280405Srpaulo
8902280405Srpaulo
8903280405Srpaulo<h2>6.5 &ndash; <a name="6.5">UTF-8 Support</a></h2>
8904280405Srpaulo
8905280405Srpaulo<p>
8906280405SrpauloThis library provides basic support for UTF-8 encoding.
8907280405SrpauloIt provides all its functions inside the table <a name="pdf-utf8"><code>utf8</code></a>.
8908280405SrpauloThis library does not provide any support for Unicode other
8909280405Srpaulothan the handling of the encoding.
8910280405SrpauloAny operation that needs the meaning of a character,
8911280405Srpaulosuch as character classification, is outside its scope.
8912280405Srpaulo
8913280405Srpaulo
8914280405Srpaulo<p>
8915280405SrpauloUnless stated otherwise,
8916280405Srpauloall functions that expect a byte position as a parameter
8917280405Srpauloassume that the given position is either the start of a byte sequence
8918280405Srpauloor one plus the length of the subject string.
8919280405SrpauloAs in the string library,
8920280405Srpaulonegative indices count from the end of the string.
8921280405Srpaulo
8922280405Srpaulo
8923280405Srpaulo<p>
8924280405Srpaulo<hr><h3><a name="pdf-utf8.char"><code>utf8.char (&middot;&middot;&middot;)</code></a></h3>
8925280405SrpauloReceives zero or more integers,
8926280405Srpauloconverts each one to its corresponding UTF-8 byte sequence
8927280405Srpauloand returns a string with the concatenation of all these sequences.
8928280405Srpaulo
8929280405Srpaulo
8930280405Srpaulo
8931280405Srpaulo
8932280405Srpaulo<p>
8933280405Srpaulo<hr><h3><a name="pdf-utf8.charpattern"><code>utf8.charpattern</code></a></h3>
8934280405SrpauloThe pattern (a string, not a function) "<code>[\0-\x7F\xC2-\xF4][\x80-\xBF]*</code>"
8935280405Srpaulo(see <a href="#6.4.1">&sect;6.4.1</a>),
8936280405Srpaulowhich matches exactly one UTF-8 byte sequence,
8937280405Srpauloassuming that the subject is a valid UTF-8 string.
8938280405Srpaulo
8939280405Srpaulo
8940280405Srpaulo
8941280405Srpaulo
8942280405Srpaulo<p>
8943280405Srpaulo<hr><h3><a name="pdf-utf8.codes"><code>utf8.codes (s)</code></a></h3>
8944280405Srpaulo
8945280405Srpaulo
8946280405Srpaulo<p>
8947280405SrpauloReturns values so that the construction
8948280405Srpaulo
8949280405Srpaulo<pre>
8950280405Srpaulo     for p, c in utf8.codes(s) do <em>body</em> end
8951280405Srpaulo</pre><p>
8952280405Srpaulowill iterate over all characters in string <code>s</code>,
8953280405Srpaulowith <code>p</code> being the position (in bytes) and <code>c</code> the code point
8954280405Srpauloof each character.
8955280405SrpauloIt raises an error if it meets any invalid byte sequence.
8956280405Srpaulo
8957280405Srpaulo
8958280405Srpaulo
8959280405Srpaulo
8960280405Srpaulo<p>
8961280405Srpaulo<hr><h3><a name="pdf-utf8.codepoint"><code>utf8.codepoint (s [, i [, j]])</code></a></h3>
8962280405SrpauloReturns the codepoints (as integers) from all characters in <code>s</code>
8963280405Srpaulothat start between byte position <code>i</code> and <code>j</code> (both included).
8964280405SrpauloThe default for <code>i</code> is 1 and for <code>j</code> is <code>i</code>.
8965280405SrpauloIt raises an error if it meets any invalid byte sequence.
8966280405Srpaulo
8967280405Srpaulo
8968280405Srpaulo
8969280405Srpaulo
8970280405Srpaulo<p>
8971280405Srpaulo<hr><h3><a name="pdf-utf8.len"><code>utf8.len (s [, i [, j]])</code></a></h3>
8972280405SrpauloReturns the number of UTF-8 characters in string <code>s</code>
8973280405Srpaulothat start between positions <code>i</code> and <code>j</code> (both inclusive).
8974280405SrpauloThe default for <code>i</code> is 1 and for <code>j</code> is -1.
8975280405SrpauloIf it finds any invalid byte sequence,
8976326344Simpreturns a false value plus the position of the first invalid byte.
8977280405Srpaulo
8978280405Srpaulo
8979280405Srpaulo
8980280405Srpaulo
8981280405Srpaulo<p>
8982280405Srpaulo<hr><h3><a name="pdf-utf8.offset"><code>utf8.offset (s, n [, i])</code></a></h3>
8983280405SrpauloReturns the position (in bytes) where the encoding of the
8984280405Srpaulo<code>n</code>-th character of <code>s</code>
8985280405Srpaulo(counting from position <code>i</code>) starts.
8986280405SrpauloA negative <code>n</code> gets characters before position <code>i</code>.
8987280405SrpauloThe default for <code>i</code> is 1 when <code>n</code> is non-negative
8988280405Srpauloand <code>#s + 1</code> otherwise,
8989280405Srpauloso that <code>utf8.offset(s, -n)</code> gets the offset of the
8990280405Srpaulo<code>n</code>-th character from the end of the string.
8991280405SrpauloIf the specified character is neither in the subject
8992280405Srpaulonor right after its end,
8993280405Srpaulothe function returns <b>nil</b>.
8994280405Srpaulo
8995280405Srpaulo
8996280405Srpaulo<p>
8997280405SrpauloAs a special case,
8998280405Srpaulowhen <code>n</code> is 0 the function returns the start of the encoding
8999280405Srpauloof the character that contains the <code>i</code>-th byte of <code>s</code>.
9000280405Srpaulo
9001280405Srpaulo
9002280405Srpaulo<p>
9003280405SrpauloThis function assumes that <code>s</code> is a valid UTF-8 string.
9004280405Srpaulo
9005280405Srpaulo
9006280405Srpaulo
9007280405Srpaulo
9008280405Srpaulo
9009280405Srpaulo
9010280405Srpaulo
9011280405Srpaulo<h2>6.6 &ndash; <a name="6.6">Table Manipulation</a></h2>
9012280405Srpaulo
9013280405Srpaulo<p>
9014280405SrpauloThis library provides generic functions for table manipulation.
9015280405SrpauloIt provides all its functions inside the table <a name="pdf-table"><code>table</code></a>.
9016280405Srpaulo
9017280405Srpaulo
9018280405Srpaulo<p>
9019280405SrpauloRemember that, whenever an operation needs the length of a table,
9020326344Simpall caveats about the length operator apply (see <a href="#3.4.7">&sect;3.4.7</a>).
9021280405SrpauloAll functions ignore non-numeric keys
9022280405Srpauloin the tables given as arguments.
9023280405Srpaulo
9024280405Srpaulo
9025280405Srpaulo<p>
9026280405Srpaulo<hr><h3><a name="pdf-table.concat"><code>table.concat (list [, sep [, i [, j]]])</code></a></h3>
9027280405Srpaulo
9028280405Srpaulo
9029280405Srpaulo<p>
9030280405SrpauloGiven a list where all elements are strings or numbers,
9031280405Srpauloreturns the string <code>list[i]..sep..list[i+1] &middot;&middot;&middot; sep..list[j]</code>.
9032280405SrpauloThe default value for <code>sep</code> is the empty string,
9033280405Srpaulothe default for <code>i</code> is 1,
9034280405Srpauloand the default for <code>j</code> is <code>#list</code>.
9035280405SrpauloIf <code>i</code> is greater than <code>j</code>, returns the empty string.
9036280405Srpaulo
9037280405Srpaulo
9038280405Srpaulo
9039280405Srpaulo
9040280405Srpaulo<p>
9041280405Srpaulo<hr><h3><a name="pdf-table.insert"><code>table.insert (list, [pos,] value)</code></a></h3>
9042280405Srpaulo
9043280405Srpaulo
9044280405Srpaulo<p>
9045280405SrpauloInserts element <code>value</code> at position <code>pos</code> in <code>list</code>,
9046280405Srpauloshifting up the elements
9047280405Srpaulo<code>list[pos], list[pos+1], &middot;&middot;&middot;, list[#list]</code>.
9048280405SrpauloThe default value for <code>pos</code> is <code>#list+1</code>,
9049280405Srpauloso that a call <code>table.insert(t,x)</code> inserts <code>x</code> at the end
9050280405Srpauloof list <code>t</code>.
9051280405Srpaulo
9052280405Srpaulo
9053280405Srpaulo
9054280405Srpaulo
9055280405Srpaulo<p>
9056280405Srpaulo<hr><h3><a name="pdf-table.move"><code>table.move (a1, f, e, t [,a2])</code></a></h3>
9057280405Srpaulo
9058280405Srpaulo
9059280405Srpaulo<p>
9060326344SimpMoves elements from table <code>a1</code> to table <code>a2</code>,
9061326344Simpperforming the equivalent to the following
9062280405Srpaulomultiple assignment:
9063280405Srpaulo<code>a2[t],&middot;&middot;&middot; = a1[f],&middot;&middot;&middot;,a1[e]</code>.
9064280405SrpauloThe default for <code>a2</code> is <code>a1</code>.
9065280405SrpauloThe destination range can overlap with the source range.
9066326344SimpThe number of elements to be moved must fit in a Lua integer.
9067280405Srpaulo
9068280405Srpaulo
9069326344Simp<p>
9070326344SimpReturns the destination table <code>a2</code>.
9071280405Srpaulo
9072280405Srpaulo
9073326344Simp
9074326344Simp
9075280405Srpaulo<p>
9076280405Srpaulo<hr><h3><a name="pdf-table.pack"><code>table.pack (&middot;&middot;&middot;)</code></a></h3>
9077280405Srpaulo
9078280405Srpaulo
9079280405Srpaulo<p>
9080344220SkevansReturns a new table with all arguments stored into keys 1, 2, etc.
9081344220Skevansand with a field "<code>n</code>" with the total number of arguments.
9082280405SrpauloNote that the resulting table may not be a sequence.
9083280405Srpaulo
9084280405Srpaulo
9085280405Srpaulo
9086280405Srpaulo
9087280405Srpaulo<p>
9088280405Srpaulo<hr><h3><a name="pdf-table.remove"><code>table.remove (list [, pos])</code></a></h3>
9089280405Srpaulo
9090280405Srpaulo
9091280405Srpaulo<p>
9092280405SrpauloRemoves from <code>list</code> the element at position <code>pos</code>,
9093280405Srpauloreturning the value of the removed element.
9094280405SrpauloWhen <code>pos</code> is an integer between 1 and <code>#list</code>,
9095280405Srpauloit shifts down the elements
9096280405Srpaulo<code>list[pos+1], list[pos+2], &middot;&middot;&middot;, list[#list]</code>
9097280405Srpauloand erases element <code>list[#list]</code>;
9098280405SrpauloThe index <code>pos</code> can also be 0 when <code>#list</code> is 0,
9099280405Srpauloor <code>#list + 1</code>;
9100280405Srpauloin those cases, the function erases the element <code>list[pos]</code>.
9101280405Srpaulo
9102280405Srpaulo
9103280405Srpaulo<p>
9104280405SrpauloThe default value for <code>pos</code> is <code>#list</code>,
9105280405Srpauloso that a call <code>table.remove(l)</code> removes the last element
9106280405Srpauloof list <code>l</code>.
9107280405Srpaulo
9108280405Srpaulo
9109280405Srpaulo
9110280405Srpaulo
9111280405Srpaulo<p>
9112280405Srpaulo<hr><h3><a name="pdf-table.sort"><code>table.sort (list [, comp])</code></a></h3>
9113280405Srpaulo
9114280405Srpaulo
9115280405Srpaulo<p>
9116280405SrpauloSorts list elements in a given order, <em>in-place</em>,
9117280405Srpaulofrom <code>list[1]</code> to <code>list[#list]</code>.
9118280405SrpauloIf <code>comp</code> is given,
9119280405Srpaulothen it must be a function that receives two list elements
9120280405Srpauloand returns true when the first element must come
9121280405Srpaulobefore the second in the final order
9122326344Simp(so that, after the sort,
9123326344Simp<code>i &lt; j</code> implies <code>not comp(list[j],list[i])</code>).
9124280405SrpauloIf <code>comp</code> is not given,
9125280405Srpaulothen the standard Lua operator <code>&lt;</code> is used instead.
9126280405Srpaulo
9127280405Srpaulo
9128280405Srpaulo<p>
9129326344SimpNote that the <code>comp</code> function must define
9130326344Simpa strict partial order over the elements in the list;
9131326344Simpthat is, it must be asymmetric and transitive.
9132326344SimpOtherwise, no valid sort may be possible.
9133326344Simp
9134326344Simp
9135326344Simp<p>
9136326344SimpThe sort algorithm is not stable:
9137326344Simpelements considered equal by the given order
9138280405Srpaulomay have their relative positions changed by the sort.
9139280405Srpaulo
9140280405Srpaulo
9141280405Srpaulo
9142280405Srpaulo
9143280405Srpaulo<p>
9144280405Srpaulo<hr><h3><a name="pdf-table.unpack"><code>table.unpack (list [, i [, j]])</code></a></h3>
9145280405Srpaulo
9146280405Srpaulo
9147280405Srpaulo<p>
9148280405SrpauloReturns the elements from the given list.
9149280405SrpauloThis function is equivalent to
9150280405Srpaulo
9151280405Srpaulo<pre>
9152280405Srpaulo     return list[i], list[i+1], &middot;&middot;&middot;, list[j]
9153280405Srpaulo</pre><p>
9154280405SrpauloBy default, <code>i</code> is&nbsp;1 and <code>j</code> is <code>#list</code>.
9155280405Srpaulo
9156280405Srpaulo
9157280405Srpaulo
9158280405Srpaulo
9159280405Srpaulo
9160280405Srpaulo
9161280405Srpaulo
9162280405Srpaulo<h2>6.7 &ndash; <a name="6.7">Mathematical Functions</a></h2>
9163280405Srpaulo
9164280405Srpaulo<p>
9165280405SrpauloThis library provides basic mathematical functions.
9166280405SrpauloIt provides all its functions and constants inside the table <a name="pdf-math"><code>math</code></a>.
9167280405SrpauloFunctions with the annotation "<code>integer/float</code>" give
9168280405Srpaulointeger results for integer arguments
9169280405Srpauloand float results for float (or mixed) arguments.
9170280405SrpauloRounding functions
9171280405Srpaulo(<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>)
9172280405Srpauloreturn an integer when the result fits in the range of an integer,
9173280405Srpauloor a float otherwise.
9174280405Srpaulo
9175280405Srpaulo
9176280405Srpaulo<p>
9177280405Srpaulo<hr><h3><a name="pdf-math.abs"><code>math.abs (x)</code></a></h3>
9178280405Srpaulo
9179280405Srpaulo
9180280405Srpaulo<p>
9181280405SrpauloReturns the absolute value of <code>x</code>. (integer/float)
9182280405Srpaulo
9183280405Srpaulo
9184280405Srpaulo
9185280405Srpaulo
9186280405Srpaulo<p>
9187280405Srpaulo<hr><h3><a name="pdf-math.acos"><code>math.acos (x)</code></a></h3>
9188280405Srpaulo
9189280405Srpaulo
9190280405Srpaulo<p>
9191280405SrpauloReturns the arc cosine of <code>x</code> (in radians).
9192280405Srpaulo
9193280405Srpaulo
9194280405Srpaulo
9195280405Srpaulo
9196280405Srpaulo<p>
9197280405Srpaulo<hr><h3><a name="pdf-math.asin"><code>math.asin (x)</code></a></h3>
9198280405Srpaulo
9199280405Srpaulo
9200280405Srpaulo<p>
9201280405SrpauloReturns the arc sine of <code>x</code> (in radians).
9202280405Srpaulo
9203280405Srpaulo
9204280405Srpaulo
9205280405Srpaulo
9206280405Srpaulo<p>
9207280405Srpaulo<hr><h3><a name="pdf-math.atan"><code>math.atan (y [, x])</code></a></h3>
9208280405Srpaulo
9209280405Srpaulo
9210280405Srpaulo<p>
9211280405Srpaulo
9212280405SrpauloReturns the arc tangent of <code>y/x</code> (in radians),
9213344220Skevansbut uses the signs of both arguments to find the
9214280405Srpauloquadrant of the result.
9215280405Srpaulo(It also handles correctly the case of <code>x</code> being zero.)
9216280405Srpaulo
9217280405Srpaulo
9218280405Srpaulo<p>
9219280405SrpauloThe default value for <code>x</code> is 1,
9220280405Srpauloso that the call <code>math.atan(y)</code>
9221280405Srpauloreturns the arc tangent of <code>y</code>.
9222280405Srpaulo
9223280405Srpaulo
9224280405Srpaulo
9225280405Srpaulo
9226280405Srpaulo<p>
9227280405Srpaulo<hr><h3><a name="pdf-math.ceil"><code>math.ceil (x)</code></a></h3>
9228280405Srpaulo
9229280405Srpaulo
9230280405Srpaulo<p>
9231280405SrpauloReturns the smallest integral value larger than or equal to <code>x</code>.
9232280405Srpaulo
9233280405Srpaulo
9234280405Srpaulo
9235280405Srpaulo
9236280405Srpaulo<p>
9237280405Srpaulo<hr><h3><a name="pdf-math.cos"><code>math.cos (x)</code></a></h3>
9238280405Srpaulo
9239280405Srpaulo
9240280405Srpaulo<p>
9241280405SrpauloReturns the cosine of <code>x</code> (assumed to be in radians).
9242280405Srpaulo
9243280405Srpaulo
9244280405Srpaulo
9245280405Srpaulo
9246280405Srpaulo<p>
9247280405Srpaulo<hr><h3><a name="pdf-math.deg"><code>math.deg (x)</code></a></h3>
9248280405Srpaulo
9249280405Srpaulo
9250280405Srpaulo<p>
9251280405SrpauloConverts the angle <code>x</code> from radians to degrees.
9252280405Srpaulo
9253280405Srpaulo
9254280405Srpaulo
9255280405Srpaulo
9256280405Srpaulo<p>
9257280405Srpaulo<hr><h3><a name="pdf-math.exp"><code>math.exp (x)</code></a></h3>
9258280405Srpaulo
9259280405Srpaulo
9260280405Srpaulo<p>
9261280405SrpauloReturns the value <em>e<sup>x</sup></em>
9262280405Srpaulo(where <code>e</code> is the base of natural logarithms).
9263280405Srpaulo
9264280405Srpaulo
9265280405Srpaulo
9266280405Srpaulo
9267280405Srpaulo<p>
9268280405Srpaulo<hr><h3><a name="pdf-math.floor"><code>math.floor (x)</code></a></h3>
9269280405Srpaulo
9270280405Srpaulo
9271280405Srpaulo<p>
9272280405SrpauloReturns the largest integral value smaller than or equal to <code>x</code>.
9273280405Srpaulo
9274280405Srpaulo
9275280405Srpaulo
9276280405Srpaulo
9277280405Srpaulo<p>
9278280405Srpaulo<hr><h3><a name="pdf-math.fmod"><code>math.fmod (x, y)</code></a></h3>
9279280405Srpaulo
9280280405Srpaulo
9281280405Srpaulo<p>
9282280405SrpauloReturns the remainder of the division of <code>x</code> by <code>y</code>
9283280405Srpaulothat rounds the quotient towards zero. (integer/float)
9284280405Srpaulo
9285280405Srpaulo
9286280405Srpaulo
9287280405Srpaulo
9288280405Srpaulo<p>
9289280405Srpaulo<hr><h3><a name="pdf-math.huge"><code>math.huge</code></a></h3>
9290280405Srpaulo
9291280405Srpaulo
9292280405Srpaulo<p>
9293280405SrpauloThe float value <code>HUGE_VAL</code>,
9294326344Simpa value larger than any other numeric value.
9295280405Srpaulo
9296280405Srpaulo
9297280405Srpaulo
9298280405Srpaulo
9299280405Srpaulo<p>
9300280405Srpaulo<hr><h3><a name="pdf-math.log"><code>math.log (x [, base])</code></a></h3>
9301280405Srpaulo
9302280405Srpaulo
9303280405Srpaulo<p>
9304280405SrpauloReturns the logarithm of <code>x</code> in the given base.
9305280405SrpauloThe default for <code>base</code> is <em>e</em>
9306280405Srpaulo(so that the function returns the natural logarithm of <code>x</code>).
9307280405Srpaulo
9308280405Srpaulo
9309280405Srpaulo
9310280405Srpaulo
9311280405Srpaulo<p>
9312280405Srpaulo<hr><h3><a name="pdf-math.max"><code>math.max (x, &middot;&middot;&middot;)</code></a></h3>
9313280405Srpaulo
9314280405Srpaulo
9315280405Srpaulo<p>
9316280405SrpauloReturns the argument with the maximum value,
9317280405Srpauloaccording to the Lua operator <code>&lt;</code>. (integer/float)
9318280405Srpaulo
9319280405Srpaulo
9320280405Srpaulo
9321280405Srpaulo
9322280405Srpaulo<p>
9323280405Srpaulo<hr><h3><a name="pdf-math.maxinteger"><code>math.maxinteger</code></a></h3>
9324280405SrpauloAn integer with the maximum value for an integer.
9325280405Srpaulo
9326280405Srpaulo
9327280405Srpaulo
9328280405Srpaulo
9329280405Srpaulo<p>
9330280405Srpaulo<hr><h3><a name="pdf-math.min"><code>math.min (x, &middot;&middot;&middot;)</code></a></h3>
9331280405Srpaulo
9332280405Srpaulo
9333280405Srpaulo<p>
9334280405SrpauloReturns the argument with the minimum value,
9335280405Srpauloaccording to the Lua operator <code>&lt;</code>. (integer/float)
9336280405Srpaulo
9337280405Srpaulo
9338280405Srpaulo
9339280405Srpaulo
9340280405Srpaulo<p>
9341280405Srpaulo<hr><h3><a name="pdf-math.mininteger"><code>math.mininteger</code></a></h3>
9342280405SrpauloAn integer with the minimum value for an integer.
9343280405Srpaulo
9344280405Srpaulo
9345280405Srpaulo
9346280405Srpaulo
9347280405Srpaulo<p>
9348280405Srpaulo<hr><h3><a name="pdf-math.modf"><code>math.modf (x)</code></a></h3>
9349280405Srpaulo
9350280405Srpaulo
9351280405Srpaulo<p>
9352280405SrpauloReturns the integral part of <code>x</code> and the fractional part of <code>x</code>.
9353280405SrpauloIts second result is always a float.
9354280405Srpaulo
9355280405Srpaulo
9356280405Srpaulo
9357280405Srpaulo
9358280405Srpaulo<p>
9359280405Srpaulo<hr><h3><a name="pdf-math.pi"><code>math.pi</code></a></h3>
9360280405Srpaulo
9361280405Srpaulo
9362280405Srpaulo<p>
9363280405SrpauloThe value of <em>&pi;</em>.
9364280405Srpaulo
9365280405Srpaulo
9366280405Srpaulo
9367280405Srpaulo
9368280405Srpaulo<p>
9369280405Srpaulo<hr><h3><a name="pdf-math.rad"><code>math.rad (x)</code></a></h3>
9370280405Srpaulo
9371280405Srpaulo
9372280405Srpaulo<p>
9373280405SrpauloConverts the angle <code>x</code> from degrees to radians.
9374280405Srpaulo
9375280405Srpaulo
9376280405Srpaulo
9377280405Srpaulo
9378280405Srpaulo<p>
9379280405Srpaulo<hr><h3><a name="pdf-math.random"><code>math.random ([m [, n]])</code></a></h3>
9380280405Srpaulo
9381280405Srpaulo
9382280405Srpaulo<p>
9383280405SrpauloWhen called without arguments,
9384280405Srpauloreturns a pseudo-random float with uniform distribution
9385280405Srpauloin the range  <em>[0,1)</em>.  
9386280405SrpauloWhen called with two integers <code>m</code> and <code>n</code>,
9387280405Srpaulo<code>math.random</code> returns a pseudo-random integer
9388280405Srpaulowith uniform distribution in the range <em>[m, n]</em>.
9389326344Simp(The value <em>n-m</em> cannot be negative and must fit in a Lua integer.)
9390280405SrpauloThe call <code>math.random(n)</code> is equivalent to <code>math.random(1,n)</code>.
9391280405Srpaulo
9392280405Srpaulo
9393280405Srpaulo<p>
9394280405SrpauloThis function is an interface to the underling
9395280405Srpaulopseudo-random generator function provided by C.
9396280405Srpaulo
9397280405Srpaulo
9398280405Srpaulo
9399280405Srpaulo
9400280405Srpaulo<p>
9401280405Srpaulo<hr><h3><a name="pdf-math.randomseed"><code>math.randomseed (x)</code></a></h3>
9402280405Srpaulo
9403280405Srpaulo
9404280405Srpaulo<p>
9405280405SrpauloSets <code>x</code> as the "seed"
9406280405Srpaulofor the pseudo-random generator:
9407280405Srpauloequal seeds produce equal sequences of numbers.
9408280405Srpaulo
9409280405Srpaulo
9410280405Srpaulo
9411280405Srpaulo
9412280405Srpaulo<p>
9413280405Srpaulo<hr><h3><a name="pdf-math.sin"><code>math.sin (x)</code></a></h3>
9414280405Srpaulo
9415280405Srpaulo
9416280405Srpaulo<p>
9417280405SrpauloReturns the sine of <code>x</code> (assumed to be in radians).
9418280405Srpaulo
9419280405Srpaulo
9420280405Srpaulo
9421280405Srpaulo
9422280405Srpaulo<p>
9423280405Srpaulo<hr><h3><a name="pdf-math.sqrt"><code>math.sqrt (x)</code></a></h3>
9424280405Srpaulo
9425280405Srpaulo
9426280405Srpaulo<p>
9427280405SrpauloReturns the square root of <code>x</code>.
9428280405Srpaulo(You can also use the expression <code>x^0.5</code> to compute this value.)
9429280405Srpaulo
9430280405Srpaulo
9431280405Srpaulo
9432280405Srpaulo
9433280405Srpaulo<p>
9434280405Srpaulo<hr><h3><a name="pdf-math.tan"><code>math.tan (x)</code></a></h3>
9435280405Srpaulo
9436280405Srpaulo
9437280405Srpaulo<p>
9438280405SrpauloReturns the tangent of <code>x</code> (assumed to be in radians).
9439280405Srpaulo
9440280405Srpaulo
9441280405Srpaulo
9442280405Srpaulo
9443280405Srpaulo<p>
9444280405Srpaulo<hr><h3><a name="pdf-math.tointeger"><code>math.tointeger (x)</code></a></h3>
9445280405Srpaulo
9446280405Srpaulo
9447280405Srpaulo<p>
9448280405SrpauloIf the value <code>x</code> is convertible to an integer,
9449280405Srpauloreturns that integer.
9450280405SrpauloOtherwise, returns <b>nil</b>.
9451280405Srpaulo
9452280405Srpaulo
9453280405Srpaulo
9454280405Srpaulo
9455280405Srpaulo<p>
9456280405Srpaulo<hr><h3><a name="pdf-math.type"><code>math.type (x)</code></a></h3>
9457280405Srpaulo
9458280405Srpaulo
9459280405Srpaulo<p>
9460280405SrpauloReturns "<code>integer</code>" if <code>x</code> is an integer,
9461280405Srpaulo"<code>float</code>" if it is a float,
9462280405Srpauloor <b>nil</b> if <code>x</code> is not a number.
9463280405Srpaulo
9464280405Srpaulo
9465280405Srpaulo
9466280405Srpaulo
9467280405Srpaulo<p>
9468280405Srpaulo<hr><h3><a name="pdf-math.ult"><code>math.ult (m, n)</code></a></h3>
9469280405Srpaulo
9470280405Srpaulo
9471280405Srpaulo<p>
9472280405SrpauloReturns a boolean,
9473326344Simptrue if and only if integer <code>m</code> is below integer <code>n</code> when
9474280405Srpaulothey are compared as unsigned integers.
9475280405Srpaulo
9476280405Srpaulo
9477280405Srpaulo
9478280405Srpaulo
9479280405Srpaulo
9480280405Srpaulo
9481280405Srpaulo
9482280405Srpaulo<h2>6.8 &ndash; <a name="6.8">Input and Output Facilities</a></h2>
9483280405Srpaulo
9484280405Srpaulo<p>
9485280405SrpauloThe I/O library provides two different styles for file manipulation.
9486280405SrpauloThe first one uses implicit file handles;
9487280405Srpaulothat is, there are operations to set a default input file and a
9488280405Srpaulodefault output file,
9489280405Srpauloand all input/output operations are over these default files.
9490280405SrpauloThe second style uses explicit file handles.
9491280405Srpaulo
9492280405Srpaulo
9493280405Srpaulo<p>
9494280405SrpauloWhen using implicit file handles,
9495280405Srpauloall operations are supplied by table <a name="pdf-io"><code>io</code></a>.
9496280405SrpauloWhen using explicit file handles,
9497280405Srpaulothe operation <a href="#pdf-io.open"><code>io.open</code></a> returns a file handle
9498280405Srpauloand then all operations are supplied as methods of the file handle.
9499280405Srpaulo
9500280405Srpaulo
9501280405Srpaulo<p>
9502280405SrpauloThe table <code>io</code> also provides
9503280405Srpaulothree predefined file handles with their usual meanings from C:
9504280405Srpaulo<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>.
9505280405SrpauloThe I/O library never closes these files.
9506280405Srpaulo
9507280405Srpaulo
9508280405Srpaulo<p>
9509280405SrpauloUnless otherwise stated,
9510280405Srpauloall I/O functions return <b>nil</b> on failure
9511280405Srpaulo(plus an error message as a second result and
9512280405Srpauloa system-dependent error code as a third result)
9513280405Srpauloand some value different from <b>nil</b> on success.
9514344220SkevansIn non-POSIX systems,
9515280405Srpaulothe computation of the error message and error code
9516280405Srpauloin case of errors
9517280405Srpaulomay be not thread safe,
9518280405Srpaulobecause they rely on the global C variable <code>errno</code>.
9519280405Srpaulo
9520280405Srpaulo
9521280405Srpaulo<p>
9522280405Srpaulo<hr><h3><a name="pdf-io.close"><code>io.close ([file])</code></a></h3>
9523280405Srpaulo
9524280405Srpaulo
9525280405Srpaulo<p>
9526280405SrpauloEquivalent to <code>file:close()</code>.
9527280405SrpauloWithout a <code>file</code>, closes the default output file.
9528280405Srpaulo
9529280405Srpaulo
9530280405Srpaulo
9531280405Srpaulo
9532280405Srpaulo<p>
9533280405Srpaulo<hr><h3><a name="pdf-io.flush"><code>io.flush ()</code></a></h3>
9534280405Srpaulo
9535280405Srpaulo
9536280405Srpaulo<p>
9537280405SrpauloEquivalent to <code>io.output():flush()</code>.
9538280405Srpaulo
9539280405Srpaulo
9540280405Srpaulo
9541280405Srpaulo
9542280405Srpaulo<p>
9543280405Srpaulo<hr><h3><a name="pdf-io.input"><code>io.input ([file])</code></a></h3>
9544280405Srpaulo
9545280405Srpaulo
9546280405Srpaulo<p>
9547280405SrpauloWhen called with a file name, it opens the named file (in text mode),
9548280405Srpauloand sets its handle as the default input file.
9549280405SrpauloWhen called with a file handle,
9550280405Srpauloit simply sets this file handle as the default input file.
9551344220SkevansWhen called without arguments,
9552280405Srpauloit returns the current default input file.
9553280405Srpaulo
9554280405Srpaulo
9555280405Srpaulo<p>
9556280405SrpauloIn case of errors this function raises the error,
9557280405Srpauloinstead of returning an error code.
9558280405Srpaulo
9559280405Srpaulo
9560280405Srpaulo
9561280405Srpaulo
9562280405Srpaulo<p>
9563326344Simp<hr><h3><a name="pdf-io.lines"><code>io.lines ([filename, &middot;&middot;&middot;])</code></a></h3>
9564280405Srpaulo
9565280405Srpaulo
9566280405Srpaulo<p>
9567280405SrpauloOpens the given file name in read mode
9568280405Srpauloand returns an iterator function that
9569280405Srpauloworks like <code>file:lines(&middot;&middot;&middot;)</code> over the opened file.
9570280405SrpauloWhen the iterator function detects the end of file,
9571280405Srpauloit returns no values (to finish the loop) and automatically closes the file.
9572280405Srpaulo
9573280405Srpaulo
9574280405Srpaulo<p>
9575280405SrpauloThe call <code>io.lines()</code> (with no file name) is equivalent
9576280405Srpauloto <code>io.input():lines("*l")</code>;
9577280405Srpaulothat is, it iterates over the lines of the default input file.
9578344220SkevansIn this case, the iterator does not close the file when the loop ends.
9579280405Srpaulo
9580280405Srpaulo
9581280405Srpaulo<p>
9582280405SrpauloIn case of errors this function raises the error,
9583280405Srpauloinstead of returning an error code.
9584280405Srpaulo
9585280405Srpaulo
9586280405Srpaulo
9587280405Srpaulo
9588280405Srpaulo<p>
9589280405Srpaulo<hr><h3><a name="pdf-io.open"><code>io.open (filename [, mode])</code></a></h3>
9590280405Srpaulo
9591280405Srpaulo
9592280405Srpaulo<p>
9593280405SrpauloThis function opens a file,
9594280405Srpauloin the mode specified in the string <code>mode</code>.
9595326344SimpIn case of success,
9596326344Simpit returns a new file handle.
9597280405Srpaulo
9598280405Srpaulo
9599280405Srpaulo<p>
9600280405SrpauloThe <code>mode</code> string can be any of the following:
9601280405Srpaulo
9602280405Srpaulo<ul>
9603280405Srpaulo<li><b>"<code>r</code>": </b> read mode (the default);</li>
9604280405Srpaulo<li><b>"<code>w</code>": </b> write mode;</li>
9605280405Srpaulo<li><b>"<code>a</code>": </b> append mode;</li>
9606280405Srpaulo<li><b>"<code>r+</code>": </b> update mode, all previous data is preserved;</li>
9607280405Srpaulo<li><b>"<code>w+</code>": </b> update mode, all previous data is erased;</li>
9608280405Srpaulo<li><b>"<code>a+</code>": </b> append update mode, previous data is preserved,
9609280405Srpaulo  writing is only allowed at the end of file.</li>
9610280405Srpaulo</ul><p>
9611280405SrpauloThe <code>mode</code> string can also have a '<code>b</code>' at the end,
9612280405Srpaulowhich is needed in some systems to open the file in binary mode.
9613280405Srpaulo
9614280405Srpaulo
9615280405Srpaulo
9616280405Srpaulo
9617280405Srpaulo<p>
9618280405Srpaulo<hr><h3><a name="pdf-io.output"><code>io.output ([file])</code></a></h3>
9619280405Srpaulo
9620280405Srpaulo
9621280405Srpaulo<p>
9622280405SrpauloSimilar to <a href="#pdf-io.input"><code>io.input</code></a>, but operates over the default output file.
9623280405Srpaulo
9624280405Srpaulo
9625280405Srpaulo
9626280405Srpaulo
9627280405Srpaulo<p>
9628280405Srpaulo<hr><h3><a name="pdf-io.popen"><code>io.popen (prog [, mode])</code></a></h3>
9629280405Srpaulo
9630280405Srpaulo
9631280405Srpaulo<p>
9632280405SrpauloThis function is system dependent and is not available
9633280405Srpauloon all platforms.
9634280405Srpaulo
9635280405Srpaulo
9636280405Srpaulo<p>
9637280405SrpauloStarts program <code>prog</code> in a separated process and returns
9638280405Srpauloa file handle that you can use to read data from this program
9639280405Srpaulo(if <code>mode</code> is <code>"r"</code>, the default)
9640280405Srpauloor to write data to this program
9641280405Srpaulo(if <code>mode</code> is <code>"w"</code>).
9642280405Srpaulo
9643280405Srpaulo
9644280405Srpaulo
9645280405Srpaulo
9646280405Srpaulo<p>
9647280405Srpaulo<hr><h3><a name="pdf-io.read"><code>io.read (&middot;&middot;&middot;)</code></a></h3>
9648280405Srpaulo
9649280405Srpaulo
9650280405Srpaulo<p>
9651280405SrpauloEquivalent to <code>io.input():read(&middot;&middot;&middot;)</code>.
9652280405Srpaulo
9653280405Srpaulo
9654280405Srpaulo
9655280405Srpaulo
9656280405Srpaulo<p>
9657280405Srpaulo<hr><h3><a name="pdf-io.tmpfile"><code>io.tmpfile ()</code></a></h3>
9658280405Srpaulo
9659280405Srpaulo
9660280405Srpaulo<p>
9661326344SimpIn case of success,
9662326344Simpreturns a handle for a temporary file.
9663280405SrpauloThis file is opened in update mode
9664280405Srpauloand it is automatically removed when the program ends.
9665280405Srpaulo
9666280405Srpaulo
9667280405Srpaulo
9668280405Srpaulo
9669280405Srpaulo<p>
9670280405Srpaulo<hr><h3><a name="pdf-io.type"><code>io.type (obj)</code></a></h3>
9671280405Srpaulo
9672280405Srpaulo
9673280405Srpaulo<p>
9674280405SrpauloChecks whether <code>obj</code> is a valid file handle.
9675280405SrpauloReturns the string <code>"file"</code> if <code>obj</code> is an open file handle,
9676280405Srpaulo<code>"closed file"</code> if <code>obj</code> is a closed file handle,
9677280405Srpauloor <b>nil</b> if <code>obj</code> is not a file handle.
9678280405Srpaulo
9679280405Srpaulo
9680280405Srpaulo
9681280405Srpaulo
9682280405Srpaulo<p>
9683280405Srpaulo<hr><h3><a name="pdf-io.write"><code>io.write (&middot;&middot;&middot;)</code></a></h3>
9684280405Srpaulo
9685280405Srpaulo
9686280405Srpaulo<p>
9687280405SrpauloEquivalent to <code>io.output():write(&middot;&middot;&middot;)</code>.
9688280405Srpaulo
9689280405Srpaulo
9690280405Srpaulo
9691280405Srpaulo
9692280405Srpaulo<p>
9693280405Srpaulo<hr><h3><a name="pdf-file:close"><code>file:close ()</code></a></h3>
9694280405Srpaulo
9695280405Srpaulo
9696280405Srpaulo<p>
9697280405SrpauloCloses <code>file</code>.
9698280405SrpauloNote that files are automatically closed when
9699280405Srpaulotheir handles are garbage collected,
9700280405Srpaulobut that takes an unpredictable amount of time to happen.
9701280405Srpaulo
9702280405Srpaulo
9703280405Srpaulo<p>
9704280405SrpauloWhen closing a file handle created with <a href="#pdf-io.popen"><code>io.popen</code></a>,
9705280405Srpaulo<a href="#pdf-file:close"><code>file:close</code></a> returns the same values
9706280405Srpauloreturned by <a href="#pdf-os.execute"><code>os.execute</code></a>.
9707280405Srpaulo
9708280405Srpaulo
9709280405Srpaulo
9710280405Srpaulo
9711280405Srpaulo<p>
9712280405Srpaulo<hr><h3><a name="pdf-file:flush"><code>file:flush ()</code></a></h3>
9713280405Srpaulo
9714280405Srpaulo
9715280405Srpaulo<p>
9716280405SrpauloSaves any written data to <code>file</code>.
9717280405Srpaulo
9718280405Srpaulo
9719280405Srpaulo
9720280405Srpaulo
9721280405Srpaulo<p>
9722280405Srpaulo<hr><h3><a name="pdf-file:lines"><code>file:lines (&middot;&middot;&middot;)</code></a></h3>
9723280405Srpaulo
9724280405Srpaulo
9725280405Srpaulo<p>
9726280405SrpauloReturns an iterator function that,
9727280405Srpauloeach time it is called,
9728280405Srpauloreads the file according to the given formats.
9729280405SrpauloWhen no format is given,
9730280405Srpaulouses "<code>l</code>" as a default.
9731280405SrpauloAs an example, the construction
9732280405Srpaulo
9733280405Srpaulo<pre>
9734280405Srpaulo     for c in file:lines(1) do <em>body</em> end
9735280405Srpaulo</pre><p>
9736280405Srpaulowill iterate over all characters of the file,
9737280405Srpaulostarting at the current position.
9738280405SrpauloUnlike <a href="#pdf-io.lines"><code>io.lines</code></a>, this function does not close the file
9739280405Srpaulowhen the loop ends.
9740280405Srpaulo
9741280405Srpaulo
9742280405Srpaulo<p>
9743280405SrpauloIn case of errors this function raises the error,
9744280405Srpauloinstead of returning an error code.
9745280405Srpaulo
9746280405Srpaulo
9747280405Srpaulo
9748280405Srpaulo
9749280405Srpaulo<p>
9750280405Srpaulo<hr><h3><a name="pdf-file:read"><code>file:read (&middot;&middot;&middot;)</code></a></h3>
9751280405Srpaulo
9752280405Srpaulo
9753280405Srpaulo<p>
9754280405SrpauloReads the file <code>file</code>,
9755280405Srpauloaccording to the given formats, which specify what to read.
9756280405SrpauloFor each format,
9757280405Srpaulothe function returns a string or a number with the characters read,
9758280405Srpauloor <b>nil</b> if it cannot read data with the specified format.
9759280405Srpaulo(In this latter case,
9760280405Srpaulothe function does not read subsequent formats.)
9761280405SrpauloWhen called without formats,
9762280405Srpauloit uses a default format that reads the next line
9763280405Srpaulo(see below).
9764280405Srpaulo
9765280405Srpaulo
9766280405Srpaulo<p>
9767280405SrpauloThe available formats are
9768280405Srpaulo
9769280405Srpaulo<ul>
9770280405Srpaulo
9771280405Srpaulo<li><b>"<code>n</code>": </b>
9772280405Srpauloreads a numeral and returns it as a float or an integer,
9773280405Srpaulofollowing the lexical conventions of Lua.
9774280405Srpaulo(The numeral may have leading spaces and a sign.)
9775280405SrpauloThis format always reads the longest input sequence that
9776326344Simpis a valid prefix for a numeral;
9777326344Simpif that prefix does not form a valid numeral
9778280405Srpaulo(e.g., an empty string, "<code>0x</code>", or "<code>3.4e-</code>"),
9779280405Srpauloit is discarded and the function returns <b>nil</b>.
9780280405Srpaulo</li>
9781280405Srpaulo
9782280405Srpaulo<li><b>"<code>a</code>": </b>
9783280405Srpauloreads the whole file, starting at the current position.
9784280405SrpauloOn end of file, it returns the empty string.
9785280405Srpaulo</li>
9786280405Srpaulo
9787280405Srpaulo<li><b>"<code>l</code>": </b>
9788280405Srpauloreads the next line skipping the end of line,
9789280405Srpauloreturning <b>nil</b> on end of file.
9790280405SrpauloThis is the default format.
9791280405Srpaulo</li>
9792280405Srpaulo
9793280405Srpaulo<li><b>"<code>L</code>": </b>
9794280405Srpauloreads the next line keeping the end-of-line character (if present),
9795280405Srpauloreturning <b>nil</b> on end of file.
9796280405Srpaulo</li>
9797280405Srpaulo
9798280405Srpaulo<li><b><em>number</em>: </b>
9799280405Srpauloreads a string with up to this number of bytes,
9800280405Srpauloreturning <b>nil</b> on end of file.
9801280405SrpauloIf <code>number</code> is zero,
9802280405Srpauloit reads nothing and returns an empty string,
9803280405Srpauloor <b>nil</b> on end of file.
9804280405Srpaulo</li>
9805280405Srpaulo
9806280405Srpaulo</ul><p>
9807280405SrpauloThe formats "<code>l</code>" and "<code>L</code>" should be used only for text files.
9808280405Srpaulo
9809280405Srpaulo
9810280405Srpaulo
9811280405Srpaulo
9812280405Srpaulo<p>
9813280405Srpaulo<hr><h3><a name="pdf-file:seek"><code>file:seek ([whence [, offset]])</code></a></h3>
9814280405Srpaulo
9815280405Srpaulo
9816280405Srpaulo<p>
9817280405SrpauloSets and gets the file position,
9818280405Srpaulomeasured from the beginning of the file,
9819280405Srpauloto the position given by <code>offset</code> plus a base
9820280405Srpaulospecified by the string <code>whence</code>, as follows:
9821280405Srpaulo
9822280405Srpaulo<ul>
9823280405Srpaulo<li><b>"<code>set</code>": </b> base is position 0 (beginning of the file);</li>
9824280405Srpaulo<li><b>"<code>cur</code>": </b> base is current position;</li>
9825280405Srpaulo<li><b>"<code>end</code>": </b> base is end of file;</li>
9826280405Srpaulo</ul><p>
9827280405SrpauloIn case of success, <code>seek</code> returns the final file position,
9828280405Srpaulomeasured in bytes from the beginning of the file.
9829280405SrpauloIf <code>seek</code> fails, it returns <b>nil</b>,
9830280405Srpauloplus a string describing the error.
9831280405Srpaulo
9832280405Srpaulo
9833280405Srpaulo<p>
9834280405SrpauloThe default value for <code>whence</code> is <code>"cur"</code>,
9835280405Srpauloand for <code>offset</code> is 0.
9836280405SrpauloTherefore, the call <code>file:seek()</code> returns the current
9837280405Srpaulofile position, without changing it;
9838280405Srpaulothe call <code>file:seek("set")</code> sets the position to the
9839280405Srpaulobeginning of the file (and returns 0);
9840280405Srpauloand the call <code>file:seek("end")</code> sets the position to the
9841280405Srpauloend of the file, and returns its size.
9842280405Srpaulo
9843280405Srpaulo
9844280405Srpaulo
9845280405Srpaulo
9846280405Srpaulo<p>
9847280405Srpaulo<hr><h3><a name="pdf-file:setvbuf"><code>file:setvbuf (mode [, size])</code></a></h3>
9848280405Srpaulo
9849280405Srpaulo
9850280405Srpaulo<p>
9851280405SrpauloSets the buffering mode for an output file.
9852280405SrpauloThere are three available modes:
9853280405Srpaulo
9854280405Srpaulo<ul>
9855280405Srpaulo
9856280405Srpaulo<li><b>"<code>no</code>": </b>
9857280405Srpaulono buffering; the result of any output operation appears immediately.
9858280405Srpaulo</li>
9859280405Srpaulo
9860280405Srpaulo<li><b>"<code>full</code>": </b>
9861280405Srpaulofull buffering; output operation is performed only
9862280405Srpaulowhen the buffer is full or when
9863280405Srpauloyou explicitly <code>flush</code> the file (see <a href="#pdf-io.flush"><code>io.flush</code></a>).
9864280405Srpaulo</li>
9865280405Srpaulo
9866280405Srpaulo<li><b>"<code>line</code>": </b>
9867280405Srpauloline buffering; output is buffered until a newline is output
9868280405Srpauloor there is any input from some special files
9869280405Srpaulo(such as a terminal device).
9870280405Srpaulo</li>
9871280405Srpaulo
9872280405Srpaulo</ul><p>
9873280405SrpauloFor the last two cases, <code>size</code>
9874280405Srpaulospecifies the size of the buffer, in bytes.
9875280405SrpauloThe default is an appropriate size.
9876280405Srpaulo
9877280405Srpaulo
9878280405Srpaulo
9879280405Srpaulo
9880280405Srpaulo<p>
9881280405Srpaulo<hr><h3><a name="pdf-file:write"><code>file:write (&middot;&middot;&middot;)</code></a></h3>
9882280405Srpaulo
9883280405Srpaulo
9884280405Srpaulo<p>
9885280405SrpauloWrites the value of each of its arguments to <code>file</code>.
9886280405SrpauloThe arguments must be strings or numbers.
9887280405Srpaulo
9888280405Srpaulo
9889280405Srpaulo<p>
9890280405SrpauloIn case of success, this function returns <code>file</code>.
9891280405SrpauloOtherwise it returns <b>nil</b> plus a string describing the error.
9892280405Srpaulo
9893280405Srpaulo
9894280405Srpaulo
9895280405Srpaulo
9896280405Srpaulo
9897280405Srpaulo
9898280405Srpaulo
9899280405Srpaulo<h2>6.9 &ndash; <a name="6.9">Operating System Facilities</a></h2>
9900280405Srpaulo
9901280405Srpaulo<p>
9902280405SrpauloThis library is implemented through table <a name="pdf-os"><code>os</code></a>.
9903280405Srpaulo
9904280405Srpaulo
9905280405Srpaulo<p>
9906280405Srpaulo<hr><h3><a name="pdf-os.clock"><code>os.clock ()</code></a></h3>
9907280405Srpaulo
9908280405Srpaulo
9909280405Srpaulo<p>
9910280405SrpauloReturns an approximation of the amount in seconds of CPU time
9911280405Srpauloused by the program.
9912280405Srpaulo
9913280405Srpaulo
9914280405Srpaulo
9915280405Srpaulo
9916280405Srpaulo<p>
9917280405Srpaulo<hr><h3><a name="pdf-os.date"><code>os.date ([format [, time]])</code></a></h3>
9918280405Srpaulo
9919280405Srpaulo
9920280405Srpaulo<p>
9921280405SrpauloReturns a string or a table containing date and time,
9922280405Srpauloformatted according to the given string <code>format</code>.
9923280405Srpaulo
9924280405Srpaulo
9925280405Srpaulo<p>
9926280405SrpauloIf the <code>time</code> argument is present,
9927280405Srpaulothis is the time to be formatted
9928280405Srpaulo(see the <a href="#pdf-os.time"><code>os.time</code></a> function for a description of this value).
9929280405SrpauloOtherwise, <code>date</code> formats the current time.
9930280405Srpaulo
9931280405Srpaulo
9932280405Srpaulo<p>
9933280405SrpauloIf <code>format</code> starts with '<code>!</code>',
9934280405Srpaulothen the date is formatted in Coordinated Universal Time.
9935280405SrpauloAfter this optional character,
9936280405Srpauloif <code>format</code> is the string "<code>*t</code>",
9937280405Srpaulothen <code>date</code> returns a table with the following fields:
9938326344Simp<code>year</code>, <code>month</code> (1&ndash;12), <code>day</code> (1&ndash;31),
9939280405Srpaulo<code>hour</code> (0&ndash;23), <code>min</code> (0&ndash;59), <code>sec</code> (0&ndash;61),
9940326344Simp<code>wday</code> (weekday, 1&ndash;7, Sunday is&nbsp;1),
9941326344Simp<code>yday</code> (day of the year, 1&ndash;366),
9942280405Srpauloand <code>isdst</code> (daylight saving flag, a boolean).
9943280405SrpauloThis last field may be absent
9944280405Srpauloif the information is not available.
9945280405Srpaulo
9946280405Srpaulo
9947280405Srpaulo<p>
9948280405SrpauloIf <code>format</code> is not "<code>*t</code>",
9949280405Srpaulothen <code>date</code> returns the date as a string,
9950280405Srpauloformatted according to the same rules as the ISO&nbsp;C function <code>strftime</code>.
9951280405Srpaulo
9952280405Srpaulo
9953280405Srpaulo<p>
9954280405SrpauloWhen called without arguments,
9955280405Srpaulo<code>date</code> returns a reasonable date and time representation that depends on
9956326344Simpthe host system and on the current locale.
9957326344Simp(More specifically, <code>os.date()</code> is equivalent to <code>os.date("%c")</code>.)
9958280405Srpaulo
9959280405Srpaulo
9960280405Srpaulo<p>
9961344220SkevansIn non-POSIX systems,
9962280405Srpaulothis function may be not thread safe
9963280405Srpaulobecause of its reliance on C&nbsp;function <code>gmtime</code> and C&nbsp;function <code>localtime</code>.
9964280405Srpaulo
9965280405Srpaulo
9966280405Srpaulo
9967280405Srpaulo
9968280405Srpaulo<p>
9969280405Srpaulo<hr><h3><a name="pdf-os.difftime"><code>os.difftime (t2, t1)</code></a></h3>
9970280405Srpaulo
9971280405Srpaulo
9972280405Srpaulo<p>
9973280405SrpauloReturns the difference, in seconds,
9974280405Srpaulofrom time <code>t1</code> to time <code>t2</code>
9975280405Srpaulo(where the times are values returned by <a href="#pdf-os.time"><code>os.time</code></a>).
9976280405SrpauloIn POSIX, Windows, and some other systems,
9977280405Srpaulothis value is exactly <code>t2</code><em>-</em><code>t1</code>.
9978280405Srpaulo
9979280405Srpaulo
9980280405Srpaulo
9981280405Srpaulo
9982280405Srpaulo<p>
9983280405Srpaulo<hr><h3><a name="pdf-os.execute"><code>os.execute ([command])</code></a></h3>
9984280405Srpaulo
9985280405Srpaulo
9986280405Srpaulo<p>
9987280405SrpauloThis function is equivalent to the ISO&nbsp;C function <code>system</code>.
9988280405SrpauloIt passes <code>command</code> to be executed by an operating system shell.
9989280405SrpauloIts first result is <b>true</b>
9990280405Srpauloif the command terminated successfully,
9991280405Srpauloor <b>nil</b> otherwise.
9992280405SrpauloAfter this first result
9993280405Srpaulothe function returns a string plus a number,
9994280405Srpauloas follows:
9995280405Srpaulo
9996280405Srpaulo<ul>
9997280405Srpaulo
9998280405Srpaulo<li><b>"<code>exit</code>": </b>
9999280405Srpaulothe command terminated normally;
10000280405Srpaulothe following number is the exit status of the command.
10001280405Srpaulo</li>
10002280405Srpaulo
10003280405Srpaulo<li><b>"<code>signal</code>": </b>
10004280405Srpaulothe command was terminated by a signal;
10005280405Srpaulothe following number is the signal that terminated the command.
10006280405Srpaulo</li>
10007280405Srpaulo
10008280405Srpaulo</ul>
10009280405Srpaulo
10010280405Srpaulo<p>
10011280405SrpauloWhen called without a <code>command</code>,
10012280405Srpaulo<code>os.execute</code> returns a boolean that is true if a shell is available.
10013280405Srpaulo
10014280405Srpaulo
10015280405Srpaulo
10016280405Srpaulo
10017280405Srpaulo<p>
10018280405Srpaulo<hr><h3><a name="pdf-os.exit"><code>os.exit ([code [, close]])</code></a></h3>
10019280405Srpaulo
10020280405Srpaulo
10021280405Srpaulo<p>
10022280405SrpauloCalls the ISO&nbsp;C function <code>exit</code> to terminate the host program.
10023280405SrpauloIf <code>code</code> is <b>true</b>,
10024280405Srpaulothe returned status is <code>EXIT_SUCCESS</code>;
10025280405Srpauloif <code>code</code> is <b>false</b>,
10026280405Srpaulothe returned status is <code>EXIT_FAILURE</code>;
10027280405Srpauloif <code>code</code> is a number,
10028280405Srpaulothe returned status is this number.
10029280405SrpauloThe default value for <code>code</code> is <b>true</b>.
10030280405Srpaulo
10031280405Srpaulo
10032280405Srpaulo<p>
10033280405SrpauloIf the optional second argument <code>close</code> is true,
10034280405Srpaulocloses the Lua state before exiting.
10035280405Srpaulo
10036280405Srpaulo
10037280405Srpaulo
10038280405Srpaulo
10039280405Srpaulo<p>
10040280405Srpaulo<hr><h3><a name="pdf-os.getenv"><code>os.getenv (varname)</code></a></h3>
10041280405Srpaulo
10042280405Srpaulo
10043280405Srpaulo<p>
10044280405SrpauloReturns the value of the process environment variable <code>varname</code>,
10045280405Srpauloor <b>nil</b> if the variable is not defined.
10046280405Srpaulo
10047280405Srpaulo
10048280405Srpaulo
10049280405Srpaulo
10050280405Srpaulo<p>
10051280405Srpaulo<hr><h3><a name="pdf-os.remove"><code>os.remove (filename)</code></a></h3>
10052280405Srpaulo
10053280405Srpaulo
10054280405Srpaulo<p>
10055280405SrpauloDeletes the file (or empty directory, on POSIX systems)
10056280405Srpaulowith the given name.
10057280405SrpauloIf this function fails, it returns <b>nil</b>,
10058280405Srpauloplus a string describing the error and the error code.
10059326344SimpOtherwise, it returns true.
10060280405Srpaulo
10061280405Srpaulo
10062280405Srpaulo
10063280405Srpaulo
10064280405Srpaulo<p>
10065280405Srpaulo<hr><h3><a name="pdf-os.rename"><code>os.rename (oldname, newname)</code></a></h3>
10066280405Srpaulo
10067280405Srpaulo
10068280405Srpaulo<p>
10069326344SimpRenames the file or directory named <code>oldname</code> to <code>newname</code>.
10070280405SrpauloIf this function fails, it returns <b>nil</b>,
10071280405Srpauloplus a string describing the error and the error code.
10072326344SimpOtherwise, it returns true.
10073280405Srpaulo
10074280405Srpaulo
10075280405Srpaulo
10076280405Srpaulo
10077280405Srpaulo<p>
10078280405Srpaulo<hr><h3><a name="pdf-os.setlocale"><code>os.setlocale (locale [, category])</code></a></h3>
10079280405Srpaulo
10080280405Srpaulo
10081280405Srpaulo<p>
10082280405SrpauloSets the current locale of the program.
10083280405Srpaulo<code>locale</code> is a system-dependent string specifying a locale;
10084280405Srpaulo<code>category</code> is an optional string describing which category to change:
10085280405Srpaulo<code>"all"</code>, <code>"collate"</code>, <code>"ctype"</code>,
10086280405Srpaulo<code>"monetary"</code>, <code>"numeric"</code>, or <code>"time"</code>;
10087280405Srpaulothe default category is <code>"all"</code>.
10088280405SrpauloThe function returns the name of the new locale,
10089280405Srpauloor <b>nil</b> if the request cannot be honored.
10090280405Srpaulo
10091280405Srpaulo
10092280405Srpaulo<p>
10093280405SrpauloIf <code>locale</code> is the empty string,
10094280405Srpaulothe current locale is set to an implementation-defined native locale.
10095280405SrpauloIf <code>locale</code> is the string "<code>C</code>",
10096280405Srpaulothe current locale is set to the standard C locale.
10097280405Srpaulo
10098280405Srpaulo
10099280405Srpaulo<p>
10100280405SrpauloWhen called with <b>nil</b> as the first argument,
10101280405Srpaulothis function only returns the name of the current locale
10102280405Srpaulofor the given category.
10103280405Srpaulo
10104280405Srpaulo
10105280405Srpaulo<p>
10106280405SrpauloThis function may be not thread safe
10107280405Srpaulobecause of its reliance on C&nbsp;function <code>setlocale</code>.
10108280405Srpaulo
10109280405Srpaulo
10110280405Srpaulo
10111280405Srpaulo
10112280405Srpaulo<p>
10113280405Srpaulo<hr><h3><a name="pdf-os.time"><code>os.time ([table])</code></a></h3>
10114280405Srpaulo
10115280405Srpaulo
10116280405Srpaulo<p>
10117280405SrpauloReturns the current time when called without arguments,
10118326344Simpor a time representing the local date and time specified by the given table.
10119280405SrpauloThis table must have fields <code>year</code>, <code>month</code>, and <code>day</code>,
10120280405Srpauloand may have fields
10121280405Srpaulo<code>hour</code> (default is 12),
10122280405Srpaulo<code>min</code> (default is 0),
10123280405Srpaulo<code>sec</code> (default is 0),
10124280405Srpauloand <code>isdst</code> (default is <b>nil</b>).
10125326344SimpOther fields are ignored.
10126280405SrpauloFor a description of these fields, see the <a href="#pdf-os.date"><code>os.date</code></a> function.
10127280405Srpaulo
10128280405Srpaulo
10129280405Srpaulo<p>
10130326344SimpThe values in these fields do not need to be inside their valid ranges.
10131326344SimpFor instance, if <code>sec</code> is -10,
10132326344Simpit means -10 seconds from the time specified by the other fields;
10133326344Simpif <code>hour</code> is 1000,
10134326344Simpit means +1000 hours from the time specified by the other fields.
10135326344Simp
10136326344Simp
10137326344Simp<p>
10138280405SrpauloThe returned value is a number, whose meaning depends on your system.
10139280405SrpauloIn POSIX, Windows, and some other systems,
10140280405Srpaulothis number counts the number
10141280405Srpauloof seconds since some given start time (the "epoch").
10142280405SrpauloIn other systems, the meaning is not specified,
10143280405Srpauloand the number returned by <code>time</code> can be used only as an argument to
10144280405Srpaulo<a href="#pdf-os.date"><code>os.date</code></a> and <a href="#pdf-os.difftime"><code>os.difftime</code></a>.
10145280405Srpaulo
10146280405Srpaulo
10147280405Srpaulo
10148280405Srpaulo
10149280405Srpaulo<p>
10150280405Srpaulo<hr><h3><a name="pdf-os.tmpname"><code>os.tmpname ()</code></a></h3>
10151280405Srpaulo
10152280405Srpaulo
10153280405Srpaulo<p>
10154280405SrpauloReturns a string with a file name that can
10155280405Srpaulobe used for a temporary file.
10156280405SrpauloThe file must be explicitly opened before its use
10157280405Srpauloand explicitly removed when no longer needed.
10158280405Srpaulo
10159280405Srpaulo
10160280405Srpaulo<p>
10161344220SkevansIn POSIX systems,
10162280405Srpaulothis function also creates a file with that name,
10163280405Srpauloto avoid security risks.
10164280405Srpaulo(Someone else might create the file with wrong permissions
10165280405Srpauloin the time between getting the name and creating the file.)
10166280405SrpauloYou still have to open the file to use it
10167280405Srpauloand to remove it (even if you do not use it).
10168280405Srpaulo
10169280405Srpaulo
10170280405Srpaulo<p>
10171280405SrpauloWhen possible,
10172280405Srpauloyou may prefer to use <a href="#pdf-io.tmpfile"><code>io.tmpfile</code></a>,
10173280405Srpaulowhich automatically removes the file when the program ends.
10174280405Srpaulo
10175280405Srpaulo
10176280405Srpaulo
10177280405Srpaulo
10178280405Srpaulo
10179280405Srpaulo
10180280405Srpaulo
10181280405Srpaulo<h2>6.10 &ndash; <a name="6.10">The Debug Library</a></h2>
10182280405Srpaulo
10183280405Srpaulo<p>
10184280405SrpauloThis library provides
10185280405Srpaulothe functionality of the debug interface (<a href="#4.9">&sect;4.9</a>) to Lua programs.
10186280405SrpauloYou should exert care when using this library.
10187280405SrpauloSeveral of its functions
10188280405Srpauloviolate basic assumptions about Lua code
10189280405Srpaulo(e.g., that variables local to a function
10190280405Srpaulocannot be accessed from outside;
10191280405Srpaulothat userdata metatables cannot be changed by Lua code;
10192280405Srpaulothat Lua programs do not crash)
10193280405Srpauloand therefore can compromise otherwise secure code.
10194280405SrpauloMoreover, some functions in this library may be slow.
10195280405Srpaulo
10196280405Srpaulo
10197280405Srpaulo<p>
10198280405SrpauloAll functions in this library are provided
10199280405Srpauloinside the <a name="pdf-debug"><code>debug</code></a> table.
10200280405SrpauloAll functions that operate over a thread
10201280405Srpaulohave an optional first argument which is the
10202280405Srpaulothread to operate over.
10203280405SrpauloThe default is always the current thread.
10204280405Srpaulo
10205280405Srpaulo
10206280405Srpaulo<p>
10207280405Srpaulo<hr><h3><a name="pdf-debug.debug"><code>debug.debug ()</code></a></h3>
10208280405Srpaulo
10209280405Srpaulo
10210280405Srpaulo<p>
10211280405SrpauloEnters an interactive mode with the user,
10212280405Srpaulorunning each string that the user enters.
10213280405SrpauloUsing simple commands and other debug facilities,
10214280405Srpaulothe user can inspect global and local variables,
10215280405Srpaulochange their values, evaluate expressions, and so on.
10216280405SrpauloA line containing only the word <code>cont</code> finishes this function,
10217280405Srpauloso that the caller continues its execution.
10218280405Srpaulo
10219280405Srpaulo
10220280405Srpaulo<p>
10221280405SrpauloNote that commands for <code>debug.debug</code> are not lexically nested
10222280405Srpaulowithin any function and so have no direct access to local variables.
10223280405Srpaulo
10224280405Srpaulo
10225280405Srpaulo
10226280405Srpaulo
10227280405Srpaulo<p>
10228280405Srpaulo<hr><h3><a name="pdf-debug.gethook"><code>debug.gethook ([thread])</code></a></h3>
10229280405Srpaulo
10230280405Srpaulo
10231280405Srpaulo<p>
10232280405SrpauloReturns the current hook settings of the thread, as three values:
10233280405Srpaulothe current hook function, the current hook mask,
10234280405Srpauloand the current hook count
10235280405Srpaulo(as set by the <a href="#pdf-debug.sethook"><code>debug.sethook</code></a> function).
10236280405Srpaulo
10237280405Srpaulo
10238280405Srpaulo
10239280405Srpaulo
10240280405Srpaulo<p>
10241280405Srpaulo<hr><h3><a name="pdf-debug.getinfo"><code>debug.getinfo ([thread,] f [, what])</code></a></h3>
10242280405Srpaulo
10243280405Srpaulo
10244280405Srpaulo<p>
10245280405SrpauloReturns a table with information about a function.
10246280405SrpauloYou can give the function directly
10247280405Srpauloor you can give a number as the value of <code>f</code>,
10248280405Srpaulowhich means the function running at level <code>f</code> of the call stack
10249280405Srpauloof the given thread:
10250280405Srpaulolevel&nbsp;0 is the current function (<code>getinfo</code> itself);
10251280405Srpaulolevel&nbsp;1 is the function that called <code>getinfo</code>
10252280405Srpaulo(except for tail calls, which do not count on the stack);
10253280405Srpauloand so on.
10254280405SrpauloIf <code>f</code> is a number larger than the number of active functions,
10255280405Srpaulothen <code>getinfo</code> returns <b>nil</b>.
10256280405Srpaulo
10257280405Srpaulo
10258280405Srpaulo<p>
10259280405SrpauloThe returned table can contain all the fields returned by <a href="#lua_getinfo"><code>lua_getinfo</code></a>,
10260280405Srpaulowith the string <code>what</code> describing which fields to fill in.
10261280405SrpauloThe default for <code>what</code> is to get all information available,
10262280405Srpauloexcept the table of valid lines.
10263280405SrpauloIf present,
10264280405Srpaulothe option '<code>f</code>'
10265280405Srpauloadds a field named <code>func</code> with the function itself.
10266280405SrpauloIf present,
10267280405Srpaulothe option '<code>L</code>'
10268280405Srpauloadds a field named <code>activelines</code> with the table of
10269280405Srpaulovalid lines.
10270280405Srpaulo
10271280405Srpaulo
10272280405Srpaulo<p>
10273280405SrpauloFor instance, the expression <code>debug.getinfo(1,"n").name</code> returns
10274326344Simpa name for the current function,
10275280405Srpauloif a reasonable name can be found,
10276280405Srpauloand the expression <code>debug.getinfo(print)</code>
10277280405Srpauloreturns a table with all available information
10278280405Srpauloabout the <a href="#pdf-print"><code>print</code></a> function.
10279280405Srpaulo
10280280405Srpaulo
10281280405Srpaulo
10282280405Srpaulo
10283280405Srpaulo<p>
10284280405Srpaulo<hr><h3><a name="pdf-debug.getlocal"><code>debug.getlocal ([thread,] f, local)</code></a></h3>
10285280405Srpaulo
10286280405Srpaulo
10287280405Srpaulo<p>
10288280405SrpauloThis function returns the name and the value of the local variable
10289280405Srpaulowith index <code>local</code> of the function at level <code>f</code> of the stack.
10290280405SrpauloThis function accesses not only explicit local variables,
10291280405Srpaulobut also parameters, temporaries, etc.
10292280405Srpaulo
10293280405Srpaulo
10294280405Srpaulo<p>
10295280405SrpauloThe first parameter or local variable has index&nbsp;1, and so on,
10296280405Srpaulofollowing the order that they are declared in the code,
10297280405Srpaulocounting only the variables that are active
10298280405Srpauloin the current scope of the function.
10299344220SkevansNegative indices refer to vararg arguments;
10300344220Skevans-1 is the first vararg argument.
10301280405SrpauloThe function returns <b>nil</b> if there is no variable with the given index,
10302280405Srpauloand raises an error when called with a level out of range.
10303280405Srpaulo(You can call <a href="#pdf-debug.getinfo"><code>debug.getinfo</code></a> to check whether the level is valid.)
10304280405Srpaulo
10305280405Srpaulo
10306280405Srpaulo<p>
10307280405SrpauloVariable names starting with '<code>(</code>' (open parenthesis) 
10308280405Srpaulorepresent variables with no known names
10309280405Srpaulo(internal variables such as loop control variables,
10310280405Srpauloand variables from chunks saved without debug information).
10311280405Srpaulo
10312280405Srpaulo
10313280405Srpaulo<p>
10314280405SrpauloThe parameter <code>f</code> may also be a function.
10315280405SrpauloIn that case, <code>getlocal</code> returns only the name of function parameters.
10316280405Srpaulo
10317280405Srpaulo
10318280405Srpaulo
10319280405Srpaulo
10320280405Srpaulo<p>
10321280405Srpaulo<hr><h3><a name="pdf-debug.getmetatable"><code>debug.getmetatable (value)</code></a></h3>
10322280405Srpaulo
10323280405Srpaulo
10324280405Srpaulo<p>
10325280405SrpauloReturns the metatable of the given <code>value</code>
10326280405Srpauloor <b>nil</b> if it does not have a metatable.
10327280405Srpaulo
10328280405Srpaulo
10329280405Srpaulo
10330280405Srpaulo
10331280405Srpaulo<p>
10332280405Srpaulo<hr><h3><a name="pdf-debug.getregistry"><code>debug.getregistry ()</code></a></h3>
10333280405Srpaulo
10334280405Srpaulo
10335280405Srpaulo<p>
10336280405SrpauloReturns the registry table (see <a href="#4.5">&sect;4.5</a>).
10337280405Srpaulo
10338280405Srpaulo
10339280405Srpaulo
10340280405Srpaulo
10341280405Srpaulo<p>
10342280405Srpaulo<hr><h3><a name="pdf-debug.getupvalue"><code>debug.getupvalue (f, up)</code></a></h3>
10343280405Srpaulo
10344280405Srpaulo
10345280405Srpaulo<p>
10346280405SrpauloThis function returns the name and the value of the upvalue
10347280405Srpaulowith index <code>up</code> of the function <code>f</code>.
10348280405SrpauloThe function returns <b>nil</b> if there is no upvalue with the given index.
10349280405Srpaulo
10350280405Srpaulo
10351280405Srpaulo<p>
10352280405SrpauloVariable names starting with '<code>(</code>' (open parenthesis) 
10353280405Srpaulorepresent variables with no known names
10354280405Srpaulo(variables from chunks saved without debug information).
10355280405Srpaulo
10356280405Srpaulo
10357280405Srpaulo
10358280405Srpaulo
10359280405Srpaulo<p>
10360280405Srpaulo<hr><h3><a name="pdf-debug.getuservalue"><code>debug.getuservalue (u)</code></a></h3>
10361280405Srpaulo
10362280405Srpaulo
10363280405Srpaulo<p>
10364280405SrpauloReturns the Lua value associated to <code>u</code>.
10365326344SimpIf <code>u</code> is not a full userdata,
10366280405Srpauloreturns <b>nil</b>.
10367280405Srpaulo
10368280405Srpaulo
10369280405Srpaulo
10370280405Srpaulo
10371280405Srpaulo<p>
10372280405Srpaulo<hr><h3><a name="pdf-debug.sethook"><code>debug.sethook ([thread,] hook, mask [, count])</code></a></h3>
10373280405Srpaulo
10374280405Srpaulo
10375280405Srpaulo<p>
10376280405SrpauloSets the given function as a hook.
10377280405SrpauloThe string <code>mask</code> and the number <code>count</code> describe
10378280405Srpaulowhen the hook will be called.
10379280405SrpauloThe string mask may have any combination of the following characters,
10380280405Srpaulowith the given meaning:
10381280405Srpaulo
10382280405Srpaulo<ul>
10383280405Srpaulo<li><b>'<code>c</code>': </b> the hook is called every time Lua calls a function;</li>
10384280405Srpaulo<li><b>'<code>r</code>': </b> the hook is called every time Lua returns from a function;</li>
10385280405Srpaulo<li><b>'<code>l</code>': </b> the hook is called every time Lua enters a new line of code.</li>
10386280405Srpaulo</ul><p>
10387280405SrpauloMoreover,
10388280405Srpaulowith a <code>count</code> different from zero,
10389280405Srpaulothe hook is called also after every <code>count</code> instructions.
10390280405Srpaulo
10391280405Srpaulo
10392280405Srpaulo<p>
10393280405SrpauloWhen called without arguments,
10394280405Srpaulo<a href="#pdf-debug.sethook"><code>debug.sethook</code></a> turns off the hook.
10395280405Srpaulo
10396280405Srpaulo
10397280405Srpaulo<p>
10398344220SkevansWhen the hook is called, its first argument is a string
10399280405Srpaulodescribing the event that has triggered its call:
10400280405Srpaulo<code>"call"</code> (or <code>"tail call"</code>),
10401280405Srpaulo<code>"return"</code>,
10402280405Srpaulo<code>"line"</code>, and <code>"count"</code>.
10403280405SrpauloFor line events,
10404280405Srpaulothe hook also gets the new line number as its second parameter.
10405280405SrpauloInside a hook,
10406280405Srpauloyou can call <code>getinfo</code> with level&nbsp;2 to get more information about
10407280405Srpaulothe running function
10408280405Srpaulo(level&nbsp;0 is the <code>getinfo</code> function,
10409280405Srpauloand level&nbsp;1 is the hook function).
10410280405Srpaulo
10411280405Srpaulo
10412280405Srpaulo
10413280405Srpaulo
10414280405Srpaulo<p>
10415280405Srpaulo<hr><h3><a name="pdf-debug.setlocal"><code>debug.setlocal ([thread,] level, local, value)</code></a></h3>
10416280405Srpaulo
10417280405Srpaulo
10418280405Srpaulo<p>
10419280405SrpauloThis function assigns the value <code>value</code> to the local variable
10420280405Srpaulowith index <code>local</code> of the function at level <code>level</code> of the stack.
10421280405SrpauloThe function returns <b>nil</b> if there is no local
10422280405Srpaulovariable with the given index,
10423280405Srpauloand raises an error when called with a <code>level</code> out of range.
10424280405Srpaulo(You can call <code>getinfo</code> to check whether the level is valid.)
10425280405SrpauloOtherwise, it returns the name of the local variable.
10426280405Srpaulo
10427280405Srpaulo
10428280405Srpaulo<p>
10429280405SrpauloSee <a href="#pdf-debug.getlocal"><code>debug.getlocal</code></a> for more information about
10430280405Srpaulovariable indices and names.
10431280405Srpaulo
10432280405Srpaulo
10433280405Srpaulo
10434280405Srpaulo
10435280405Srpaulo<p>
10436280405Srpaulo<hr><h3><a name="pdf-debug.setmetatable"><code>debug.setmetatable (value, table)</code></a></h3>
10437280405Srpaulo
10438280405Srpaulo
10439280405Srpaulo<p>
10440280405SrpauloSets the metatable for the given <code>value</code> to the given <code>table</code>
10441280405Srpaulo(which can be <b>nil</b>).
10442280405SrpauloReturns <code>value</code>.
10443280405Srpaulo
10444280405Srpaulo
10445280405Srpaulo
10446280405Srpaulo
10447280405Srpaulo<p>
10448280405Srpaulo<hr><h3><a name="pdf-debug.setupvalue"><code>debug.setupvalue (f, up, value)</code></a></h3>
10449280405Srpaulo
10450280405Srpaulo
10451280405Srpaulo<p>
10452280405SrpauloThis function assigns the value <code>value</code> to the upvalue
10453280405Srpaulowith index <code>up</code> of the function <code>f</code>.
10454280405SrpauloThe function returns <b>nil</b> if there is no upvalue
10455280405Srpaulowith the given index.
10456280405SrpauloOtherwise, it returns the name of the upvalue.
10457280405Srpaulo
10458280405Srpaulo
10459280405Srpaulo
10460280405Srpaulo
10461280405Srpaulo<p>
10462280405Srpaulo<hr><h3><a name="pdf-debug.setuservalue"><code>debug.setuservalue (udata, value)</code></a></h3>
10463280405Srpaulo
10464280405Srpaulo
10465280405Srpaulo<p>
10466280405SrpauloSets the given <code>value</code> as
10467280405Srpaulothe Lua value associated to the given <code>udata</code>.
10468280405Srpaulo<code>udata</code> must be a full userdata.
10469280405Srpaulo
10470280405Srpaulo
10471280405Srpaulo<p>
10472280405SrpauloReturns <code>udata</code>.
10473280405Srpaulo
10474280405Srpaulo
10475280405Srpaulo
10476280405Srpaulo
10477280405Srpaulo<p>
10478280405Srpaulo<hr><h3><a name="pdf-debug.traceback"><code>debug.traceback ([thread,] [message [, level]])</code></a></h3>
10479280405Srpaulo
10480280405Srpaulo
10481280405Srpaulo<p>
10482280405SrpauloIf <code>message</code> is present but is neither a string nor <b>nil</b>,
10483280405Srpaulothis function returns <code>message</code> without further processing.
10484280405SrpauloOtherwise,
10485280405Srpauloit returns a string with a traceback of the call stack.
10486280405SrpauloThe optional <code>message</code> string is appended
10487280405Srpauloat the beginning of the traceback.
10488280405SrpauloAn optional <code>level</code> number tells at which level
10489280405Srpauloto start the traceback
10490280405Srpaulo(default is 1, the function calling <code>traceback</code>).
10491280405Srpaulo
10492280405Srpaulo
10493280405Srpaulo
10494280405Srpaulo
10495280405Srpaulo<p>
10496280405Srpaulo<hr><h3><a name="pdf-debug.upvalueid"><code>debug.upvalueid (f, n)</code></a></h3>
10497280405Srpaulo
10498280405Srpaulo
10499280405Srpaulo<p>
10500280405SrpauloReturns a unique identifier (as a light userdata)
10501280405Srpaulofor the upvalue numbered <code>n</code>
10502280405Srpaulofrom the given function.
10503280405Srpaulo
10504280405Srpaulo
10505280405Srpaulo<p>
10506280405SrpauloThese unique identifiers allow a program to check whether different
10507280405Srpauloclosures share upvalues.
10508280405SrpauloLua closures that share an upvalue
10509280405Srpaulo(that is, that access a same external local variable)
10510280405Srpaulowill return identical ids for those upvalue indices.
10511280405Srpaulo
10512280405Srpaulo
10513280405Srpaulo
10514280405Srpaulo
10515280405Srpaulo<p>
10516280405Srpaulo<hr><h3><a name="pdf-debug.upvaluejoin"><code>debug.upvaluejoin (f1, n1, f2, n2)</code></a></h3>
10517280405Srpaulo
10518280405Srpaulo
10519280405Srpaulo<p>
10520280405SrpauloMake the <code>n1</code>-th upvalue of the Lua closure <code>f1</code>
10521280405Srpaulorefer to the <code>n2</code>-th upvalue of the Lua closure <code>f2</code>.
10522280405Srpaulo
10523280405Srpaulo
10524280405Srpaulo
10525280405Srpaulo
10526280405Srpaulo
10527280405Srpaulo
10528280405Srpaulo
10529280405Srpaulo<h1>7 &ndash; <a name="7">Lua Standalone</a></h1>
10530280405Srpaulo
10531280405Srpaulo<p>
10532280405SrpauloAlthough Lua has been designed as an extension language,
10533280405Srpauloto be embedded in a host C&nbsp;program,
10534280405Srpauloit is also frequently used as a standalone language.
10535280405SrpauloAn interpreter for Lua as a standalone language,
10536280405Srpaulocalled simply <code>lua</code>,
10537280405Srpaulois provided with the standard distribution.
10538280405SrpauloThe standalone interpreter includes
10539280405Srpauloall standard libraries, including the debug library.
10540280405SrpauloIts usage is:
10541280405Srpaulo
10542280405Srpaulo<pre>
10543280405Srpaulo     lua [options] [script [args]]
10544280405Srpaulo</pre><p>
10545280405SrpauloThe options are:
10546280405Srpaulo
10547280405Srpaulo<ul>
10548280405Srpaulo<li><b><code>-e <em>stat</em></code>: </b> executes string <em>stat</em>;</li>
10549344220Skevans<li><b><code>-l <em>mod</em></code>: </b> "requires" <em>mod</em> and assigns the
10550344220Skevans  result to global @<em>mod</em>;</li>
10551280405Srpaulo<li><b><code>-i</code>: </b> enters interactive mode after running <em>script</em>;</li>
10552280405Srpaulo<li><b><code>-v</code>: </b> prints version information;</li>
10553280405Srpaulo<li><b><code>-E</code>: </b> ignores environment variables;</li>
10554280405Srpaulo<li><b><code>--</code>: </b> stops handling options;</li>
10555280405Srpaulo<li><b><code>-</code>: </b> executes <code>stdin</code> as a file and stops handling options.</li>
10556280405Srpaulo</ul><p>
10557280405SrpauloAfter handling its options, <code>lua</code> runs the given <em>script</em>.
10558280405SrpauloWhen called without arguments,
10559280405Srpaulo<code>lua</code> behaves as <code>lua -v -i</code>
10560280405Srpaulowhen the standard input (<code>stdin</code>) is a terminal,
10561280405Srpauloand as <code>lua -</code> otherwise.
10562280405Srpaulo
10563280405Srpaulo
10564280405Srpaulo<p>
10565326344SimpWhen called without option <code>-E</code>,
10566280405Srpaulothe interpreter checks for an environment variable <a name="pdf-LUA_INIT_5_3"><code>LUA_INIT_5_3</code></a>
10567280405Srpaulo(or <a name="pdf-LUA_INIT"><code>LUA_INIT</code></a> if the versioned name is not defined)
10568280405Srpaulobefore running any argument.
10569280405SrpauloIf the variable content has the format <code>@<em>filename</em></code>,
10570280405Srpaulothen <code>lua</code> executes the file.
10571280405SrpauloOtherwise, <code>lua</code> executes the string itself.
10572280405Srpaulo
10573280405Srpaulo
10574280405Srpaulo<p>
10575280405SrpauloWhen called with option <code>-E</code>,
10576280405Srpaulobesides ignoring <code>LUA_INIT</code>,
10577280405SrpauloLua also ignores
10578280405Srpaulothe values of <code>LUA_PATH</code> and <code>LUA_CPATH</code>,
10579280405Srpaulosetting the values of
10580280405Srpaulo<a href="#pdf-package.path"><code>package.path</code></a> and <a href="#pdf-package.cpath"><code>package.cpath</code></a>
10581280405Srpaulowith the default paths defined in <code>luaconf.h</code>.
10582280405Srpaulo
10583280405Srpaulo
10584280405Srpaulo<p>
10585280405SrpauloAll options are handled in order, except <code>-i</code> and <code>-E</code>.
10586280405SrpauloFor instance, an invocation like
10587280405Srpaulo
10588280405Srpaulo<pre>
10589280405Srpaulo     $ lua -e'a=1' -e 'print(a)' script.lua
10590280405Srpaulo</pre><p>
10591280405Srpaulowill first set <code>a</code> to 1, then print the value of <code>a</code>,
10592280405Srpauloand finally run the file <code>script.lua</code> with no arguments.
10593280405Srpaulo(Here <code>$</code> is the shell prompt. Your prompt may be different.)
10594280405Srpaulo
10595280405Srpaulo
10596280405Srpaulo<p>
10597280405SrpauloBefore running any code,
10598280405Srpaulo<code>lua</code> collects all command-line arguments
10599280405Srpauloin a global table called <code>arg</code>.
10600280405SrpauloThe script name goes to index 0,
10601280405Srpaulothe first argument after the script name goes to index 1,
10602280405Srpauloand so on.
10603280405SrpauloAny arguments before the script name
10604280405Srpaulo(that is, the interpreter name plus its options)
10605280405Srpaulogo to negative indices.
10606280405SrpauloFor instance, in the call
10607280405Srpaulo
10608280405Srpaulo<pre>
10609280405Srpaulo     $ lua -la b.lua t1 t2
10610280405Srpaulo</pre><p>
10611280405Srpaulothe table is like this:
10612280405Srpaulo
10613280405Srpaulo<pre>
10614280405Srpaulo     arg = { [-2] = "lua", [-1] = "-la",
10615280405Srpaulo             [0] = "b.lua",
10616280405Srpaulo             [1] = "t1", [2] = "t2" }
10617280405Srpaulo</pre><p>
10618280405SrpauloIf there is no script in the call,
10619280405Srpaulothe interpreter name goes to index 0,
10620280405Srpaulofollowed by the other arguments.
10621280405SrpauloFor instance, the call
10622280405Srpaulo
10623280405Srpaulo<pre>
10624280405Srpaulo     $ lua -e "print(arg[1])"
10625280405Srpaulo</pre><p>
10626280405Srpaulowill print "<code>-e</code>".
10627280405SrpauloIf there is a script,
10628344220Skevansthe script is called with arguments
10629280405Srpaulo<code>arg[1]</code>, &middot;&middot;&middot;, <code>arg[#arg]</code>.
10630280405Srpaulo(Like all chunks in Lua,
10631280405Srpaulothe script is compiled as a vararg function.)
10632280405Srpaulo
10633280405Srpaulo
10634280405Srpaulo<p>
10635280405SrpauloIn interactive mode,
10636280405SrpauloLua repeatedly prompts and waits for a line.
10637280405SrpauloAfter reading a line,
10638280405SrpauloLua first try to interpret the line as an expression.
10639280405SrpauloIf it succeeds, it prints its value.
10640280405SrpauloOtherwise, it interprets the line as a statement.
10641280405SrpauloIf you write an incomplete statement,
10642280405Srpaulothe interpreter waits for its completion
10643280405Srpauloby issuing a different prompt.
10644280405Srpaulo
10645280405Srpaulo
10646280405Srpaulo<p>
10647326344SimpIf the global variable <a name="pdf-_PROMPT"><code>_PROMPT</code></a> contains a string,
10648326344Simpthen its value is used as the prompt.
10649326344SimpSimilarly, if the global variable <a name="pdf-_PROMPT2"><code>_PROMPT2</code></a> contains a string,
10650326344Simpits value is used as the secondary prompt
10651326344Simp(issued during incomplete statements).
10652326344Simp
10653326344Simp
10654326344Simp<p>
10655280405SrpauloIn case of unprotected errors in the script,
10656280405Srpaulothe interpreter reports the error to the standard error stream.
10657326344SimpIf the error object is not a string but
10658280405Srpaulohas a metamethod <code>__tostring</code>,
10659280405Srpaulothe interpreter calls this metamethod to produce the final message.
10660280405SrpauloOtherwise, the interpreter converts the error object to a string
10661280405Srpauloand adds a stack traceback to it.
10662280405Srpaulo
10663280405Srpaulo
10664280405Srpaulo<p>
10665280405SrpauloWhen finishing normally,
10666280405Srpaulothe interpreter closes its main Lua state
10667280405Srpaulo(see <a href="#lua_close"><code>lua_close</code></a>).
10668280405SrpauloThe script can avoid this step by
10669280405Srpaulocalling <a href="#pdf-os.exit"><code>os.exit</code></a> to terminate.
10670280405Srpaulo
10671280405Srpaulo
10672280405Srpaulo<p>
10673280405SrpauloTo allow the use of Lua as a
10674280405Srpauloscript interpreter in Unix systems,
10675280405Srpaulothe standalone interpreter skips
10676280405Srpaulothe first line of a chunk if it starts with <code>#</code>.
10677280405SrpauloTherefore, Lua scripts can be made into executable programs
10678280405Srpauloby using <code>chmod +x</code> and the&nbsp;<code>#!</code> form,
10679280405Srpauloas in
10680280405Srpaulo
10681280405Srpaulo<pre>
10682280405Srpaulo     #!/usr/local/bin/lua
10683280405Srpaulo</pre><p>
10684280405Srpaulo(Of course,
10685280405Srpaulothe location of the Lua interpreter may be different in your machine.
10686280405SrpauloIf <code>lua</code> is in your <code>PATH</code>,
10687280405Srpaulothen
10688280405Srpaulo
10689280405Srpaulo<pre>
10690280405Srpaulo     #!/usr/bin/env lua
10691280405Srpaulo</pre><p>
10692280405Srpaulois a more portable solution.)
10693280405Srpaulo
10694280405Srpaulo
10695280405Srpaulo
10696280405Srpaulo<h1>8 &ndash; <a name="8">Incompatibilities with the Previous Version</a></h1>
10697280405Srpaulo
10698280405Srpaulo<p>
10699280405SrpauloHere we list the incompatibilities that you may find when moving a program
10700280405Srpaulofrom Lua&nbsp;5.2 to Lua&nbsp;5.3.
10701280405SrpauloYou can avoid some incompatibilities by compiling Lua with
10702280405Srpauloappropriate options (see file <code>luaconf.h</code>).
10703280405SrpauloHowever,
10704280405Srpauloall these compatibility options will be removed in the future.
10705280405Srpaulo
10706280405Srpaulo
10707280405Srpaulo<p>
10708280405SrpauloLua versions can always change the C API in ways that
10709280405Srpaulodo not imply source-code changes in a program,
10710280405Srpaulosuch as the numeric values for constants
10711280405Srpauloor the implementation of functions as macros.
10712280405SrpauloTherefore,
10713280405Srpauloyou should not assume that binaries are compatible between
10714280405Srpaulodifferent Lua versions.
10715280405SrpauloAlways recompile clients of the Lua API when
10716280405Srpaulousing a new version.
10717280405Srpaulo
10718280405Srpaulo
10719280405Srpaulo<p>
10720280405SrpauloSimilarly, Lua versions can always change the internal representation
10721280405Srpauloof precompiled chunks;
10722280405Srpauloprecompiled chunks are not compatible between different Lua versions.
10723280405Srpaulo
10724280405Srpaulo
10725280405Srpaulo<p>
10726280405SrpauloThe standard paths in the official distribution may
10727280405Srpaulochange between versions.
10728280405Srpaulo
10729280405Srpaulo
10730280405Srpaulo
10731280405Srpaulo<h2>8.1 &ndash; <a name="8.1">Changes in the Language</a></h2>
10732280405Srpaulo<ul>
10733280405Srpaulo
10734280405Srpaulo<li>
10735280405SrpauloThe main difference between Lua&nbsp;5.2 and Lua&nbsp;5.3 is the
10736280405Srpaulointroduction of an integer subtype for numbers.
10737280405SrpauloAlthough this change should not affect "normal" computations,
10738280405Srpaulosome computations
10739280405Srpaulo(mainly those that involve some kind of overflow)
10740280405Srpaulocan give different results.
10741280405Srpaulo
10742280405Srpaulo
10743280405Srpaulo<p>
10744280405SrpauloYou can fix these differences by forcing a number to be a float
10745280405Srpaulo(in Lua&nbsp;5.2 all numbers were float),
10746280405Srpauloin particular writing constants with an ending <code>.0</code>
10747280405Srpauloor using <code>x = x + 0.0</code> to convert a variable.
10748280405Srpaulo(This recommendation is only for a quick fix
10749280405Srpaulofor an occasional incompatibility;
10750280405Srpauloit is not a general guideline for good programming.
10751280405SrpauloFor good programming,
10752280405Srpaulouse floats where you need floats
10753280405Srpauloand integers where you need integers.)
10754280405Srpaulo</li>
10755280405Srpaulo
10756280405Srpaulo<li>
10757280405SrpauloThe conversion of a float to a string now adds a <code>.0</code> suffix
10758280405Srpauloto the result if it looks like an integer.
10759280405Srpaulo(For instance, the float 2.0 will be printed as <code>2.0</code>,
10760280405Srpaulonot as <code>2</code>.)
10761280405SrpauloYou should always use an explicit format
10762280405Srpaulowhen you need a specific format for numbers.
10763280405Srpaulo
10764280405Srpaulo
10765280405Srpaulo<p>
10766280405Srpaulo(Formally this is not an incompatibility,
10767280405Srpaulobecause Lua does not specify how numbers are formatted as strings,
10768280405Srpaulobut some programs assumed a specific format.)
10769280405Srpaulo</li>
10770280405Srpaulo
10771280405Srpaulo<li>
10772280405SrpauloThe generational mode for the garbage collector was removed.
10773280405Srpaulo(It was an experimental feature in Lua&nbsp;5.2.)
10774280405Srpaulo</li>
10775280405Srpaulo
10776280405Srpaulo</ul>
10777280405Srpaulo
10778280405Srpaulo
10779280405Srpaulo
10780280405Srpaulo
10781280405Srpaulo<h2>8.2 &ndash; <a name="8.2">Changes in the Libraries</a></h2>
10782280405Srpaulo<ul>
10783280405Srpaulo
10784280405Srpaulo<li>
10785280405SrpauloThe <code>bit32</code> library has been deprecated.
10786280405SrpauloIt is easy to require a compatible external library or,
10787280405Srpaulobetter yet, to replace its functions with appropriate bitwise operations.
10788280405Srpaulo(Keep in mind that <code>bit32</code> operates on 32-bit integers,
10789326344Simpwhile the bitwise operators in Lua&nbsp;5.3 operate on Lua integers,
10790326344Simpwhich by default have 64&nbsp;bits.)
10791280405Srpaulo</li>
10792280405Srpaulo
10793280405Srpaulo<li>
10794280405SrpauloThe Table library now respects metamethods
10795280405Srpaulofor setting and getting elements.
10796280405Srpaulo</li>
10797280405Srpaulo
10798280405Srpaulo<li>
10799280405SrpauloThe <a href="#pdf-ipairs"><code>ipairs</code></a> iterator now respects metamethods and
10800280405Srpauloits <code>__ipairs</code> metamethod has been deprecated.
10801280405Srpaulo</li>
10802280405Srpaulo
10803280405Srpaulo<li>
10804280405SrpauloOption names in <a href="#pdf-io.read"><code>io.read</code></a> do not have a starting '<code>*</code>' anymore.
10805326344SimpFor compatibility, Lua will continue to accept (and ignore) this character.
10806280405Srpaulo</li>
10807280405Srpaulo
10808280405Srpaulo<li>
10809280405SrpauloThe following functions were deprecated in the mathematical library:
10810280405Srpaulo<code>atan2</code>, <code>cosh</code>, <code>sinh</code>, <code>tanh</code>, <code>pow</code>,
10811280405Srpaulo<code>frexp</code>, and <code>ldexp</code>.
10812280405SrpauloYou can replace <code>math.pow(x,y)</code> with <code>x^y</code>;
10813280405Srpauloyou can replace <code>math.atan2</code> with <code>math.atan</code>,
10814344220Skevanswhich now accepts one or two arguments;
10815280405Srpauloyou can replace <code>math.ldexp(x,exp)</code> with <code>x * 2.0^exp</code>.
10816280405SrpauloFor the other operations,
10817280405Srpauloyou can either use an external library or
10818280405Srpauloimplement them in Lua.
10819280405Srpaulo</li>
10820280405Srpaulo
10821280405Srpaulo<li>
10822280405SrpauloThe searcher for C loaders used by <a href="#pdf-require"><code>require</code></a>
10823280405Srpaulochanged the way it handles versioned names.
10824280405SrpauloNow, the version should come after the module name
10825280405Srpaulo(as is usual in most other tools).
10826280405SrpauloFor compatibility, that searcher still tries the old format
10827280405Srpauloif it cannot find an open function according to the new style.
10828280405Srpaulo(Lua&nbsp;5.2 already worked that way,
10829280405Srpaulobut it did not document the change.)
10830280405Srpaulo</li>
10831280405Srpaulo
10832326344Simp<li>
10833326344SimpThe call <code>collectgarbage("count")</code> now returns only one result.
10834326344Simp(You can compute that second result from the fractional part
10835326344Simpof the first result.)
10836326344Simp</li>
10837326344Simp
10838280405Srpaulo</ul>
10839280405Srpaulo
10840280405Srpaulo
10841280405Srpaulo
10842280405Srpaulo
10843280405Srpaulo<h2>8.3 &ndash; <a name="8.3">Changes in the API</a></h2>
10844280405Srpaulo
10845280405Srpaulo
10846280405Srpaulo<ul>
10847280405Srpaulo
10848280405Srpaulo<li>
10849344220SkevansContinuation functions now receive as arguments what they needed
10850280405Srpauloto get through <code>lua_getctx</code>,
10851280405Srpauloso <code>lua_getctx</code> has been removed.
10852280405SrpauloAdapt your code accordingly.
10853280405Srpaulo</li>
10854280405Srpaulo
10855280405Srpaulo<li>
10856280405SrpauloFunction <a href="#lua_dump"><code>lua_dump</code></a> has an extra parameter, <code>strip</code>.
10857280405SrpauloUse 0 as the value of this parameter to get the old behavior.
10858280405Srpaulo</li>
10859280405Srpaulo
10860280405Srpaulo<li>
10861280405SrpauloFunctions to inject/project unsigned integers
10862280405Srpaulo(<code>lua_pushunsigned</code>, <code>lua_tounsigned</code>, <code>lua_tounsignedx</code>,
10863280405Srpaulo<code>luaL_checkunsigned</code>, <code>luaL_optunsigned</code>)
10864280405Srpaulowere deprecated.
10865280405SrpauloUse their signed equivalents with a type cast.
10866280405Srpaulo</li>
10867280405Srpaulo
10868280405Srpaulo<li>
10869280405SrpauloMacros to project non-default integer types
10870280405Srpaulo(<code>luaL_checkint</code>, <code>luaL_optint</code>, <code>luaL_checklong</code>, <code>luaL_optlong</code>)
10871280405Srpaulowere deprecated.
10872280405SrpauloUse their equivalent over <a href="#lua_Integer"><code>lua_Integer</code></a> with a type cast
10873280405Srpaulo(or, when possible, use <a href="#lua_Integer"><code>lua_Integer</code></a> in your code).
10874280405Srpaulo</li>
10875280405Srpaulo
10876280405Srpaulo</ul>
10877280405Srpaulo
10878280405Srpaulo
10879280405Srpaulo
10880280405Srpaulo
10881280405Srpaulo<h1>9 &ndash; <a name="9">The Complete Syntax of Lua</a></h1>
10882280405Srpaulo
10883280405Srpaulo<p>
10884280405SrpauloHere is the complete syntax of Lua in extended BNF.
10885280405SrpauloAs usual in extended BNF,
10886280405Srpaulo{A} means 0 or more As,
10887280405Srpauloand [A] means an optional A.
10888280405Srpaulo(For operator precedences, see <a href="#3.4.8">&sect;3.4.8</a>;
10889280405Srpaulofor a description of the terminals
10890280405SrpauloName, Numeral,
10891280405Srpauloand LiteralString, see <a href="#3.1">&sect;3.1</a>.)
10892280405Srpaulo
10893280405Srpaulo
10894280405Srpaulo
10895280405Srpaulo
10896280405Srpaulo<pre>
10897280405Srpaulo
10898280405Srpaulo	chunk ::= block
10899280405Srpaulo
10900280405Srpaulo	block ::= {stat} [retstat]
10901280405Srpaulo
10902280405Srpaulo	stat ::=  &lsquo;<b>;</b>&rsquo; | 
10903280405Srpaulo		 varlist &lsquo;<b>=</b>&rsquo; explist | 
10904280405Srpaulo		 functioncall | 
10905280405Srpaulo		 label | 
10906280405Srpaulo		 <b>break</b> | 
10907280405Srpaulo		 <b>goto</b> Name | 
10908280405Srpaulo		 <b>do</b> block <b>end</b> | 
10909280405Srpaulo		 <b>while</b> exp <b>do</b> block <b>end</b> | 
10910280405Srpaulo		 <b>repeat</b> block <b>until</b> exp | 
10911280405Srpaulo		 <b>if</b> exp <b>then</b> block {<b>elseif</b> exp <b>then</b> block} [<b>else</b> block] <b>end</b> | 
10912280405Srpaulo		 <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> | 
10913280405Srpaulo		 <b>for</b> namelist <b>in</b> explist <b>do</b> block <b>end</b> | 
10914280405Srpaulo		 <b>function</b> funcname funcbody | 
10915280405Srpaulo		 <b>local</b> <b>function</b> Name funcbody | 
10916280405Srpaulo		 <b>local</b> namelist [&lsquo;<b>=</b>&rsquo; explist] 
10917280405Srpaulo
10918280405Srpaulo	retstat ::= <b>return</b> [explist] [&lsquo;<b>;</b>&rsquo;]
10919280405Srpaulo
10920280405Srpaulo	label ::= &lsquo;<b>::</b>&rsquo; Name &lsquo;<b>::</b>&rsquo;
10921280405Srpaulo
10922280405Srpaulo	funcname ::= Name {&lsquo;<b>.</b>&rsquo; Name} [&lsquo;<b>:</b>&rsquo; Name]
10923280405Srpaulo
10924280405Srpaulo	varlist ::= var {&lsquo;<b>,</b>&rsquo; var}
10925280405Srpaulo
10926280405Srpaulo	var ::=  Name | prefixexp &lsquo;<b>[</b>&rsquo; exp &lsquo;<b>]</b>&rsquo; | prefixexp &lsquo;<b>.</b>&rsquo; Name 
10927280405Srpaulo
10928280405Srpaulo	namelist ::= Name {&lsquo;<b>,</b>&rsquo; Name}
10929280405Srpaulo
10930280405Srpaulo	explist ::= exp {&lsquo;<b>,</b>&rsquo; exp}
10931280405Srpaulo
10932280405Srpaulo	exp ::=  <b>nil</b> | <b>false</b> | <b>true</b> | Numeral | LiteralString | &lsquo;<b>...</b>&rsquo; | functiondef | 
10933280405Srpaulo		 prefixexp | tableconstructor | exp binop exp | unop exp 
10934280405Srpaulo
10935280405Srpaulo	prefixexp ::= var | functioncall | &lsquo;<b>(</b>&rsquo; exp &lsquo;<b>)</b>&rsquo;
10936280405Srpaulo
10937280405Srpaulo	functioncall ::=  prefixexp args | prefixexp &lsquo;<b>:</b>&rsquo; Name args 
10938280405Srpaulo
10939280405Srpaulo	args ::=  &lsquo;<b>(</b>&rsquo; [explist] &lsquo;<b>)</b>&rsquo; | tableconstructor | LiteralString 
10940280405Srpaulo
10941280405Srpaulo	functiondef ::= <b>function</b> funcbody
10942280405Srpaulo
10943280405Srpaulo	funcbody ::= &lsquo;<b>(</b>&rsquo; [parlist] &lsquo;<b>)</b>&rsquo; block <b>end</b>
10944280405Srpaulo
10945280405Srpaulo	parlist ::= namelist [&lsquo;<b>,</b>&rsquo; &lsquo;<b>...</b>&rsquo;] | &lsquo;<b>...</b>&rsquo;
10946280405Srpaulo
10947280405Srpaulo	tableconstructor ::= &lsquo;<b>{</b>&rsquo; [fieldlist] &lsquo;<b>}</b>&rsquo;
10948280405Srpaulo
10949280405Srpaulo	fieldlist ::= field {fieldsep field} [fieldsep]
10950280405Srpaulo
10951280405Srpaulo	field ::= &lsquo;<b>[</b>&rsquo; exp &lsquo;<b>]</b>&rsquo; &lsquo;<b>=</b>&rsquo; exp | Name &lsquo;<b>=</b>&rsquo; exp | exp
10952280405Srpaulo
10953280405Srpaulo	fieldsep ::= &lsquo;<b>,</b>&rsquo; | &lsquo;<b>;</b>&rsquo;
10954280405Srpaulo
10955280405Srpaulo	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; | 
10956280405Srpaulo		 &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; | 
10957280405Srpaulo		 &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; | 
10958280405Srpaulo		 <b>and</b> | <b>or</b>
10959280405Srpaulo
10960280405Srpaulo	unop ::= &lsquo;<b>-</b>&rsquo; | <b>not</b> | &lsquo;<b>#</b>&rsquo; | &lsquo;<b>~</b>&rsquo;
10961280405Srpaulo
10962280405Srpaulo</pre>
10963280405Srpaulo
10964280405Srpaulo<p>
10965280405Srpaulo
10966280405Srpaulo
10967280405Srpaulo
10968280405Srpaulo
10969280405Srpaulo
10970280405Srpaulo
10971280405Srpaulo
10972344220Skevans
10973326344Simp<P CLASS="footer">
10974280405SrpauloLast update:
10975344220SkevansTue Jun 26 13:16:37 -03 2018
10976326344Simp</P>
10977280405Srpaulo<!--
10978344220SkevansLast change: revised for Lua 5.3.5
10979280405Srpaulo-->
10980280405Srpaulo
10981280405Srpaulo</body></html>
10982280405Srpaulo
10983