git.saurik.com Git - redis.git/blame - deps/lua/doc/manual.html

Commit	Line	Data
21d3294c	1	<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
	2	<html>
	3
	4	<head>
	5	<title>Lua 5.1 Reference Manual</title>
	6	<link rel="stylesheet" type="text/css" href="lua.css">
	7	<link rel="stylesheet" type="text/css" href="manual.css">
	8	<META HTTP-EQUIV="content-type" CONTENT="text/html; charset=iso-8859-1">
	9	</head>
	10
	11	<body>
	12
	13	<hr>
	14	<h1>
	15	<a href="http://www.lua.org/"><img src="logo.gif" alt="" border="0"></a>
	16	Lua 5.1 Reference Manual
	17	</h1>
	18
	19	by Roberto Ierusalimschy, Luiz Henrique de Figueiredo, Waldemar Celes
	20	<p>
	21	<small>
	22	Copyright © 2006-2008 Lua.org, PUC-Rio.
	23	Freely available under the terms of the
	24	<a href="http://www.lua.org/license.html#5">Lua license</a>.
	25	</small>
	26	<hr>
	27	<p>
	28
	29	<a href="contents.html#contents">contents</A>
	30	·
	31	<a href="contents.html#index">index</A>
	32
	33	<!-- ====================================================================== -->
	34	<p>
	35
	36	<!-- $Id: manual.of,v 1.48 2008/08/18 15:24:20 roberto Exp $ -->
	37
	38
	39
	40
	41	<h1>1 - <a name="1">Introduction</a></h1>
	42
	43	<p>
	44	Lua is an extension programming language designed to support
	45	general procedural programming with data description
	46	facilities.
	47	It also offers good support for object-oriented programming,
	48	functional programming, and data-driven programming.
	49	Lua is intended to be used as a powerful, light-weight
	50	scripting language for any program that needs one.
	51	Lua is implemented as a library, written in <em>clean</em> C
	52	(that is, in the common subset of ANSI C and C++).
	53
	54
	55	<p>
	56	Being an extension language, Lua has no notion of a "main" program:
	57	it only works <em>embedded</em> in a host client,
	58	called the <em>embedding program</em> or simply the <em>host</em>.
	59	This host program can invoke functions to execute a piece of Lua code,
	60	can write and read Lua variables,
	61	and can register C functions to be called by Lua code.
	62	Through the use of C functions, Lua can be augmented to cope with
	63	a wide range of different domains,
	64	thus creating customized programming languages sharing a syntactical framework.
65	The Lua distribution includes a sample host program called <code>lua</code>,
66	which uses the Lua library to offer a complete, stand-alone Lua interpreter.
67
68
69	<p>
70	Lua is free software,
71	and is provided as usual with no guarantees,
72	as stated in its license.
73	The implementation described in this manual is available
74	at Lua's official web site, <code>www.lua.org</code>.
75
76
77	<p>
78	Like any other reference manual,
79	this document is dry in places.
80	For a discussion of the decisions behind the design of Lua,
81	see the technical papers available at Lua's web site.
82	For a detailed introduction to programming in Lua,
83	see Roberto's book, <em>Programming in Lua (Second Edition)</em>.
84
85
86
87	<h1>2 - <a name="2">The Language</a></h1>
88
89	<p>
90	This section describes the lexis, the syntax, and the semantics of Lua.
91	In other words,
92	this section describes
93	which tokens are valid,
94	how they can be combined,
95	and what their combinations mean.
96
97
98	<p>
99	The language constructs will be explained using the usual extended BNF notation,
100	in which
101	{<em>a</em>} means 0 or more <em>a</em>'s, and
102	[<em>a</em>] means an optional <em>a</em>.
103	Non-terminals are shown like non-terminal,
104	keywords are shown like <b>kword</b>,
105	and other terminal symbols are shown like `<b>=</b>´.
106	The complete syntax of Lua can be found in <a href="#8">§8</a>
107	at the end of this manual.
108
109
110
111	<h2>2.1 - <a name="2.1">Lexical Conventions</a></h2>
112
113	<p>
114	<em>Names</em>
115	(also called <em>identifiers</em>)
116	in Lua can be any string of letters,
117	digits, and underscores,
118	not beginning with a digit.
119	This coincides with the definition of names in most languages.
120	(The definition of letter depends on the current locale:
121	any character considered alphabetic by the current locale
122	can be used in an identifier.)
123	Identifiers are used to name variables and table fields.
124
125
126	<p>
127	The following <em>keywords</em> are reserved
128	and cannot be used as names:
129
130
131	<pre>
132	and break do else elseif
133	end false for function if
134	in local nil not or
135	repeat return then true until while
136	</pre>
137
138	<p>
139	Lua is a case-sensitive language:
140	<code>and</code> is a reserved word, but <code>And</code> and <code>AND</code>
141	are two different, valid names.
142	As a convention, names starting with an underscore followed by
143	uppercase letters (such as <a href="#pdf-_VERSION"><code>_VERSION</code></a>)
144	are reserved for internal global variables used by Lua.
145
146
147	<p>
148	The following strings denote other tokens:
149
150	<pre>
151	+ - * / % ^ #
152	== ~= <= >= < > =
153	( ) { } [ ]
154	; : , . .. ...
155	</pre>
156
157	<p>
158	<em>Literal strings</em>
159	can be delimited by matching single or double quotes,
160	and can contain the following C-like escape sequences:
161	'<code>\a</code>' (bell),
162	'<code>\b</code>' (backspace),
163	'<code>\f</code>' (form feed),
164	'<code>\n</code>' (newline),
165	'<code>\r</code>' (carriage return),
166	'<code>\t</code>' (horizontal tab),
167	'<code>\v</code>' (vertical tab),
168	'<code>\\</code>' (backslash),
169	'<code>\"</code>' (quotation mark [double quote]),
170	and '<code>\'</code>' (apostrophe [single quote]).
171	Moreover, a backslash followed by a real newline
172	results in a newline in the string.
173	A character in a string can also be specified by its numerical value
174	using the escape sequence <code>\<em>ddd</em></code>,
175	where <em>ddd</em> is a sequence of up to three decimal digits.
176	(Note that if a numerical escape is to be followed by a digit,
177	it must be expressed using exactly three digits.)
178	Strings in Lua can contain any 8-bit value, including embedded zeros,
179	which can be specified as '<code>\0</code>'.
180
181
182	<p>
183	Literal strings can also be defined using a long format
184	enclosed by <em>long brackets</em>.
185	We define an <em>opening long bracket of level <em>n</em></em> as an opening
186	square bracket followed by <em>n</em> equal signs followed by another
187	opening square bracket.
188	So, an opening long bracket of level 0 is written as <code>[[</code>,
189	an opening long bracket of level 1 is written as <code>[=[</code>,
190	and so on.
191	A <em>closing long bracket</em> is defined similarly;
192	for instance, a closing long bracket of level 4 is written as <code>]====]</code>.
193	A long string starts with an opening long bracket of any level and
194	ends at the first closing long bracket of the same level.
195	Literals in this bracketed form can run for several lines,
196	do not interpret any escape sequences,
197	and ignore long brackets of any other level.
198	They can contain anything except a closing bracket of the proper level.
199
200
201	<p>
202	For convenience,
203	when the opening long bracket is immediately followed by a newline,
204	the newline is not included in the string.
205	As an example, in a system using ASCII
206	(in which '<code>a</code>' is coded as 97,
207	newline is coded as 10, and '<code>1</code>' is coded as 49),
208	the five literal strings below denote the same string:
209
210	<pre>
211	a = 'alo\n123"'
212	a = "alo\n123\""
213	a = '\97lo\10\04923"'
214	a = [[alo
215	123"]]
216	a = [==[
217	alo
218	123"]==]
219	</pre>
220
221	<p>
222	A <em>numerical constant</em> can be written with an optional decimal part
223	and an optional decimal exponent.
224	Lua also accepts integer hexadecimal constants,
225	by prefixing them with <code>0x</code>.
226	Examples of valid numerical constants are
227
228	<pre>
229	3 3.0 3.1416 314.16e-2 0.31416E1 0xff 0x56
230	</pre>
231
232	<p>
233	A <em>comment</em> starts with a double hyphen (<code>--</code>)
234	anywhere outside a string.
235	If the text immediately after <code>--</code> is not an opening long bracket,
236	the comment is a <em>short comment</em>,
237	which runs until the end of the line.
238	Otherwise, it is a <em>long comment</em>,
239	which runs until the corresponding closing long bracket.
240	Long comments are frequently used to disable code temporarily.
241
242
243
244
245
246	<h2>2.2 - <a name="2.2">Values and Types</a></h2>
247
248	<p>
249	Lua is a <em>dynamically typed language</em>.
250	This means that
251	variables do not have types; only values do.
252	There are no type definitions in the language.
253	All values carry their own type.
254
255
256	<p>
257	All values in Lua are <em>first-class values</em>.
258	This means that all values can be stored in variables,
259	passed as arguments to other functions, and returned as results.
260
261
262	<p>
263	There are eight basic types in Lua:
264	<em>nil</em>, <em>boolean</em>, <em>number</em>,
265	<em>string</em>, <em>function</em>, <em>userdata</em>,
266	<em>thread</em>, and <em>table</em>.
267	<em>Nil</em> is the type of the value <b>nil</b>,
268	whose main property is to be different from any other value;
269	it usually represents the absence of a useful value.
270	<em>Boolean</em> is the type of the values <b>false</b> and <b>true</b>.
271	Both <b>nil</b> and <b>false</b> make a condition false;
272	any other value makes it true.
273	<em>Number</em> represents real (double-precision floating-point) numbers.
274	(It is easy to build Lua interpreters that use other
275	internal representations for numbers,
276	such as single-precision float or long integers;
277	see file <code>luaconf.h</code>.)
278	<em>String</em> represents arrays of characters.
279
280	Lua is 8-bit clean:
281	strings can contain any 8-bit character,
282	including embedded zeros ('<code>\0</code>') (see <a href="#2.1">§2.1</a>).
283
284
285	<p>
286	Lua can call (and manipulate) functions written in Lua and
287	functions written in C
288	(see <a href="#2.5.8">§2.5.8</a>).
289
290
291	<p>
292	The type <em>userdata</em> is provided to allow arbitrary C data to
293	be stored in Lua variables.
294	This type corresponds to a block of raw memory
295	and has no pre-defined operations in Lua,
296	except assignment and identity test.
297	However, by using <em>metatables</em>,
298	the programmer can define operations for userdata values
299	(see <a href="#2.8">§2.8</a>).
300	Userdata values cannot be created or modified in Lua,
301	only through the C API.
302	This guarantees the integrity of data owned by the host program.
303
304
305	<p>
306	The type <em>thread</em> represents independent threads of execution
307	and it is used to implement coroutines (see <a href="#2.11">§2.11</a>).
308	Do not confuse Lua threads with operating-system threads.
309	Lua supports coroutines on all systems,
310	even those that do not support threads.
311
312
313	<p>
314	The type <em>table</em> implements associative arrays,
315	that is, arrays that can be indexed not only with numbers,
316	but with any value (except <b>nil</b>).
317	Tables can be <em>heterogeneous</em>;
318	that is, they can contain values of all types (except <b>nil</b>).
319	Tables are the sole data structuring mechanism in Lua;
320	they can be used to represent ordinary arrays,
321	symbol tables, sets, records, graphs, trees, etc.
322	To represent records, Lua uses the field name as an index.
323	The language supports this representation by
324	providing <code>a.name</code> as syntactic sugar for <code>a["name"]</code>.
325	There are several convenient ways to create tables in Lua
326	(see <a href="#2.5.7">§2.5.7</a>).
327
328
329	<p>
330	Like indices,
331	the value of a table field can be of any type (except <b>nil</b>).
332	In particular,
333	because functions are first-class values,
334	table fields can contain functions.
335	Thus tables can also carry <em>methods</em> (see <a href="#2.5.9">§2.5.9</a>).
336
337
338	<p>
339	Tables, functions, threads, and (full) userdata values are <em>objects</em>:
340	variables do not actually <em>contain</em> these values,
341	only <em>references</em> to them.
342	Assignment, parameter passing, and function returns
343	always manipulate references to such values;
344	these operations do not imply any kind of copy.
345
346
347	<p>
348	The library function <a href="#pdf-type"><code>type</code></a> returns a string describing the type
349	of a given value.
350
351
352
353	<h3>2.2.1 - <a name="2.2.1">Coercion</a></h3>
354
355	<p>
356	Lua provides automatic conversion between
357	string and number values at run time.
358	Any arithmetic operation applied to a string tries to convert
359	this string to a number, following the usual conversion rules.
360	Conversely, whenever a number is used where a string is expected,
361	the number is converted to a string, in a reasonable format.
362	For complete control over how numbers are converted to strings,
363	use the <code>format</code> function from the string library
364	(see <a href="#pdf-string.format"><code>string.format</code></a>).
365
366
367
368
369
370
371
372	<h2>2.3 - <a name="2.3">Variables</a></h2>
373
374	<p>
375	Variables are places that store values.
376
377	There are three kinds of variables in Lua:
378	global variables, local variables, and table fields.
379
380
381	<p>
382	A single name can denote a global variable or a local variable
383	(or a function's formal parameter,
384	which is a particular kind of local variable):
385
386	<pre>
387	var ::= Name
388	</pre><p>
389	Name denotes identifiers, as defined in <a href="#2.1">§2.1</a>.
390
391
392	<p>
393	Any variable is assumed to be global unless explicitly declared
394	as a local (see <a href="#2.4.7">§2.4.7</a>).
395	Local variables are <em>lexically scoped</em>:
396	local variables can be freely accessed by functions
397	defined inside their scope (see <a href="#2.6">§2.6</a>).
398
399
400	<p>
401	Before the first assignment to a variable, its value is <b>nil</b>.
402
403
404	<p>
405	Square brackets are used to index a table:
406
407	<pre>
408	var ::= prefixexp `<b>[</b>´ exp `<b>]</b>´
409	</pre><p>
410	The meaning of accesses to global variables
411	and table fields can be changed via metatables.
412	An access to an indexed variable <code>t[i]</code> is equivalent to
413	a call <code>gettable_event(t,i)</code>.
414	(See <a href="#2.8">§2.8</a> for a complete description of the
415	<code>gettable_event</code> function.
416	This function is not defined or callable in Lua.
417	We use it here only for explanatory purposes.)
418
419
420	<p>
421	The syntax <code>var.Name</code> is just syntactic sugar for
422	<code>var["Name"]</code>:
423
424	<pre>
425	var ::= prefixexp `<b>.</b>´ Name
426	</pre>
427
428	<p>
429	All global variables live as fields in ordinary Lua tables,
430	called <em>environment tables</em> or simply
431	<em>environments</em> (see <a href="#2.9">§2.9</a>).
432	Each function has its own reference to an environment,
433	so that all global variables in this function
434	will refer to this environment table.
435	When a function is created,
436	it inherits the environment from the function that created it.
437	To get the environment table of a Lua function,
438	you call <a href="#pdf-getfenv"><code>getfenv</code></a>.
439	To replace it,
440	you call <a href="#pdf-setfenv"><code>setfenv</code></a>.
441	(You can only manipulate the environment of C functions
442	through the debug library; (see <a href="#5.9">§5.9</a>).)
443
444
445	<p>
446	An access to a global variable <code>x</code>
447	is equivalent to <code>_env.x</code>,
448	which in turn is equivalent to
449
450	<pre>
451	gettable_event(_env, "x")
452	</pre><p>
453	where <code>_env</code> is the environment of the running function.
454	(See <a href="#2.8">§2.8</a> for a complete description of the
455	<code>gettable_event</code> function.
456	This function is not defined or callable in Lua.
457	Similarly, the <code>_env</code> variable is not defined in Lua.
458	We use them here only for explanatory purposes.)
459
460
461
462
463
464	<h2>2.4 - <a name="2.4">Statements</a></h2>
465
466	<p>
467	Lua supports an almost conventional set of statements,
468	similar to those in Pascal or C.
469	This set includes
470	assignments, control structures, function calls,
471	and variable declarations.
472
473
474
475	<h3>2.4.1 - <a name="2.4.1">Chunks</a></h3>
476
477	<p>
478	The unit of execution of Lua is called a <em>chunk</em>.
479	A chunk is simply a sequence of statements,
480	which are executed sequentially.
481	Each statement can be optionally followed by a semicolon:
482
483	<pre>
484	chunk ::= {stat [`<b>;</b>´]}
485	</pre><p>
486	There are no empty statements and thus '<code>;;</code>' is not legal.
487
488
489	<p>
490	Lua handles a chunk as the body of an anonymous function
491	with a variable number of arguments
492	(see <a href="#2.5.9">§2.5.9</a>).
493	As such, chunks can define local variables,
494	receive arguments, and return values.
495
496
497	<p>
498	A chunk can be stored in a file or in a string inside the host program.
499	To execute a chunk,
500	Lua first pre-compiles the chunk into instructions for a virtual machine,
501	and then it executes the compiled code
502	with an interpreter for the virtual machine.
503
504
505	<p>
506	Chunks can also be pre-compiled into binary form;
507	see program <code>luac</code> for details.
508	Programs in source and compiled forms are interchangeable;
509	Lua automatically detects the file type and acts accordingly.
510
511
512
513
514
515
516	<h3>2.4.2 - <a name="2.4.2">Blocks</a></h3><p>
517	A block is a list of statements;
518	syntactically, a block is the same as a chunk:
519
520	<pre>
521	block ::= chunk
522	</pre>
523
524	<p>
525	A block can be explicitly delimited to produce a single statement:
526
527	<pre>
528	stat ::= <b>do</b> block <b>end</b>
529	</pre><p>
530	Explicit blocks are useful
531	to control the scope of variable declarations.
532	Explicit blocks are also sometimes used to
533	add a <b>return</b> or <b>break</b> statement in the middle
534	of another block (see <a href="#2.4.4">§2.4.4</a>).
535
536
537
538
539
540	<h3>2.4.3 - <a name="2.4.3">Assignment</a></h3>
541
542	<p>
543	Lua allows multiple assignments.
544	Therefore, the syntax for assignment
545	defines a list of variables on the left side
546	and a list of expressions on the right side.
547	The elements in both lists are separated by commas:
548
549	<pre>
550	stat ::= varlist `<b>=</b>´ explist
551	varlist ::= var {`<b>,</b>´ var}
552	explist ::= exp {`<b>,</b>´ exp}
553	</pre><p>
554	Expressions are discussed in <a href="#2.5">§2.5</a>.
555
556
557	<p>
558	Before the assignment,
559	the list of values is <em>adjusted</em> to the length of
560	the list of variables.
561	If there are more values than needed,
562	the excess values are thrown away.
563	If there are fewer values than needed,
564	the list is extended with as many <b>nil</b>'s as needed.
565	If the list of expressions ends with a function call,
566	then all values returned by that call enter the list of values,
567	before the adjustment
568	(except when the call is enclosed in parentheses; see <a href="#2.5">§2.5</a>).
569
570
571	<p>
572	The assignment statement first evaluates all its expressions
573	and only then are the assignments performed.
574	Thus the code
575
576	<pre>
577	i = 3
578	i, a[i] = i+1, 20
579	</pre><p>
580	sets <code>a[3]</code> to 20, without affecting <code>a[4]</code>
581	because the <code>i</code> in <code>a[i]</code> is evaluated (to 3)
582	before it is assigned 4.
583	Similarly, the line
584
585	<pre>
586	x, y = y, x
587	</pre><p>
588	exchanges the values of <code>x</code> and <code>y</code>,
589	and
590
591	<pre>
592	x, y, z = y, z, x
593	</pre><p>
594	cyclically permutes the values of <code>x</code>, <code>y</code>, and <code>z</code>.
595
596
597	<p>
598	The meaning of assignments to global variables
599	and table fields can be changed via metatables.
600	An assignment to an indexed variable <code>t[i] = val</code> is equivalent to
601	<code>settable_event(t,i,val)</code>.
602	(See <a href="#2.8">§2.8</a> for a complete description of the
603	<code>settable_event</code> function.
604	This function is not defined or callable in Lua.
605	We use it here only for explanatory purposes.)
606
607
608	<p>
609	An assignment to a global variable <code>x = val</code>
610	is equivalent to the assignment
611	<code>_env.x = val</code>,
612	which in turn is equivalent to
613
614	<pre>
615	settable_event(_env, "x", val)
616	</pre><p>
617	where <code>_env</code> is the environment of the running function.
618	(The <code>_env</code> variable is not defined in Lua.
619	We use it here only for explanatory purposes.)
620
621
622
623
624
625	<h3>2.4.4 - <a name="2.4.4">Control Structures</a></h3><p>
626	The control structures
627	<b>if</b>, <b>while</b>, and <b>repeat</b> have the usual meaning and
628	familiar syntax:
629
630
631
632
633	<pre>
634	stat ::= <b>while</b> exp <b>do</b> block <b>end</b>
635	stat ::= <b>repeat</b> block <b>until</b> exp
636	stat ::= <b>if</b> exp <b>then</b> block {<b>elseif</b> exp <b>then</b> block} [<b>else</b> block] <b>end</b>
637	</pre><p>
638	Lua also has a <b>for</b> statement, in two flavors (see <a href="#2.4.5">§2.4.5</a>).
639
640
641	<p>
642	The condition expression of a
643	control structure can return any value.
644	Both <b>false</b> and <b>nil</b> are considered false.
645	All values different from <b>nil</b> and <b>false</b> are considered true
646	(in particular, the number 0 and the empty string are also true).
647
648
649	<p>
650	In the <b>repeat</b>–<b>until</b> loop,
651	the inner block does not end at the <b>until</b> keyword,
652	but only after the condition.
653	So, the condition can refer to local variables
654	declared inside the loop block.
655
656
657	<p>
658	The <b>return</b> statement is used to return values
659	from a function or a chunk (which is just a function).
660
661	Functions and chunks can return more than one value,
662	and so the syntax for the <b>return</b> statement is
663
664	<pre>
665	stat ::= <b>return</b> [explist]
666	</pre>
667
668	<p>
669	The <b>break</b> statement is used to terminate the execution of a
670	<b>while</b>, <b>repeat</b>, or <b>for</b> loop,
671	skipping to the next statement after the loop:
672
673
674	<pre>
675	stat ::= <b>break</b>
676	</pre><p>
677	A <b>break</b> ends the innermost enclosing loop.
678
679
680	<p>
681	The <b>return</b> and <b>break</b>
682	statements can only be written as the <em>last</em> statement of a block.
683	If it is really necessary to <b>return</b> or <b>break</b> in the
684	middle of a block,
685	then an explicit inner block can be used,
686	as in the idioms
687	<code>do return end</code> and <code>do break end</code>,
688	because now <b>return</b> and <b>break</b> are the last statements in
689	their (inner) blocks.
690
691
692
693
694
695	<h3>2.4.5 - <a name="2.4.5">For Statement</a></h3>
696
697	<p>
698
699	The <b>for</b> statement has two forms:
700	one numeric and one generic.
701
702
703	<p>
704	The numeric <b>for</b> loop repeats a block of code while a
705	control variable runs through an arithmetic progression.
706	It has the following syntax:
707
708	<pre>
709	stat ::= <b>for</b> Name `<b>=</b>´ exp `<b>,</b>´ exp [`<b>,</b>´ exp] <b>do</b> block <b>end</b>
710	</pre><p>
711	The <em>block</em> is repeated for <em>name</em> starting at the value of
712	the first <em>exp</em>, until it passes the second <em>exp</em> by steps of the
713	third <em>exp</em>.
714	More precisely, a <b>for</b> statement like
715
716	<pre>
717	for v = <em>e1</em>, <em>e2</em>, <em>e3</em> do <em>block</em> end
718	</pre><p>
719	is equivalent to the code:
720
721	<pre>
722	do
723	local <em>var</em>, <em>limit</em>, <em>step</em> = tonumber(<em>e1</em>), tonumber(<em>e2</em>), tonumber(<em>e3</em>)
724	if not (<em>var</em> and <em>limit</em> and <em>step</em>) then error() end
725	while (<em>step</em> > 0 and <em>var</em> <= <em>limit</em>) or (<em>step</em> <= 0 and <em>var</em> >= <em>limit</em>) do
726	local v = <em>var</em>
727	<em>block</em>
728	<em>var</em> = <em>var</em> + <em>step</em>
729	end
730	end
731	</pre><p>
732	Note the following:
733
734	<ul>
735
736	<li>
737	All three control expressions are evaluated only once,
738	before the loop starts.
739	They must all result in numbers.
740	</li>
741
742	<li>
743	<code><em>var</em></code>, <code><em>limit</em></code>, and <code><em>step</em></code> are invisible variables.
744	The names shown here are for explanatory purposes only.
745	</li>
746
747	<li>
748	If the third expression (the step) is absent,
749	then a step of 1 is used.
750	</li>
751
752	<li>
753	You can use <b>break</b> to exit a <b>for</b> loop.
754	</li>
755
756	<li>
757	The loop variable <code>v</code> is local to the loop;
758	you cannot use its value after the <b>for</b> ends or is broken.
759	If you need this value,
760	assign it to another variable before breaking or exiting the loop.
761	</li>
762
763	</ul>
764
765	<p>
766	The generic <b>for</b> statement works over functions,
767	called <em>iterators</em>.
768	On each iteration, the iterator function is called to produce a new value,
769	stopping when this new value is <b>nil</b>.
770	The generic <b>for</b> loop has the following syntax:
771
772	<pre>
773	stat ::= <b>for</b> namelist <b>in</b> explist <b>do</b> block <b>end</b>
774	namelist ::= Name {`<b>,</b>´ Name}
775	</pre><p>
776	A <b>for</b> statement like
777
778	<pre>
779	for <em>var_1</em>, ···, <em>var_n</em> in <em>explist</em> do <em>block</em> end
780	</pre><p>
781	is equivalent to the code:
782
783	<pre>
784	do
785	local <em>f</em>, <em>s</em>, <em>var</em> = <em>explist</em>
786	while true do
787	local <em>var_1</em>, ···, <em>var_n</em> = <em>f</em>(<em>s</em>, <em>var</em>)
788	<em>var</em> = <em>var_1</em>
789	if <em>var</em> == nil then break end
790	<em>block</em>
791	end
792	end
793	</pre><p>
794	Note the following:
795
796	<ul>
797
798	<li>
799	<code><em>explist</em></code> is evaluated only once.
800	Its results are an <em>iterator</em> function,
801	a <em>state</em>,
802	and an initial value for the first <em>iterator variable</em>.
803	</li>
804
805	<li>
806	<code><em>f</em></code>, <code><em>s</em></code>, and <code><em>var</em></code> are invisible variables.
807	The names are here for explanatory purposes only.
808	</li>
809
810	<li>
811	You can use <b>break</b> to exit a <b>for</b> loop.
812	</li>
813
814	<li>
815	The loop variables <code><em>var_i</em></code> are local to the loop;
816	you cannot use their values after the <b>for</b> ends.
817	If you need these values,
818	then assign them to other variables before breaking or exiting the loop.
819	</li>
820
821	</ul>
822
823
824
825
826	<h3>2.4.6 - <a name="2.4.6">Function Calls as Statements</a></h3><p>
827	To allow possible side-effects,
828	function calls can be executed as statements:
829
830	<pre>
831	stat ::= functioncall
832	</pre><p>
833	In this case, all returned values are thrown away.
834	Function calls are explained in <a href="#2.5.8">§2.5.8</a>.
835
836
837
838
839
840	<h3>2.4.7 - <a name="2.4.7">Local Declarations</a></h3><p>
841	Local variables can be declared anywhere inside a block.
842	The declaration can include an initial assignment:
843
844	<pre>
845	stat ::= <b>local</b> namelist [`<b>=</b>´ explist]
846	</pre><p>
847	If present, an initial assignment has the same semantics
848	of a multiple assignment (see <a href="#2.4.3">§2.4.3</a>).
849	Otherwise, all variables are initialized with <b>nil</b>.
850
851
852	<p>
853	A chunk is also a block (see <a href="#2.4.1">§2.4.1</a>),
854	and so local variables can be declared in a chunk outside any explicit block.
855	The scope of such local variables extends until the end of the chunk.
856
857
858	<p>
859	The visibility rules for local variables are explained in <a href="#2.6">§2.6</a>.
860
861
862
863
864
865
866
867	<h2>2.5 - <a name="2.5">Expressions</a></h2>
868
869	<p>
870	The basic expressions in Lua are the following:
871
872	<pre>
873	exp ::= prefixexp
874	exp ::= <b>nil</b> \| <b>false</b> \| <b>true</b>
875	exp ::= Number
876	exp ::= String
877	exp ::= function
878	exp ::= tableconstructor
879	exp ::= `<b>...</b>´
880	exp ::= exp binop exp
881	exp ::= unop exp
882	prefixexp ::= var \| functioncall \| `<b>(</b>´ exp `<b>)</b>´
883	</pre>
884
885	<p>
886	Numbers and literal strings are explained in <a href="#2.1">§2.1</a>;
887	variables are explained in <a href="#2.3">§2.3</a>;
888	function definitions are explained in <a href="#2.5.9">§2.5.9</a>;
889	function calls are explained in <a href="#2.5.8">§2.5.8</a>;
890	table constructors are explained in <a href="#2.5.7">§2.5.7</a>.
891	Vararg expressions,
892	denoted by three dots ('<code>...</code>'), can only be used when
893	directly inside a vararg function;
894	they are explained in <a href="#2.5.9">§2.5.9</a>.
895
896
897	<p>
898	Binary operators comprise arithmetic operators (see <a href="#2.5.1">§2.5.1</a>),
899	relational operators (see <a href="#2.5.2">§2.5.2</a>), logical operators (see <a href="#2.5.3">§2.5.3</a>),
900	and the concatenation operator (see <a href="#2.5.4">§2.5.4</a>).
901	Unary operators comprise the unary minus (see <a href="#2.5.1">§2.5.1</a>),
902	the unary <b>not</b> (see <a href="#2.5.3">§2.5.3</a>),
903	and the unary <em>length operator</em> (see <a href="#2.5.5">§2.5.5</a>).
904
905
906	<p>
907	Both function calls and vararg expressions can result in multiple values.
908	If an expression is used as a statement
909	(only possible for function calls (see <a href="#2.4.6">§2.4.6</a>)),
910	then its return list is adjusted to zero elements,
911	thus discarding all returned values.
912	If an expression is used as the last (or the only) element
913	of a list of expressions,
914	then no adjustment is made
915	(unless the call is enclosed in parentheses).
916	In all other contexts,
917	Lua adjusts the result list to one element,
918	discarding all values except the first one.
919
920
921	<p>
922	Here are some examples:
923
924	<pre>
925	f() -- adjusted to 0 results
926	g(f(), x) -- f() is adjusted to 1 result
927	g(x, f()) -- g gets x plus all results from f()
928	a,b,c = f(), x -- f() is adjusted to 1 result (c gets nil)
929	a,b = ... -- a gets the first vararg parameter, b gets
930	-- the second (both a and b can get nil if there
931	-- is no corresponding vararg parameter)
932
933	a,b,c = x, f() -- f() is adjusted to 2 results
934	a,b,c = f() -- f() is adjusted to 3 results
935	return f() -- returns all results from f()
936	return ... -- returns all received vararg parameters
937	return x,y,f() -- returns x, y, and all results from f()
938	{f()} -- creates a list with all results from f()
939	{...} -- creates a list with all vararg parameters
940	{f(), nil} -- f() is adjusted to 1 result
941	</pre>
942
943	<p>
944	Any expression enclosed in parentheses always results in only one value.
945	Thus,
946	<code>(f(x,y,z))</code> is always a single value,
947	even if <code>f</code> returns several values.
948	(The value of <code>(f(x,y,z))</code> is the first value returned by <code>f</code>
949	or <b>nil</b> if <code>f</code> does not return any values.)
950
951
952
953	<h3>2.5.1 - <a name="2.5.1">Arithmetic Operators</a></h3><p>
954	Lua supports the usual arithmetic operators:
955	the binary <code>+</code> (addition),
956	<code>-</code> (subtraction), <code>*</code> (multiplication),
957	<code>/</code> (division), <code>%</code> (modulo), and <code>^</code> (exponentiation);
958	and unary <code>-</code> (negation).
959	If the operands are numbers, or strings that can be converted to
960	numbers (see <a href="#2.2.1">§2.2.1</a>),
961	then all operations have the usual meaning.
962	Exponentiation works for any exponent.
963	For instance, <code>x^(-0.5)</code> computes the inverse of the square root of <code>x</code>.
964	Modulo is defined as
965
966	<pre>
967	a % b == a - math.floor(a/b)*b
968	</pre><p>
969	That is, it is the remainder of a division that rounds
970	the quotient towards minus infinity.
971
972
973
974
975
976	<h3>2.5.2 - <a name="2.5.2">Relational Operators</a></h3><p>
977	The relational operators in Lua are
978
979	<pre>
980	== ~= < > <= >=
981	</pre><p>
982	These operators always result in <b>false</b> or <b>true</b>.
983
984
985	<p>
986	Equality (<code>==</code>) first compares the type of its operands.
987	If the types are different, then the result is <b>false</b>.
988	Otherwise, the values of the operands are compared.
989	Numbers and strings are compared in the usual way.
990	Objects (tables, userdata, threads, and functions)
991	are compared by <em>reference</em>:
992	two objects are considered equal only if they are the <em>same</em> object.
993	Every time you create a new object
994	(a table, userdata, thread, or function),
995	this new object is different from any previously existing object.
996
997
998	<p>
999	You can change the way that Lua compares tables and userdata
1000	by using the "eq" metamethod (see <a href="#2.8">§2.8</a>).
1001
1002
1003	<p>
1004	The conversion rules of <a href="#2.2.1">§2.2.1</a>
1005	<em>do not</em> apply to equality comparisons.
1006	Thus, <code>"0"==0</code> evaluates to <b>false</b>,
1007	and <code>t[0]</code> and <code>t["0"]</code> denote different
1008	entries in a table.
1009
1010
1011	<p>
1012	The operator <code>~=</code> is exactly the negation of equality (<code>==</code>).
1013
1014
1015	<p>
1016	The order operators work as follows.
1017	If both arguments are numbers, then they are compared as such.
1018	Otherwise, if both arguments are strings,
1019	then their values are compared according to the current locale.
1020	Otherwise, Lua tries to call the "lt" or the "le"
1021	metamethod (see <a href="#2.8">§2.8</a>).
1022	A comparison <code>a > b</code> is translated to <code>b < a</code>
1023	and <code>a >= b</code> is translated to <code>b <= a</code>.
1024
1025
1026
1027
1028
1029	<h3>2.5.3 - <a name="2.5.3">Logical Operators</a></h3><p>
1030	The logical operators in Lua are
1031	<b>and</b>, <b>or</b>, and <b>not</b>.
1032	Like the control structures (see <a href="#2.4.4">§2.4.4</a>),
1033	all logical operators consider both <b>false</b> and <b>nil</b> as false
1034	and anything else as true.
1035
1036
1037	<p>
1038	The negation operator <b>not</b> always returns <b>false</b> or <b>true</b>.
1039	The conjunction operator <b>and</b> returns its first argument
1040	if this value is <b>false</b> or <b>nil</b>;
1041	otherwise, <b>and</b> returns its second argument.
1042	The disjunction operator <b>or</b> returns its first argument
1043	if this value is different from <b>nil</b> and <b>false</b>;
1044	otherwise, <b>or</b> returns its second argument.
1045	Both <b>and</b> and <b>or</b> use short-cut evaluation;
1046	that is,
1047	the second operand is evaluated only if necessary.
1048	Here are some examples:
1049
1050	<pre>
1051	10 or 20 --> 10
1052	10 or error() --> 10
1053	nil or "a" --> "a"
1054	nil and 10 --> nil
1055	false and error() --> false
1056	false and nil --> false
1057	false or nil --> nil
1058	10 and 20 --> 20
1059	</pre><p>
1060	(In this manual,
1061	<code>--></code> indicates the result of the preceding expression.)
1062
1063
1064
1065
1066
1067	<h3>2.5.4 - <a name="2.5.4">Concatenation</a></h3><p>
1068	The string concatenation operator in Lua is
1069	denoted by two dots ('<code>..</code>').
1070	If both operands are strings or numbers, then they are converted to
1071	strings according to the rules mentioned in <a href="#2.2.1">§2.2.1</a>.
1072	Otherwise, the "concat" metamethod is called (see <a href="#2.8">§2.8</a>).
1073
1074
1075
1076
1077
1078	<h3>2.5.5 - <a name="2.5.5">The Length Operator</a></h3>
1079
1080	<p>
1081	The length operator is denoted by the unary operator <code>#</code>.
1082	The length of a string is its number of bytes
1083	(that is, the usual meaning of string length when each
1084	character is one byte).
1085
1086
1087	<p>
1088	The length of a table <code>t</code> is defined to be any
1089	integer index <code>n</code>
1090	such that <code>t[n]</code> is not <b>nil</b> and <code>t[n+1]</code> is <b>nil</b>;
1091	moreover, if <code>t[1]</code> is <b>nil</b>, <code>n</code> can be zero.
1092	For a regular array, with non-nil values from 1 to a given <code>n</code>,
1093	its length is exactly that <code>n</code>,
1094	the index of its last value.
1095	If the array has "holes"
1096	(that is, <b>nil</b> values between other non-nil values),
1097	then <code>#t</code> can be any of the indices that
1098	directly precedes a <b>nil</b> value
1099	(that is, it may consider any such <b>nil</b> value as the end of
1100	the array).
1101
1102
1103
1104
1105
1106	<h3>2.5.6 - <a name="2.5.6">Precedence</a></h3><p>
1107	Operator precedence in Lua follows the table below,
1108	from lower to higher priority:
1109
1110	<pre>
1111	or
1112	and
1113	< > <= >= ~= ==
1114	..
1115	+ -
1116	* / %
1117	not # - (unary)
1118	^
1119	</pre><p>
1120	As usual,
1121	you can use parentheses to change the precedences of an expression.
1122	The concatenation ('<code>..</code>') and exponentiation ('<code>^</code>')
1123	operators are right associative.
1124	All other binary operators are left associative.
1125
1126
1127
1128
1129
1130	<h3>2.5.7 - <a name="2.5.7">Table Constructors</a></h3><p>
1131	Table constructors are expressions that create tables.
1132	Every time a constructor is evaluated, a new table is created.
1133	A constructor can be used to create an empty table
1134	or to create a table and initialize some of its fields.
1135	The general syntax for constructors is
1136
1137	<pre>
1138	tableconstructor ::= `<b>{</b>´ [fieldlist] `<b>}</b>´
1139	fieldlist ::= field {fieldsep field} [fieldsep]
1140	field ::= `<b>[</b>´ exp `<b>]</b>´ `<b>=</b>´ exp \| Name `<b>=</b>´ exp \| exp
1141	fieldsep ::= `<b>,</b>´ \| `<b>;</b>´
1142	</pre>
1143
1144	<p>
1145	Each field of the form <code>[exp1] = exp2</code> adds to the new table an entry
1146	with key <code>exp1</code> and value <code>exp2</code>.
1147	A field of the form <code>name = exp</code> is equivalent to
1148	<code>["name"] = exp</code>.
1149	Finally, fields of the form <code>exp</code> are equivalent to
1150	<code>[i] = exp</code>, where <code>i</code> are consecutive numerical integers,
1151	starting with 1.
1152	Fields in the other formats do not affect this counting.
1153	For example,
1154
1155	<pre>
1156	a = { [f(1)] = g; "x", "y"; x = 1, f(x), [30] = 23; 45 }
1157	</pre><p>
1158	is equivalent to
1159
1160	<pre>
1161	do
1162	local t = {}
1163	t[f(1)] = g
1164	t[1] = "x" -- 1st exp
1165	t[2] = "y" -- 2nd exp
1166	t.x = 1 -- t["x"] = 1
1167	t[3] = f(x) -- 3rd exp
1168	t[30] = 23
1169	t[4] = 45 -- 4th exp
1170	a = t
1171	end
1172	</pre>
1173
1174	<p>
1175	If the last field in the list has the form <code>exp</code>
1176	and the expression is a function call or a vararg expression,
1177	then all values returned by this expression enter the list consecutively
1178	(see <a href="#2.5.8">§2.5.8</a>).
1179	To avoid this,
1180	enclose the function call or the vararg expression
1181	in parentheses (see <a href="#2.5">§2.5</a>).
1182
1183
1184	<p>
1185	The field list can have an optional trailing separator,
1186	as a convenience for machine-generated code.
1187
1188
1189
1190
1191
1192	<h3>2.5.8 - <a name="2.5.8">Function Calls</a></h3><p>
1193	A function call in Lua has the following syntax:
1194
1195	<pre>
1196	functioncall ::= prefixexp args
1197	</pre><p>
1198	In a function call,
1199	first prefixexp and args are evaluated.
1200	If the value of prefixexp has type <em>function</em>,
1201	then this function is called
1202	with the given arguments.
1203	Otherwise, the prefixexp "call" metamethod is called,
1204	having as first parameter the value of prefixexp,
1205	followed by the original call arguments
1206	(see <a href="#2.8">§2.8</a>).
1207
1208
1209	<p>
1210	The form
1211
1212	<pre>
1213	functioncall ::= prefixexp `<b>:</b>´ Name args
1214	</pre><p>
1215	can be used to call "methods".
1216	A call <code>v:name(<em>args</em>)</code>
1217	is syntactic sugar for <code>v.name(v,<em>args</em>)</code>,
1218	except that <code>v</code> is evaluated only once.
1219
1220
1221	<p>
1222	Arguments have the following syntax:
1223
1224	<pre>
1225	args ::= `<b>(</b>´ [explist] `<b>)</b>´
1226	args ::= tableconstructor
1227	args ::= String
1228	</pre><p>
1229	All argument expressions are evaluated before the call.
1230	A call of the form <code>f{<em>fields</em>}</code> is
1231	syntactic sugar for <code>f({<em>fields</em>})</code>;
1232	that is, the argument list is a single new table.
1233	A call of the form <code>f'<em>string</em>'</code>
1234	(or <code>f"<em>string</em>"</code> or <code>f[[<em>string</em>]]</code>)
1235	is syntactic sugar for <code>f('<em>string</em>')</code>;
1236	that is, the argument list is a single literal string.
1237
1238
1239	<p>
1240	As an exception to the free-format syntax of Lua,
1241	you cannot put a line break before the '<code>(</code>' in a function call.
1242	This restriction avoids some ambiguities in the language.
1243	If you write
1244
1245	<pre>
1246	a = f
1247	(g).x(a)
1248	</pre><p>
1249	Lua would see that as a single statement, <code>a = f(g).x(a)</code>.
1250	So, if you want two statements, you must add a semi-colon between them.
1251	If you actually want to call <code>f</code>,
1252	you must remove the line break before <code>(g)</code>.
1253
1254
1255	<p>
1256	A call of the form <code>return</code> <em>functioncall</em> is called
1257	a <em>tail call</em>.
1258	Lua implements <em>proper tail calls</em>
1259	(or <em>proper tail recursion</em>):
1260	in a tail call,
1261	the called function reuses the stack entry of the calling function.
1262	Therefore, there is no limit on the number of nested tail calls that
1263	a program can execute.
1264	However, a tail call erases any debug information about the
1265	calling function.
1266	Note that a tail call only happens with a particular syntax,
1267	where the <b>return</b> has one single function call as argument;
1268	this syntax makes the calling function return exactly
1269	the returns of the called function.
1270	So, none of the following examples are tail calls:
1271
1272	<pre>
1273	return (f(x)) -- results adjusted to 1
1274	return 2 * f(x)
1275	return x, f(x) -- additional results
1276	f(x); return -- results discarded
1277	return x or f(x) -- results adjusted to 1
1278	</pre>
1279
1280
1281
1282
1283	<h3>2.5.9 - <a name="2.5.9">Function Definitions</a></h3>
1284
1285	<p>
1286	The syntax for function definition is
1287
1288	<pre>
1289	function ::= <b>function</b> funcbody
1290	funcbody ::= `<b>(</b>´ [parlist] `<b>)</b>´ block <b>end</b>
1291	</pre>
1292
1293	<p>
1294	The following syntactic sugar simplifies function definitions:
1295
1296	<pre>
1297	stat ::= <b>function</b> funcname funcbody
1298	stat ::= <b>local</b> <b>function</b> Name funcbody
1299	funcname ::= Name {`<b>.</b>´ Name} [`<b>:</b>´ Name]
1300	</pre><p>
1301	The statement
1302
1303	<pre>
1304	function f () <em>body</em> end
1305	</pre><p>
1306	translates to
1307
1308	<pre>
1309	f = function () <em>body</em> end
1310	</pre><p>
1311	The statement
1312
1313	<pre>
1314	function t.a.b.c.f () <em>body</em> end
1315	</pre><p>
1316	translates to
1317
1318	<pre>
1319	t.a.b.c.f = function () <em>body</em> end
1320	</pre><p>
1321	The statement
1322
1323	<pre>
1324	local function f () <em>body</em> end
1325	</pre><p>
1326	translates to
1327
1328	<pre>
1329	local f; f = function () <em>body</em> end
1330	</pre><p>
1331	<em>not</em> to
1332
1333	<pre>
1334	local f = function () <em>body</em> end
1335	</pre><p>
1336	(This only makes a difference when the body of the function
1337	contains references to <code>f</code>.)
1338
1339
1340	<p>
1341	A function definition is an executable expression,
1342	whose value has type <em>function</em>.
1343	When Lua pre-compiles a chunk,
1344	all its function bodies are pre-compiled too.
1345	Then, whenever Lua executes the function definition,
1346	the function is <em>instantiated</em> (or <em>closed</em>).
1347	This function instance (or <em>closure</em>)
1348	is the final value of the expression.
1349	Different instances of the same function
1350	can refer to different external local variables
1351	and can have different environment tables.
1352
1353
1354	<p>
1355	Parameters act as local variables that are
1356	initialized with the argument values:
1357
1358	<pre>
1359	parlist ::= namelist [`<b>,</b>´ `<b>...</b>´] \| `<b>...</b>´
1360	</pre><p>
1361	When a function is called,
1362	the list of arguments is adjusted to
1363	the length of the list of parameters,
1364	unless the function is a variadic or <em>vararg function</em>,
1365	which is
1366	indicated by three dots ('<code>...</code>') at the end of its parameter list.
1367	A vararg function does not adjust its argument list;
1368	instead, it collects all extra arguments and supplies them
1369	to the function through a <em>vararg expression</em>,
1370	which is also written as three dots.
1371	The value of this expression is a list of all actual extra arguments,
1372	similar to a function with multiple results.
1373	If a vararg expression is used inside another expression
1374	or in the middle of a list of expressions,
1375	then its return list is adjusted to one element.
1376	If the expression is used as the last element of a list of expressions,
1377	then no adjustment is made
1378	(unless that last expression is enclosed in parentheses).
1379
1380
1381	<p>
1382	As an example, consider the following definitions:
1383
1384	<pre>
1385	function f(a, b) end
1386	function g(a, b, ...) end
1387	function r() return 1,2,3 end
1388	</pre><p>
1389	Then, we have the following mapping from arguments to parameters and
1390	to the vararg expression:
1391
1392	<pre>
1393	CALL PARAMETERS
1394
1395	f(3) a=3, b=nil
1396	f(3, 4) a=3, b=4
1397	f(3, 4, 5) a=3, b=4
1398	f(r(), 10) a=1, b=10
1399	f(r()) a=1, b=2
1400
1401	g(3) a=3, b=nil, ... --> (nothing)
1402	g(3, 4) a=3, b=4, ... --> (nothing)
1403	g(3, 4, 5, 8) a=3, b=4, ... --> 5 8
1404	g(5, r()) a=5, b=1, ... --> 2 3
1405	</pre>
1406
1407	<p>
1408	Results are returned using the <b>return</b> statement (see <a href="#2.4.4">§2.4.4</a>).
1409	If control reaches the end of a function
1410	without encountering a <b>return</b> statement,
1411	then the function returns with no results.
1412
1413
1414	<p>
1415	The <em>colon</em> syntax
1416	is used for defining <em>methods</em>,
1417	that is, functions that have an implicit extra parameter <code>self</code>.
1418	Thus, the statement
1419
1420	<pre>
1421	function t.a.b.c:f (<em>params</em>) <em>body</em> end
1422	</pre><p>
1423	is syntactic sugar for
1424
1425	<pre>
1426	t.a.b.c.f = function (self, <em>params</em>) <em>body</em> end
1427	</pre>
1428
1429
1430
1431
1432
1433
1434	<h2>2.6 - <a name="2.6">Visibility Rules</a></h2>
1435
1436	<p>
1437
1438	Lua is a lexically scoped language.
1439	The scope of variables begins at the first statement <em>after</em>
1440	their declaration and lasts until the end of the innermost block that
1441	includes the declaration.
1442	Consider the following example:
1443
1444	<pre>
1445	x = 10 -- global variable
1446	do -- new block
1447	local x = x -- new 'x', with value 10
1448	print(x) --> 10
1449	x = x+1
1450	do -- another block
1451	local x = x+1 -- another 'x'
1452	print(x) --> 12
1453	end
1454	print(x) --> 11
1455	end
1456	print(x) --> 10 (the global one)
1457	</pre>
1458
1459	<p>
1460	Notice that, in a declaration like <code>local x = x</code>,
1461	the new <code>x</code> being declared is not in scope yet,
1462	and so the second <code>x</code> refers to the outside variable.
1463
1464
1465	<p>
1466	Because of the lexical scoping rules,
1467	local variables can be freely accessed by functions
1468	defined inside their scope.
1469	A local variable used by an inner function is called
1470	an <em>upvalue</em>, or <em>external local variable</em>,
1471	inside the inner function.
1472
1473
1474	<p>
1475	Notice that each execution of a <b>local</b> statement
1476	defines new local variables.
1477	Consider the following example:
1478
1479	<pre>
1480	a = {}
1481	local x = 20
1482	for i=1,10 do
1483	local y = 0
1484	a[i] = function () y=y+1; return x+y end
1485	end
1486	</pre><p>
1487	The loop creates ten closures
1488	(that is, ten instances of the anonymous function).
1489	Each of these closures uses a different <code>y</code> variable,
1490	while all of them share the same <code>x</code>.
1491
1492
1493
1494
1495
1496	<h2>2.7 - <a name="2.7">Error Handling</a></h2>
1497
1498	<p>
1499	Because Lua is an embedded extension language,
1500	all Lua actions start from C code in the host program
1501	calling a function from the Lua library (see <a href="#lua_pcall"><code>lua_pcall</code></a>).
1502	Whenever an error occurs during Lua compilation or execution,
1503	control returns to C,
1504	which can take appropriate measures
1505	(such as printing an error message).
1506
1507
1508	<p>
1509	Lua code can explicitly generate an error by calling the
1510	<a href="#pdf-error"><code>error</code></a> function.
1511	If you need to catch errors in Lua,
1512	you can use the <a href="#pdf-pcall"><code>pcall</code></a> function.
1513
1514
1515
1516
1517
1518	<h2>2.8 - <a name="2.8">Metatables</a></h2>
1519
1520	<p>
1521	Every value in Lua can have a <em>metatable</em>.
1522	This <em>metatable</em> is an ordinary Lua table
1523	that defines the behavior of the original value
1524	under certain special operations.
1525	You can change several aspects of the behavior
1526	of operations over a value by setting specific fields in its metatable.
1527	For instance, when a non-numeric value is the operand of an addition,
1528	Lua checks for a function in the field <code>"__add"</code> in its metatable.
1529	If it finds one,
1530	Lua calls this function to perform the addition.
1531
1532
1533	<p>
1534	We call the keys in a metatable <em>events</em>
1535	and the values <em>metamethods</em>.
1536	In the previous example, the event is <code>"add"</code>
1537	and the metamethod is the function that performs the addition.
1538
1539
1540	<p>
1541	You can query the metatable of any value
1542	through the <a href="#pdf-getmetatable"><code>getmetatable</code></a> function.
1543
1544
1545	<p>
1546	You can replace the metatable of tables
1547	through the <a href="#pdf-setmetatable"><code>setmetatable</code></a>
1548	function.
1549	You cannot change the metatable of other types from Lua
1550	(except by using the debug library);
1551	you must use the C API for that.
1552
1553
1554	<p>
1555	Tables and full userdata have individual metatables
1556	(although multiple tables and userdata can share their metatables).
1557	Values of all other types share one single metatable per type;
1558	that is, there is one single metatable for all numbers,
1559	one for all strings, etc.
1560
1561
1562	<p>
1563	A metatable controls how an object behaves in arithmetic operations,
1564	order comparisons, concatenation, length operation, and indexing.
1565	A metatable also can define a function to be called when a userdata
1566	is garbage collected.
1567	For each of these operations Lua associates a specific key
1568	called an <em>event</em>.
1569	When Lua performs one of these operations over a value,
1570	it checks whether this value has a metatable with the corresponding event.
1571	If so, the value associated with that key (the metamethod)
1572	controls how Lua will perform the operation.
1573
1574
1575	<p>
1576	Metatables control the operations listed next.
1577	Each operation is identified by its corresponding name.
1578	The key for each operation is a string with its name prefixed by
1579	two underscores, '<code>__</code>';
1580	for instance, the key for operation "add" is the
1581	string <code>"__add"</code>.
1582	The semantics of these operations is better explained by a Lua function
1583	describing how the interpreter executes the operation.
1584
1585
1586	<p>
1587	The code shown here in Lua is only illustrative;
1588	the real behavior is hard coded in the interpreter
1589	and it is much more efficient than this simulation.
1590	All functions used in these descriptions
1591	(<a href="#pdf-rawget"><code>rawget</code></a>, <a href="#pdf-tonumber"><code>tonumber</code></a>, etc.)
1592	are described in <a href="#5.1">§5.1</a>.
1593	In particular, to retrieve the metamethod of a given object,
1594	we use the expression
1595
1596	<pre>
1597	metatable(obj)[event]
1598	</pre><p>
1599	This should be read as
1600
1601	<pre>
1602	rawget(getmetatable(obj) or {}, event)
1603	</pre><p>
1604
1605	That is, the access to a metamethod does not invoke other metamethods,
1606	and the access to objects with no metatables does not fail
1607	(it simply results in <b>nil</b>).
1608
1609
1610
1611	<ul>
1612
1613	<li><b>"add":</b>
1614	the <code>+</code> operation.
1615
1616
1617
1618	<p>
1619	The function <code>getbinhandler</code> below defines how Lua chooses a handler
1620	for a binary operation.
1621	First, Lua tries the first operand.
1622	If its type does not define a handler for the operation,
1623	then Lua tries the second operand.
1624
1625	<pre>
1626	function getbinhandler (op1, op2, event)
1627	return metatable(op1)[event] or metatable(op2)[event]
1628	end
1629	</pre><p>
1630	By using this function,
1631	the behavior of the <code>op1 + op2</code> is
1632
1633	<pre>
1634	function add_event (op1, op2)
1635	local o1, o2 = tonumber(op1), tonumber(op2)
1636	if o1 and o2 then -- both operands are numeric?
1637	return o1 + o2 -- '+' here is the primitive 'add'
1638	else -- at least one of the operands is not numeric
1639	local h = getbinhandler(op1, op2, "__add")
1640	if h then
1641	-- call the handler with both operands
1642	return (h(op1, op2))
1643	else -- no handler available: default behavior
1644	error(···)
1645	end
1646	end
1647	end
1648	</pre><p>
1649	</li>
1650
1651	<li><b>"sub":</b>
1652	the <code>-</code> operation.
1653
1654	Behavior similar to the "add" operation.
1655	</li>
1656
1657	<li><b>"mul":</b>
1658	the <code>*</code> operation.
1659
1660	Behavior similar to the "add" operation.
1661	</li>
1662
1663	<li><b>"div":</b>
1664	the <code>/</code> operation.
1665
1666	Behavior similar to the "add" operation.
1667	</li>
1668
1669	<li><b>"mod":</b>
1670	the <code>%</code> operation.
1671
1672	Behavior similar to the "add" operation,
1673	with the operation
1674	<code>o1 - floor(o1/o2)*o2</code> as the primitive operation.
1675	</li>
1676
1677	<li><b>"pow":</b>
1678	the <code>^</code> (exponentiation) operation.
1679
1680	Behavior similar to the "add" operation,
1681	with the function <code>pow</code> (from the C math library)
1682	as the primitive operation.
1683	</li>
1684
1685	<li><b>"unm":</b>
1686	the unary <code>-</code> operation.
1687
1688
1689	<pre>
1690	function unm_event (op)
1691	local o = tonumber(op)
1692	if o then -- operand is numeric?
1693	return -o -- '-' here is the primitive 'unm'
1694	else -- the operand is not numeric.
1695	-- Try to get a handler from the operand
1696	local h = metatable(op).__unm
1697	if h then
1698	-- call the handler with the operand
1699	return (h(op))
1700	else -- no handler available: default behavior
1701	error(···)
1702	end
1703	end
1704	end
1705	</pre><p>
1706	</li>
1707
1708	<li><b>"concat":</b>
1709	the <code>..</code> (concatenation) operation.
1710
1711
1712	<pre>
1713	function concat_event (op1, op2)
1714	if (type(op1) == "string" or type(op1) == "number") and
1715	(type(op2) == "string" or type(op2) == "number") then
1716	return op1 .. op2 -- primitive string concatenation
1717	else
1718	local h = getbinhandler(op1, op2, "__concat")
1719	if h then
1720	return (h(op1, op2))
1721	else
1722	error(···)
1723	end
1724	end
1725	end
1726	</pre><p>
1727	</li>
1728
1729	<li><b>"len":</b>
1730	the <code>#</code> operation.
1731
1732
1733	<pre>
1734	function len_event (op)
1735	if type(op) == "string" then
1736	return strlen(op) -- primitive string length
1737	elseif type(op) == "table" then
1738	return #op -- primitive table length
1739	else
1740	local h = metatable(op).__len
1741	if h then
1742	-- call the handler with the operand
1743	return (h(op))
1744	else -- no handler available: default behavior
1745	error(···)
1746	end
1747	end
1748	end
1749	</pre><p>
1750	See <a href="#2.5.5">§2.5.5</a> for a description of the length of a table.
1751	</li>
1752
1753	<li><b>"eq":</b>
1754	the <code>==</code> operation.
1755
1756	The function <code>getcomphandler</code> defines how Lua chooses a metamethod
1757	for comparison operators.
1758	A metamethod only is selected when both objects
1759	being compared have the same type
1760	and the same metamethod for the selected operation.
1761
1762	<pre>
1763	function getcomphandler (op1, op2, event)
1764	if type(op1) ~= type(op2) then return nil end
1765	local mm1 = metatable(op1)[event]
1766	local mm2 = metatable(op2)[event]
1767	if mm1 == mm2 then return mm1 else return nil end
1768	end
1769	</pre><p>
1770	The "eq" event is defined as follows:
1771
1772	<pre>
1773	function eq_event (op1, op2)
1774	if type(op1) ~= type(op2) then -- different types?
1775	return false -- different objects
1776	end
1777	if op1 == op2 then -- primitive equal?
1778	return true -- objects are equal
1779	end
1780	-- try metamethod
1781	local h = getcomphandler(op1, op2, "__eq")
1782	if h then
1783	return (h(op1, op2))
1784	else
1785	return false
1786	end
1787	end
1788	</pre><p>
1789	<code>a ~= b</code> is equivalent to <code>not (a == b)</code>.
1790	</li>
1791
1792	<li><b>"lt":</b>
1793	the <code><</code> operation.
1794
1795
1796	<pre>
1797	function lt_event (op1, op2)
1798	if type(op1) == "number" and type(op2) == "number" then
1799	return op1 < op2 -- numeric comparison
1800	elseif type(op1) == "string" and type(op2) == "string" then
1801	return op1 < op2 -- lexicographic comparison
1802	else
1803	local h = getcomphandler(op1, op2, "__lt")
1804	if h then
1805	return (h(op1, op2))
1806	else
1807	error(···)
1808	end
1809	end
1810	end
1811	</pre><p>
1812	<code>a > b</code> is equivalent to <code>b < a</code>.
1813	</li>
1814
1815	<li><b>"le":</b>
1816	the <code><=</code> operation.
1817
1818
1819	<pre>
1820	function le_event (op1, op2)
1821	if type(op1) == "number" and type(op2) == "number" then
1822	return op1 <= op2 -- numeric comparison
1823	elseif type(op1) == "string" and type(op2) == "string" then
1824	return op1 <= op2 -- lexicographic comparison
1825	else
1826	local h = getcomphandler(op1, op2, "__le")
1827	if h then
1828	return (h(op1, op2))
1829	else
1830	h = getcomphandler(op1, op2, "__lt")
1831	if h then
1832	return not h(op2, op1)
1833	else
1834	error(···)
1835	end
1836	end
1837	end
1838	end
1839	</pre><p>
1840	<code>a >= b</code> is equivalent to <code>b <= a</code>.
1841	Note that, in the absence of a "le" metamethod,
1842	Lua tries the "lt", assuming that <code>a <= b</code> is
1843	equivalent to <code>not (b < a)</code>.
1844	</li>
1845
1846	<li><b>"index":</b>
1847	The indexing access <code>table[key]</code>.
1848
1849
1850	<pre>
1851	function gettable_event (table, key)
1852	local h
1853	if type(table) == "table" then
1854	local v = rawget(table, key)
1855	if v ~= nil then return v end
1856	h = metatable(table).__index
1857	if h == nil then return nil end
1858	else
1859	h = metatable(table).__index
1860	if h == nil then
1861	error(···)
1862	end
1863	end
1864	if type(h) == "function" then
1865	return (h(table, key)) -- call the handler
1866	else return h[key] -- or repeat operation on it
1867	end
1868	end
1869	</pre><p>
1870	</li>
1871
1872	<li><b>"newindex":</b>
1873	The indexing assignment <code>table[key] = value</code>.
1874
1875
1876	<pre>
1877	function settable_event (table, key, value)
1878	local h
1879	if type(table) == "table" then
1880	local v = rawget(table, key)
1881	if v ~= nil then rawset(table, key, value); return end
1882	h = metatable(table).__newindex
1883	if h == nil then rawset(table, key, value); return end
1884	else
1885	h = metatable(table).__newindex
1886	if h == nil then
1887	error(···)
1888	end
1889	end
1890	if type(h) == "function" then
1891	h(table, key,value) -- call the handler
1892	else h[key] = value -- or repeat operation on it
1893	end
1894	end
1895	</pre><p>
1896	</li>
1897
1898	<li><b>"call":</b>
1899	called when Lua calls a value.
1900
1901
1902	<pre>
1903	function function_event (func, ...)
1904	if type(func) == "function" then
1905	return func(...) -- primitive call
1906	else
1907	local h = metatable(func).__call
1908	if h then
1909	return h(func, ...)
1910	else
1911	error(···)
1912	end
1913	end
1914	end
1915	</pre><p>
1916	</li>
1917
1918	</ul>
1919
1920
1921
1922
1923	<h2>2.9 - <a name="2.9">Environments</a></h2>
1924
1925	<p>
1926	Besides metatables,
1927	objects of types thread, function, and userdata
1928	have another table associated with them,
1929	called their <em>environment</em>.
1930	Like metatables, environments are regular tables and
1931	multiple objects can share the same environment.
1932
1933
1934	<p>
1935	Threads are created sharing the environment of the creating thread.
1936	Userdata and C functions are created sharing the environment
1937	of the creating C function.
1938	Non-nested Lua functions
1939	(created by <a href="#pdf-loadfile"><code>loadfile</code></a>, <a href="#pdf-loadstring"><code>loadstring</code></a> or <a href="#pdf-load"><code>load</code></a>)
1940	are created sharing the environment of the creating thread.
1941	Nested Lua functions are created sharing the environment of
1942	the creating Lua function.
1943
1944
1945	<p>
1946	Environments associated with userdata have no meaning for Lua.
1947	It is only a convenience feature for programmers to associate a table to
1948	a userdata.
1949
1950
1951	<p>
1952	Environments associated with threads are called
1953	<em>global environments</em>.
1954	They are used as the default environment for threads and
1955	non-nested Lua functions created by the thread
1956	and can be directly accessed by C code (see <a href="#3.3">§3.3</a>).
1957
1958
1959	<p>
1960	The environment associated with a C function can be directly
1961	accessed by C code (see <a href="#3.3">§3.3</a>).
1962	It is used as the default environment for other C functions
1963	and userdata created by the function.
1964
1965
1966	<p>
1967	Environments associated with Lua functions are used to resolve
1968	all accesses to global variables within the function (see <a href="#2.3">§2.3</a>).
1969	They are used as the default environment for nested Lua functions
1970	created by the function.
1971
1972
1973	<p>
1974	You can change the environment of a Lua function or the
1975	running thread by calling <a href="#pdf-setfenv"><code>setfenv</code></a>.
1976	You can get the environment of a Lua function or the running thread
1977	by calling <a href="#pdf-getfenv"><code>getfenv</code></a>.
1978	To manipulate the environment of other objects
1979	(userdata, C functions, other threads) you must
1980	use the C API.
1981
1982
1983
1984
1985
1986	<h2>2.10 - <a name="2.10">Garbage Collection</a></h2>
1987
1988	<p>
1989	Lua performs automatic memory management.
1990	This means that
1991	you have to worry neither about allocating memory for new objects
1992	nor about freeing it when the objects are no longer needed.
1993	Lua manages memory automatically by running
1994	a <em>garbage collector</em> from time to time
1995	to collect all <em>dead objects</em>
1996	(that is, objects that are no longer accessible from Lua).
1997	All memory used by Lua is subject to automatic management:
1998	tables, userdata, functions, threads, strings, etc.
1999
2000
2001	<p>
2002	Lua implements an incremental mark-and-sweep collector.
2003	It uses two numbers to control its garbage-collection cycles:
2004	the <em>garbage-collector pause</em> and
2005	the <em>garbage-collector step multiplier</em>.
2006	Both use percentage points as units
2007	(so that a value of 100 means an internal value of 1).
2008
2009
2010	<p>
2011	The garbage-collector pause
2012	controls how long the collector waits before starting a new cycle.
2013	Larger values make the collector less aggressive.
2014	Values smaller than 100 mean the collector will not wait to
2015	start a new cycle.
2016	A value of 200 means that the collector waits for the total memory in use
2017	to double before starting a new cycle.
2018
2019
2020	<p>
2021	The step multiplier
2022	controls the relative speed of the collector relative to
2023	memory allocation.
2024	Larger values make the collector more aggressive but also increase
2025	the size of each incremental step.
2026	Values smaller than 100 make the collector too slow and
2027	can result in the collector never finishing a cycle.
2028	The default, 200, means that the collector runs at "twice"
2029	the speed of memory allocation.
2030
2031
2032	<p>
2033	You can change these numbers by calling <a href="#lua_gc"><code>lua_gc</code></a> in C
2034	or <a href="#pdf-collectgarbage"><code>collectgarbage</code></a> in Lua.
2035	With these functions you can also control
2036	the collector directly (e.g., stop and restart it).
2037
2038
2039
2040	<h3>2.10.1 - <a name="2.10.1">Garbage-Collection Metamethods</a></h3>
2041
2042	<p>
2043	Using the C API,
2044	you can set garbage-collector metamethods for userdata (see <a href="#2.8">§2.8</a>).
2045	These metamethods are also called <em>finalizers</em>.
2046	Finalizers allow you to coordinate Lua's garbage collection
2047	with external resource management
2048	(such as closing files, network or database connections,
2049	or freeing your own memory).
2050
2051
2052	<p>
2053	Garbage userdata with a field <code>__gc</code> in their metatables are not
2054	collected immediately by the garbage collector.
2055	Instead, Lua puts them in a list.
2056	After the collection,
2057	Lua does the equivalent of the following function
2058	for each userdata in that list:
2059
2060	<pre>
2061	function gc_event (udata)
2062	local h = metatable(udata).__gc
2063	if h then
2064	h(udata)
2065	end
2066	end
2067	</pre>
2068
2069	<p>
2070	At the end of each garbage-collection cycle,
2071	the finalizers for userdata are called in <em>reverse</em>
2072	order of their creation,
2073	among those collected in that cycle.
2074	That is, the first finalizer to be called is the one associated
2075	with the userdata created last in the program.
2076	The userdata itself is freed only in the next garbage-collection cycle.
2077
2078
2079
2080
2081
2082	<h3>2.10.2 - <a name="2.10.2">Weak Tables</a></h3>
2083
2084	<p>
2085	A <em>weak table</em> is a table whose elements are
2086	<em>weak references</em>.
2087	A weak reference is ignored by the garbage collector.
2088	In other words,
2089	if the only references to an object are weak references,
2090	then the garbage collector will collect this object.
2091
2092
2093	<p>
2094	A weak table can have weak keys, weak values, or both.
2095	A table with weak keys allows the collection of its keys,
2096	but prevents the collection of its values.
2097	A table with both weak keys and weak values allows the collection of
2098	both keys and values.
2099	In any case, if either the key or the value is collected,
2100	the whole pair is removed from the table.
2101	The weakness of a table is controlled by the
2102	<code>__mode</code> field of its metatable.
2103	If the <code>__mode</code> field is a string containing the character '<code>k</code>',
2104	the keys in the table are weak.
2105	If <code>__mode</code> contains '<code>v</code>',
2106	the values in the table are weak.
2107
2108
2109	<p>
2110	After you use a table as a metatable,
2111	you should not change the value of its <code>__mode</code> field.
2112	Otherwise, the weak behavior of the tables controlled by this
2113	metatable is undefined.
2114
2115
2116
2117
2118
2119
2120
2121	<h2>2.11 - <a name="2.11">Coroutines</a></h2>
2122
2123	<p>
2124	Lua supports coroutines,
2125	also called <em>collaborative multithreading</em>.
2126	A coroutine in Lua represents an independent thread of execution.
2127	Unlike threads in multithread systems, however,
2128	a coroutine only suspends its execution by explicitly calling
2129	a yield function.
2130
2131
2132	<p>
2133	You create a coroutine with a call to <a href="#pdf-coroutine.create"><code>coroutine.create</code></a>.
2134	Its sole argument is a function
2135	that is the main function of the coroutine.
2136	The <code>create</code> function only creates a new coroutine and
2137	returns a handle to it (an object of type <em>thread</em>);
2138	it does not start the coroutine execution.
2139
2140
2141	<p>
2142	When you first call <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a>,
2143	passing as its first argument
2144	a thread returned by <a href="#pdf-coroutine.create"><code>coroutine.create</code></a>,
2145	the coroutine starts its execution,
2146	at the first line of its main function.
2147	Extra arguments passed to <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a> are passed on
2148	to the coroutine main function.
2149	After the coroutine starts running,
2150	it runs until it terminates or <em>yields</em>.
2151
2152
2153	<p>
2154	A coroutine can terminate its execution in two ways:
2155	normally, when its main function returns
2156	(explicitly or implicitly, after the last instruction);
2157	and abnormally, if there is an unprotected error.
2158	In the first case, <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a> returns <b>true</b>,
2159	plus any values returned by the coroutine main function.
2160	In case of errors, <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a> returns <b>false</b>
2161	plus an error message.
2162
2163
2164	<p>
2165	A coroutine yields by calling <a href="#pdf-coroutine.yield"><code>coroutine.yield</code></a>.
2166	When a coroutine yields,
2167	the corresponding <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a> returns immediately,
2168	even if the yield happens inside nested function calls
2169	(that is, not in the main function,
2170	but in a function directly or indirectly called by the main function).
2171	In the case of a yield, <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a> also returns <b>true</b>,
2172	plus any values passed to <a href="#pdf-coroutine.yield"><code>coroutine.yield</code></a>.
2173	The next time you resume the same coroutine,
2174	it continues its execution from the point where it yielded,
2175	with the call to <a href="#pdf-coroutine.yield"><code>coroutine.yield</code></a> returning any extra
2176	arguments passed to <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a>.
2177
2178
2179	<p>
2180	Like <a href="#pdf-coroutine.create"><code>coroutine.create</code></a>,
2181	the <a href="#pdf-coroutine.wrap"><code>coroutine.wrap</code></a> function also creates a coroutine,
2182	but instead of returning the coroutine itself,
2183	it returns a function that, when called, resumes the coroutine.
2184	Any arguments passed to this function
2185	go as extra arguments to <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a>.
2186	<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>,
2187	except the first one (the boolean error code).
2188	Unlike <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a>,
2189	<a href="#pdf-coroutine.wrap"><code>coroutine.wrap</code></a> does not catch errors;
2190	any error is propagated to the caller.
2191
2192
2193	<p>
2194	As an example,
2195	consider the following code:
2196
2197	<pre>
2198	function foo (a)
2199	print("foo", a)
2200	return coroutine.yield(2*a)
2201	end
2202
2203	co = coroutine.create(function (a,b)
2204	print("co-body", a, b)
2205	local r = foo(a+1)
2206	print("co-body", r)
2207	local r, s = coroutine.yield(a+b, a-b)
2208	print("co-body", r, s)
2209	return b, "end"
2210	end)
2211
2212	print("main", coroutine.resume(co, 1, 10))
2213	print("main", coroutine.resume(co, "r"))
2214	print("main", coroutine.resume(co, "x", "y"))
2215	print("main", coroutine.resume(co, "x", "y"))
2216	</pre><p>
2217	When you run it, it produces the following output:
2218
2219	<pre>
2220	co-body 1 10
2221	foo 2
2222
2223	main true 4
2224	co-body r
2225	main true 11 -9
2226	co-body x y
2227	main true 10 end
2228	main false cannot resume dead coroutine
2229	</pre>
2230
2231
2232
2233
2234	<h1>3 - <a name="3">The Application Program Interface</a></h1>
2235
2236	<p>
2237
2238	This section describes the C API for Lua, that is,
2239	the set of C functions available to the host program to communicate
2240	with Lua.
2241	All API functions and related types and constants
2242	are declared in the header file <a name="pdf-lua.h"><code>lua.h</code></a>.
2243
2244
2245	<p>
2246	Even when we use the term "function",
2247	any facility in the API may be provided as a macro instead.
2248	All such macros use each of their arguments exactly once
2249	(except for the first argument, which is always a Lua state),
2250	and so do not generate any hidden side-effects.
2251
2252
2253	<p>
2254	As in most C libraries,
2255	the Lua API functions do not check their arguments for validity or consistency.
2256	However, you can change this behavior by compiling Lua
2257	with a proper definition for the macro <a name="pdf-luai_apicheck"><code>luai_apicheck</code></a>,
2258	in file <code>luaconf.h</code>.
2259
2260
2261
2262	<h2>3.1 - <a name="3.1">The Stack</a></h2>
2263
2264	<p>
2265	Lua uses a <em>virtual stack</em> to pass values to and from C.
2266	Each element in this stack represents a Lua value
2267	(<b>nil</b>, number, string, etc.).
2268
2269
2270	<p>
2271	Whenever Lua calls C, the called function gets a new stack,
2272	which is independent of previous stacks and of stacks of
2273	C functions that are still active.
2274	This stack initially contains any arguments to the C function
2275	and it is where the C function pushes its results
2276	to be returned to the caller (see <a href="#lua_CFunction"><code>lua_CFunction</code></a>).
2277
2278
2279	<p>
2280	For convenience,
2281	most query operations in the API do not follow a strict stack discipline.
2282	Instead, they can refer to any element in the stack
2283	by using an <em>index</em>:
2284	A positive index represents an <em>absolute</em> stack position
2285	(starting at 1);
2286	a negative index represents an <em>offset</em> relative to the top of the stack.
2287	More specifically, if the stack has <em>n</em> elements,
2288	then index 1 represents the first element
2289	(that is, the element that was pushed onto the stack first)
2290	and
2291	index <em>n</em> represents the last element;
2292	index -1 also represents the last element
2293	(that is, the element at the top)
2294	and index <em>-n</em> represents the first element.
2295	We say that an index is <em>valid</em>
2296	if it lies between 1 and the stack top
2297	(that is, if <code>1 ≤ abs(index) ≤ top</code>).
2298
2299
2300
2301
2302
2303
2304	<h2>3.2 - <a name="3.2">Stack Size</a></h2>
2305
2306	<p>
2307	When you interact with Lua API,
2308	you are responsible for ensuring consistency.
2309	In particular,
2310	<em>you are responsible for controlling stack overflow</em>.
2311	You can use the function <a href="#lua_checkstack"><code>lua_checkstack</code></a>
2312	to grow the stack size.
2313
2314
2315	<p>
2316	Whenever Lua calls C,
2317	it ensures that at least <a name="pdf-LUA_MINSTACK"><code>LUA_MINSTACK</code></a> stack positions are available.
2318	<code>LUA_MINSTACK</code> is defined as 20,
2319	so that usually you do not have to worry about stack space
2320	unless your code has loops pushing elements onto the stack.
2321
2322
2323	<p>
2324	Most query functions accept as indices any value inside the
2325	available stack space, that is, indices up to the maximum stack size
2326	you have set through <a href="#lua_checkstack"><code>lua_checkstack</code></a>.
2327	Such indices are called <em>acceptable indices</em>.
2328	More formally, we define an <em>acceptable index</em>
2329	as follows:
2330
2331	<pre>
2332	(index < 0 && abs(index) <= top) \|\|
2333	(index > 0 && index <= stackspace)
2334	</pre><p>
2335	Note that 0 is never an acceptable index.
2336
2337
2338
2339
2340
2341	<h2>3.3 - <a name="3.3">Pseudo-Indices</a></h2>
2342
2343	<p>
2344	Unless otherwise noted,
2345	any function that accepts valid indices can also be called with
2346	<em>pseudo-indices</em>,
2347	which represent some Lua values that are accessible to C code
2348	but which are not in the stack.
2349	Pseudo-indices are used to access the thread environment,
2350	the function environment,
2351	the registry,
2352	and the upvalues of a C function (see <a href="#3.4">§3.4</a>).
2353
2354
2355	<p>
2356	The thread environment (where global variables live) is
2357	always at pseudo-index <a name="pdf-LUA_GLOBALSINDEX"><code>LUA_GLOBALSINDEX</code></a>.
2358	The environment of the running C function is always
2359	at pseudo-index <a name="pdf-LUA_ENVIRONINDEX"><code>LUA_ENVIRONINDEX</code></a>.
2360
2361
2362	<p>
2363	To access and change the value of global variables,
2364	you can use regular table operations over an environment table.
2365	For instance, to access the value of a global variable, do
2366
2367	<pre>
2368	lua_getfield(L, LUA_GLOBALSINDEX, varname);
2369	</pre>
2370
2371
2372
2373
2374	<h2>3.4 - <a name="3.4">C Closures</a></h2>
2375
2376	<p>
2377	When a C function is created,
2378	it is possible to associate some values with it,
2379	thus creating a <em>C closure</em>;
2380	these values are called <em>upvalues</em> and are
2381	accessible to the function whenever it is called
2382	(see <a href="#lua_pushcclosure"><code>lua_pushcclosure</code></a>).
2383
2384
2385	<p>
2386	Whenever a C function is called,
2387	its upvalues are located at specific pseudo-indices.
2388	These pseudo-indices are produced by the macro
2389	<a name="lua_upvalueindex"><code>lua_upvalueindex</code></a>.
2390	The first value associated with a function is at position
2391	<code>lua_upvalueindex(1)</code>, and so on.
2392	Any access to <code>lua_upvalueindex(<em>n</em>)</code>,
2393	where <em>n</em> is greater than the number of upvalues of the
2394	current function (but not greater than 256),
2395	produces an acceptable (but invalid) index.
2396
2397
2398
2399
2400
2401	<h2>3.5 - <a name="3.5">Registry</a></h2>
2402
2403	<p>
2404	Lua provides a <em>registry</em>,
2405	a pre-defined table that can be used by any C code to
2406	store whatever Lua value it needs to store.
2407	This table is always located at pseudo-index
2408	<a name="pdf-LUA_REGISTRYINDEX"><code>LUA_REGISTRYINDEX</code></a>.
2409	Any C library can store data into this table,
2410	but it should take care to choose keys different from those used
2411	by other libraries, to avoid collisions.
2412	Typically, you should use as key a string containing your library name
2413	or a light userdata with the address of a C object in your code.
2414
2415
2416	<p>
2417	The integer keys in the registry are used by the reference mechanism,
2418	implemented by the auxiliary library,
2419	and therefore should not be used for other purposes.
2420
2421
2422
2423
2424
2425	<h2>3.6 - <a name="3.6">Error Handling in C</a></h2>
2426
2427	<p>
2428	Internally, Lua uses the C <code>longjmp</code> facility to handle errors.
2429	(You can also choose to use exceptions if you use C++;
2430	see file <code>luaconf.h</code>.)
2431	When Lua faces any error
2432	(such as memory allocation errors, type errors, syntax errors,
2433	and runtime errors)
2434	it <em>raises</em> an error;
2435	that is, it does a long jump.
2436	A <em>protected environment</em> uses <code>setjmp</code>
2437	to set a recover point;
2438	any error jumps to the most recent active recover point.
2439
2440
2441	<p>
2442	Most functions in the API can throw an error,
2443	for instance due to a memory allocation error.
2444	The documentation for each function indicates whether
2445	it can throw errors.
2446
2447
2448	<p>
2449	Inside a C function you can throw an error by calling <a href="#lua_error"><code>lua_error</code></a>.
2450
2451
2452
2453
2454
2455	<h2>3.7 - <a name="3.7">Functions and Types</a></h2>
2456
2457	<p>
2458	Here we list all functions and types from the C API in
2459	alphabetical order.
2460	Each function has an indicator like this:
2461	<span class="apii">[-o, +p, <em>x</em>]</span>
2462
2463
2464	<p>
2465	The first field, <code>o</code>,
2466	is how many elements the function pops from the stack.
2467	The second field, <code>p</code>,
2468	is how many elements the function pushes onto the stack.
2469	(Any function always pushes its results after popping its arguments.)
2470	A field in the form <code>x\|y</code> means the function can push (or pop)
2471	<code>x</code> or <code>y</code> elements,
2472	depending on the situation;
2473	an interrogation mark '<code>?</code>' means that
2474	we cannot know how many elements the function pops/pushes
2475	by looking only at its arguments
2476	(e.g., they may depend on what is on the stack).
2477	The third field, <code>x</code>,
2478	tells whether the function may throw errors:
2479	'<code>-</code>' means the function never throws any error;
2480	'<code>m</code>' means the function may throw an error
2481	only due to not enough memory;
2482	'<code>e</code>' means the function may throw other kinds of errors;
2483	'<code>v</code>' means the function may throw an error on purpose.
2484
2485
2486
2487	<hr><h3><a name="lua_Alloc"><code>lua_Alloc</code></a></h3>
2488	<pre>typedef void * (lua_Alloc) (void ud,
2489	void *ptr,
2490	size_t osize,
2491	size_t nsize);</pre>
2492
2493	<p>
2494	The type of the memory-allocation function used by Lua states.
2495	The allocator function must provide a
2496	functionality similar to <code>realloc</code>,
2497	but not exactly the same.
2498	Its arguments are
2499	<code>ud</code>, an opaque pointer passed to <a href="#lua_newstate"><code>lua_newstate</code></a>;
2500	<code>ptr</code>, a pointer to the block being allocated/reallocated/freed;
2501	<code>osize</code>, the original size of the block;
2502	<code>nsize</code>, the new size of the block.
2503	<code>ptr</code> is <code>NULL</code> if and only if <code>osize</code> is zero.
2504	When <code>nsize</code> is zero, the allocator must return <code>NULL</code>;
2505	if <code>osize</code> is not zero,
2506	it should free the block pointed to by <code>ptr</code>.
2507	When <code>nsize</code> is not zero, the allocator returns <code>NULL</code>
2508	if and only if it cannot fill the request.
2509	When <code>nsize</code> is not zero and <code>osize</code> is zero,
2510	the allocator should behave like <code>malloc</code>.
2511	When <code>nsize</code> and <code>osize</code> are not zero,
2512	the allocator behaves like <code>realloc</code>.
2513	Lua assumes that the allocator never fails when
2514	<code>osize >= nsize</code>.
2515
2516
2517	<p>
2518	Here is a simple implementation for the allocator function.
2519	It is used in the auxiliary library by <a href="#luaL_newstate"><code>luaL_newstate</code></a>.
2520
2521	<pre>
2522	static void l_alloc (void ud, void *ptr, size_t osize,
2523	size_t nsize) {
2524	(void)ud; (void)osize; /* not used */
2525	if (nsize == 0) {
2526	free(ptr);
2527	return NULL;
2528	}
2529	else
2530	return realloc(ptr, nsize);
2531	}
2532	</pre><p>
2533	This code assumes
2534	that <code>free(NULL)</code> has no effect and that
2535	<code>realloc(NULL, size)</code> is equivalent to <code>malloc(size)</code>.
2536	ANSI C ensures both behaviors.
2537
2538
2539
2540
2541
2542	<hr><h3><a name="lua_atpanic"><code>lua_atpanic</code></a></h3><p>
2543	<span class="apii">[-0, +0, <em>-</em>]</span>
2544	<pre>lua_CFunction lua_atpanic (lua_State *L, lua_CFunction panicf);</pre>
2545
2546	<p>
2547	Sets a new panic function and returns the old one.
2548
2549
2550	<p>
2551	If an error happens outside any protected environment,
2552	Lua calls a <em>panic function</em>
2553	and then calls <code>exit(EXIT_FAILURE)</code>,
2554	thus exiting the host application.
2555	Your panic function can avoid this exit by
2556	never returning (e.g., doing a long jump).
2557
2558
2559	<p>
2560	The panic function can access the error message at the top of the stack.
2561
2562
2563
2564
2565
2566	<hr><h3><a name="lua_call"><code>lua_call</code></a></h3><p>
2567	<span class="apii">[-(nargs + 1), +nresults, <em>e</em>]</span>
2568	<pre>void lua_call (lua_State *L, int nargs, int nresults);</pre>
2569
2570	<p>
2571	Calls a function.
2572
2573
2574	<p>
2575	To call a function you must use the following protocol:
2576	first, the function to be called is pushed onto the stack;
2577	then, the arguments to the function are pushed
2578	in direct order;
2579	that is, the first argument is pushed first.
2580	Finally you call <a href="#lua_call"><code>lua_call</code></a>;
2581	<code>nargs</code> is the number of arguments that you pushed onto the stack.
2582	All arguments and the function value are popped from the stack
2583	when the function is called.
2584	The function results are pushed onto the stack when the function returns.
2585	The number of results is adjusted to <code>nresults</code>,
2586	unless <code>nresults</code> is <a name="pdf-LUA_MULTRET"><code>LUA_MULTRET</code></a>.
2587	In this case, <em>all</em> results from the function are pushed.
2588	Lua takes care that the returned values fit into the stack space.
2589	The function results are pushed onto the stack in direct order
2590	(the first result is pushed first),
2591	so that after the call the last result is on the top of the stack.
2592
2593
2594	<p>
2595	Any error inside the called function is propagated upwards
2596	(with a <code>longjmp</code>).
2597
2598
2599	<p>
2600	The following example shows how the host program can do the
2601	equivalent to this Lua code:
2602
2603	<pre>
2604	a = f("how", t.x, 14)
2605	</pre><p>
2606	Here it is in C:
2607
2608	<pre>
2609	lua_getfield(L, LUA_GLOBALSINDEX, "f"); /* function to be called */
2610	lua_pushstring(L, "how"); /* 1st argument */
2611	lua_getfield(L, LUA_GLOBALSINDEX, "t"); /* table to be indexed */
2612	lua_getfield(L, -1, "x"); /* push result of t.x (2nd arg) */
2613	lua_remove(L, -2); /* remove 't' from the stack */
2614	lua_pushinteger(L, 14); /* 3rd argument */
2615	lua_call(L, 3, 1); /* call 'f' with 3 arguments and 1 result */
2616	lua_setfield(L, LUA_GLOBALSINDEX, "a"); /* set global 'a' */
2617	</pre><p>
2618	Note that the code above is "balanced":
2619	at its end, the stack is back to its original configuration.
2620	This is considered good programming practice.
2621
2622
2623
2624
2625
2626	<hr><h3><a name="lua_CFunction"><code>lua_CFunction</code></a></h3>
2627	<pre>typedef int (lua_CFunction) (lua_State L);</pre>
2628
2629	<p>
2630	Type for C functions.
2631
2632
2633	<p>
2634	In order to communicate properly with Lua,
2635	a C function must use the following protocol,
2636	which defines the way parameters and results are passed:
2637	a C function receives its arguments from Lua in its stack
2638	in direct order (the first argument is pushed first).
2639	So, when the function starts,
2640	<code>lua_gettop(L)</code> returns the number of arguments received by the function.
2641	The first argument (if any) is at index 1
2642	and its last argument is at index <code>lua_gettop(L)</code>.
2643	To return values to Lua, a C function just pushes them onto the stack,
2644	in direct order (the first result is pushed first),
2645	and returns the number of results.
2646	Any other value in the stack below the results will be properly
2647	discarded by Lua.
2648	Like a Lua function, a C function called by Lua can also return
2649	many results.
2650
2651
2652	<p>
2653	As an example, the following function receives a variable number
2654	of numerical arguments and returns their average and sum:
2655
2656	<pre>
2657	static int foo (lua_State *L) {
2658	int n = lua_gettop(L); /* number of arguments */
2659	lua_Number sum = 0;
2660	int i;
2661	for (i = 1; i <= n; i++) {
2662	if (!lua_isnumber(L, i)) {
2663	lua_pushstring(L, "incorrect argument");
2664	lua_error(L);
2665	}
2666	sum += lua_tonumber(L, i);
2667	}
2668	lua_pushnumber(L, sum/n); /* first result */
2669	lua_pushnumber(L, sum); /* second result */
2670	return 2; /* number of results */
2671	}
2672	</pre>
2673
2674
2675
2676
2677	<hr><h3><a name="lua_checkstack"><code>lua_checkstack</code></a></h3><p>
2678	<span class="apii">[-0, +0, <em>m</em>]</span>
2679	<pre>int lua_checkstack (lua_State *L, int extra);</pre>
2680
2681	<p>
2682	Ensures that there are at least <code>extra</code> free stack slots in the stack.
2683	It returns false if it cannot grow the stack to that size.
2684	This function never shrinks the stack;
2685	if the stack is already larger than the new size,
2686	it is left unchanged.
2687
2688
2689
2690
2691
2692	<hr><h3><a name="lua_close"><code>lua_close</code></a></h3><p>
2693	<span class="apii">[-0, +0, <em>-</em>]</span>
2694	<pre>void lua_close (lua_State *L);</pre>
2695
2696	<p>
2697	Destroys all objects in the given Lua state
2698	(calling the corresponding garbage-collection metamethods, if any)
2699	and frees all dynamic memory used by this state.
2700	On several platforms, you may not need to call this function,
2701	because all resources are naturally released when the host program ends.
2702	On the other hand, long-running programs,
2703	such as a daemon or a web server,
2704	might need to release states as soon as they are not needed,
2705	to avoid growing too large.
2706
2707
2708
2709
2710
2711	<hr><h3><a name="lua_concat"><code>lua_concat</code></a></h3><p>
2712	<span class="apii">[-n, +1, <em>e</em>]</span>
2713	<pre>void lua_concat (lua_State *L, int n);</pre>
2714
2715	<p>
2716	Concatenates the <code>n</code> values at the top of the stack,
2717	pops them, and leaves the result at the top.
2718	If <code>n</code> is 1, the result is the single value on the stack
2719	(that is, the function does nothing);
2720	if <code>n</code> is 0, the result is the empty string.
2721	Concatenation is performed following the usual semantics of Lua
2722	(see <a href="#2.5.4">§2.5.4</a>).
2723
2724
2725
2726
2727
2728	<hr><h3><a name="lua_cpcall"><code>lua_cpcall</code></a></h3><p>
2729	<span class="apii">[-0, +(0\|1), <em>-</em>]</span>
2730	<pre>int lua_cpcall (lua_State L, lua_CFunction func, void ud);</pre>
2731
2732	<p>
2733	Calls the C function <code>func</code> in protected mode.
2734	<code>func</code> starts with only one element in its stack,
2735	a light userdata containing <code>ud</code>.
2736	In case of errors,
2737	<a href="#lua_cpcall"><code>lua_cpcall</code></a> returns the same error codes as <a href="#lua_pcall"><code>lua_pcall</code></a>,
2738	plus the error object on the top of the stack;
2739	otherwise, it returns zero, and does not change the stack.
2740	All values returned by <code>func</code> are discarded.
2741
2742
2743
2744
2745
2746	<hr><h3><a name="lua_createtable"><code>lua_createtable</code></a></h3><p>
2747	<span class="apii">[-0, +1, <em>m</em>]</span>
2748	<pre>void lua_createtable (lua_State *L, int narr, int nrec);</pre>
2749
2750	<p>
2751	Creates a new empty table and pushes it onto the stack.
2752	The new table has space pre-allocated
2753	for <code>narr</code> array elements and <code>nrec</code> non-array elements.
2754	This pre-allocation is useful when you know exactly how many elements
2755	the table will have.
2756	Otherwise you can use the function <a href="#lua_newtable"><code>lua_newtable</code></a>.
2757
2758
2759
2760
2761
2762	<hr><h3><a name="lua_dump"><code>lua_dump</code></a></h3><p>
2763	<span class="apii">[-0, +0, <em>m</em>]</span>
2764	<pre>int lua_dump (lua_State L, lua_Writer writer, void data);</pre>
2765
2766	<p>
2767	Dumps a function as a binary chunk.
2768	Receives a Lua function on the top of the stack
2769	and produces a binary chunk that,
2770	if loaded again,
2771	results in a function equivalent to the one dumped.
2772	As it produces parts of the chunk,
2773	<a href="#lua_dump"><code>lua_dump</code></a> calls function <code>writer</code> (see <a href="#lua_Writer"><code>lua_Writer</code></a>)
2774	with the given <code>data</code>
2775	to write them.
2776
2777
2778	<p>
2779	The value returned is the error code returned by the last
2780	call to the writer;
2781	0 means no errors.
2782
2783
2784	<p>
2785	This function does not pop the Lua function from the stack.
2786
2787
2788
2789
2790
2791	<hr><h3><a name="lua_equal"><code>lua_equal</code></a></h3><p>
2792	<span class="apii">[-0, +0, <em>e</em>]</span>
2793	<pre>int lua_equal (lua_State *L, int index1, int index2);</pre>
2794
2795	<p>
2796	Returns 1 if the two values in acceptable indices <code>index1</code> and
2797	<code>index2</code> are equal,
2798	following the semantics of the Lua <code>==</code> operator
2799	(that is, may call metamethods).
2800	Otherwise returns 0.
2801	Also returns 0 if any of the indices is non valid.
2802
2803
2804
2805
2806
2807	<hr><h3><a name="lua_error"><code>lua_error</code></a></h3><p>
2808	<span class="apii">[-1, +0, <em>v</em>]</span>
2809	<pre>int lua_error (lua_State *L);</pre>
2810
2811	<p>
2812	Generates a Lua error.
2813	The error message (which can actually be a Lua value of any type)
2814	must be on the stack top.
2815	This function does a long jump,
2816	and therefore never returns.
2817	(see <a href="#luaL_error"><code>luaL_error</code></a>).
2818
2819
2820
2821
2822
2823	<hr><h3><a name="lua_gc"><code>lua_gc</code></a></h3><p>
2824	<span class="apii">[-0, +0, <em>e</em>]</span>
2825	<pre>int lua_gc (lua_State *L, int what, int data);</pre>
2826
2827	<p>
2828	Controls the garbage collector.
2829
2830
2831	<p>
2832	This function performs several tasks,
2833	according to the value of the parameter <code>what</code>:
2834
2835	<ul>
2836
2837	<li><b><code>LUA_GCSTOP</code>:</b>
2838	stops the garbage collector.
2839	</li>
2840
2841	<li><b><code>LUA_GCRESTART</code>:</b>
2842	restarts the garbage collector.
2843	</li>
2844
2845	<li><b><code>LUA_GCCOLLECT</code>:</b>
2846	performs a full garbage-collection cycle.
2847	</li>
2848
2849	<li><b><code>LUA_GCCOUNT</code>:</b>
2850	returns the current amount of memory (in Kbytes) in use by Lua.
2851	</li>
2852
2853	<li><b><code>LUA_GCCOUNTB</code>:</b>
2854	returns the remainder of dividing the current amount of bytes of
2855	memory in use by Lua by 1024.
2856	</li>
2857
2858	<li><b><code>LUA_GCSTEP</code>:</b>
2859	performs an incremental step of garbage collection.
2860	The step "size" is controlled by <code>data</code>
2861	(larger values mean more steps) in a non-specified way.
2862	If you want to control the step size
2863	you must experimentally tune the value of <code>data</code>.
2864	The function returns 1 if the step finished a
2865	garbage-collection cycle.
2866	</li>
2867
2868	<li><b><code>LUA_GCSETPAUSE</code>:</b>
2869	sets <code>data</code> as the new value
2870	for the <em>pause</em> of the collector (see <a href="#2.10">§2.10</a>).
2871	The function returns the previous value of the pause.
2872	</li>
2873
2874	<li><b><code>LUA_GCSETSTEPMUL</code>:</b>
2875	sets <code>data</code> as the new value for the <em>step multiplier</em> of
2876	the collector (see <a href="#2.10">§2.10</a>).
2877	The function returns the previous value of the step multiplier.
2878	</li>
2879
2880	</ul>
2881
2882
2883
2884
2885	<hr><h3><a name="lua_getallocf"><code>lua_getallocf</code></a></h3><p>
2886	<span class="apii">[-0, +0, <em>-</em>]</span>
2887	<pre>lua_Alloc lua_getallocf (lua_State L, void *ud);</pre>
2888
2889	<p>
2890	Returns the memory-allocation function of a given state.
2891	If <code>ud</code> is not <code>NULL</code>, Lua stores in <code>*ud</code> the
2892	opaque pointer passed to <a href="#lua_newstate"><code>lua_newstate</code></a>.
2893
2894
2895
2896
2897
2898	<hr><h3><a name="lua_getfenv"><code>lua_getfenv</code></a></h3><p>
2899	<span class="apii">[-0, +1, <em>-</em>]</span>
2900	<pre>void lua_getfenv (lua_State *L, int index);</pre>
2901
2902	<p>
2903	Pushes onto the stack the environment table of
2904	the value at the given index.
2905
2906
2907
2908
2909
2910	<hr><h3><a name="lua_getfield"><code>lua_getfield</code></a></h3><p>
2911	<span class="apii">[-0, +1, <em>e</em>]</span>
2912	<pre>void lua_getfield (lua_State L, int index, const char k);</pre>
2913
2914	<p>
2915	Pushes onto the stack the value <code>t[k]</code>,
2916	where <code>t</code> is the value at the given valid index.
2917	As in Lua, this function may trigger a metamethod
2918	for the "index" event (see <a href="#2.8">§2.8</a>).
2919
2920
2921
2922
2923
2924	<hr><h3><a name="lua_getglobal"><code>lua_getglobal</code></a></h3><p>
2925	<span class="apii">[-0, +1, <em>e</em>]</span>
2926	<pre>void lua_getglobal (lua_State L, const char name);</pre>
2927
2928	<p>
2929	Pushes onto the stack the value of the global <code>name</code>.
2930	It is defined as a macro:
2931
2932	<pre>
2933	#define lua_getglobal(L,s) lua_getfield(L, LUA_GLOBALSINDEX, s)
2934	</pre>
2935
2936
2937
2938
2939	<hr><h3><a name="lua_getmetatable"><code>lua_getmetatable</code></a></h3><p>
2940	<span class="apii">[-0, +(0\|1), <em>-</em>]</span>
2941	<pre>int lua_getmetatable (lua_State *L, int index);</pre>
2942
2943	<p>
2944	Pushes onto the stack the metatable of the value at the given
2945	acceptable index.
2946	If the index is not valid,
2947	or if the value does not have a metatable,
2948	the function returns 0 and pushes nothing on the stack.
2949
2950
2951
2952
2953
2954	<hr><h3><a name="lua_gettable"><code>lua_gettable</code></a></h3><p>
2955	<span class="apii">[-1, +1, <em>e</em>]</span>
2956	<pre>void lua_gettable (lua_State *L, int index);</pre>
2957
2958	<p>
2959	Pushes onto the stack the value <code>t[k]</code>,
2960	where <code>t</code> is the value at the given valid index
2961	and <code>k</code> is the value at the top of the stack.
2962
2963
2964	<p>
2965	This function pops the key from the stack
2966	(putting the resulting value in its place).
2967	As in Lua, this function may trigger a metamethod
2968	for the "index" event (see <a href="#2.8">§2.8</a>).
2969
2970
2971
2972
2973
2974	<hr><h3><a name="lua_gettop"><code>lua_gettop</code></a></h3><p>
2975	<span class="apii">[-0, +0, <em>-</em>]</span>
2976	<pre>int lua_gettop (lua_State *L);</pre>
2977
2978	<p>
2979	Returns the index of the top element in the stack.
2980	Because indices start at 1,
2981	this result is equal to the number of elements in the stack
2982	(and so 0 means an empty stack).
2983
2984
2985
2986
2987
2988	<hr><h3><a name="lua_insert"><code>lua_insert</code></a></h3><p>
2989	<span class="apii">[-1, +1, <em>-</em>]</span>
2990	<pre>void lua_insert (lua_State *L, int index);</pre>
2991
2992	<p>
2993	Moves the top element into the given valid index,
2994	shifting up the elements above this index to open space.
2995	Cannot be called with a pseudo-index,
2996	because a pseudo-index is not an actual stack position.
2997
2998
2999
3000
3001
3002	<hr><h3><a name="lua_Integer"><code>lua_Integer</code></a></h3>
3003	<pre>typedef ptrdiff_t lua_Integer;</pre>
3004
3005	<p>
3006	The type used by the Lua API to represent integral values.
3007
3008
3009	<p>
3010	By default it is a <code>ptrdiff_t</code>,
3011	which is usually the largest signed integral type the machine handles
3012	"comfortably".
3013
3014
3015
3016
3017
3018	<hr><h3><a name="lua_isboolean"><code>lua_isboolean</code></a></h3><p>
3019	<span class="apii">[-0, +0, <em>-</em>]</span>
3020	<pre>int lua_isboolean (lua_State *L, int index);</pre>
3021
3022	<p>
3023	Returns 1 if the value at the given acceptable index has type boolean,
3024	and 0 otherwise.
3025
3026
3027
3028
3029
3030	<hr><h3><a name="lua_iscfunction"><code>lua_iscfunction</code></a></h3><p>
3031	<span class="apii">[-0, +0, <em>-</em>]</span>
3032	<pre>int lua_iscfunction (lua_State *L, int index);</pre>
3033
3034	<p>
3035	Returns 1 if the value at the given acceptable index is a C function,
3036	and 0 otherwise.
3037
3038
3039
3040
3041
3042	<hr><h3><a name="lua_isfunction"><code>lua_isfunction</code></a></h3><p>
3043	<span class="apii">[-0, +0, <em>-</em>]</span>
3044	<pre>int lua_isfunction (lua_State *L, int index);</pre>
3045
3046	<p>
3047	Returns 1 if the value at the given acceptable index is a function
3048	(either C or Lua), and 0 otherwise.
3049
3050
3051
3052
3053
3054	<hr><h3><a name="lua_islightuserdata"><code>lua_islightuserdata</code></a></h3><p>
3055	<span class="apii">[-0, +0, <em>-</em>]</span>
3056	<pre>int lua_islightuserdata (lua_State *L, int index);</pre>
3057
3058	<p>
3059	Returns 1 if the value at the given acceptable index is a light userdata,
3060	and 0 otherwise.
3061
3062
3063
3064
3065
3066	<hr><h3><a name="lua_isnil"><code>lua_isnil</code></a></h3><p>
3067	<span class="apii">[-0, +0, <em>-</em>]</span>
3068	<pre>int lua_isnil (lua_State *L, int index);</pre>
3069
3070	<p>
3071	Returns 1 if the value at the given acceptable index is <b>nil</b>,
3072	and 0 otherwise.
3073
3074
3075
3076
3077
3078	<hr><h3><a name="lua_isnone"><code>lua_isnone</code></a></h3><p>
3079	<span class="apii">[-0, +0, <em>-</em>]</span>
3080	<pre>int lua_isnone (lua_State *L, int index);</pre>
3081
3082	<p>
3083	Returns 1 if the given acceptable index is not valid
3084	(that is, it refers to an element outside the current stack),
3085	and 0 otherwise.
3086
3087
3088
3089
3090
3091	<hr><h3><a name="lua_isnoneornil"><code>lua_isnoneornil</code></a></h3><p>
3092	<span class="apii">[-0, +0, <em>-</em>]</span>
3093	<pre>int lua_isnoneornil (lua_State *L, int index);</pre>
3094
3095	<p>
3096	Returns 1 if the given acceptable index is not valid
3097	(that is, it refers to an element outside the current stack)
3098	or if the value at this index is <b>nil</b>,
3099	and 0 otherwise.
3100
3101
3102
3103
3104
3105	<hr><h3><a name="lua_isnumber"><code>lua_isnumber</code></a></h3><p>
3106	<span class="apii">[-0, +0, <em>-</em>]</span>
3107	<pre>int lua_isnumber (lua_State *L, int index);</pre>
3108
3109	<p>
3110	Returns 1 if the value at the given acceptable index is a number
3111	or a string convertible to a number,
3112	and 0 otherwise.
3113
3114
3115
3116
3117
3118	<hr><h3><a name="lua_isstring"><code>lua_isstring</code></a></h3><p>
3119	<span class="apii">[-0, +0, <em>-</em>]</span>
3120	<pre>int lua_isstring (lua_State *L, int index);</pre>
3121
3122	<p>
3123	Returns 1 if the value at the given acceptable index is a string
3124	or a number (which is always convertible to a string),
3125	and 0 otherwise.
3126
3127
3128
3129
3130
3131	<hr><h3><a name="lua_istable"><code>lua_istable</code></a></h3><p>
3132	<span class="apii">[-0, +0, <em>-</em>]</span>
3133	<pre>int lua_istable (lua_State *L, int index);</pre>
3134
3135	<p>
3136	Returns 1 if the value at the given acceptable index is a table,
3137	and 0 otherwise.
3138
3139
3140
3141
3142
3143	<hr><h3><a name="lua_isthread"><code>lua_isthread</code></a></h3><p>
3144	<span class="apii">[-0, +0, <em>-</em>]</span>
3145	<pre>int lua_isthread (lua_State *L, int index);</pre>
3146
3147	<p>
3148	Returns 1 if the value at the given acceptable index is a thread,
3149	and 0 otherwise.
3150
3151
3152
3153
3154
3155	<hr><h3><a name="lua_isuserdata"><code>lua_isuserdata</code></a></h3><p>
3156	<span class="apii">[-0, +0, <em>-</em>]</span>
3157	<pre>int lua_isuserdata (lua_State *L, int index);</pre>
3158
3159	<p>
3160	Returns 1 if the value at the given acceptable index is a userdata
3161	(either full or light), and 0 otherwise.
3162
3163
3164
3165
3166
3167	<hr><h3><a name="lua_lessthan"><code>lua_lessthan</code></a></h3><p>
3168	<span class="apii">[-0, +0, <em>e</em>]</span>
3169	<pre>int lua_lessthan (lua_State *L, int index1, int index2);</pre>
3170
3171	<p>
3172	Returns 1 if the value at acceptable index <code>index1</code> is smaller
3173	than the value at acceptable index <code>index2</code>,
3174	following the semantics of the Lua <code><</code> operator
3175	(that is, may call metamethods).
3176	Otherwise returns 0.
3177	Also returns 0 if any of the indices is non valid.
3178
3179
3180
3181
3182
3183	<hr><h3><a name="lua_load"><code>lua_load</code></a></h3><p>
3184	<span class="apii">[-0, +1, <em>-</em>]</span>
3185	<pre>int lua_load (lua_State *L,
3186	lua_Reader reader,
3187	void *data,
3188	const char *chunkname);</pre>
3189
3190	<p>
3191	Loads a Lua chunk.
3192	If there are no errors,
3193	<a href="#lua_load"><code>lua_load</code></a> pushes the compiled chunk as a Lua
3194	function on top of the stack.
3195	Otherwise, it pushes an error message.
3196	The return values of <a href="#lua_load"><code>lua_load</code></a> are:
3197
3198	<ul>
3199
3200	<li><b>0:</b> no errors;</li>
3201
3202	<li><b><a name="pdf-LUA_ERRSYNTAX"><code>LUA_ERRSYNTAX</code></a>:</b>
3203	syntax error during pre-compilation;</li>
3204
3205	<li><b><a href="#pdf-LUA_ERRMEM"><code>LUA_ERRMEM</code></a>:</b>
3206	memory allocation error.</li>
3207
3208	</ul>
3209
3210	<p>
3211	This function only loads a chunk;
3212	it does not run it.
3213
3214
3215	<p>
3216	<a href="#lua_load"><code>lua_load</code></a> automatically detects whether the chunk is text or binary,
3217	and loads it accordingly (see program <code>luac</code>).
3218
3219
3220	<p>
3221	The <a href="#lua_load"><code>lua_load</code></a> function uses a user-supplied <code>reader</code> function
3222	to read the chunk (see <a href="#lua_Reader"><code>lua_Reader</code></a>).
3223	The <code>data</code> argument is an opaque value passed to the reader function.
3224
3225
3226	<p>
3227	The <code>chunkname</code> argument gives a name to the chunk,
3228	which is used for error messages and in debug information (see <a href="#3.8">§3.8</a>).
3229
3230
3231
3232
3233
3234	<hr><h3><a name="lua_newstate"><code>lua_newstate</code></a></h3><p>
3235	<span class="apii">[-0, +0, <em>-</em>]</span>
3236	<pre>lua_State lua_newstate (lua_Alloc f, void ud);</pre>
3237
3238	<p>
3239	Creates a new, independent state.
3240	Returns <code>NULL</code> if cannot create the state
3241	(due to lack of memory).
3242	The argument <code>f</code> is the allocator function;
3243	Lua does all memory allocation for this state through this function.
3244	The second argument, <code>ud</code>, is an opaque pointer that Lua
3245	simply passes to the allocator in every call.
3246
3247
3248
3249
3250
3251	<hr><h3><a name="lua_newtable"><code>lua_newtable</code></a></h3><p>
3252	<span class="apii">[-0, +1, <em>m</em>]</span>
3253	<pre>void lua_newtable (lua_State *L);</pre>
3254
3255	<p>
3256	Creates a new empty table and pushes it onto the stack.
3257	It is equivalent to <code>lua_createtable(L, 0, 0)</code>.
3258
3259
3260
3261
3262
3263	<hr><h3><a name="lua_newthread"><code>lua_newthread</code></a></h3><p>
3264	<span class="apii">[-0, +1, <em>m</em>]</span>
3265	<pre>lua_State lua_newthread (lua_State L);</pre>
3266
3267	<p>
3268	Creates a new thread, pushes it on the stack,
3269	and returns a pointer to a <a href="#lua_State"><code>lua_State</code></a> that represents this new thread.
3270	The new state returned by this function shares with the original state
3271	all global objects (such as tables),
3272	but has an independent execution stack.
3273
3274
3275	<p>
3276	There is no explicit function to close or to destroy a thread.
3277	Threads are subject to garbage collection,
3278	like any Lua object.
3279
3280
3281
3282
3283
3284	<hr><h3><a name="lua_newuserdata"><code>lua_newuserdata</code></a></h3><p>
3285	<span class="apii">[-0, +1, <em>m</em>]</span>
3286	<pre>void lua_newuserdata (lua_State L, size_t size);</pre>
3287
3288	<p>
3289	This function allocates a new block of memory with the given size,
3290	pushes onto the stack a new full userdata with the block address,
3291	and returns this address.
3292
3293
3294	<p>
3295	Userdata represent C values in Lua.
3296	A <em>full userdata</em> represents a block of memory.
3297	It is an object (like a table):
3298	you must create it, it can have its own metatable,
3299	and you can detect when it is being collected.
3300	A full userdata is only equal to itself (under raw equality).
3301
3302
3303	<p>
3304	When Lua collects a full userdata with a <code>gc</code> metamethod,
3305	Lua calls the metamethod and marks the userdata as finalized.
3306	When this userdata is collected again then
3307	Lua frees its corresponding memory.
3308
3309
3310
3311
3312
3313	<hr><h3><a name="lua_next"><code>lua_next</code></a></h3><p>
3314	<span class="apii">[-1, +(2\|0), <em>e</em>]</span>
3315	<pre>int lua_next (lua_State *L, int index);</pre>
3316
3317	<p>
3318	Pops a key from the stack,
3319	and pushes a key-value pair from the table at the given index
3320	(the "next" pair after the given key).
3321	If there are no more elements in the table,
3322	then <a href="#lua_next"><code>lua_next</code></a> returns 0 (and pushes nothing).
3323
3324
3325	<p>
3326	A typical traversal looks like this:
3327
3328	<pre>
3329	/* table is in the stack at index 't' */
3330	lua_pushnil(L); /* first key */
3331	while (lua_next(L, t) != 0) {
3332	/* uses 'key' (at index -2) and 'value' (at index -1) */
3333	printf("%s - %s\n",
3334	lua_typename(L, lua_type(L, -2)),
3335	lua_typename(L, lua_type(L, -1)));
3336	/* removes 'value'; keeps 'key' for next iteration */
3337	lua_pop(L, 1);
3338	}
3339	</pre>
3340
3341	<p>
3342	While traversing a table,
3343	do not call <a href="#lua_tolstring"><code>lua_tolstring</code></a> directly on a key,
3344	unless you know that the key is actually a string.
3345	Recall that <a href="#lua_tolstring"><code>lua_tolstring</code></a> <em>changes</em>
3346	the value at the given index;
3347	this confuses the next call to <a href="#lua_next"><code>lua_next</code></a>.
3348
3349
3350
3351
3352
3353	<hr><h3><a name="lua_Number"><code>lua_Number</code></a></h3>
3354	<pre>typedef double lua_Number;</pre>
3355
3356	<p>
3357	The type of numbers in Lua.
3358	By default, it is double, but that can be changed in <code>luaconf.h</code>.
3359
3360
3361	<p>
3362	Through the configuration file you can change
3363	Lua to operate with another type for numbers (e.g., float or long).
3364
3365
3366
3367
3368
3369	<hr><h3><a name="lua_objlen"><code>lua_objlen</code></a></h3><p>
3370	<span class="apii">[-0, +0, <em>-</em>]</span>
3371	<pre>size_t lua_objlen (lua_State *L, int index);</pre>
3372
3373	<p>
3374	Returns the "length" of the value at the given acceptable index:
3375	for strings, this is the string length;
3376	for tables, this is the result of the length operator ('<code>#</code>');
3377	for userdata, this is the size of the block of memory allocated
3378	for the userdata;
3379	for other values, it is 0.
3380
3381
3382
3383
3384
3385	<hr><h3><a name="lua_pcall"><code>lua_pcall</code></a></h3><p>
3386	<span class="apii">[-(nargs + 1), +(nresults\|1), <em>-</em>]</span>
3387	<pre>int lua_pcall (lua_State *L, int nargs, int nresults, int errfunc);</pre>
3388
3389	<p>
3390	Calls a function in protected mode.
3391
3392
3393	<p>
3394	Both <code>nargs</code> and <code>nresults</code> have the same meaning as
3395	in <a href="#lua_call"><code>lua_call</code></a>.
3396	If there are no errors during the call,
3397	<a href="#lua_pcall"><code>lua_pcall</code></a> behaves exactly like <a href="#lua_call"><code>lua_call</code></a>.
3398	However, if there is any error,
3399	<a href="#lua_pcall"><code>lua_pcall</code></a> catches it,
3400	pushes a single value on the stack (the error message),
3401	and returns an error code.
3402	Like <a href="#lua_call"><code>lua_call</code></a>,
3403	<a href="#lua_pcall"><code>lua_pcall</code></a> always removes the function
3404	and its arguments from the stack.
3405
3406
3407	<p>
3408	If <code>errfunc</code> is 0,
3409	then the error message returned on the stack
3410	is exactly the original error message.
3411	Otherwise, <code>errfunc</code> is the stack index of an
3412	<em>error handler function</em>.
3413	(In the current implementation, this index cannot be a pseudo-index.)
3414	In case of runtime errors,
3415	this function will be called with the error message
3416	and its return value will be the message returned on the stack by <a href="#lua_pcall"><code>lua_pcall</code></a>.
3417
3418
3419	<p>
3420	Typically, the error handler function is used to add more debug
3421	information to the error message, such as a stack traceback.
3422	Such information cannot be gathered after the return of <a href="#lua_pcall"><code>lua_pcall</code></a>,
3423	since by then the stack has unwound.
3424
3425
3426	<p>
3427	The <a href="#lua_pcall"><code>lua_pcall</code></a> function returns 0 in case of success
3428	or one of the following error codes
3429	(defined in <code>lua.h</code>):
3430
3431	<ul>
3432
3433	<li><b><a name="pdf-LUA_ERRRUN"><code>LUA_ERRRUN</code></a>:</b>
3434	a runtime error.
3435	</li>
3436
3437	<li><b><a name="pdf-LUA_ERRMEM"><code>LUA_ERRMEM</code></a>:</b>
3438	memory allocation error.
3439	For such errors, Lua does not call the error handler function.
3440	</li>
3441
3442	<li><b><a name="pdf-LUA_ERRERR"><code>LUA_ERRERR</code></a>:</b>
3443	error while running the error handler function.
3444	</li>
3445
3446	</ul>
3447
3448
3449
3450
3451	<hr><h3><a name="lua_pop"><code>lua_pop</code></a></h3><p>
3452	<span class="apii">[-n, +0, <em>-</em>]</span>
3453	<pre>void lua_pop (lua_State *L, int n);</pre>
3454
3455	<p>
3456	Pops <code>n</code> elements from the stack.
3457
3458
3459
3460
3461
3462	<hr><h3><a name="lua_pushboolean"><code>lua_pushboolean</code></a></h3><p>
3463	<span class="apii">[-0, +1, <em>-</em>]</span>
3464	<pre>void lua_pushboolean (lua_State *L, int b);</pre>
3465
3466	<p>
3467	Pushes a boolean value with value <code>b</code> onto the stack.
3468
3469
3470
3471
3472
3473	<hr><h3><a name="lua_pushcclosure"><code>lua_pushcclosure</code></a></h3><p>
3474	<span class="apii">[-n, +1, <em>m</em>]</span>
3475	<pre>void lua_pushcclosure (lua_State *L, lua_CFunction fn, int n);</pre>
3476
3477	<p>
3478	Pushes a new C closure onto the stack.
3479
3480
3481	<p>
3482	When a C function is created,
3483	it is possible to associate some values with it,
3484	thus creating a C closure (see <a href="#3.4">§3.4</a>);
3485	these values are then accessible to the function whenever it is called.
3486	To associate values with a C function,
3487	first these values should be pushed onto the stack
3488	(when there are multiple values, the first value is pushed first).
3489	Then <a href="#lua_pushcclosure"><code>lua_pushcclosure</code></a>
3490	is called to create and push the C function onto the stack,
3491	with the argument <code>n</code> telling how many values should be
3492	associated with the function.
3493	<a href="#lua_pushcclosure"><code>lua_pushcclosure</code></a> also pops these values from the stack.
3494
3495
3496	<p>
3497	The maximum value for <code>n</code> is 255.
3498
3499
3500
3501
3502
3503	<hr><h3><a name="lua_pushcfunction"><code>lua_pushcfunction</code></a></h3><p>
3504	<span class="apii">[-0, +1, <em>m</em>]</span>
3505	<pre>void lua_pushcfunction (lua_State *L, lua_CFunction f);</pre>
3506
3507	<p>
3508	Pushes a C function onto the stack.
3509	This function receives a pointer to a C function
3510	and pushes onto the stack a Lua value of type <code>function</code> that,
3511	when called, invokes the corresponding C function.
3512
3513
3514	<p>
3515	Any function to be registered in Lua must
3516	follow the correct protocol to receive its parameters
3517	and return its results (see <a href="#lua_CFunction"><code>lua_CFunction</code></a>).
3518
3519
3520	<p>
3521	<code>lua_pushcfunction</code> is defined as a macro:
3522
3523	<pre>
3524	#define lua_pushcfunction(L,f) lua_pushcclosure(L,f,0)
3525	</pre>
3526
3527
3528
3529
3530	<hr><h3><a name="lua_pushfstring"><code>lua_pushfstring</code></a></h3><p>
3531	<span class="apii">[-0, +1, <em>m</em>]</span>
3532	<pre>const char lua_pushfstring (lua_State L, const char *fmt, ...);</pre>
3533
3534	<p>
3535	Pushes onto the stack a formatted string
3536	and returns a pointer to this string.
3537	It is similar to the C function <code>sprintf</code>,
3538	but has some important differences:
3539
3540	<ul>
3541
3542	<li>
3543	You do not have to allocate space for the result:
3544	the result is a Lua string and Lua takes care of memory allocation
3545	(and deallocation, through garbage collection).
3546	</li>
3547
3548	<li>
3549	The conversion specifiers are quite restricted.
3550	There are no flags, widths, or precisions.
3551	The conversion specifiers can only be
3552	'<code>%%</code>' (inserts a '<code>%</code>' in the string),
3553	'<code>%s</code>' (inserts a zero-terminated string, with no size restrictions),
3554	'<code>%f</code>' (inserts a <a href="#lua_Number"><code>lua_Number</code></a>),
3555	'<code>%p</code>' (inserts a pointer as a hexadecimal numeral),
3556	'<code>%d</code>' (inserts an <code>int</code>), and
3557	'<code>%c</code>' (inserts an <code>int</code> as a character).
3558	</li>
3559
3560	</ul>
3561
3562
3563
3564
3565	<hr><h3><a name="lua_pushinteger"><code>lua_pushinteger</code></a></h3><p>
3566	<span class="apii">[-0, +1, <em>-</em>]</span>
3567	<pre>void lua_pushinteger (lua_State *L, lua_Integer n);</pre>
3568
3569	<p>
3570	Pushes a number with value <code>n</code> onto the stack.
3571
3572
3573
3574
3575
3576	<hr><h3><a name="lua_pushlightuserdata"><code>lua_pushlightuserdata</code></a></h3><p>
3577	<span class="apii">[-0, +1, <em>-</em>]</span>
3578	<pre>void lua_pushlightuserdata (lua_State L, void p);</pre>
3579
3580	<p>
3581	Pushes a light userdata onto the stack.
3582
3583
3584	<p>
3585	Userdata represent C values in Lua.
3586	A <em>light userdata</em> represents a pointer.
3587	It is a value (like a number):
3588	you do not create it, it has no individual metatable,
3589	and it is not collected (as it was never created).
3590	A light userdata is equal to "any"
3591	light userdata with the same C address.
3592
3593
3594
3595
3596
3597	<hr><h3><a name="lua_pushliteral"><code>lua_pushliteral</code></a></h3><p>
3598	<span class="apii">[-0, +1, <em>m</em>]</span>
3599	<pre>void lua_pushliteral (lua_State L, const char s);</pre>
3600
3601	<p>
3602	This macro is equivalent to <a href="#lua_pushlstring"><code>lua_pushlstring</code></a>,
3603	but can be used only when <code>s</code> is a literal string.
3604	In these cases, it automatically provides the string length.
3605
3606
3607
3608
3609
3610	<hr><h3><a name="lua_pushlstring"><code>lua_pushlstring</code></a></h3><p>
3611	<span class="apii">[-0, +1, <em>m</em>]</span>
3612	<pre>void lua_pushlstring (lua_State L, const char s, size_t len);</pre>
3613
3614	<p>
3615	Pushes the string pointed to by <code>s</code> with size <code>len</code>
3616	onto the stack.
3617	Lua makes (or reuses) an internal copy of the given string,
3618	so the memory at <code>s</code> can be freed or reused immediately after
3619	the function returns.
3620	The string can contain embedded zeros.
3621
3622
3623
3624
3625
3626	<hr><h3><a name="lua_pushnil"><code>lua_pushnil</code></a></h3><p>
3627	<span class="apii">[-0, +1, <em>-</em>]</span>
3628	<pre>void lua_pushnil (lua_State *L);</pre>
3629
3630	<p>
3631	Pushes a nil value onto the stack.
3632
3633
3634
3635
3636
3637	<hr><h3><a name="lua_pushnumber"><code>lua_pushnumber</code></a></h3><p>
3638	<span class="apii">[-0, +1, <em>-</em>]</span>
3639	<pre>void lua_pushnumber (lua_State *L, lua_Number n);</pre>
3640
3641	<p>
3642	Pushes a number with value <code>n</code> onto the stack.
3643
3644
3645
3646
3647
3648	<hr><h3><a name="lua_pushstring"><code>lua_pushstring</code></a></h3><p>
3649	<span class="apii">[-0, +1, <em>m</em>]</span>
3650	<pre>void lua_pushstring (lua_State L, const char s);</pre>
3651
3652	<p>
3653	Pushes the zero-terminated string pointed to by <code>s</code>
3654	onto the stack.
3655	Lua makes (or reuses) an internal copy of the given string,
3656	so the memory at <code>s</code> can be freed or reused immediately after
3657	the function returns.
3658	The string cannot contain embedded zeros;
3659	it is assumed to end at the first zero.
3660
3661
3662
3663
3664
3665	<hr><h3><a name="lua_pushthread"><code>lua_pushthread</code></a></h3><p>
3666	<span class="apii">[-0, +1, <em>-</em>]</span>
3667	<pre>int lua_pushthread (lua_State *L);</pre>
3668
3669	<p>
3670	Pushes the thread represented by <code>L</code> onto the stack.
3671	Returns 1 if this thread is the main thread of its state.
3672
3673
3674
3675
3676
3677	<hr><h3><a name="lua_pushvalue"><code>lua_pushvalue</code></a></h3><p>
3678	<span class="apii">[-0, +1, <em>-</em>]</span>
3679	<pre>void lua_pushvalue (lua_State *L, int index);</pre>
3680
3681	<p>
3682	Pushes a copy of the element at the given valid index
3683	onto the stack.
3684
3685
3686
3687
3688
3689	<hr><h3><a name="lua_pushvfstring"><code>lua_pushvfstring</code></a></h3><p>
3690	<span class="apii">[-0, +1, <em>m</em>]</span>
3691	<pre>const char lua_pushvfstring (lua_State L,
3692	const char *fmt,
3693	va_list argp);</pre>
3694
3695	<p>
3696	Equivalent to <a href="#lua_pushfstring"><code>lua_pushfstring</code></a>, except that it receives a <code>va_list</code>
3697	instead of a variable number of arguments.
3698
3699
3700
3701
3702
3703	<hr><h3><a name="lua_rawequal"><code>lua_rawequal</code></a></h3><p>
3704	<span class="apii">[-0, +0, <em>-</em>]</span>
3705	<pre>int lua_rawequal (lua_State *L, int index1, int index2);</pre>
3706
3707	<p>
3708	Returns 1 if the two values in acceptable indices <code>index1</code> and
3709	<code>index2</code> are primitively equal
3710	(that is, without calling metamethods).
3711	Otherwise returns 0.
3712	Also returns 0 if any of the indices are non valid.
3713
3714
3715
3716
3717
3718	<hr><h3><a name="lua_rawget"><code>lua_rawget</code></a></h3><p>
3719	<span class="apii">[-1, +1, <em>-</em>]</span>
3720	<pre>void lua_rawget (lua_State *L, int index);</pre>
3721
3722	<p>
3723	Similar to <a href="#lua_gettable"><code>lua_gettable</code></a>, but does a raw access
3724	(i.e., without metamethods).
3725
3726
3727
3728
3729
3730	<hr><h3><a name="lua_rawgeti"><code>lua_rawgeti</code></a></h3><p>
3731	<span class="apii">[-0, +1, <em>-</em>]</span>
3732	<pre>void lua_rawgeti (lua_State *L, int index, int n);</pre>
3733
3734	<p>
3735	Pushes onto the stack the value <code>t[n]</code>,
3736	where <code>t</code> is the value at the given valid index.
3737	The access is raw;
3738	that is, it does not invoke metamethods.
3739
3740
3741
3742
3743
3744	<hr><h3><a name="lua_rawset"><code>lua_rawset</code></a></h3><p>
3745	<span class="apii">[-2, +0, <em>m</em>]</span>
3746	<pre>void lua_rawset (lua_State *L, int index);</pre>
3747
3748	<p>
3749	Similar to <a href="#lua_settable"><code>lua_settable</code></a>, but does a raw assignment
3750	(i.e., without metamethods).
3751
3752
3753
3754
3755
3756	<hr><h3><a name="lua_rawseti"><code>lua_rawseti</code></a></h3><p>
3757	<span class="apii">[-1, +0, <em>m</em>]</span>
3758	<pre>void lua_rawseti (lua_State *L, int index, int n);</pre>
3759
3760	<p>
3761	Does the equivalent of <code>t[n] = v</code>,
3762	where <code>t</code> is the value at the given valid index
3763	and <code>v</code> is the value at the top of the stack.
3764
3765
3766	<p>
3767	This function pops the value from the stack.
3768	The assignment is raw;
3769	that is, it does not invoke metamethods.
3770
3771
3772
3773
3774
3775	<hr><h3><a name="lua_Reader"><code>lua_Reader</code></a></h3>
3776	<pre>typedef const char * (lua_Reader) (lua_State L,
3777	void *data,
3778	size_t *size);</pre>
3779
3780	<p>
3781	The reader function used by <a href="#lua_load"><code>lua_load</code></a>.
3782	Every time it needs another piece of the chunk,
3783	<a href="#lua_load"><code>lua_load</code></a> calls the reader,
3784	passing along its <code>data</code> parameter.
3785	The reader must return a pointer to a block of memory
3786	with a new piece of the chunk
3787	and set <code>size</code> to the block size.
3788	The block must exist until the reader function is called again.
3789	To signal the end of the chunk,
3790	the reader must return <code>NULL</code> or set <code>size</code> to zero.
3791	The reader function may return pieces of any size greater than zero.
3792
3793
3794
3795
3796
3797	<hr><h3><a name="lua_register"><code>lua_register</code></a></h3><p>
3798	<span class="apii">[-0, +0, <em>e</em>]</span>
3799	<pre>void lua_register (lua_State *L,
3800	const char *name,
3801	lua_CFunction f);</pre>
3802
3803	<p>
3804	Sets the C function <code>f</code> as the new value of global <code>name</code>.
3805	It is defined as a macro:
3806
3807	<pre>
3808	#define lua_register(L,n,f) \
3809	(lua_pushcfunction(L, f), lua_setglobal(L, n))
3810	</pre>
3811
3812
3813
3814
3815	<hr><h3><a name="lua_remove"><code>lua_remove</code></a></h3><p>
3816	<span class="apii">[-1, +0, <em>-</em>]</span>
3817	<pre>void lua_remove (lua_State *L, int index);</pre>
3818
3819	<p>
3820	Removes the element at the given valid index,
3821	shifting down the elements above this index to fill the gap.
3822	Cannot be called with a pseudo-index,
3823	because a pseudo-index is not an actual stack position.
3824
3825
3826
3827
3828
3829	<hr><h3><a name="lua_replace"><code>lua_replace</code></a></h3><p>
3830	<span class="apii">[-1, +0, <em>-</em>]</span>
3831	<pre>void lua_replace (lua_State *L, int index);</pre>
3832
3833	<p>
3834	Moves the top element into the given position (and pops it),
3835	without shifting any element
3836	(therefore replacing the value at the given position).
3837
3838
3839
3840
3841
3842	<hr><h3><a name="lua_resume"><code>lua_resume</code></a></h3><p>
3843	<span class="apii">[-?, +?, <em>-</em>]</span>
3844	<pre>int lua_resume (lua_State *L, int narg);</pre>
3845
3846	<p>
3847	Starts and resumes a coroutine in a given thread.
3848
3849
3850	<p>
3851	To start a coroutine, you first create a new thread
3852	(see <a href="#lua_newthread"><code>lua_newthread</code></a>);
3853	then you push onto its stack the main function plus any arguments;
3854	then you call <a href="#lua_resume"><code>lua_resume</code></a>,
3855	with <code>narg</code> being the number of arguments.
3856	This call returns when the coroutine suspends or finishes its execution.
3857	When it returns, the stack contains all values passed to <a href="#lua_yield"><code>lua_yield</code></a>,
3858	or all values returned by the body function.
3859	<a href="#lua_resume"><code>lua_resume</code></a> returns
3860	<a href="#pdf-LUA_YIELD"><code>LUA_YIELD</code></a> if the coroutine yields,
3861	0 if the coroutine finishes its execution
3862	without errors,
3863	or an error code in case of errors (see <a href="#lua_pcall"><code>lua_pcall</code></a>).
3864	In case of errors,
3865	the stack is not unwound,
3866	so you can use the debug API over it.
3867	The error message is on the top of the stack.
3868	To restart a coroutine, you put on its stack only the values to
3869	be passed as results from <code>yield</code>,
3870	and then call <a href="#lua_resume"><code>lua_resume</code></a>.
3871
3872
3873
3874
3875
3876	<hr><h3><a name="lua_setallocf"><code>lua_setallocf</code></a></h3><p>
3877	<span class="apii">[-0, +0, <em>-</em>]</span>
3878	<pre>void lua_setallocf (lua_State L, lua_Alloc f, void ud);</pre>
3879
3880	<p>
3881	Changes the allocator function of a given state to <code>f</code>
3882	with user data <code>ud</code>.
3883
3884
3885
3886
3887
3888	<hr><h3><a name="lua_setfenv"><code>lua_setfenv</code></a></h3><p>
3889	<span class="apii">[-1, +0, <em>-</em>]</span>
3890	<pre>int lua_setfenv (lua_State *L, int index);</pre>
3891
3892	<p>
3893	Pops a table from the stack and sets it as
3894	the new environment for the value at the given index.
3895	If the value at the given index is
3896	neither a function nor a thread nor a userdata,
3897	<a href="#lua_setfenv"><code>lua_setfenv</code></a> returns 0.
3898	Otherwise it returns 1.
3899
3900
3901
3902
3903
3904	<hr><h3><a name="lua_setfield"><code>lua_setfield</code></a></h3><p>
3905	<span class="apii">[-1, +0, <em>e</em>]</span>
3906	<pre>void lua_setfield (lua_State L, int index, const char k);</pre>
3907
3908	<p>
3909	Does the equivalent to <code>t[k] = v</code>,
3910	where <code>t</code> is the value at the given valid index
3911	and <code>v</code> is the value at the top of the stack.
3912
3913
3914	<p>
3915	This function pops the value from the stack.
3916	As in Lua, this function may trigger a metamethod
3917	for the "newindex" event (see <a href="#2.8">§2.8</a>).
3918
3919
3920
3921
3922
3923	<hr><h3><a name="lua_setglobal"><code>lua_setglobal</code></a></h3><p>
3924	<span class="apii">[-1, +0, <em>e</em>]</span>
3925	<pre>void lua_setglobal (lua_State L, const char name);</pre>
3926
3927	<p>
3928	Pops a value from the stack and
3929	sets it as the new value of global <code>name</code>.
3930	It is defined as a macro:
3931
3932	<pre>
3933	#define lua_setglobal(L,s) lua_setfield(L, LUA_GLOBALSINDEX, s)
3934	</pre>
3935
3936
3937
3938
3939	<hr><h3><a name="lua_setmetatable"><code>lua_setmetatable</code></a></h3><p>
3940	<span class="apii">[-1, +0, <em>-</em>]</span>
3941	<pre>int lua_setmetatable (lua_State *L, int index);</pre>
3942
3943	<p>
3944	Pops a table from the stack and
3945	sets it as the new metatable for the value at the given
3946	acceptable index.
3947
3948
3949
3950
3951
3952	<hr><h3><a name="lua_settable"><code>lua_settable</code></a></h3><p>
3953	<span class="apii">[-2, +0, <em>e</em>]</span>
3954	<pre>void lua_settable (lua_State *L, int index);</pre>
3955
3956	<p>
3957	Does the equivalent to <code>t[k] = v</code>,
3958	where <code>t</code> is the value at the given valid index,
3959	<code>v</code> is the value at the top of the stack,
3960	and <code>k</code> is the value just below the top.
3961
3962
3963	<p>
3964	This function pops both the key and the value from the stack.
3965	As in Lua, this function may trigger a metamethod
3966	for the "newindex" event (see <a href="#2.8">§2.8</a>).
3967
3968
3969
3970
3971
3972	<hr><h3><a name="lua_settop"><code>lua_settop</code></a></h3><p>
3973	<span class="apii">[-?, +?, <em>-</em>]</span>
3974	<pre>void lua_settop (lua_State *L, int index);</pre>
3975
3976	<p>
3977	Accepts any acceptable index, or 0,
3978	and sets the stack top to this index.
3979	If the new top is larger than the old one,
3980	then the new elements are filled with <b>nil</b>.
3981	If <code>index</code> is 0, then all stack elements are removed.
3982
3983
3984
3985
3986
3987	<hr><h3><a name="lua_State"><code>lua_State</code></a></h3>
3988	<pre>typedef struct lua_State lua_State;</pre>
3989
3990	<p>
3991	Opaque structure that keeps the whole state of a Lua interpreter.
3992	The Lua library is fully reentrant:
3993	it has no global variables.
3994	All information about a state is kept in this structure.
3995
3996
3997	<p>
3998	A pointer to this state must be passed as the first argument to
3999	every function in the library, except to <a href="#lua_newstate"><code>lua_newstate</code></a>,
4000	which creates a Lua state from scratch.
4001
4002
4003
4004
4005
4006	<hr><h3><a name="lua_status"><code>lua_status</code></a></h3><p>
4007	<span class="apii">[-0, +0, <em>-</em>]</span>
4008	<pre>int lua_status (lua_State *L);</pre>
4009
4010	<p>
4011	Returns the status of the thread <code>L</code>.
4012
4013
4014	<p>
4015	The status can be 0 for a normal thread,
4016	an error code if the thread finished its execution with an error,
4017	or <a name="pdf-LUA_YIELD"><code>LUA_YIELD</code></a> if the thread is suspended.
4018
4019
4020
4021
4022
4023	<hr><h3><a name="lua_toboolean"><code>lua_toboolean</code></a></h3><p>
4024	<span class="apii">[-0, +0, <em>-</em>]</span>
4025	<pre>int lua_toboolean (lua_State *L, int index);</pre>
4026
4027	<p>
4028	Converts the Lua value at the given acceptable index to a C boolean
4029	value (0 or 1).
4030	Like all tests in Lua,
4031	<a href="#lua_toboolean"><code>lua_toboolean</code></a> returns 1 for any Lua value
4032	different from <b>false</b> and <b>nil</b>;
4033	otherwise it returns 0.
4034	It also returns 0 when called with a non-valid index.
4035	(If you want to accept only actual boolean values,
4036	use <a href="#lua_isboolean"><code>lua_isboolean</code></a> to test the value's type.)
4037
4038
4039
4040
4041
4042	<hr><h3><a name="lua_tocfunction"><code>lua_tocfunction</code></a></h3><p>
4043	<span class="apii">[-0, +0, <em>-</em>]</span>
4044	<pre>lua_CFunction lua_tocfunction (lua_State *L, int index);</pre>
4045
4046	<p>
4047	Converts a value at the given acceptable index to a C function.
4048	That value must be a C function;
4049	otherwise, returns <code>NULL</code>.
4050
4051
4052
4053
4054
4055	<hr><h3><a name="lua_tointeger"><code>lua_tointeger</code></a></h3><p>
4056	<span class="apii">[-0, +0, <em>-</em>]</span>
4057	<pre>lua_Integer lua_tointeger (lua_State *L, int index);</pre>
4058
4059	<p>
4060	Converts the Lua value at the given acceptable index
4061	to the signed integral type <a href="#lua_Integer"><code>lua_Integer</code></a>.
4062	The Lua value must be a number or a string convertible to a number
4063	(see <a href="#2.2.1">§2.2.1</a>);
4064	otherwise, <a href="#lua_tointeger"><code>lua_tointeger</code></a> returns 0.
4065
4066
4067	<p>
4068	If the number is not an integer,
4069	it is truncated in some non-specified way.
4070
4071
4072
4073
4074
4075	<hr><h3><a name="lua_tolstring"><code>lua_tolstring</code></a></h3><p>
4076	<span class="apii">[-0, +0, <em>m</em>]</span>
4077	<pre>const char lua_tolstring (lua_State L, int index, size_t *len);</pre>
4078
4079	<p>
4080	Converts the Lua value at the given acceptable index to a C string.
4081	If <code>len</code> is not <code>NULL</code>,
4082	it also sets <code>*len</code> with the string length.
4083	The Lua value must be a string or a number;
4084	otherwise, the function returns <code>NULL</code>.
4085	If the value is a number,
4086	then <a href="#lua_tolstring"><code>lua_tolstring</code></a> also
4087	<em>changes the actual value in the stack to a string</em>.
4088	(This change confuses <a href="#lua_next"><code>lua_next</code></a>
4089	when <a href="#lua_tolstring"><code>lua_tolstring</code></a> is applied to keys during a table traversal.)
4090
4091
4092	<p>
4093	<a href="#lua_tolstring"><code>lua_tolstring</code></a> returns a fully aligned pointer
4094	to a string inside the Lua state.
4095	This string always has a zero ('<code>\0</code>')
4096	after its last character (as in C),
4097	but can contain other zeros in its body.
4098	Because Lua has garbage collection,
4099	there is no guarantee that the pointer returned by <a href="#lua_tolstring"><code>lua_tolstring</code></a>
4100	will be valid after the corresponding value is removed from the stack.
4101
4102
4103
4104
4105
4106	<hr><h3><a name="lua_tonumber"><code>lua_tonumber</code></a></h3><p>
4107	<span class="apii">[-0, +0, <em>-</em>]</span>
4108	<pre>lua_Number lua_tonumber (lua_State *L, int index);</pre>
4109
4110	<p>
4111	Converts the Lua value at the given acceptable index
4112	to the C type <a href="#lua_Number"><code>lua_Number</code></a> (see <a href="#lua_Number"><code>lua_Number</code></a>).
4113	The Lua value must be a number or a string convertible to a number
4114	(see <a href="#2.2.1">§2.2.1</a>);
4115	otherwise, <a href="#lua_tonumber"><code>lua_tonumber</code></a> returns 0.
4116
4117
4118
4119
4120
4121	<hr><h3><a name="lua_topointer"><code>lua_topointer</code></a></h3><p>
4122	<span class="apii">[-0, +0, <em>-</em>]</span>
4123	<pre>const void lua_topointer (lua_State L, int index);</pre>
4124
4125	<p>
4126	Converts the value at the given acceptable index to a generic
4127	C pointer (<code>void*</code>).
4128	The value can be a userdata, a table, a thread, or a function;
4129	otherwise, <a href="#lua_topointer"><code>lua_topointer</code></a> returns <code>NULL</code>.
4130	Different objects will give different pointers.
4131	There is no way to convert the pointer back to its original value.
4132
4133
4134	<p>
4135	Typically this function is used only for debug information.
4136
4137
4138
4139
4140
4141	<hr><h3><a name="lua_tostring"><code>lua_tostring</code></a></h3><p>
4142	<span class="apii">[-0, +0, <em>m</em>]</span>
4143	<pre>const char lua_tostring (lua_State L, int index);</pre>
4144
4145	<p>
4146	Equivalent to <a href="#lua_tolstring"><code>lua_tolstring</code></a> with <code>len</code> equal to <code>NULL</code>.
4147
4148
4149
4150
4151
4152	<hr><h3><a name="lua_tothread"><code>lua_tothread</code></a></h3><p>
4153	<span class="apii">[-0, +0, <em>-</em>]</span>
4154	<pre>lua_State lua_tothread (lua_State L, int index);</pre>
4155
4156	<p>
4157	Converts the value at the given acceptable index to a Lua thread
4158	(represented as <code>lua_State*</code>).
4159	This value must be a thread;
4160	otherwise, the function returns <code>NULL</code>.
4161
4162
4163
4164
4165
4166	<hr><h3><a name="lua_touserdata"><code>lua_touserdata</code></a></h3><p>
4167	<span class="apii">[-0, +0, <em>-</em>]</span>
4168	<pre>void lua_touserdata (lua_State L, int index);</pre>
4169
4170	<p>
4171	If the value at the given acceptable index is a full userdata,
4172	returns its block address.
4173	If the value is a light userdata,
4174	returns its pointer.
4175	Otherwise, returns <code>NULL</code>.
4176
4177
4178
4179
4180
4181	<hr><h3><a name="lua_type"><code>lua_type</code></a></h3><p>
4182	<span class="apii">[-0, +0, <em>-</em>]</span>
4183	<pre>int lua_type (lua_State *L, int index);</pre>
4184
4185	<p>
4186	Returns the type of the value in the given acceptable index,
4187	or <code>LUA_TNONE</code> for a non-valid index
4188	(that is, an index to an "empty" stack position).
4189	The types returned by <a href="#lua_type"><code>lua_type</code></a> are coded by the following constants
4190	defined in <code>lua.h</code>:
4191	<code>LUA_TNIL</code>,
4192	<code>LUA_TNUMBER</code>,
4193	<code>LUA_TBOOLEAN</code>,
4194	<code>LUA_TSTRING</code>,
4195	<code>LUA_TTABLE</code>,
4196	<code>LUA_TFUNCTION</code>,
4197	<code>LUA_TUSERDATA</code>,
4198	<code>LUA_TTHREAD</code>,
4199	and
4200	<code>LUA_TLIGHTUSERDATA</code>.
4201
4202
4203
4204
4205
4206	<hr><h3><a name="lua_typename"><code>lua_typename</code></a></h3><p>
4207	<span class="apii">[-0, +0, <em>-</em>]</span>
4208	<pre>const char lua_typename (lua_State L, int tp);</pre>
4209
4210	<p>
4211	Returns the name of the type encoded by the value <code>tp</code>,
4212	which must be one the values returned by <a href="#lua_type"><code>lua_type</code></a>.
4213
4214
4215
4216
4217
4218	<hr><h3><a name="lua_Writer"><code>lua_Writer</code></a></h3>
4219	<pre>typedef int (lua_Writer) (lua_State L,
4220	const void* p,
4221	size_t sz,
4222	void* ud);</pre>
4223
4224	<p>
4225	The type of the writer function used by <a href="#lua_dump"><code>lua_dump</code></a>.
4226	Every time it produces another piece of chunk,
4227	<a href="#lua_dump"><code>lua_dump</code></a> calls the writer,
4228	passing along the buffer to be written (<code>p</code>),
4229	its size (<code>sz</code>),
4230	and the <code>data</code> parameter supplied to <a href="#lua_dump"><code>lua_dump</code></a>.
4231
4232
4233	<p>
4234	The writer returns an error code:
4235	0 means no errors;
4236	any other value means an error and stops <a href="#lua_dump"><code>lua_dump</code></a> from
4237	calling the writer again.
4238
4239
4240
4241
4242
4243	<hr><h3><a name="lua_xmove"><code>lua_xmove</code></a></h3><p>
4244	<span class="apii">[-?, +?, <em>-</em>]</span>
4245	<pre>void lua_xmove (lua_State from, lua_State to, int n);</pre>
4246
4247	<p>
4248	Exchange values between different threads of the <em>same</em> global state.
4249
4250
4251	<p>
4252	This function pops <code>n</code> values from the stack <code>from</code>,
4253	and pushes them onto the stack <code>to</code>.
4254
4255
4256
4257
4258
4259	<hr><h3><a name="lua_yield"><code>lua_yield</code></a></h3><p>
4260	<span class="apii">[-?, +?, <em>-</em>]</span>
4261	<pre>int lua_yield (lua_State *L, int nresults);</pre>
4262
4263	<p>
4264	Yields a coroutine.
4265
4266
4267	<p>
4268	This function should only be called as the
4269	return expression of a C function, as follows:
4270
4271	<pre>
4272	return lua_yield (L, nresults);
4273	</pre><p>
4274	When a C function calls <a href="#lua_yield"><code>lua_yield</code></a> in that way,
4275	the running coroutine suspends its execution,
4276	and the call to <a href="#lua_resume"><code>lua_resume</code></a> that started this coroutine returns.
4277	The parameter <code>nresults</code> is the number of values from the stack
4278	that are passed as results to <a href="#lua_resume"><code>lua_resume</code></a>.
4279
4280
4281
4282
4283
4284
4285
4286	<h2>3.8 - <a name="3.8">The Debug Interface</a></h2>
4287
4288	<p>
4289	Lua has no built-in debugging facilities.
4290	Instead, it offers a special interface
4291	by means of functions and <em>hooks</em>.
4292	This interface allows the construction of different
4293	kinds of debuggers, profilers, and other tools
4294	that need "inside information" from the interpreter.
4295
4296
4297
4298	<hr><h3><a name="lua_Debug"><code>lua_Debug</code></a></h3>
4299	<pre>typedef struct lua_Debug {
4300	int event;
4301	const char name; / (n) */
4302	const char namewhat; / (n) */
4303	const char what; / (S) */
4304	const char source; / (S) */
4305	int currentline; /* (l) */
4306	int nups; /* (u) number of upvalues */
4307	int linedefined; /* (S) */
4308	int lastlinedefined; /* (S) */
4309	char short_src[LUA_IDSIZE]; /* (S) */
4310	/* private part */
4311	<em>other fields</em>
4312	} lua_Debug;</pre>
4313
4314	<p>
4315	A structure used to carry different pieces of
4316	information about an active function.
4317	<a href="#lua_getstack"><code>lua_getstack</code></a> fills only the private part
4318	of this structure, for later use.
4319	To fill the other fields of <a href="#lua_Debug"><code>lua_Debug</code></a> with useful information,
4320	call <a href="#lua_getinfo"><code>lua_getinfo</code></a>.
4321
4322
4323	<p>
4324	The fields of <a href="#lua_Debug"><code>lua_Debug</code></a> have the following meaning:
4325
4326	<ul>
4327
4328	<li><b><code>source</code>:</b>
4329	If the function was defined in a string,
4330	then <code>source</code> is that string.
4331	If the function was defined in a file,
4332	then <code>source</code> starts with a '<code>@</code>' followed by the file name.
4333	</li>
4334
4335	<li><b><code>short_src</code>:</b>
4336	a "printable" version of <code>source</code>, to be used in error messages.
4337	</li>
4338
4339	<li><b><code>linedefined</code>:</b>
4340	the line number where the definition of the function starts.
4341	</li>
4342
4343	<li><b><code>lastlinedefined</code>:</b>
4344	the line number where the definition of the function ends.
4345	</li>
4346
4347	<li><b><code>what</code>:</b>
4348	the string <code>"Lua"</code> if the function is a Lua function,
4349	<code>"C"</code> if it is a C function,
4350	<code>"main"</code> if it is the main part of a chunk,
4351	and <code>"tail"</code> if it was a function that did a tail call.
4352	In the latter case,
4353	Lua has no other information about the function.
4354	</li>
4355
4356	<li><b><code>currentline</code>:</b>
4357	the current line where the given function is executing.
4358	When no line information is available,
4359	<code>currentline</code> is set to -1.
4360	</li>
4361
4362	<li><b><code>name</code>:</b>
4363	a reasonable name for the given function.
4364	Because functions in Lua are first-class values,
4365	they do not have a fixed name:
4366	some functions can be the value of multiple global variables,
4367	while others can be stored only in a table field.
4368	The <code>lua_getinfo</code> function checks how the function was
4369	called to find a suitable name.
4370	If it cannot find a name,
4371	then <code>name</code> is set to <code>NULL</code>.
4372	</li>
4373
4374	<li><b><code>namewhat</code>:</b>
4375	explains the <code>name</code> field.
4376	The value of <code>namewhat</code> can be
4377	<code>"global"</code>, <code>"local"</code>, <code>"method"</code>,
4378	<code>"field"</code>, <code>"upvalue"</code>, or <code>""</code> (the empty string),
4379	according to how the function was called.
4380	(Lua uses the empty string when no other option seems to apply.)
4381	</li>
4382
4383	<li><b><code>nups</code>:</b>
4384	the number of upvalues of the function.
4385	</li>
4386
4387	</ul>
4388
4389
4390
4391
4392	<hr><h3><a name="lua_gethook"><code>lua_gethook</code></a></h3><p>
4393	<span class="apii">[-0, +0, <em>-</em>]</span>
4394	<pre>lua_Hook lua_gethook (lua_State *L);</pre>
4395
4396	<p>
4397	Returns the current hook function.
4398
4399
4400
4401
4402
4403	<hr><h3><a name="lua_gethookcount"><code>lua_gethookcount</code></a></h3><p>
4404	<span class="apii">[-0, +0, <em>-</em>]</span>
4405	<pre>int lua_gethookcount (lua_State *L);</pre>
4406
4407	<p>
4408	Returns the current hook count.
4409
4410
4411
4412
4413
4414	<hr><h3><a name="lua_gethookmask"><code>lua_gethookmask</code></a></h3><p>
4415	<span class="apii">[-0, +0, <em>-</em>]</span>
4416	<pre>int lua_gethookmask (lua_State *L);</pre>
4417
4418	<p>
4419	Returns the current hook mask.
4420
4421
4422
4423
4424
4425	<hr><h3><a name="lua_getinfo"><code>lua_getinfo</code></a></h3><p>
4426	<span class="apii">[-(0\|1), +(0\|1\|2), <em>m</em>]</span>
4427	<pre>int lua_getinfo (lua_State L, const char what, lua_Debug *ar);</pre>
4428
4429	<p>
4430	Returns information about a specific function or function invocation.
4431
4432
4433	<p>
4434	To get information about a function invocation,
4435	the parameter <code>ar</code> must be a valid activation record that was
4436	filled by a previous call to <a href="#lua_getstack"><code>lua_getstack</code></a> or
4437	given as argument to a hook (see <a href="#lua_Hook"><code>lua_Hook</code></a>).
4438
4439
4440	<p>
4441	To get information about a function you push it onto the stack
4442	and start the <code>what</code> string with the character '<code>></code>'.
4443	(In that case,
4444	<code>lua_getinfo</code> pops the function in the top of the stack.)
4445	For instance, to know in which line a function <code>f</code> was defined,
4446	you can write the following code:
4447
4448	<pre>
4449	lua_Debug ar;
4450	lua_getfield(L, LUA_GLOBALSINDEX, "f"); /* get global 'f' */
4451	lua_getinfo(L, ">S", &ar);
4452	printf("%d\n", ar.linedefined);
4453	</pre>
4454
4455	<p>
4456	Each character in the string <code>what</code>
4457	selects some fields of the structure <code>ar</code> to be filled or
4458	a value to be pushed on the stack:
4459
4460	<ul>
4461
4462	<li><b>'<code>n</code>':</b> fills in the field <code>name</code> and <code>namewhat</code>;
4463	</li>
4464
4465	<li><b>'<code>S</code>':</b>
4466	fills in the fields <code>source</code>, <code>short_src</code>,
4467	<code>linedefined</code>, <code>lastlinedefined</code>, and <code>what</code>;
4468	</li>
4469
4470	<li><b>'<code>l</code>':</b> fills in the field <code>currentline</code>;
4471	</li>
4472
4473	<li><b>'<code>u</code>':</b> fills in the field <code>nups</code>;
4474	</li>
4475
4476	<li><b>'<code>f</code>':</b>
4477	pushes onto the stack the function that is
4478	running at the given level;
4479	</li>
4480
4481	<li><b>'<code>L</code>':</b>
4482	pushes onto the stack a table whose indices are the
4483	numbers of the lines that are valid on the function.
4484	(A <em>valid line</em> is a line with some associated code,
4485	that is, a line where you can put a break point.
4486	Non-valid lines include empty lines and comments.)
4487	</li>
4488
4489	</ul>
4490
4491	<p>
4492	This function returns 0 on error
4493	(for instance, an invalid option in <code>what</code>).
4494
4495
4496
4497
4498
4499	<hr><h3><a name="lua_getlocal"><code>lua_getlocal</code></a></h3><p>
4500	<span class="apii">[-0, +(0\|1), <em>-</em>]</span>
4501	<pre>const char lua_getlocal (lua_State L, lua_Debug *ar, int n);</pre>
4502
4503	<p>
4504	Gets information about a local variable of a given activation record.
4505	The parameter <code>ar</code> must be a valid activation record that was
4506	filled by a previous call to <a href="#lua_getstack"><code>lua_getstack</code></a> or
4507	given as argument to a hook (see <a href="#lua_Hook"><code>lua_Hook</code></a>).
4508	The index <code>n</code> selects which local variable to inspect
4509	(1 is the first parameter or active local variable, and so on,
4510	until the last active local variable).
4511	<a href="#lua_getlocal"><code>lua_getlocal</code></a> pushes the variable's value onto the stack
4512	and returns its name.
4513
4514
4515	<p>
4516	Variable names starting with '<code>(</code>' (open parentheses)
4517	represent internal variables
4518	(loop control variables, temporaries, and C function locals).
4519
4520
4521	<p>
4522	Returns <code>NULL</code> (and pushes nothing)
4523	when the index is greater than
4524	the number of active local variables.
4525
4526
4527
4528
4529
4530	<hr><h3><a name="lua_getstack"><code>lua_getstack</code></a></h3><p>
4531	<span class="apii">[-0, +0, <em>-</em>]</span>
4532	<pre>int lua_getstack (lua_State L, int level, lua_Debug ar);</pre>
4533
4534	<p>
4535	Get information about the interpreter runtime stack.
4536
4537
4538	<p>
4539	This function fills parts of a <a href="#lua_Debug"><code>lua_Debug</code></a> structure with
4540	an identification of the <em>activation record</em>
4541	of the function executing at a given level.
4542	Level 0 is the current running function,
4543	whereas level <em>n+1</em> is the function that has called level <em>n</em>.
4544	When there are no errors, <a href="#lua_getstack"><code>lua_getstack</code></a> returns 1;
4545	when called with a level greater than the stack depth,
4546	it returns 0.
4547
4548
4549
4550
4551
4552	<hr><h3><a name="lua_getupvalue"><code>lua_getupvalue</code></a></h3><p>
4553	<span class="apii">[-0, +(0\|1), <em>-</em>]</span>
4554	<pre>const char lua_getupvalue (lua_State L, int funcindex, int n);</pre>
4555
4556	<p>
4557	Gets information about a closure's upvalue.
4558	(For Lua functions,
4559	upvalues are the external local variables that the function uses,
4560	and that are consequently included in its closure.)
4561	<a href="#lua_getupvalue"><code>lua_getupvalue</code></a> gets the index <code>n</code> of an upvalue,
4562	pushes the upvalue's value onto the stack,
4563	and returns its name.
4564	<code>funcindex</code> points to the closure in the stack.
4565	(Upvalues have no particular order,
4566	as they are active through the whole function.
4567	So, they are numbered in an arbitrary order.)
4568
4569
4570	<p>
4571	Returns <code>NULL</code> (and pushes nothing)
4572	when the index is greater than the number of upvalues.
4573	For C functions, this function uses the empty string <code>""</code>
4574	as a name for all upvalues.
4575
4576
4577
4578
4579
4580	<hr><h3><a name="lua_Hook"><code>lua_Hook</code></a></h3>
4581	<pre>typedef void (lua_Hook) (lua_State L, lua_Debug *ar);</pre>
4582
4583	<p>
4584	Type for debugging hook functions.
4585
4586
4587	<p>
4588	Whenever a hook is called, its <code>ar</code> argument has its field
4589	<code>event</code> set to the specific event that triggered the hook.
4590	Lua identifies these events with the following constants:
4591	<a name="pdf-LUA_HOOKCALL"><code>LUA_HOOKCALL</code></a>, <a name="pdf-LUA_HOOKRET"><code>LUA_HOOKRET</code></a>,
4592	<a name="pdf-LUA_HOOKTAILRET"><code>LUA_HOOKTAILRET</code></a>, <a name="pdf-LUA_HOOKLINE"><code>LUA_HOOKLINE</code></a>,
4593	and <a name="pdf-LUA_HOOKCOUNT"><code>LUA_HOOKCOUNT</code></a>.
4594	Moreover, for line events, the field <code>currentline</code> is also set.
4595	To get the value of any other field in <code>ar</code>,
4596	the hook must call <a href="#lua_getinfo"><code>lua_getinfo</code></a>.
4597	For return events, <code>event</code> can be <code>LUA_HOOKRET</code>,
4598	the normal value, or <code>LUA_HOOKTAILRET</code>.
4599	In the latter case, Lua is simulating a return from
4600	a function that did a tail call;
4601	in this case, it is useless to call <a href="#lua_getinfo"><code>lua_getinfo</code></a>.
4602
4603
4604	<p>
4605	While Lua is running a hook, it disables other calls to hooks.
4606	Therefore, if a hook calls back Lua to execute a function or a chunk,
4607	this execution occurs without any calls to hooks.
4608
4609
4610
4611
4612
4613	<hr><h3><a name="lua_sethook"><code>lua_sethook</code></a></h3><p>
4614	<span class="apii">[-0, +0, <em>-</em>]</span>
4615	<pre>int lua_sethook (lua_State *L, lua_Hook f, int mask, int count);</pre>
4616
4617	<p>
4618	Sets the debugging hook function.
4619
4620
4621	<p>
4622	Argument <code>f</code> is the hook function.
4623	<code>mask</code> specifies on which events the hook will be called:
4624	it is formed by a bitwise or of the constants
4625	<a name="pdf-LUA_MASKCALL"><code>LUA_MASKCALL</code></a>,
4626	<a name="pdf-LUA_MASKRET"><code>LUA_MASKRET</code></a>,
4627	<a name="pdf-LUA_MASKLINE"><code>LUA_MASKLINE</code></a>,
4628	and <a name="pdf-LUA_MASKCOUNT"><code>LUA_MASKCOUNT</code></a>.
4629	The <code>count</code> argument is only meaningful when the mask
4630	includes <code>LUA_MASKCOUNT</code>.
4631	For each event, the hook is called as explained below:
4632
4633	<ul>
4634
4635	<li><b>The call hook:</b> is called when the interpreter calls a function.
4636	The hook is called just after Lua enters the new function,
4637	before the function gets its arguments.
4638	</li>
4639
4640	<li><b>The return hook:</b> is called when the interpreter returns from a function.
4641	The hook is called just before Lua leaves the function.
4642	You have no access to the values to be returned by the function.
4643	</li>
4644
4645	<li><b>The line hook:</b> is called when the interpreter is about to
4646	start the execution of a new line of code,
4647	or when it jumps back in the code (even to the same line).
4648	(This event only happens while Lua is executing a Lua function.)
4649	</li>
4650
4651	<li><b>The count hook:</b> is called after the interpreter executes every
4652	<code>count</code> instructions.
4653	(This event only happens while Lua is executing a Lua function.)
4654	</li>
4655
4656	</ul>
4657
4658	<p>
4659	A hook is disabled by setting <code>mask</code> to zero.
4660
4661
4662
4663
4664
4665	<hr><h3><a name="lua_setlocal"><code>lua_setlocal</code></a></h3><p>
4666	<span class="apii">[-(0\|1), +0, <em>-</em>]</span>
4667	<pre>const char lua_setlocal (lua_State L, lua_Debug *ar, int n);</pre>
4668
4669	<p>
4670	Sets the value of a local variable of a given activation record.
4671	Parameters <code>ar</code> and <code>n</code> are as in <a href="#lua_getlocal"><code>lua_getlocal</code></a>
4672	(see <a href="#lua_getlocal"><code>lua_getlocal</code></a>).
4673	<a href="#lua_setlocal"><code>lua_setlocal</code></a> assigns the value at the top of the stack
4674	to the variable and returns its name.
4675	It also pops the value from the stack.
4676
4677
4678	<p>
4679	Returns <code>NULL</code> (and pops nothing)
4680	when the index is greater than
4681	the number of active local variables.
4682
4683
4684
4685
4686
4687	<hr><h3><a name="lua_setupvalue"><code>lua_setupvalue</code></a></h3><p>
4688	<span class="apii">[-(0\|1), +0, <em>-</em>]</span>
4689	<pre>const char lua_setupvalue (lua_State L, int funcindex, int n);</pre>
4690
4691	<p>
4692	Sets the value of a closure's upvalue.
4693	It assigns the value at the top of the stack
4694	to the upvalue and returns its name.
4695	It also pops the value from the stack.
4696	Parameters <code>funcindex</code> and <code>n</code> are as in the <a href="#lua_getupvalue"><code>lua_getupvalue</code></a>
4697	(see <a href="#lua_getupvalue"><code>lua_getupvalue</code></a>).
4698
4699
4700	<p>
4701	Returns <code>NULL</code> (and pops nothing)
4702	when the index is greater than the number of upvalues.
4703
4704
4705
4706
4707
4708
4709
4710	<h1>4 - <a name="4">The Auxiliary Library</a></h1>
4711
4712	<p>
4713
4714	The <em>auxiliary library</em> provides several convenient functions
4715	to interface C with Lua.
4716	While the basic API provides the primitive functions for all
4717	interactions between C and Lua,
4718	the auxiliary library provides higher-level functions for some
4719	common tasks.
4720
4721
4722	<p>
4723	All functions from the auxiliary library
4724	are defined in header file <code>lauxlib.h</code> and
4725	have a prefix <code>luaL_</code>.
4726
4727
4728	<p>
4729	All functions in the auxiliary library are built on
4730	top of the basic API,
4731	and so they provide nothing that cannot be done with this API.
4732
4733
4734	<p>
4735	Several functions in the auxiliary library are used to
4736	check C function arguments.
4737	Their names are always <code>luaL_check</code> or <code>luaL_opt</code>.
4738	All of these functions throw an error if the check is not satisfied.
4739	Because the error message is formatted for arguments
4740	(e.g., "<code>bad argument #1</code>"),
4741	you should not use these functions for other stack values.
4742
4743
4744
4745	<h2>4.1 - <a name="4.1">Functions and Types</a></h2>
4746
4747	<p>
4748	Here we list all functions and types from the auxiliary library
4749	in alphabetical order.
4750
4751
4752
4753	<hr><h3><a name="luaL_addchar"><code>luaL_addchar</code></a></h3><p>
4754	<span class="apii">[-0, +0, <em>m</em>]</span>
4755	<pre>void luaL_addchar (luaL_Buffer *B, char c);</pre>
4756
4757	<p>
4758	Adds the character <code>c</code> to the buffer <code>B</code>
4759	(see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>).
4760
4761
4762
4763
4764
4765	<hr><h3><a name="luaL_addlstring"><code>luaL_addlstring</code></a></h3><p>
4766	<span class="apii">[-0, +0, <em>m</em>]</span>
4767	<pre>void luaL_addlstring (luaL_Buffer B, const char s, size_t l);</pre>
4768
4769	<p>
4770	Adds the string pointed to by <code>s</code> with length <code>l</code> to
4771	the buffer <code>B</code>
4772	(see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>).
4773	The string may contain embedded zeros.
4774
4775
4776
4777
4778
4779	<hr><h3><a name="luaL_addsize"><code>luaL_addsize</code></a></h3><p>
4780	<span class="apii">[-0, +0, <em>m</em>]</span>
4781	<pre>void luaL_addsize (luaL_Buffer *B, size_t n);</pre>
4782
4783	<p>
4784	Adds to the buffer <code>B</code> (see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>)
4785	a string of length <code>n</code> previously copied to the
4786	buffer area (see <a href="#luaL_prepbuffer"><code>luaL_prepbuffer</code></a>).
4787
4788
4789
4790
4791
4792	<hr><h3><a name="luaL_addstring"><code>luaL_addstring</code></a></h3><p>
4793	<span class="apii">[-0, +0, <em>m</em>]</span>
4794	<pre>void luaL_addstring (luaL_Buffer B, const char s);</pre>
4795
4796	<p>
4797	Adds the zero-terminated string pointed to by <code>s</code>
4798	to the buffer <code>B</code>
4799	(see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>).
4800	The string may not contain embedded zeros.
4801
4802
4803
4804
4805
4806	<hr><h3><a name="luaL_addvalue"><code>luaL_addvalue</code></a></h3><p>
4807	<span class="apii">[-1, +0, <em>m</em>]</span>
4808	<pre>void luaL_addvalue (luaL_Buffer *B);</pre>
4809
4810	<p>
4811	Adds the value at the top of the stack
4812	to the buffer <code>B</code>
4813	(see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>).
4814	Pops the value.
4815
4816
4817	<p>
4818	This is the only function on string buffers that can (and must)
4819	be called with an extra element on the stack,
4820	which is the value to be added to the buffer.
4821
4822
4823
4824
4825
4826	<hr><h3><a name="luaL_argcheck"><code>luaL_argcheck</code></a></h3><p>
4827	<span class="apii">[-0, +0, <em>v</em>]</span>
4828	<pre>void luaL_argcheck (lua_State *L,
4829	int cond,
4830	int narg,
4831	const char *extramsg);</pre>
4832
4833	<p>
4834	Checks whether <code>cond</code> is true.
4835	If not, raises an error with the following message,
4836	where <code>func</code> is retrieved from the call stack:
4837
4838	<pre>
4839	bad argument #<narg> to <func> (<extramsg>)
4840	</pre>
4841
4842
4843
4844
4845	<hr><h3><a name="luaL_argerror"><code>luaL_argerror</code></a></h3><p>
4846	<span class="apii">[-0, +0, <em>v</em>]</span>
4847	<pre>int luaL_argerror (lua_State L, int narg, const char extramsg);</pre>
4848
4849	<p>
4850	Raises an error with the following message,
4851	where <code>func</code> is retrieved from the call stack:
4852
4853	<pre>
4854	bad argument #<narg> to <func> (<extramsg>)
4855	</pre>
4856
4857	<p>
4858	This function never returns,
4859	but it is an idiom to use it in C functions
4860	as <code>return luaL_argerror(<em>args</em>)</code>.
4861
4862
4863
4864
4865
4866	<hr><h3><a name="luaL_Buffer"><code>luaL_Buffer</code></a></h3>
4867	<pre>typedef struct luaL_Buffer luaL_Buffer;</pre>
4868
4869	<p>
4870	Type for a <em>string buffer</em>.
4871
4872
4873	<p>
4874	A string buffer allows C code to build Lua strings piecemeal.
4875	Its pattern of use is as follows:
4876
4877	<ul>
4878
4879	<li>First you declare a variable <code>b</code> of type <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>.</li>
4880
4881	<li>Then you initialize it with a call <code>luaL_buffinit(L, &b)</code>.</li>
4882
4883	<li>
4884	Then you add string pieces to the buffer calling any of
4885	the <code>luaL_add*</code> functions.
4886	</li>
4887
4888	<li>
4889	You finish by calling <code>luaL_pushresult(&b)</code>.
4890	This call leaves the final string on the top of the stack.
4891	</li>
4892
4893	</ul>
4894
4895	<p>
4896	During its normal operation,
4897	a string buffer uses a variable number of stack slots.
4898	So, while using a buffer, you cannot assume that you know where
4899	the top of the stack is.
4900	You can use the stack between successive calls to buffer operations
4901	as long as that use is balanced;
4902	that is,
4903	when you call a buffer operation,
4904	the stack is at the same level
4905	it was immediately after the previous buffer operation.
4906	(The only exception to this rule is <a href="#luaL_addvalue"><code>luaL_addvalue</code></a>.)
4907	After calling <a href="#luaL_pushresult"><code>luaL_pushresult</code></a> the stack is back to its
4908	level when the buffer was initialized,
4909	plus the final string on its top.
4910
4911
4912
4913
4914
4915	<hr><h3><a name="luaL_buffinit"><code>luaL_buffinit</code></a></h3><p>
4916	<span class="apii">[-0, +0, <em>-</em>]</span>
4917	<pre>void luaL_buffinit (lua_State L, luaL_Buffer B);</pre>
4918
4919	<p>
4920	Initializes a buffer <code>B</code>.
4921	This function does not allocate any space;
4922	the buffer must be declared as a variable
4923	(see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>).
4924
4925
4926
4927
4928
4929	<hr><h3><a name="luaL_callmeta"><code>luaL_callmeta</code></a></h3><p>
4930	<span class="apii">[-0, +(0\|1), <em>e</em>]</span>
4931	<pre>int luaL_callmeta (lua_State L, int obj, const char e);</pre>
4932
4933	<p>
4934	Calls a metamethod.
4935
4936
4937	<p>
4938	If the object at index <code>obj</code> has a metatable and this
4939	metatable has a field <code>e</code>,
4940	this function calls this field and passes the object as its only argument.
4941	In this case this function returns 1 and pushes onto the
4942	stack the value returned by the call.
4943	If there is no metatable or no metamethod,
4944	this function returns 0 (without pushing any value on the stack).
4945
4946
4947
4948
4949
4950	<hr><h3><a name="luaL_checkany"><code>luaL_checkany</code></a></h3><p>
4951	<span class="apii">[-0, +0, <em>v</em>]</span>
4952	<pre>void luaL_checkany (lua_State *L, int narg);</pre>
4953
4954	<p>
4955	Checks whether the function has an argument
4956	of any type (including <b>nil</b>) at position <code>narg</code>.
4957
4958
4959
4960
4961
4962	<hr><h3><a name="luaL_checkint"><code>luaL_checkint</code></a></h3><p>
4963	<span class="apii">[-0, +0, <em>v</em>]</span>
4964	<pre>int luaL_checkint (lua_State *L, int narg);</pre>
4965
4966	<p>
4967	Checks whether the function argument <code>narg</code> is a number
4968	and returns this number cast to an <code>int</code>.
4969
4970
4971
4972
4973
4974	<hr><h3><a name="luaL_checkinteger"><code>luaL_checkinteger</code></a></h3><p>
4975	<span class="apii">[-0, +0, <em>v</em>]</span>
4976	<pre>lua_Integer luaL_checkinteger (lua_State *L, int narg);</pre>
4977
4978	<p>
4979	Checks whether the function argument <code>narg</code> is a number
4980	and returns this number cast to a <a href="#lua_Integer"><code>lua_Integer</code></a>.
4981
4982
4983
4984
4985
4986	<hr><h3><a name="luaL_checklong"><code>luaL_checklong</code></a></h3><p>
4987	<span class="apii">[-0, +0, <em>v</em>]</span>
4988	<pre>long luaL_checklong (lua_State *L, int narg);</pre>
4989
4990	<p>
4991	Checks whether the function argument <code>narg</code> is a number
4992	and returns this number cast to a <code>long</code>.
4993
4994
4995
4996
4997
4998	<hr><h3><a name="luaL_checklstring"><code>luaL_checklstring</code></a></h3><p>
4999	<span class="apii">[-0, +0, <em>v</em>]</span>
5000	<pre>const char luaL_checklstring (lua_State L, int narg, size_t *l);</pre>
5001
5002	<p>
5003	Checks whether the function argument <code>narg</code> is a string
5004	and returns this string;
5005	if <code>l</code> is not <code>NULL</code> fills <code>*l</code>
5006	with the string's length.
5007
5008
5009	<p>
5010	This function uses <a href="#lua_tolstring"><code>lua_tolstring</code></a> to get its result,
5011	so all conversions and caveats of that function apply here.
5012
5013
5014
5015
5016
5017	<hr><h3><a name="luaL_checknumber"><code>luaL_checknumber</code></a></h3><p>
5018	<span class="apii">[-0, +0, <em>v</em>]</span>
5019	<pre>lua_Number luaL_checknumber (lua_State *L, int narg);</pre>
5020
5021	<p>
5022	Checks whether the function argument <code>narg</code> is a number
5023	and returns this number.
5024
5025
5026
5027
5028
5029	<hr><h3><a name="luaL_checkoption"><code>luaL_checkoption</code></a></h3><p>
5030	<span class="apii">[-0, +0, <em>v</em>]</span>
5031	<pre>int luaL_checkoption (lua_State *L,
5032	int narg,
5033	const char *def,
5034	const char *const lst[]);</pre>
5035
5036	<p>
5037	Checks whether the function argument <code>narg</code> is a string and
5038	searches for this string in the array <code>lst</code>
5039	(which must be NULL-terminated).
5040	Returns the index in the array where the string was found.
5041	Raises an error if the argument is not a string or
5042	if the string cannot be found.
5043
5044
5045	<p>
5046	If <code>def</code> is not <code>NULL</code>,
5047	the function uses <code>def</code> as a default value when
5048	there is no argument <code>narg</code> or if this argument is <b>nil</b>.
5049
5050
5051	<p>
5052	This is a useful function for mapping strings to C enums.
5053	(The usual convention in Lua libraries is
5054	to use strings instead of numbers to select options.)
5055
5056
5057
5058
5059
5060	<hr><h3><a name="luaL_checkstack"><code>luaL_checkstack</code></a></h3><p>
5061	<span class="apii">[-0, +0, <em>v</em>]</span>
5062	<pre>void luaL_checkstack (lua_State L, int sz, const char msg);</pre>
5063
5064	<p>
5065	Grows the stack size to <code>top + sz</code> elements,
5066	raising an error if the stack cannot grow to that size.
5067	<code>msg</code> is an additional text to go into the error message.
5068
5069
5070
5071
5072
5073	<hr><h3><a name="luaL_checkstring"><code>luaL_checkstring</code></a></h3><p>
5074	<span class="apii">[-0, +0, <em>v</em>]</span>
5075	<pre>const char luaL_checkstring (lua_State L, int narg);</pre>
5076
5077	<p>
5078	Checks whether the function argument <code>narg</code> is a string
5079	and returns this string.
5080
5081
5082	<p>
5083	This function uses <a href="#lua_tolstring"><code>lua_tolstring</code></a> to get its result,
5084	so all conversions and caveats of that function apply here.
5085
5086
5087
5088
5089
5090	<hr><h3><a name="luaL_checktype"><code>luaL_checktype</code></a></h3><p>
5091	<span class="apii">[-0, +0, <em>v</em>]</span>
5092	<pre>void luaL_checktype (lua_State *L, int narg, int t);</pre>
5093
5094	<p>
5095	Checks whether the function argument <code>narg</code> has type <code>t</code>.
5096	See <a href="#lua_type"><code>lua_type</code></a> for the encoding of types for <code>t</code>.
5097
5098
5099
5100
5101
5102	<hr><h3><a name="luaL_checkudata"><code>luaL_checkudata</code></a></h3><p>
5103	<span class="apii">[-0, +0, <em>v</em>]</span>
5104	<pre>void luaL_checkudata (lua_State L, int narg, const char *tname);</pre>
5105
5106	<p>
5107	Checks whether the function argument <code>narg</code> is a userdata
5108	of the type <code>tname</code> (see <a href="#luaL_newmetatable"><code>luaL_newmetatable</code></a>).
5109
5110
5111
5112
5113
5114	<hr><h3><a name="luaL_dofile"><code>luaL_dofile</code></a></h3><p>
5115	<span class="apii">[-0, +?, <em>m</em>]</span>
5116	<pre>int luaL_dofile (lua_State L, const char filename);</pre>
5117
5118	<p>
5119	Loads and runs the given file.
5120	It is defined as the following macro:
5121
5122	<pre>
5123	(luaL_loadfile(L, filename) \|\| lua_pcall(L, 0, LUA_MULTRET, 0))
5124	</pre><p>
5125	It returns 0 if there are no errors
5126	or 1 in case of errors.
5127
5128
5129
5130
5131
5132	<hr><h3><a name="luaL_dostring"><code>luaL_dostring</code></a></h3><p>
5133	<span class="apii">[-0, +?, <em>m</em>]</span>
5134	<pre>int luaL_dostring (lua_State L, const char str);</pre>
5135
5136	<p>
5137	Loads and runs the given string.
5138	It is defined as the following macro:
5139
5140	<pre>
5141	(luaL_loadstring(L, str) \|\| lua_pcall(L, 0, LUA_MULTRET, 0))
5142	</pre><p>
5143	It returns 0 if there are no errors
5144	or 1 in case of errors.
5145
5146
5147
5148
5149
5150	<hr><h3><a name="luaL_error"><code>luaL_error</code></a></h3><p>
5151	<span class="apii">[-0, +0, <em>v</em>]</span>
5152	<pre>int luaL_error (lua_State L, const char fmt, ...);</pre>
5153
5154	<p>
5155	Raises an error.
5156	The error message format is given by <code>fmt</code>
5157	plus any extra arguments,
5158	following the same rules of <a href="#lua_pushfstring"><code>lua_pushfstring</code></a>.
5159	It also adds at the beginning of the message the file name and
5160	the line number where the error occurred,
5161	if this information is available.
5162
5163
5164	<p>
5165	This function never returns,
5166	but it is an idiom to use it in C functions
5167	as <code>return luaL_error(<em>args</em>)</code>.
5168
5169
5170
5171
5172
5173	<hr><h3><a name="luaL_getmetafield"><code>luaL_getmetafield</code></a></h3><p>
5174	<span class="apii">[-0, +(0\|1), <em>m</em>]</span>
5175	<pre>int luaL_getmetafield (lua_State L, int obj, const char e);</pre>
5176
5177	<p>
5178	Pushes onto the stack the field <code>e</code> from the metatable
5179	of the object at index <code>obj</code>.
5180	If the object does not have a metatable,
5181	or if the metatable does not have this field,
5182	returns 0 and pushes nothing.
5183
5184
5185
5186
5187
5188	<hr><h3><a name="luaL_getmetatable"><code>luaL_getmetatable</code></a></h3><p>
5189	<span class="apii">[-0, +1, <em>-</em>]</span>
5190	<pre>void luaL_getmetatable (lua_State L, const char tname);</pre>
5191
5192	<p>
5193	Pushes onto the stack the metatable associated with name <code>tname</code>
5194	in the registry (see <a href="#luaL_newmetatable"><code>luaL_newmetatable</code></a>).
5195
5196
5197
5198
5199
5200	<hr><h3><a name="luaL_gsub"><code>luaL_gsub</code></a></h3><p>
5201	<span class="apii">[-0, +1, <em>m</em>]</span>
5202	<pre>const char luaL_gsub (lua_State L,
5203	const char *s,
5204	const char *p,
5205	const char *r);</pre>
5206
5207	<p>
5208	Creates a copy of string <code>s</code> by replacing
5209	any occurrence of the string <code>p</code>
5210	with the string <code>r</code>.
5211	Pushes the resulting string on the stack and returns it.
5212
5213
5214
5215
5216
5217	<hr><h3><a name="luaL_loadbuffer"><code>luaL_loadbuffer</code></a></h3><p>
5218	<span class="apii">[-0, +1, <em>m</em>]</span>
5219	<pre>int luaL_loadbuffer (lua_State *L,
5220	const char *buff,
5221	size_t sz,
5222	const char *name);</pre>
5223
5224	<p>
5225	Loads a buffer as a Lua chunk.
5226	This function uses <a href="#lua_load"><code>lua_load</code></a> to load the chunk in the
5227	buffer pointed to by <code>buff</code> with size <code>sz</code>.
5228
5229
5230	<p>
5231	This function returns the same results as <a href="#lua_load"><code>lua_load</code></a>.
5232	<code>name</code> is the chunk name,
5233	used for debug information and error messages.
5234
5235
5236
5237
5238
5239	<hr><h3><a name="luaL_loadfile"><code>luaL_loadfile</code></a></h3><p>
5240	<span class="apii">[-0, +1, <em>m</em>]</span>
5241	<pre>int luaL_loadfile (lua_State L, const char filename);</pre>
5242
5243	<p>
5244	Loads a file as a Lua chunk.
5245	This function uses <a href="#lua_load"><code>lua_load</code></a> to load the chunk in the file
5246	named <code>filename</code>.
5247	If <code>filename</code> is <code>NULL</code>,
5248	then it loads from the standard input.
5249	The first line in the file is ignored if it starts with a <code>#</code>.
5250
5251
5252	<p>
5253	This function returns the same results as <a href="#lua_load"><code>lua_load</code></a>,
5254	but it has an extra error code <a name="pdf-LUA_ERRFILE"><code>LUA_ERRFILE</code></a>
5255	if it cannot open/read the file.
5256
5257
5258	<p>
5259	As <a href="#lua_load"><code>lua_load</code></a>, this function only loads the chunk;
5260	it does not run it.
5261
5262
5263
5264
5265
5266	<hr><h3><a name="luaL_loadstring"><code>luaL_loadstring</code></a></h3><p>
5267	<span class="apii">[-0, +1, <em>m</em>]</span>
5268	<pre>int luaL_loadstring (lua_State L, const char s);</pre>
5269
5270	<p>
5271	Loads a string as a Lua chunk.
5272	This function uses <a href="#lua_load"><code>lua_load</code></a> to load the chunk in
5273	the zero-terminated string <code>s</code>.
5274
5275
5276	<p>
5277	This function returns the same results as <a href="#lua_load"><code>lua_load</code></a>.
5278
5279
5280	<p>
5281	Also as <a href="#lua_load"><code>lua_load</code></a>, this function only loads the chunk;
5282	it does not run it.
5283
5284
5285
5286
5287
5288	<hr><h3><a name="luaL_newmetatable"><code>luaL_newmetatable</code></a></h3><p>
5289	<span class="apii">[-0, +1, <em>m</em>]</span>
5290	<pre>int luaL_newmetatable (lua_State L, const char tname);</pre>
5291
5292	<p>
5293	If the registry already has the key <code>tname</code>,
5294	returns 0.
5295	Otherwise,
5296	creates a new table to be used as a metatable for userdata,
5297	adds it to the registry with key <code>tname</code>,
5298	and returns 1.
5299
5300
5301	<p>
5302	In both cases pushes onto the stack the final value associated
5303	with <code>tname</code> in the registry.
5304
5305
5306
5307
5308
5309	<hr><h3><a name="luaL_newstate"><code>luaL_newstate</code></a></h3><p>
5310	<span class="apii">[-0, +0, <em>-</em>]</span>
5311	<pre>lua_State *luaL_newstate (void);</pre>
5312
5313	<p>
5314	Creates a new Lua state.
5315	It calls <a href="#lua_newstate"><code>lua_newstate</code></a> with an
5316	allocator based on the standard C <code>realloc</code> function
5317	and then sets a panic function (see <a href="#lua_atpanic"><code>lua_atpanic</code></a>) that prints
5318	an error message to the standard error output in case of fatal
5319	errors.
5320
5321
5322	<p>
5323	Returns the new state,
5324	or <code>NULL</code> if there is a memory allocation error.
5325
5326
5327
5328
5329
5330	<hr><h3><a name="luaL_openlibs"><code>luaL_openlibs</code></a></h3><p>
5331	<span class="apii">[-0, +0, <em>m</em>]</span>
5332	<pre>void luaL_openlibs (lua_State *L);</pre>
5333
5334	<p>
5335	Opens all standard Lua libraries into the given state.
5336
5337
5338
5339
5340
5341	<hr><h3><a name="luaL_optint"><code>luaL_optint</code></a></h3><p>
5342	<span class="apii">[-0, +0, <em>v</em>]</span>
5343	<pre>int luaL_optint (lua_State *L, int narg, int d);</pre>
5344
5345	<p>
5346	If the function argument <code>narg</code> is a number,
5347	returns this number cast to an <code>int</code>.
5348	If this argument is absent or is <b>nil</b>,
5349	returns <code>d</code>.
5350	Otherwise, raises an error.
5351
5352
5353
5354
5355
5356	<hr><h3><a name="luaL_optinteger"><code>luaL_optinteger</code></a></h3><p>
5357	<span class="apii">[-0, +0, <em>v</em>]</span>
5358	<pre>lua_Integer luaL_optinteger (lua_State *L,
5359	int narg,
5360	lua_Integer d);</pre>
5361
5362	<p>
5363	If the function argument <code>narg</code> is a number,
5364	returns this number cast to a <a href="#lua_Integer"><code>lua_Integer</code></a>.
5365	If this argument is absent or is <b>nil</b>,
5366	returns <code>d</code>.
5367	Otherwise, raises an error.
5368
5369
5370
5371
5372
5373	<hr><h3><a name="luaL_optlong"><code>luaL_optlong</code></a></h3><p>
5374	<span class="apii">[-0, +0, <em>v</em>]</span>
5375	<pre>long luaL_optlong (lua_State *L, int narg, long d);</pre>
5376
5377	<p>
5378	If the function argument <code>narg</code> is a number,
5379	returns this number cast to a <code>long</code>.
5380	If this argument is absent or is <b>nil</b>,
5381	returns <code>d</code>.
5382	Otherwise, raises an error.
5383
5384
5385
5386
5387
5388	<hr><h3><a name="luaL_optlstring"><code>luaL_optlstring</code></a></h3><p>
5389	<span class="apii">[-0, +0, <em>v</em>]</span>
5390	<pre>const char luaL_optlstring (lua_State L,
5391	int narg,
5392	const char *d,
5393	size_t *l);</pre>
5394
5395	<p>
5396	If the function argument <code>narg</code> is a string,
5397	returns this string.
5398	If this argument is absent or is <b>nil</b>,
5399	returns <code>d</code>.
5400	Otherwise, raises an error.
5401
5402
5403	<p>
5404	If <code>l</code> is not <code>NULL</code>,
5405	fills the position <code>*l</code> with the results's length.
5406
5407
5408
5409
5410
5411	<hr><h3><a name="luaL_optnumber"><code>luaL_optnumber</code></a></h3><p>
5412	<span class="apii">[-0, +0, <em>v</em>]</span>
5413	<pre>lua_Number luaL_optnumber (lua_State *L, int narg, lua_Number d);</pre>
5414
5415	<p>
5416	If the function argument <code>narg</code> is a number,
5417	returns this number.
5418	If this argument is absent or is <b>nil</b>,
5419	returns <code>d</code>.
5420	Otherwise, raises an error.
5421
5422
5423
5424
5425
5426	<hr><h3><a name="luaL_optstring"><code>luaL_optstring</code></a></h3><p>
5427	<span class="apii">[-0, +0, <em>v</em>]</span>
5428	<pre>const char luaL_optstring (lua_State L,
5429	int narg,
5430	const char *d);</pre>
5431
5432	<p>
5433	If the function argument <code>narg</code> is a string,
5434	returns this string.
5435	If this argument is absent or is <b>nil</b>,
5436	returns <code>d</code>.
5437	Otherwise, raises an error.
5438
5439
5440
5441
5442
5443	<hr><h3><a name="luaL_prepbuffer"><code>luaL_prepbuffer</code></a></h3><p>
5444	<span class="apii">[-0, +0, <em>-</em>]</span>
5445	<pre>char luaL_prepbuffer (luaL_Buffer B);</pre>
5446
5447	<p>
5448	Returns an address to a space of size <a name="pdf-LUAL_BUFFERSIZE"><code>LUAL_BUFFERSIZE</code></a>
5449	where you can copy a string to be added to buffer <code>B</code>
5450	(see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>).
5451	After copying the string into this space you must call
5452	<a href="#luaL_addsize"><code>luaL_addsize</code></a> with the size of the string to actually add
5453	it to the buffer.
5454
5455
5456
5457
5458
5459	<hr><h3><a name="luaL_pushresult"><code>luaL_pushresult</code></a></h3><p>
5460	<span class="apii">[-?, +1, <em>m</em>]</span>
5461	<pre>void luaL_pushresult (luaL_Buffer *B);</pre>
5462
5463	<p>
5464	Finishes the use of buffer <code>B</code> leaving the final string on
5465	the top of the stack.
5466
5467
5468
5469
5470
5471	<hr><h3><a name="luaL_ref"><code>luaL_ref</code></a></h3><p>
5472	<span class="apii">[-1, +0, <em>m</em>]</span>
5473	<pre>int luaL_ref (lua_State *L, int t);</pre>
5474
5475	<p>
5476	Creates and returns a <em>reference</em>,
5477	in the table at index <code>t</code>,
5478	for the object at the top of the stack (and pops the object).
5479
5480
5481	<p>
5482	A reference is a unique integer key.
5483	As long as you do not manually add integer keys into table <code>t</code>,
5484	<a href="#luaL_ref"><code>luaL_ref</code></a> ensures the uniqueness of the key it returns.
5485	You can retrieve an object referred by reference <code>r</code>
5486	by calling <code>lua_rawgeti(L, t, r)</code>.
5487	Function <a href="#luaL_unref"><code>luaL_unref</code></a> frees a reference and its associated object.
5488
5489
5490	<p>
5491	If the object at the top of the stack is <b>nil</b>,
5492	<a href="#luaL_ref"><code>luaL_ref</code></a> returns the constant <a name="pdf-LUA_REFNIL"><code>LUA_REFNIL</code></a>.
5493	The constant <a name="pdf-LUA_NOREF"><code>LUA_NOREF</code></a> is guaranteed to be different
5494	from any reference returned by <a href="#luaL_ref"><code>luaL_ref</code></a>.
5495
5496
5497
5498
5499
5500	<hr><h3><a name="luaL_Reg"><code>luaL_Reg</code></a></h3>
5501	<pre>typedef struct luaL_Reg {
5502	const char *name;
5503	lua_CFunction func;
5504	} luaL_Reg;</pre>
5505
5506	<p>
5507	Type for arrays of functions to be registered by
5508	<a href="#luaL_register"><code>luaL_register</code></a>.
5509	<code>name</code> is the function name and <code>func</code> is a pointer to
5510	the function.
5511	Any array of <a href="#luaL_Reg"><code>luaL_Reg</code></a> must end with an sentinel entry
5512	in which both <code>name</code> and <code>func</code> are <code>NULL</code>.
5513
5514
5515
5516
5517
5518	<hr><h3><a name="luaL_register"><code>luaL_register</code></a></h3><p>
5519	<span class="apii">[-(0\|1), +1, <em>m</em>]</span>
5520	<pre>void luaL_register (lua_State *L,
5521	const char *libname,
5522	const luaL_Reg *l);</pre>
5523
5524	<p>
5525	Opens a library.
5526
5527
5528	<p>
5529	When called with <code>libname</code> equal to <code>NULL</code>,
5530	it simply registers all functions in the list <code>l</code>
5531	(see <a href="#luaL_Reg"><code>luaL_Reg</code></a>) into the table on the top of the stack.
5532
5533
5534	<p>
5535	When called with a non-null <code>libname</code>,
5536	<code>luaL_register</code> creates a new table <code>t</code>,
5537	sets it as the value of the global variable <code>libname</code>,
5538	sets it as the value of <code>package.loaded[libname]</code>,
5539	and registers on it all functions in the list <code>l</code>.
5540	If there is a table in <code>package.loaded[libname]</code> or in
5541	variable <code>libname</code>,
5542	reuses this table instead of creating a new one.
5543
5544
5545	<p>
5546	In any case the function leaves the table
5547	on the top of the stack.
5548
5549
5550
5551
5552
5553	<hr><h3><a name="luaL_typename"><code>luaL_typename</code></a></h3><p>
5554	<span class="apii">[-0, +0, <em>-</em>]</span>
5555	<pre>const char luaL_typename (lua_State L, int index);</pre>
5556
5557	<p>
5558	Returns the name of the type of the value at the given index.
5559
5560
5561
5562
5563
5564	<hr><h3><a name="luaL_typerror"><code>luaL_typerror</code></a></h3><p>
5565	<span class="apii">[-0, +0, <em>v</em>]</span>
5566	<pre>int luaL_typerror (lua_State L, int narg, const char tname);</pre>
5567
5568	<p>
5569	Generates an error with a message like the following:
5570
5571	<pre>
5572	<em>location</em>: bad argument <em>narg</em> to '<em>func</em>' (<em>tname</em> expected, got <em>rt</em>)
5573	</pre><p>
5574	where <code><em>location</em></code> is produced by <a href="#luaL_where"><code>luaL_where</code></a>,
5575	<code><em>func</em></code> is the name of the current function,
5576	and <code><em>rt</em></code> is the type name of the actual argument.
5577
5578
5579
5580
5581
5582	<hr><h3><a name="luaL_unref"><code>luaL_unref</code></a></h3><p>
5583	<span class="apii">[-0, +0, <em>-</em>]</span>
5584	<pre>void luaL_unref (lua_State *L, int t, int ref);</pre>
5585
5586	<p>
5587	Releases reference <code>ref</code> from the table at index <code>t</code>
5588	(see <a href="#luaL_ref"><code>luaL_ref</code></a>).
5589	The entry is removed from the table,
5590	so that the referred object can be collected.
5591	The reference <code>ref</code> is also freed to be used again.
5592
5593
5594	<p>
5595	If <code>ref</code> is <a href="#pdf-LUA_NOREF"><code>LUA_NOREF</code></a> or <a href="#pdf-LUA_REFNIL"><code>LUA_REFNIL</code></a>,
5596	<a href="#luaL_unref"><code>luaL_unref</code></a> does nothing.
5597
5598
5599
5600
5601
5602	<hr><h3><a name="luaL_where"><code>luaL_where</code></a></h3><p>
5603	<span class="apii">[-0, +1, <em>m</em>]</span>
5604	<pre>void luaL_where (lua_State *L, int lvl);</pre>
5605
5606	<p>
5607	Pushes onto the stack a string identifying the current position
5608	of the control at level <code>lvl</code> in the call stack.
5609	Typically this string has the following format:
5610
5611	<pre>
5612	<em>chunkname</em>:<em>currentline</em>:
5613	</pre><p>
5614	Level 0 is the running function,
5615	level 1 is the function that called the running function,
5616	etc.
5617
5618
5619	<p>
5620	This function is used to build a prefix for error messages.
5621
5622
5623
5624
5625
5626
5627
5628	<h1>5 - <a name="5">Standard Libraries</a></h1>
5629
5630	<p>
5631	The standard Lua libraries provide useful functions
5632	that are implemented directly through the C API.
5633	Some of these functions provide essential services to the language
5634	(e.g., <a href="#pdf-type"><code>type</code></a> and <a href="#pdf-getmetatable"><code>getmetatable</code></a>);
5635	others provide access to "outside" services (e.g., I/O);
5636	and others could be implemented in Lua itself,
5637	but are quite useful or have critical performance requirements that
5638	deserve an implementation in C (e.g., <a href="#pdf-table.sort"><code>table.sort</code></a>).
5639
5640
5641	<p>
5642	All libraries are implemented through the official C API
5643	and are provided as separate C modules.
5644	Currently, Lua has the following standard libraries:
5645
5646	<ul>
5647
5648	<li>basic library,</li> which includes the coroutine sub-library;
5649
5650	<li>package library;</li>
5651
5652	<li>string manipulation;</li>
5653
5654	<li>table manipulation;</li>
5655
5656	<li>mathematical functions (sin, log, etc.);</li>
5657
5658	<li>input and output;</li>
5659
5660	<li>operating system facilities;</li>
5661
5662	<li>debug facilities.</li>
5663
5664	</ul><p>
5665	Except for the basic and package libraries,
5666	each library provides all its functions as fields of a global table
5667	or as methods of its objects.
5668
5669
5670	<p>
5671	To have access to these libraries,
5672	the C host program should call the <a href="#luaL_openlibs"><code>luaL_openlibs</code></a> function,
5673	which opens all standard libraries.
5674	Alternatively,
5675	it can open them individually by calling
5676	<a name="pdf-luaopen_base"><code>luaopen_base</code></a> (for the basic library),
5677	<a name="pdf-luaopen_package"><code>luaopen_package</code></a> (for the package library),
5678	<a name="pdf-luaopen_string"><code>luaopen_string</code></a> (for the string library),
5679	<a name="pdf-luaopen_table"><code>luaopen_table</code></a> (for the table library),
5680	<a name="pdf-luaopen_math"><code>luaopen_math</code></a> (for the mathematical library),
5681	<a name="pdf-luaopen_io"><code>luaopen_io</code></a> (for the I/O library),
5682	<a name="pdf-luaopen_os"><code>luaopen_os</code></a> (for the Operating System library),
5683	and <a name="pdf-luaopen_debug"><code>luaopen_debug</code></a> (for the debug library).
5684	These functions are declared in <a name="pdf-lualib.h"><code>lualib.h</code></a>
5685	and should not be called directly:
5686	you must call them like any other Lua C function,
5687	e.g., by using <a href="#lua_call"><code>lua_call</code></a>.
5688
5689
5690
5691	<h2>5.1 - <a name="5.1">Basic Functions</a></h2>
5692
5693	<p>
5694	The basic library provides some core functions to Lua.
5695	If you do not include this library in your application,
5696	you should check carefully whether you need to provide
5697	implementations for some of its facilities.
5698
5699
5700	<p>
5701	<hr><h3><a name="pdf-assert"><code>assert (v [, message])</code></a></h3>
5702	Issues an error when
5703	the value of its argument <code>v</code> is false (i.e., <b>nil</b> or <b>false</b>);
5704	otherwise, returns all its arguments.
5705	<code>message</code> is an error message;
5706	when absent, it defaults to "assertion failed!"
5707
5708
5709
5710
5711	<p>
5712	<hr><h3><a name="pdf-collectgarbage"><code>collectgarbage (opt [, arg])</code></a></h3>
5713
5714
5715	<p>
5716	This function is a generic interface to the garbage collector.
5717	It performs different functions according to its first argument, <code>opt</code>:
5718
5719	<ul>
5720
5721	<li><b>"stop":</b>
5722	stops the garbage collector.
5723	</li>
5724
5725	<li><b>"restart":</b>
5726	restarts the garbage collector.
5727	</li>
5728
5729	<li><b>"collect":</b>
5730	performs a full garbage-collection cycle.
5731	</li>
5732
5733	<li><b>"count":</b>
5734	returns the total memory in use by Lua (in Kbytes).
5735	</li>
5736
5737	<li><b>"step":</b>
5738	performs a garbage-collection step.
5739	The step "size" is controlled by <code>arg</code>
5740	(larger values mean more steps) in a non-specified way.
5741	If you want to control the step size
5742	you must experimentally tune the value of <code>arg</code>.
5743	Returns <b>true</b> if the step finished a collection cycle.
5744	</li>
5745
5746	<li><b>"setpause":</b>
5747	sets <code>arg</code> as the new value for the <em>pause</em> of
5748	the collector (see <a href="#2.10">§2.10</a>).
5749	Returns the previous value for <em>pause</em>.
5750	</li>
5751
5752	<li><b>"setstepmul":</b>
5753	sets <code>arg</code> as the new value for the <em>step multiplier</em> of
5754	the collector (see <a href="#2.10">§2.10</a>).
5755	Returns the previous value for <em>step</em>.
5756	</li>
5757
5758	</ul>
5759
5760
5761
5762	<p>
5763	<hr><h3><a name="pdf-dofile"><code>dofile (filename)</code></a></h3>
5764	Opens the named file and executes its contents as a Lua chunk.
5765	When called without arguments,
5766	<code>dofile</code> executes the contents of the standard input (<code>stdin</code>).
5767	Returns all values returned by the chunk.
5768	In case of errors, <code>dofile</code> propagates the error
5769	to its caller (that is, <code>dofile</code> does not run in protected mode).
5770
5771
5772
5773
5774	<p>
5775	<hr><h3><a name="pdf-error"><code>error (message [, level])</code></a></h3>
5776	Terminates the last protected function called
5777	and returns <code>message</code> as the error message.
5778	Function <code>error</code> never returns.
5779
5780
5781	<p>
5782	Usually, <code>error</code> adds some information about the error position
5783	at the beginning of the message.
5784	The <code>level</code> argument specifies how to get the error position.
5785	With level 1 (the default), the error position is where the
5786	<code>error</code> function was called.
5787	Level 2 points the error to where the function
5788	that called <code>error</code> was called; and so on.
5789	Passing a level 0 avoids the addition of error position information
5790	to the message.
5791
5792
5793
5794
5795	<p>
5796	<hr><h3><a name="pdf-_G"><code>_G</code></a></h3>
5797	A global variable (not a function) that
5798	holds the global environment (that is, <code>_G._G = _G</code>).
5799	Lua itself does not use this variable;
5800	changing its value does not affect any environment,
5801	nor vice-versa.
5802	(Use <a href="#pdf-setfenv"><code>setfenv</code></a> to change environments.)
5803
5804
5805
5806
5807	<p>
5808	<hr><h3><a name="pdf-getfenv"><code>getfenv ([f])</code></a></h3>
5809	Returns the current environment in use by the function.
5810	<code>f</code> can be a Lua function or a number
5811	that specifies the function at that stack level:
5812	Level 1 is the function calling <code>getfenv</code>.
5813	If the given function is not a Lua function,
5814	or if <code>f</code> is 0,
5815	<code>getfenv</code> returns the global environment.
5816	The default for <code>f</code> is 1.
5817
5818
5819
5820
5821	<p>
5822	<hr><h3><a name="pdf-getmetatable"><code>getmetatable (object)</code></a></h3>
5823
5824
5825	<p>
5826	If <code>object</code> does not have a metatable, returns <b>nil</b>.
5827	Otherwise,
5828	if the object's metatable has a <code>"__metatable"</code> field,
5829	returns the associated value.
5830	Otherwise, returns the metatable of the given object.
5831
5832
5833
5834
5835	<p>
5836	<hr><h3><a name="pdf-ipairs"><code>ipairs (t)</code></a></h3>
5837
5838
5839	<p>
5840	Returns three values: an iterator function, the table <code>t</code>, and 0,
5841	so that the construction
5842
5843	<pre>
5844	for i,v in ipairs(t) do <em>body</em> end
5845	</pre><p>
5846	will iterate over the pairs (<code>1,t[1]</code>), (<code>2,t[2]</code>), ···,
5847	up to the first integer key absent from the table.
5848
5849
5850
5851
5852	<p>
5853	<hr><h3><a name="pdf-load"><code>load (func [, chunkname])</code></a></h3>
5854
5855
5856	<p>
5857	Loads a chunk using function <code>func</code> to get its pieces.
5858	Each call to <code>func</code> must return a string that concatenates
5859	with previous results.
5860	A return of an empty string, <b>nil</b>, or no value signals the end of the chunk.
5861
5862
5863	<p>
5864	If there are no errors,
5865	returns the compiled chunk as a function;
5866	otherwise, returns <b>nil</b> plus the error message.
5867	The environment of the returned function is the global environment.
5868
5869
5870	<p>
5871	<code>chunkname</code> is used as the chunk name for error messages
5872	and debug information.
5873	When absent,
5874	it defaults to "<code>=(load)</code>".
5875
5876
5877
5878
5879	<p>
5880	<hr><h3><a name="pdf-loadfile"><code>loadfile ([filename])</code></a></h3>
5881
5882
5883	<p>
5884	Similar to <a href="#pdf-load"><code>load</code></a>,
5885	but gets the chunk from file <code>filename</code>
5886	or from the standard input,
5887	if no file name is given.
5888
5889
5890
5891
5892	<p>
5893	<hr><h3><a name="pdf-loadstring"><code>loadstring (string [, chunkname])</code></a></h3>
5894
5895
5896	<p>
5897	Similar to <a href="#pdf-load"><code>load</code></a>,
5898	but gets the chunk from the given string.
5899
5900
5901	<p>
5902	To load and run a given string, use the idiom
5903
5904	<pre>
5905	assert(loadstring(s))()
5906	</pre>
5907
5908	<p>
5909	When absent,
5910	<code>chunkname</code> defaults to the given string.
5911
5912
5913
5914
5915	<p>
5916	<hr><h3><a name="pdf-next"><code>next (table [, index])</code></a></h3>
5917
5918
5919	<p>
5920	Allows a program to traverse all fields of a table.
5921	Its first argument is a table and its second argument
5922	is an index in this table.
5923	<code>next</code> returns the next index of the table
5924	and its associated value.
5925	When called with <b>nil</b> as its second argument,
5926	<code>next</code> returns an initial index
5927	and its associated value.
5928	When called with the last index,
5929	or with <b>nil</b> in an empty table,
5930	<code>next</code> returns <b>nil</b>.
5931	If the second argument is absent, then it is interpreted as <b>nil</b>.
5932	In particular,
5933	you can use <code>next(t)</code> to check whether a table is empty.
5934
5935
5936	<p>
5937	The order in which the indices are enumerated is not specified,
5938	<em>even for numeric indices</em>.
5939	(To traverse a table in numeric order,
5940	use a numerical <b>for</b> or the <a href="#pdf-ipairs"><code>ipairs</code></a> function.)
5941
5942
5943	<p>
5944	The behavior of <code>next</code> is <em>undefined</em> if,
5945	during the traversal,
5946	you assign any value to a non-existent field in the table.
5947	You may however modify existing fields.
5948	In particular, you may clear existing fields.
5949
5950
5951
5952
5953	<p>
5954	<hr><h3><a name="pdf-pairs"><code>pairs (t)</code></a></h3>
5955
5956
5957	<p>
5958	Returns three values: the <a href="#pdf-next"><code>next</code></a> function, the table <code>t</code>, and <b>nil</b>,
5959	so that the construction
5960
5961	<pre>
5962	for k,v in pairs(t) do <em>body</em> end
5963	</pre><p>
5964	will iterate over all key–value pairs of table <code>t</code>.
5965
5966
5967	<p>
5968	See function <a href="#pdf-next"><code>next</code></a> for the caveats of modifying
5969	the table during its traversal.
5970
5971
5972
5973
5974	<p>
5975	<hr><h3><a name="pdf-pcall"><code>pcall (f, arg1, ···)</code></a></h3>
5976
5977
5978	<p>
5979	Calls function <code>f</code> with
5980	the given arguments in <em>protected mode</em>.
5981	This means that any error inside <code>f</code> is not propagated;
5982	instead, <code>pcall</code> catches the error
5983	and returns a status code.
5984	Its first result is the status code (a boolean),
5985	which is true if the call succeeds without errors.
5986	In such case, <code>pcall</code> also returns all results from the call,
5987	after this first result.
5988	In case of any error, <code>pcall</code> returns <b>false</b> plus the error message.
5989
5990
5991
5992
5993	<p>
5994	<hr><h3><a name="pdf-print"><code>print (···)</code></a></h3>
5995	Receives any number of arguments,
5996	and prints their values to <code>stdout</code>,
5997	using the <a href="#pdf-tostring"><code>tostring</code></a> function to convert them to strings.
5998	<code>print</code> is not intended for formatted output,
5999	but only as a quick way to show a value,
6000	typically for debugging.
6001	For formatted output, use <a href="#pdf-string.format"><code>string.format</code></a>.
6002
6003
6004
6005
6006	<p>
6007	<hr><h3><a name="pdf-rawequal"><code>rawequal (v1, v2)</code></a></h3>
6008	Checks whether <code>v1</code> is equal to <code>v2</code>,
6009	without invoking any metamethod.
6010	Returns a boolean.
6011
6012
6013
6014
6015	<p>
6016	<hr><h3><a name="pdf-rawget"><code>rawget (table, index)</code></a></h3>
6017	Gets the real value of <code>table[index]</code>,
6018	without invoking any metamethod.
6019	<code>table</code> must be a table;
6020	<code>index</code> may be any value.
6021
6022
6023
6024
6025	<p>
6026	<hr><h3><a name="pdf-rawset"><code>rawset (table, index, value)</code></a></h3>
6027	Sets the real value of <code>table[index]</code> to <code>value</code>,
6028	without invoking any metamethod.
6029	<code>table</code> must be a table,
6030	<code>index</code> any value different from <b>nil</b>,
6031	and <code>value</code> any Lua value.
6032
6033
6034	<p>
6035	This function returns <code>table</code>.
6036
6037
6038
6039
6040	<p>
6041	<hr><h3><a name="pdf-select"><code>select (index, ···)</code></a></h3>
6042
6043
6044	<p>
6045	If <code>index</code> is a number,
6046	returns all arguments after argument number <code>index</code>.
6047	Otherwise, <code>index</code> must be the string <code>"#"</code>,
6048	and <code>select</code> returns the total number of extra arguments it received.
6049
6050
6051
6052
6053	<p>
6054	<hr><h3><a name="pdf-setfenv"><code>setfenv (f, table)</code></a></h3>
6055
6056
6057	<p>
6058	Sets the environment to be used by the given function.
6059	<code>f</code> can be a Lua function or a number
6060	that specifies the function at that stack level:
6061	Level 1 is the function calling <code>setfenv</code>.
6062	<code>setfenv</code> returns the given function.
6063
6064
6065	<p>
6066	As a special case, when <code>f</code> is 0 <code>setfenv</code> changes
6067	the environment of the running thread.
6068	In this case, <code>setfenv</code> returns no values.
6069
6070
6071
6072
6073	<p>
6074	<hr><h3><a name="pdf-setmetatable"><code>setmetatable (table, metatable)</code></a></h3>
6075
6076
6077	<p>
6078	Sets the metatable for the given table.
6079	(You cannot change the metatable of other types from Lua, only from C.)
6080	If <code>metatable</code> is <b>nil</b>,
6081	removes the metatable of the given table.
6082	If the original metatable has a <code>"__metatable"</code> field,
6083	raises an error.
6084
6085
6086	<p>
6087	This function returns <code>table</code>.
6088
6089
6090
6091
6092	<p>
6093	<hr><h3><a name="pdf-tonumber"><code>tonumber (e [, base])</code></a></h3>
6094	Tries to convert its argument to a number.
6095	If the argument is already a number or a string convertible
6096	to a number, then <code>tonumber</code> returns this number;
6097	otherwise, it returns <b>nil</b>.
6098
6099
6100	<p>
6101	An optional argument specifies the base to interpret the numeral.
6102	The base may be any integer between 2 and 36, inclusive.
6103	In bases above 10, the letter '<code>A</code>' (in either upper or lower case)
6104	represents 10, '<code>B</code>' represents 11, and so forth,
6105	with '<code>Z</code>' representing 35.
6106	In base 10 (the default), the number can have a decimal part,
6107	as well as an optional exponent part (see <a href="#2.1">§2.1</a>).
6108	In other bases, only unsigned integers are accepted.
6109
6110
6111
6112
6113	<p>
6114	<hr><h3><a name="pdf-tostring"><code>tostring (e)</code></a></h3>
6115	Receives an argument of any type and
6116	converts it to a string in a reasonable format.
6117	For complete control of how numbers are converted,
6118	use <a href="#pdf-string.format"><code>string.format</code></a>.
6119
6120
6121	<p>
6122	If the metatable of <code>e</code> has a <code>"__tostring"</code> field,
6123	then <code>tostring</code> calls the corresponding value
6124	with <code>e</code> as argument,
6125	and uses the result of the call as its result.
6126
6127
6128
6129
6130	<p>
6131	<hr><h3><a name="pdf-type"><code>type (v)</code></a></h3>
6132	Returns the type of its only argument, coded as a string.
6133	The possible results of this function are
6134	"<code>nil</code>" (a string, not the value <b>nil</b>),
6135	"<code>number</code>",
6136	"<code>string</code>",
6137	"<code>boolean</code>",
6138	"<code>table</code>",
6139	"<code>function</code>",
6140	"<code>thread</code>",
6141	and "<code>userdata</code>".
6142
6143
6144
6145
6146	<p>
6147	<hr><h3><a name="pdf-unpack"><code>unpack (list [, i [, j]])</code></a></h3>
6148	Returns the elements from the given table.
6149	This function is equivalent to
6150
6151	<pre>
6152	return list[i], list[i+1], ···, list[j]
6153	</pre><p>
6154	except that the above code can be written only for a fixed number
6155	of elements.
6156	By default, <code>i</code> is 1 and <code>j</code> is the length of the list,
6157	as defined by the length operator (see <a href="#2.5.5">§2.5.5</a>).
6158
6159
6160
6161
6162	<p>
6163	<hr><h3><a name="pdf-_VERSION"><code>_VERSION</code></a></h3>
6164	A global variable (not a function) that
6165	holds a string containing the current interpreter version.
6166	The current contents of this variable is "<code>Lua 5.1</code>".
6167
6168
6169
6170
6171	<p>
6172	<hr><h3><a name="pdf-xpcall"><code>xpcall (f, err)</code></a></h3>
6173
6174
6175	<p>
6176	This function is similar to <a href="#pdf-pcall"><code>pcall</code></a>,
6177	except that you can set a new error handler.
6178
6179
6180	<p>
6181	<code>xpcall</code> calls function <code>f</code> in protected mode,
6182	using <code>err</code> as the error handler.
6183	Any error inside <code>f</code> is not propagated;
6184	instead, <code>xpcall</code> catches the error,
6185	calls the <code>err</code> function with the original error object,
6186	and returns a status code.
6187	Its first result is the status code (a boolean),
6188	which is true if the call succeeds without errors.
6189	In this case, <code>xpcall</code> also returns all results from the call,
6190	after this first result.
6191	In case of any error,
6192	<code>xpcall</code> returns <b>false</b> plus the result from <code>err</code>.
6193
6194
6195
6196
6197
6198
6199
6200	<h2>5.2 - <a name="5.2">Coroutine Manipulation</a></h2>
6201
6202	<p>
6203	The operations related to coroutines comprise a sub-library of
6204	the basic library and come inside the table <a name="pdf-coroutine"><code>coroutine</code></a>.
6205	See <a href="#2.11">§2.11</a> for a general description of coroutines.
6206
6207
6208	<p>
6209	<hr><h3><a name="pdf-coroutine.create"><code>coroutine.create (f)</code></a></h3>
6210
6211
6212	<p>
6213	Creates a new coroutine, with body <code>f</code>.
6214	<code>f</code> must be a Lua function.
6215	Returns this new coroutine,
6216	an object with type <code>"thread"</code>.
6217
6218
6219
6220
6221	<p>
6222	<hr><h3><a name="pdf-coroutine.resume"><code>coroutine.resume (co [, val1, ···])</code></a></h3>
6223
6224
6225	<p>
6226	Starts or continues the execution of coroutine <code>co</code>.
6227	The first time you resume a coroutine,
6228	it starts running its body.
6229	The values <code>val1</code>, ··· are passed
6230	as the arguments to the body function.
6231	If the coroutine has yielded,
6232	<code>resume</code> restarts it;
6233	the values <code>val1</code>, ··· are passed
6234	as the results from the yield.
6235
6236
6237	<p>
6238	If the coroutine runs without any errors,
6239	<code>resume</code> returns <b>true</b> plus any values passed to <code>yield</code>
6240	(if the coroutine yields) or any values returned by the body function
6241	(if the coroutine terminates).
6242	If there is any error,
6243	<code>resume</code> returns <b>false</b> plus the error message.
6244
6245
6246
6247
6248	<p>
6249	<hr><h3><a name="pdf-coroutine.running"><code>coroutine.running ()</code></a></h3>
6250
6251
6252	<p>
6253	Returns the running coroutine,
6254	or <b>nil</b> when called by the main thread.
6255
6256
6257
6258
6259	<p>
6260	<hr><h3><a name="pdf-coroutine.status"><code>coroutine.status (co)</code></a></h3>
6261
6262
6263	<p>
6264	Returns the status of coroutine <code>co</code>, as a string:
6265	<code>"running"</code>,
6266	if the coroutine is running (that is, it called <code>status</code>);
6267	<code>"suspended"</code>, if the coroutine is suspended in a call to <code>yield</code>,
6268	or if it has not started running yet;
6269	<code>"normal"</code> if the coroutine is active but not running
6270	(that is, it has resumed another coroutine);
6271	and <code>"dead"</code> if the coroutine has finished its body function,
6272	or if it has stopped with an error.
6273
6274
6275
6276
6277	<p>
6278	<hr><h3><a name="pdf-coroutine.wrap"><code>coroutine.wrap (f)</code></a></h3>
6279
6280
6281	<p>
6282	Creates a new coroutine, with body <code>f</code>.
6283	<code>f</code> must be a Lua function.
6284	Returns a function that resumes the coroutine each time it is called.
6285	Any arguments passed to the function behave as the
6286	extra arguments to <code>resume</code>.
6287	Returns the same values returned by <code>resume</code>,
6288	except the first boolean.
6289	In case of error, propagates the error.
6290
6291
6292
6293
6294	<p>
6295	<hr><h3><a name="pdf-coroutine.yield"><code>coroutine.yield (···)</code></a></h3>
6296
6297
6298	<p>
6299	Suspends the execution of the calling coroutine.
6300	The coroutine cannot be running a C function,
6301	a metamethod, or an iterator.
6302	Any arguments to <code>yield</code> are passed as extra results to <code>resume</code>.
6303
6304
6305
6306
6307
6308
6309
6310	<h2>5.3 - <a name="5.3">Modules</a></h2>
6311
6312	<p>
6313	The package library provides basic
6314	facilities for loading and building modules in Lua.
6315	It exports two of its functions directly in the global environment:
6316	<a href="#pdf-require"><code>require</code></a> and <a href="#pdf-module"><code>module</code></a>.
6317	Everything else is exported in a table <a name="pdf-package"><code>package</code></a>.
6318
6319
6320	<p>
6321	<hr><h3><a name="pdf-module"><code>module (name [, ···])</code></a></h3>
6322
6323
6324	<p>
6325	Creates a module.
6326	If there is a table in <code>package.loaded[name]</code>,
6327	this table is the module.
6328	Otherwise, if there is a global table <code>t</code> with the given name,
6329	this table is the module.
6330	Otherwise creates a new table <code>t</code> and
6331	sets it as the value of the global <code>name</code> and
6332	the value of <code>package.loaded[name]</code>.
6333	This function also initializes <code>t._NAME</code> with the given name,
6334	<code>t._M</code> with the module (<code>t</code> itself),
6335	and <code>t._PACKAGE</code> with the package name
6336	(the full module name minus last component; see below).
6337	Finally, <code>module</code> sets <code>t</code> as the new environment
6338	of the current function and the new value of <code>package.loaded[name]</code>,
6339	so that <a href="#pdf-require"><code>require</code></a> returns <code>t</code>.
6340
6341
6342	<p>
6343	If <code>name</code> is a compound name
6344	(that is, one with components separated by dots),
6345	<code>module</code> creates (or reuses, if they already exist)
6346	tables for each component.
6347	For instance, if <code>name</code> is <code>a.b.c</code>,
6348	then <code>module</code> stores the module table in field <code>c</code> of
6349	field <code>b</code> of global <code>a</code>.
6350
6351
6352	<p>
6353	This function can receive optional <em>options</em> after
6354	the module name,
6355	where each option is a function to be applied over the module.
6356
6357
6358
6359
6360	<p>
6361	<hr><h3><a name="pdf-require"><code>require (modname)</code></a></h3>
6362
6363
6364	<p>
6365	Loads the given module.
6366	The function starts by looking into the <a href="#pdf-package.loaded"><code>package.loaded</code></a> table
6367	to determine whether <code>modname</code> is already loaded.
6368	If it is, then <code>require</code> returns the value stored
6369	at <code>package.loaded[modname]</code>.
6370	Otherwise, it tries to find a <em>loader</em> for the module.
6371
6372
6373	<p>
6374	To find a loader,
6375	<code>require</code> is guided by the <a href="#pdf-package.loaders"><code>package.loaders</code></a> array.
6376	By changing this array,
6377	we can change how <code>require</code> looks for a module.
6378	The following explanation is based on the default configuration
6379	for <a href="#pdf-package.loaders"><code>package.loaders</code></a>.
6380
6381
6382	<p>
6383	First <code>require</code> queries <code>package.preload[modname]</code>.
6384	If it has a value,
6385	this value (which should be a function) is the loader.
6386	Otherwise <code>require</code> searches for a Lua loader using the
6387	path stored in <a href="#pdf-package.path"><code>package.path</code></a>.
6388	If that also fails, it searches for a C loader using the
6389	path stored in <a href="#pdf-package.cpath"><code>package.cpath</code></a>.
6390	If that also fails,
6391	it tries an <em>all-in-one</em> loader (see <a href="#pdf-package.loaders"><code>package.loaders</code></a>).
6392
6393
6394	<p>
6395	Once a loader is found,
6396	<code>require</code> calls the loader with a single argument, <code>modname</code>.
6397	If the loader returns any value,
6398	<code>require</code> assigns the returned value to <code>package.loaded[modname]</code>.
6399	If the loader returns no value and
6400	has not assigned any value to <code>package.loaded[modname]</code>,
6401	then <code>require</code> assigns <b>true</b> to this entry.
6402	In any case, <code>require</code> returns the
6403	final value of <code>package.loaded[modname]</code>.
6404
6405
6406	<p>
6407	If there is any error loading or running the module,
6408	or if it cannot find any loader for the module,
6409	then <code>require</code> signals an error.
6410
6411
6412
6413
6414	<p>
6415	<hr><h3><a name="pdf-package.cpath"><code>package.cpath</code></a></h3>
6416
6417
6418	<p>
6419	The path used by <a href="#pdf-require"><code>require</code></a> to search for a C loader.
6420
6421
6422	<p>
6423	Lua initializes the C path <a href="#pdf-package.cpath"><code>package.cpath</code></a> in the same way
6424	it initializes the Lua path <a href="#pdf-package.path"><code>package.path</code></a>,
6425	using the environment variable <a name="pdf-LUA_CPATH"><code>LUA_CPATH</code></a>
6426	or a default path defined in <code>luaconf.h</code>.
6427
6428
6429
6430
6431	<p>
6432
6433	<hr><h3><a name="pdf-package.loaded"><code>package.loaded</code></a></h3>
6434
6435
6436	<p>
6437	A table used by <a href="#pdf-require"><code>require</code></a> to control which
6438	modules are already loaded.
6439	When you require a module <code>modname</code> and
6440	<code>package.loaded[modname]</code> is not false,
6441	<a href="#pdf-require"><code>require</code></a> simply returns the value stored there.
6442
6443
6444
6445
6446	<p>
6447	<hr><h3><a name="pdf-package.loaders"><code>package.loaders</code></a></h3>
6448
6449
6450	<p>
6451	A table used by <a href="#pdf-require"><code>require</code></a> to control how to load modules.
6452
6453
6454	<p>
6455	Each entry in this table is a <em>searcher function</em>.
6456	When looking for a module,
6457	<a href="#pdf-require"><code>require</code></a> calls each of these searchers in ascending order,
6458	with the module name (the argument given to <a href="#pdf-require"><code>require</code></a>) as its
6459	sole parameter.
6460	The function can return another function (the module <em>loader</em>)
6461	or a string explaining why it did not find that module
6462	(or <b>nil</b> if it has nothing to say).
6463	Lua initializes this table with four functions.
6464
6465
6466	<p>
6467	The first searcher simply looks for a loader in the
6468	<a href="#pdf-package.preload"><code>package.preload</code></a> table.
6469
6470
6471	<p>
6472	The second searcher looks for a loader as a Lua library,
6473	using the path stored at <a href="#pdf-package.path"><code>package.path</code></a>.
6474	A path is a sequence of <em>templates</em> separated by semicolons.
6475	For each template,
6476	the searcher will change each interrogation
6477	mark in the template by <code>filename</code>,
6478	which is the module name with each dot replaced by a
6479	"directory separator" (such as "<code>/</code>" in Unix);
6480	then it will try to open the resulting file name.
6481	So, for instance, if the Lua path is the string
6482
6483	<pre>
6484	"./?.lua;./?.lc;/usr/local/?/init.lua"
6485	</pre><p>
6486	the search for a Lua file for module <code>foo</code>
6487	will try to open the files
6488	<code>./foo.lua</code>, <code>./foo.lc</code>, and
6489	<code>/usr/local/foo/init.lua</code>, in that order.
6490
6491
6492	<p>
6493	The third searcher looks for a loader as a C library,
6494	using the path given by the variable <a href="#pdf-package.cpath"><code>package.cpath</code></a>.
6495	For instance,
6496	if the C path is the string
6497
6498	<pre>
6499	"./?.so;./?.dll;/usr/local/?/init.so"
6500	</pre><p>
6501	the searcher for module <code>foo</code>
6502	will try to open the files <code>./foo.so</code>, <code>./foo.dll</code>,
6503	and <code>/usr/local/foo/init.so</code>, in that order.
6504	Once it finds a C library,
6505	this searcher first uses a dynamic link facility to link the
6506	application with the library.
6507	Then it tries to find a C function inside the library to
6508	be used as the loader.
6509	The name of this C function is the string "<code>luaopen_</code>"
6510	concatenated with a copy of the module name where each dot
6511	is replaced by an underscore.
6512	Moreover, if the module name has a hyphen,
6513	its prefix up to (and including) the first hyphen is removed.
6514	For instance, if the module name is <code>a.v1-b.c</code>,
6515	the function name will be <code>luaopen_b_c</code>.
6516
6517
6518	<p>
6519	The fourth searcher tries an <em>all-in-one loader</em>.
6520	It searches the C path for a library for
6521	the root name of the given module.
6522	For instance, when requiring <code>a.b.c</code>,
6523	it will search for a C library for <code>a</code>.
6524	If found, it looks into it for an open function for
6525	the submodule;
6526	in our example, that would be <code>luaopen_a_b_c</code>.
6527	With this facility, a package can pack several C submodules
6528	into one single library,
6529	with each submodule keeping its original open function.
6530
6531
6532
6533
6534	<p>
6535	<hr><h3><a name="pdf-package.loadlib"><code>package.loadlib (libname, funcname)</code></a></h3>
6536
6537
6538	<p>
6539	Dynamically links the host program with the C library <code>libname</code>.
6540	Inside this library, looks for a function <code>funcname</code>
6541	and returns this function as a C function.
6542	(So, <code>funcname</code> must follow the protocol (see <a href="#lua_CFunction"><code>lua_CFunction</code></a>)).
6543
6544
6545	<p>
6546	This is a low-level function.
6547	It completely bypasses the package and module system.
6548	Unlike <a href="#pdf-require"><code>require</code></a>,
6549	it does not perform any path searching and
6550	does not automatically adds extensions.
6551	<code>libname</code> must be the complete file name of the C library,
6552	including if necessary a path and extension.
6553	<code>funcname</code> must be the exact name exported by the C library
6554	(which may depend on the C compiler and linker used).
6555
6556
6557	<p>
6558	This function is not supported by ANSI C.
6559	As such, it is only available on some platforms
6560	(Windows, Linux, Mac OS X, Solaris, BSD,
6561	plus other Unix systems that support the <code>dlfcn</code> standard).
6562
6563
6564
6565
6566	<p>
6567	<hr><h3><a name="pdf-package.path"><code>package.path</code></a></h3>
6568
6569
6570	<p>
6571	The path used by <a href="#pdf-require"><code>require</code></a> to search for a Lua loader.
6572
6573
6574	<p>
6575	At start-up, Lua initializes this variable with
6576	the value of the environment variable <a name="pdf-LUA_PATH"><code>LUA_PATH</code></a> or
6577	with a default path defined in <code>luaconf.h</code>,
6578	if the environment variable is not defined.
6579	Any "<code>;;</code>" in the value of the environment variable
6580	is replaced by the default path.
6581
6582
6583
6584
6585	<p>
6586	<hr><h3><a name="pdf-package.preload"><code>package.preload</code></a></h3>
6587
6588
6589	<p>
6590	A table to store loaders for specific modules
6591	(see <a href="#pdf-require"><code>require</code></a>).
6592
6593
6594
6595
6596	<p>
6597	<hr><h3><a name="pdf-package.seeall"><code>package.seeall (module)</code></a></h3>
6598
6599
6600	<p>
6601	Sets a metatable for <code>module</code> with
6602	its <code>__index</code> field referring to the global environment,
6603	so that this module inherits values
6604	from the global environment.
6605	To be used as an option to function <a href="#pdf-module"><code>module</code></a>.
6606
6607
6608
6609
6610
6611
6612
6613	<h2>5.4 - <a name="5.4">String Manipulation</a></h2>
6614
6615	<p>
6616	This library provides generic functions for string manipulation,
6617	such as finding and extracting substrings, and pattern matching.
6618	When indexing a string in Lua, the first character is at position 1
6619	(not at 0, as in C).
6620	Indices are allowed to be negative and are interpreted as indexing backwards,
6621	from the end of the string.
6622	Thus, the last character is at position -1, and so on.
6623
6624
6625	<p>
6626	The string library provides all its functions inside the table
6627	<a name="pdf-string"><code>string</code></a>.
6628	It also sets a metatable for strings
6629	where the <code>__index</code> field points to the <code>string</code> table.
6630	Therefore, you can use the string functions in object-oriented style.
6631	For instance, <code>string.byte(s, i)</code>
6632	can be written as <code>s:byte(i)</code>.
6633
6634
6635	<p>
6636	The string library assumes one-byte character encodings.
6637
6638
6639	<p>
6640	<hr><h3><a name="pdf-string.byte"><code>string.byte (s [, i [, j]])</code></a></h3>
6641	Returns the internal numerical codes of the characters <code>s[i]</code>,
6642	<code>s[i+1]</code>, ···, <code>s[j]</code>.
6643	The default value for <code>i</code> is 1;
6644	the default value for <code>j</code> is <code>i</code>.
6645
6646
6647	<p>
6648	Note that numerical codes are not necessarily portable across platforms.
6649
6650
6651
6652
6653	<p>
6654	<hr><h3><a name="pdf-string.char"><code>string.char (···)</code></a></h3>
6655	Receives zero or more integers.
6656	Returns a string with length equal to the number of arguments,
6657	in which each character has the internal numerical code equal
6658	to its corresponding argument.
6659
6660
6661	<p>
6662	Note that numerical codes are not necessarily portable across platforms.
6663
6664
6665
6666
6667	<p>
6668	<hr><h3><a name="pdf-string.dump"><code>string.dump (function)</code></a></h3>
6669
6670
6671	<p>
6672	Returns a string containing a binary representation of the given function,
6673	so that a later <a href="#pdf-loadstring"><code>loadstring</code></a> on this string returns
6674	a copy of the function.
6675	<code>function</code> must be a Lua function without upvalues.
6676
6677
6678
6679
6680	<p>
6681	<hr><h3><a name="pdf-string.find"><code>string.find (s, pattern [, init [, plain]])</code></a></h3>
6682	Looks for the first match of
6683	<code>pattern</code> in the string <code>s</code>.
6684	If it finds a match, then <code>find</code> returns the indices of <code>s</code>
6685	where this occurrence starts and ends;
6686	otherwise, it returns <b>nil</b>.
6687	A third, optional numerical argument <code>init</code> specifies
6688	where to start the search;
6689	its default value is 1 and can be negative.
6690	A value of <b>true</b> as a fourth, optional argument <code>plain</code>
6691	turns off the pattern matching facilities,
6692	so the function does a plain "find substring" operation,
6693	with no characters in <code>pattern</code> being considered "magic".
6694	Note that if <code>plain</code> is given, then <code>init</code> must be given as well.
6695
6696
6697	<p>
6698	If the pattern has captures,
6699	then in a successful match
6700	the captured values are also returned,
6701	after the two indices.
6702
6703
6704
6705
6706	<p>
6707	<hr><h3><a name="pdf-string.format"><code>string.format (formatstring, ···)</code></a></h3>
6708	Returns a formatted version of its variable number of arguments
6709	following the description given in its first argument (which must be a string).
6710	The format string follows the same rules as the <code>printf</code> family of
6711	standard C functions.
6712	The only differences are that the options/modifiers
6713	<code>*</code>, <code>l</code>, <code>L</code>, <code>n</code>, <code>p</code>,
6714	and <code>h</code> are not supported
6715	and that there is an extra option, <code>q</code>.
6716	The <code>q</code> option formats a string in a form suitable to be safely read
6717	back by the Lua interpreter:
6718	the string is written between double quotes,
6719	and all double quotes, newlines, embedded zeros,
6720	and backslashes in the string
6721	are correctly escaped when written.
6722	For instance, the call
6723
6724	<pre>
6725	string.format('%q', 'a string with "quotes" and \n new line')
6726	</pre><p>
6727	will produce the string:
6728
6729	<pre>
6730	"a string with \"quotes\" and \
6731	new line"
6732	</pre>
6733
6734	<p>
6735	The options <code>c</code>, <code>d</code>, <code>E</code>, <code>e</code>, <code>f</code>,
6736	<code>g</code>, <code>G</code>, <code>i</code>, <code>o</code>, <code>u</code>, <code>X</code>, and <code>x</code> all
6737	expect a number as argument,
6738	whereas <code>q</code> and <code>s</code> expect a string.
6739
6740
6741	<p>
6742	This function does not accept string values
6743	containing embedded zeros,
6744	except as arguments to the <code>q</code> option.
6745
6746
6747
6748
6749	<p>
6750	<hr><h3><a name="pdf-string.gmatch"><code>string.gmatch (s, pattern)</code></a></h3>
6751	Returns an iterator function that,
6752	each time it is called,
6753	returns the next captures from <code>pattern</code> over string <code>s</code>.
6754	If <code>pattern</code> specifies no captures,
6755	then the whole match is produced in each call.
6756
6757
6758	<p>
6759	As an example, the following loop
6760
6761	<pre>
6762	s = "hello world from Lua"
6763	for w in string.gmatch(s, "%a+") do
6764	print(w)
6765	end
6766	</pre><p>
6767	will iterate over all the words from string <code>s</code>,
6768	printing one per line.
6769	The next example collects all pairs <code>key=value</code> from the
6770	given string into a table:
6771
6772	<pre>
6773	t = {}
6774	s = "from=world, to=Lua"
6775	for k, v in string.gmatch(s, "(%w+)=(%w+)") do
6776	t[k] = v
6777	end
6778	</pre>
6779
6780	<p>
6781	For this function, a '<code>^</code>' at the start of a pattern does not
6782	work as an anchor, as this would prevent the iteration.
6783
6784
6785
6786
6787	<p>
6788	<hr><h3><a name="pdf-string.gsub"><code>string.gsub (s, pattern, repl [, n])</code></a></h3>
6789	Returns a copy of <code>s</code>
6790	in which all (or the first <code>n</code>, if given)
6791	occurrences of the <code>pattern</code> have been
6792	replaced by a replacement string specified by <code>repl</code>,
6793	which can be a string, a table, or a function.
6794	<code>gsub</code> also returns, as its second value,
6795	the total number of matches that occurred.
6796
6797
6798	<p>
6799	If <code>repl</code> is a string, then its value is used for replacement.
6800	The character <code>%</code> works as an escape character:
6801	any sequence in <code>repl</code> of the form <code>%<em>n</em></code>,
6802	with <em>n</em> between 1 and 9,
6803	stands for the value of the <em>n</em>-th captured substring (see below).
6804	The sequence <code>%0</code> stands for the whole match.
6805	The sequence <code>%%</code> stands for a single <code>%</code>.
6806
6807
6808	<p>
6809	If <code>repl</code> is a table, then the table is queried for every match,
6810	using the first capture as the key;
6811	if the pattern specifies no captures,
6812	then the whole match is used as the key.
6813
6814
6815	<p>
6816	If <code>repl</code> is a function, then this function is called every time a
6817	match occurs, with all captured substrings passed as arguments,
6818	in order;
6819	if the pattern specifies no captures,
6820	then the whole match is passed as a sole argument.
6821
6822
6823	<p>
6824	If the value returned by the table query or by the function call
6825	is a string or a number,
6826	then it is used as the replacement string;
6827	otherwise, if it is <b>false</b> or <b>nil</b>,
6828	then there is no replacement
6829	(that is, the original match is kept in the string).
6830
6831
6832	<p>
6833	Here are some examples:
6834
6835	<pre>
6836	x = string.gsub("hello world", "(%w+)", "%1 %1")
6837	--> x="hello hello world world"
6838
6839	x = string.gsub("hello world", "%w+", "%0 %0", 1)
6840	--> x="hello hello world"
6841
6842	x = string.gsub("hello world from Lua", "(%w+)%s*(%w+)", "%2 %1")
6843	--> x="world hello Lua from"
6844
6845	x = string.gsub("home = $HOME, user = $USER", "%$(%w+)", os.getenv)
6846	--> x="home = /home/roberto, user = roberto"
6847
6848	x = string.gsub("4+5 = $return 4+5$", "%$(.-)%$", function (s)
6849	return loadstring(s)()
6850	end)
6851	--> x="4+5 = 9"
6852
6853	local t = {name="lua", version="5.1"}
6854	x = string.gsub("$name-$version.tar.gz", "%$(%w+)", t)
6855	--> x="lua-5.1.tar.gz"
6856	</pre>
6857
6858
6859
6860	<p>
6861	<hr><h3><a name="pdf-string.len"><code>string.len (s)</code></a></h3>
6862	Receives a string and returns its length.
6863	The empty string <code>""</code> has length 0.
6864	Embedded zeros are counted,
6865	so <code>"a\000bc\000"</code> has length 5.
6866
6867
6868
6869
6870	<p>
6871	<hr><h3><a name="pdf-string.lower"><code>string.lower (s)</code></a></h3>
6872	Receives a string and returns a copy of this string with all
6873	uppercase letters changed to lowercase.
6874	All other characters are left unchanged.
6875	The definition of what an uppercase letter is depends on the current locale.
6876
6877
6878
6879
6880	<p>
6881	<hr><h3><a name="pdf-string.match"><code>string.match (s, pattern [, init])</code></a></h3>
6882	Looks for the first <em>match</em> of
6883	<code>pattern</code> in the string <code>s</code>.
6884	If it finds one, then <code>match</code> returns
6885	the captures from the pattern;
6886	otherwise it returns <b>nil</b>.
6887	If <code>pattern</code> specifies no captures,
6888	then the whole match is returned.
6889	A third, optional numerical argument <code>init</code> specifies
6890	where to start the search;
6891	its default value is 1 and can be negative.
6892
6893
6894
6895
6896	<p>
6897	<hr><h3><a name="pdf-string.rep"><code>string.rep (s, n)</code></a></h3>
6898	Returns a string that is the concatenation of <code>n</code> copies of
6899	the string <code>s</code>.
6900
6901
6902
6903
6904	<p>
6905	<hr><h3><a name="pdf-string.reverse"><code>string.reverse (s)</code></a></h3>
6906	Returns a string that is the string <code>s</code> reversed.
6907
6908
6909
6910
6911	<p>
6912	<hr><h3><a name="pdf-string.sub"><code>string.sub (s, i [, j])</code></a></h3>
6913	Returns the substring of <code>s</code> that
6914	starts at <code>i</code> and continues until <code>j</code>;
6915	<code>i</code> and <code>j</code> can be negative.
6916	If <code>j</code> is absent, then it is assumed to be equal to -1
6917	(which is the same as the string length).
6918	In particular,
6919	the call <code>string.sub(s,1,j)</code> returns a prefix of <code>s</code>
6920	with length <code>j</code>,
6921	and <code>string.sub(s, -i)</code> returns a suffix of <code>s</code>
6922	with length <code>i</code>.
6923
6924
6925
6926
6927	<p>
6928	<hr><h3><a name="pdf-string.upper"><code>string.upper (s)</code></a></h3>
6929	Receives a string and returns a copy of this string with all
6930	lowercase letters changed to uppercase.
6931	All other characters are left unchanged.
6932	The definition of what a lowercase letter is depends on the current locale.
6933
6934
6935
6936	<h3>5.4.1 - <a name="5.4.1">Patterns</a></h3>
6937
6938
6939	<h4>Character Class:</h4><p>
6940	A <em>character class</em> is used to represent a set of characters.
6941	The following combinations are allowed in describing a character class:
6942
6943	<ul>
6944
6945	<li><b><em>x</em>:</b>
6946	(where <em>x</em> is not one of the <em>magic characters</em>
6947	<code>^$()%.[]*+-?</code>)
6948	represents the character <em>x</em> itself.
6949	</li>
6950
6951	<li><b><code>.</code>:</b> (a dot) represents all characters.</li>
6952
6953	<li><b><code>%a</code>:</b> represents all letters.</li>
6954
6955	<li><b><code>%c</code>:</b> represents all control characters.</li>
6956
6957	<li><b><code>%d</code>:</b> represents all digits.</li>
6958
6959	<li><b><code>%l</code>:</b> represents all lowercase letters.</li>
6960
6961	<li><b><code>%p</code>:</b> represents all punctuation characters.</li>
6962
6963	<li><b><code>%s</code>:</b> represents all space characters.</li>
6964
6965	<li><b><code>%u</code>:</b> represents all uppercase letters.</li>
6966
6967	<li><b><code>%w</code>:</b> represents all alphanumeric characters.</li>
6968
6969	<li><b><code>%x</code>:</b> represents all hexadecimal digits.</li>
6970
6971	<li><b><code>%z</code>:</b> represents the character with representation 0.</li>
6972
6973	<li><b><code>%<em>x</em></code>:</b> (where <em>x</em> is any non-alphanumeric character)
6974	represents the character <em>x</em>.
6975	This is the standard way to escape the magic characters.
6976	Any punctuation character (even the non magic)
6977	can be preceded by a '<code>%</code>'
6978	when used to represent itself in a pattern.
6979	</li>
6980
6981	<li><b><code>[<em>set</em>]</code>:</b>
6982	represents the class which is the union of all
6983	characters in <em>set</em>.
6984	A range of characters can be specified by
6985	separating the end characters of the range with a '<code>-</code>'.
6986	All classes <code>%</code><em>x</em> described above can also be used as
6987	components in <em>set</em>.
6988	All other characters in <em>set</em> represent themselves.
6989	For example, <code>[%w_]</code> (or <code>[_%w]</code>)
6990	represents all alphanumeric characters plus the underscore,
6991	<code>[0-7]</code> represents the octal digits,
6992	and <code>[0-7%l%-]</code> represents the octal digits plus
6993	the lowercase letters plus the '<code>-</code>' character.
6994
6995
6996	<p>
6997	The interaction between ranges and classes is not defined.
6998	Therefore, patterns like <code>[%a-z]</code> or <code>[a-%%]</code>
6999	have no meaning.
7000	</li>
7001
7002	<li><b><code>[^<em>set</em>]</code>:</b>
7003	represents the complement of <em>set</em>,
7004	where <em>set</em> is interpreted as above.
7005	</li>
7006
7007	</ul><p>
7008	For all classes represented by single letters (<code>%a</code>, <code>%c</code>, etc.),
7009	the corresponding uppercase letter represents the complement of the class.
7010	For instance, <code>%S</code> represents all non-space characters.
7011
7012
7013	<p>
7014	The definitions of letter, space, and other character groups
7015	depend on the current locale.
7016	In particular, the class <code>[a-z]</code> may not be equivalent to <code>%l</code>.
7017
7018
7019
7020
7021
7022	<h4>Pattern Item:</h4><p>
7023	A <em>pattern item</em> can be
7024
7025	<ul>
7026
7027	<li>
7028	a single character class,
7029	which matches any single character in the class;
7030	</li>
7031
7032	<li>
7033	a single character class followed by '<code>*</code>',
7034	which matches 0 or more repetitions of characters in the class.
7035	These repetition items will always match the longest possible sequence;
7036	</li>
7037
7038	<li>
7039	a single character class followed by '<code>+</code>',
7040	which matches 1 or more repetitions of characters in the class.
7041	These repetition items will always match the longest possible sequence;
7042	</li>
7043
7044	<li>
7045	a single character class followed by '<code>-</code>',
7046	which also matches 0 or more repetitions of characters in the class.
7047	Unlike '<code>*</code>',
7048	these repetition items will always match the <em>shortest</em> possible sequence;
7049	</li>
7050
7051	<li>
7052	a single character class followed by '<code>?</code>',
7053	which matches 0 or 1 occurrence of a character in the class;
7054	</li>
7055
7056	<li>
7057	<code>%<em>n</em></code>, for <em>n</em> between 1 and 9;
7058	such item matches a substring equal to the <em>n</em>-th captured string
7059	(see below);
7060	</li>
7061
7062	<li>
7063	<code>%b<em>xy</em></code>, where <em>x</em> and <em>y</em> are two distinct characters;
7064	such item matches strings that start with <em>x</em>, end with <em>y</em>,
7065	and where the <em>x</em> and <em>y</em> are <em>balanced</em>.
7066	This means that, if one reads the string from left to right,
7067	counting <em>+1</em> for an <em>x</em> and <em>-1</em> for a <em>y</em>,
7068	the ending <em>y</em> is the first <em>y</em> where the count reaches 0.
7069	For instance, the item <code>%b()</code> matches expressions with
7070	balanced parentheses.
7071	</li>
7072
7073	</ul>
7074
7075
7076
7077
7078	<h4>Pattern:</h4><p>
7079	A <em>pattern</em> is a sequence of pattern items.
7080	A '<code>^</code>' at the beginning of a pattern anchors the match at the
7081	beginning of the subject string.
7082	A '<code>$</code>' at the end of a pattern anchors the match at the
7083	end of the subject string.
7084	At other positions,
7085	'<code>^</code>' and '<code>$</code>' have no special meaning and represent themselves.
7086
7087
7088
7089
7090
7091	<h4>Captures:</h4><p>
7092	A pattern can contain sub-patterns enclosed in parentheses;
7093	they describe <em>captures</em>.
7094	When a match succeeds, the substrings of the subject string
7095	that match captures are stored (<em>captured</em>) for future use.
7096	Captures are numbered according to their left parentheses.
7097	For instance, in the pattern <code>"(a(.)%w(%s))"</code>,
7098	the part of the string matching <code>"a(.)%w(%s)"</code> is
7099	stored as the first capture (and therefore has number 1);
7100	the character matching "<code>.</code>" is captured with number 2,
7101	and the part matching "<code>%s*</code>" has number 3.
7102
7103
7104	<p>
7105	As a special case, the empty capture <code>()</code> captures
7106	the current string position (a number).
7107	For instance, if we apply the pattern <code>"()aa()"</code> on the
7108	string <code>"flaaap"</code>, there will be two captures: 3 and 5.
7109
7110
7111	<p>
7112	A pattern cannot contain embedded zeros. Use <code>%z</code> instead.
7113
7114
7115
7116
7117
7118
7119
7120
7121
7122
7123
7124	<h2>5.5 - <a name="5.5">Table Manipulation</a></h2><p>
7125	This library provides generic functions for table manipulation.
7126	It provides all its functions inside the table <a name="pdf-table"><code>table</code></a>.
7127
7128
7129	<p>
7130	Most functions in the table library assume that the table
7131	represents an array or a list.
7132	For these functions, when we talk about the "length" of a table
7133	we mean the result of the length operator.
7134
7135
7136	<p>
7137	<hr><h3><a name="pdf-table.concat"><code>table.concat (table [, sep [, i [, j]]])</code></a></h3>
7138	Given an array where all elements are strings or numbers,
7139	returns <code>table[i]..sep..table[i+1] ··· sep..table[j]</code>.
7140	The default value for <code>sep</code> is the empty string,
7141	the default for <code>i</code> is 1,
7142	and the default for <code>j</code> is the length of the table.
7143	If <code>i</code> is greater than <code>j</code>, returns the empty string.
7144
7145
7146
7147
7148	<p>
7149	<hr><h3><a name="pdf-table.insert"><code>table.insert (table, [pos,] value)</code></a></h3>
7150
7151
7152	<p>
7153	Inserts element <code>value</code> at position <code>pos</code> in <code>table</code>,
7154	shifting up other elements to open space, if necessary.
7155	The default value for <code>pos</code> is <code>n+1</code>,
7156	where <code>n</code> is the length of the table (see <a href="#2.5.5">§2.5.5</a>),
7157	so that a call <code>table.insert(t,x)</code> inserts <code>x</code> at the end
7158	of table <code>t</code>.
7159
7160
7161
7162
7163	<p>
7164	<hr><h3><a name="pdf-table.maxn"><code>table.maxn (table)</code></a></h3>
7165
7166
7167	<p>
7168	Returns the largest positive numerical index of the given table,
7169	or zero if the table has no positive numerical indices.
7170	(To do its job this function does a linear traversal of
7171	the whole table.)
7172
7173
7174
7175
7176	<p>
7177	<hr><h3><a name="pdf-table.remove"><code>table.remove (table [, pos])</code></a></h3>
7178
7179
7180	<p>
7181	Removes from <code>table</code> the element at position <code>pos</code>,
7182	shifting down other elements to close the space, if necessary.
7183	Returns the value of the removed element.
7184	The default value for <code>pos</code> is <code>n</code>,
7185	where <code>n</code> is the length of the table,
7186	so that a call <code>table.remove(t)</code> removes the last element
7187	of table <code>t</code>.
7188
7189
7190
7191
7192	<p>
7193	<hr><h3><a name="pdf-table.sort"><code>table.sort (table [, comp])</code></a></h3>
7194	Sorts table elements in a given order, <em>in-place</em>,
7195	from <code>table[1]</code> to <code>table[n]</code>,
7196	where <code>n</code> is the length of the table.
7197	If <code>comp</code> is given,
7198	then it must be a function that receives two table elements,
7199	and returns true
7200	when the first is less than the second
7201	(so that <code>not comp(a[i+1],a[i])</code> will be true after the sort).
7202	If <code>comp</code> is not given,
7203	then the standard Lua operator <code><</code> is used instead.
7204
7205
7206	<p>
7207	The sort algorithm is not stable;
7208	that is, elements considered equal by the given order
7209	may have their relative positions changed by the sort.
7210
7211
7212
7213
7214
7215
7216
7217	<h2>5.6 - <a name="5.6">Mathematical Functions</a></h2>
7218
7219	<p>
7220	This library is an interface to the standard C math library.
7221	It provides all its functions inside the table <a name="pdf-math"><code>math</code></a>.
7222
7223
7224	<p>
7225	<hr><h3><a name="pdf-math.abs"><code>math.abs (x)</code></a></h3>
7226
7227
7228	<p>
7229	Returns the absolute value of <code>x</code>.
7230
7231
7232
7233
7234	<p>
7235	<hr><h3><a name="pdf-math.acos"><code>math.acos (x)</code></a></h3>
7236
7237
7238	<p>
7239	Returns the arc cosine of <code>x</code> (in radians).
7240
7241
7242
7243
7244	<p>
7245	<hr><h3><a name="pdf-math.asin"><code>math.asin (x)</code></a></h3>
7246
7247
7248	<p>
7249	Returns the arc sine of <code>x</code> (in radians).
7250
7251
7252
7253
7254	<p>
7255	<hr><h3><a name="pdf-math.atan"><code>math.atan (x)</code></a></h3>
7256
7257
7258	<p>
7259	Returns the arc tangent of <code>x</code> (in radians).
7260
7261
7262
7263
7264	<p>
7265	<hr><h3><a name="pdf-math.atan2"><code>math.atan2 (y, x)</code></a></h3>
7266
7267
7268	<p>
7269	Returns the arc tangent of <code>y/x</code> (in radians),
7270	but uses the signs of both parameters to find the
7271	quadrant of the result.
7272	(It also handles correctly the case of <code>x</code> being zero.)
7273
7274
7275
7276
7277	<p>
7278	<hr><h3><a name="pdf-math.ceil"><code>math.ceil (x)</code></a></h3>
7279
7280
7281	<p>
7282	Returns the smallest integer larger than or equal to <code>x</code>.
7283
7284
7285
7286
7287	<p>
7288	<hr><h3><a name="pdf-math.cos"><code>math.cos (x)</code></a></h3>
7289
7290
7291	<p>
7292	Returns the cosine of <code>x</code> (assumed to be in radians).
7293
7294
7295
7296
7297	<p>
7298	<hr><h3><a name="pdf-math.cosh"><code>math.cosh (x)</code></a></h3>
7299
7300
7301	<p>
7302	Returns the hyperbolic cosine of <code>x</code>.
7303
7304
7305
7306
7307	<p>
7308	<hr><h3><a name="pdf-math.deg"><code>math.deg (x)</code></a></h3>
7309
7310
7311	<p>
7312	Returns the angle <code>x</code> (given in radians) in degrees.
7313
7314
7315
7316
7317	<p>
7318	<hr><h3><a name="pdf-math.exp"><code>math.exp (x)</code></a></h3>
7319
7320
7321	<p>
7322	Returns the value <em>e<sup>x</sup></em>.
7323
7324
7325
7326
7327	<p>
7328	<hr><h3><a name="pdf-math.floor"><code>math.floor (x)</code></a></h3>
7329
7330
7331	<p>
7332	Returns the largest integer smaller than or equal to <code>x</code>.
7333
7334
7335
7336
7337	<p>
7338	<hr><h3><a name="pdf-math.fmod"><code>math.fmod (x, y)</code></a></h3>
7339
7340
7341	<p>
7342	Returns the remainder of the division of <code>x</code> by <code>y</code>
7343	that rounds the quotient towards zero.
7344
7345
7346
7347
7348	<p>
7349	<hr><h3><a name="pdf-math.frexp"><code>math.frexp (x)</code></a></h3>
7350
7351
7352	<p>
7353	Returns <code>m</code> and <code>e</code> such that <em>x = m2<sup>e</sup></em>,
7354	<code>e</code> is an integer and the absolute value of <code>m</code> is
7355	in the range <em>[0.5, 1)</em>
7356	(or zero when <code>x</code> is zero).
7357
7358
7359
7360
7361	<p>
7362	<hr><h3><a name="pdf-math.huge"><code>math.huge</code></a></h3>
7363
7364
7365	<p>
7366	The value <code>HUGE_VAL</code>,
7367	a value larger than or equal to any other numerical value.
7368
7369
7370
7371
7372	<p>
7373	<hr><h3><a name="pdf-math.ldexp"><code>math.ldexp (m, e)</code></a></h3>
7374
7375
7376	<p>
7377	Returns <em>m2<sup>e</sup></em> (<code>e</code> should be an integer).
7378
7379
7380
7381
7382	<p>
7383	<hr><h3><a name="pdf-math.log"><code>math.log (x)</code></a></h3>
7384
7385
7386	<p>
7387	Returns the natural logarithm of <code>x</code>.
7388
7389
7390
7391
7392	<p>
7393	<hr><h3><a name="pdf-math.log10"><code>math.log10 (x)</code></a></h3>
7394
7395
7396	<p>
7397	Returns the base-10 logarithm of <code>x</code>.
7398
7399
7400
7401
7402	<p>
7403	<hr><h3><a name="pdf-math.max"><code>math.max (x, ···)</code></a></h3>
7404
7405
7406	<p>
7407	Returns the maximum value among its arguments.
7408
7409
7410
7411
7412	<p>
7413	<hr><h3><a name="pdf-math.min"><code>math.min (x, ···)</code></a></h3>
7414
7415
7416	<p>
7417	Returns the minimum value among its arguments.
7418
7419
7420
7421
7422	<p>
7423	<hr><h3><a name="pdf-math.modf"><code>math.modf (x)</code></a></h3>
7424
7425
7426	<p>
7427	Returns two numbers,
7428	the integral part of <code>x</code> and the fractional part of <code>x</code>.
7429
7430
7431
7432
7433	<p>
7434	<hr><h3><a name="pdf-math.pi"><code>math.pi</code></a></h3>
7435
7436
7437	<p>
7438	The value of <em>pi</em>.
7439
7440
7441
7442
7443	<p>
7444	<hr><h3><a name="pdf-math.pow"><code>math.pow (x, y)</code></a></h3>
7445
7446
7447	<p>
7448	Returns <em>x<sup>y</sup></em>.
7449	(You can also use the expression <code>x^y</code> to compute this value.)
7450
7451
7452
7453
7454	<p>
7455	<hr><h3><a name="pdf-math.rad"><code>math.rad (x)</code></a></h3>
7456
7457
7458	<p>
7459	Returns the angle <code>x</code> (given in degrees) in radians.
7460
7461
7462
7463
7464	<p>
7465	<hr><h3><a name="pdf-math.random"><code>math.random ([m [, n]])</code></a></h3>
7466
7467
7468	<p>
7469	This function is an interface to the simple
7470	pseudo-random generator function <code>rand</code> provided by ANSI C.
7471	(No guarantees can be given for its statistical properties.)
7472
7473
7474	<p>
7475	When called without arguments,
7476	returns a uniform pseudo-random real number
7477	in the range <em>[0,1)</em>.
7478	When called with an integer number <code>m</code>,
7479	<code>math.random</code> returns
7480	a uniform pseudo-random integer in the range <em>[1, m]</em>.
7481	When called with two integer numbers <code>m</code> and <code>n</code>,
7482	<code>math.random</code> returns a uniform pseudo-random
7483	integer in the range <em>[m, n]</em>.
7484
7485
7486
7487
7488	<p>
7489	<hr><h3><a name="pdf-math.randomseed"><code>math.randomseed (x)</code></a></h3>
7490
7491
7492	<p>
7493	Sets <code>x</code> as the "seed"
7494	for the pseudo-random generator:
7495	equal seeds produce equal sequences of numbers.
7496
7497
7498
7499
7500	<p>
7501	<hr><h3><a name="pdf-math.sin"><code>math.sin (x)</code></a></h3>
7502
7503
7504	<p>
7505	Returns the sine of <code>x</code> (assumed to be in radians).
7506
7507
7508
7509
7510	<p>
7511	<hr><h3><a name="pdf-math.sinh"><code>math.sinh (x)</code></a></h3>
7512
7513
7514	<p>
7515	Returns the hyperbolic sine of <code>x</code>.
7516
7517
7518
7519
7520	<p>
7521	<hr><h3><a name="pdf-math.sqrt"><code>math.sqrt (x)</code></a></h3>
7522
7523
7524	<p>
7525	Returns the square root of <code>x</code>.
7526	(You can also use the expression <code>x^0.5</code> to compute this value.)
7527
7528
7529
7530
7531	<p>
7532	<hr><h3><a name="pdf-math.tan"><code>math.tan (x)</code></a></h3>
7533
7534
7535	<p>
7536	Returns the tangent of <code>x</code> (assumed to be in radians).
7537
7538
7539
7540
7541	<p>
7542	<hr><h3><a name="pdf-math.tanh"><code>math.tanh (x)</code></a></h3>
7543
7544
7545	<p>
7546	Returns the hyperbolic tangent of <code>x</code>.
7547
7548
7549
7550
7551
7552
7553
7554	<h2>5.7 - <a name="5.7">Input and Output Facilities</a></h2>
7555
7556	<p>
7557	The I/O library provides two different styles for file manipulation.
7558	The first one uses implicit file descriptors;
7559	that is, there are operations to set a default input file and a
7560	default output file,
7561	and all input/output operations are over these default files.
7562	The second style uses explicit file descriptors.
7563
7564
7565	<p>
7566	When using implicit file descriptors,
7567	all operations are supplied by table <a name="pdf-io"><code>io</code></a>.
7568	When using explicit file descriptors,
7569	the operation <a href="#pdf-io.open"><code>io.open</code></a> returns a file descriptor
7570	and then all operations are supplied as methods of the file descriptor.
7571
7572
7573	<p>
7574	The table <code>io</code> also provides
7575	three predefined file descriptors with their usual meanings from C:
7576	<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>.
7577	The I/O library never closes these files.
7578
7579
7580	<p>
7581	Unless otherwise stated,
7582	all I/O functions return <b>nil</b> on failure
7583	(plus an error message as a second result and
7584	a system-dependent error code as a third result)
7585	and some value different from <b>nil</b> on success.
7586
7587
7588	<p>
7589	<hr><h3><a name="pdf-io.close"><code>io.close ([file])</code></a></h3>
7590
7591
7592	<p>
7593	Equivalent to <code>file:close()</code>.
7594	Without a <code>file</code>, closes the default output file.
7595
7596
7597
7598
7599	<p>
7600	<hr><h3><a name="pdf-io.flush"><code>io.flush ()</code></a></h3>
7601
7602
7603	<p>
7604	Equivalent to <code>file:flush</code> over the default output file.
7605
7606
7607
7608
7609	<p>
7610	<hr><h3><a name="pdf-io.input"><code>io.input ([file])</code></a></h3>
7611
7612
7613	<p>
7614	When called with a file name, it opens the named file (in text mode),
7615	and sets its handle as the default input file.
7616	When called with a file handle,
7617	it simply sets this file handle as the default input file.
7618	When called without parameters,
7619	it returns the current default input file.
7620
7621
7622	<p>
7623	In case of errors this function raises the error,
7624	instead of returning an error code.
7625
7626
7627
7628
7629	<p>
7630	<hr><h3><a name="pdf-io.lines"><code>io.lines ([filename])</code></a></h3>
7631
7632
7633	<p>
7634	Opens the given file name in read mode
7635	and returns an iterator function that,
7636	each time it is called,
7637	returns a new line from the file.
7638	Therefore, the construction
7639
7640	<pre>
7641	for line in io.lines(filename) do <em>body</em> end
7642	</pre><p>
7643	will iterate over all lines of the file.
7644	When the iterator function detects the end of file,
7645	it returns <b>nil</b> (to finish the loop) and automatically closes the file.
7646
7647
7648	<p>
7649	The call <code>io.lines()</code> (with no file name) is equivalent
7650	to <code>io.input():lines()</code>;
7651	that is, it iterates over the lines of the default input file.
7652	In this case it does not close the file when the loop ends.
7653
7654
7655
7656
7657	<p>
7658	<hr><h3><a name="pdf-io.open"><code>io.open (filename [, mode])</code></a></h3>
7659
7660
7661	<p>
7662	This function opens a file,
7663	in the mode specified in the string <code>mode</code>.
7664	It returns a new file handle,
7665	or, in case of errors, <b>nil</b> plus an error message.
7666
7667
7668	<p>
7669	The <code>mode</code> string can be any of the following:
7670
7671	<ul>
7672	<li><b>"r":</b> read mode (the default);</li>
7673	<li><b>"w":</b> write mode;</li>
7674	<li><b>"a":</b> append mode;</li>
7675	<li><b>"r+":</b> update mode, all previous data is preserved;</li>
7676	<li><b>"w+":</b> update mode, all previous data is erased;</li>
7677	<li><b>"a+":</b> append update mode, previous data is preserved,
7678	writing is only allowed at the end of file.</li>
7679	</ul><p>
7680	The <code>mode</code> string can also have a '<code>b</code>' at the end,
7681	which is needed in some systems to open the file in binary mode.
7682	This string is exactly what is used in the
7683	standard C function <code>fopen</code>.
7684
7685
7686
7687
7688	<p>
7689	<hr><h3><a name="pdf-io.output"><code>io.output ([file])</code></a></h3>
7690
7691
7692	<p>
7693	Similar to <a href="#pdf-io.input"><code>io.input</code></a>, but operates over the default output file.
7694
7695
7696
7697
7698	<p>
7699	<hr><h3><a name="pdf-io.popen"><code>io.popen (prog [, mode])</code></a></h3>
7700
7701
7702	<p>
7703	Starts program <code>prog</code> in a separated process and returns
7704	a file handle that you can use to read data from this program
7705	(if <code>mode</code> is <code>"r"</code>, the default)
7706	or to write data to this program
7707	(if <code>mode</code> is <code>"w"</code>).
7708
7709
7710	<p>
7711	This function is system dependent and is not available
7712	on all platforms.
7713
7714
7715
7716
7717	<p>
7718	<hr><h3><a name="pdf-io.read"><code>io.read (···)</code></a></h3>
7719
7720
7721	<p>
7722	Equivalent to <code>io.input():read</code>.
7723
7724
7725
7726
7727	<p>
7728	<hr><h3><a name="pdf-io.tmpfile"><code>io.tmpfile ()</code></a></h3>
7729
7730
7731	<p>
7732	Returns a handle for a temporary file.
7733	This file is opened in update mode
7734	and it is automatically removed when the program ends.
7735
7736
7737
7738
7739	<p>
7740	<hr><h3><a name="pdf-io.type"><code>io.type (obj)</code></a></h3>
7741
7742
7743	<p>
7744	Checks whether <code>obj</code> is a valid file handle.
7745	Returns the string <code>"file"</code> if <code>obj</code> is an open file handle,
7746	<code>"closed file"</code> if <code>obj</code> is a closed file handle,
7747	or <b>nil</b> if <code>obj</code> is not a file handle.
7748
7749
7750
7751
7752	<p>
7753	<hr><h3><a name="pdf-io.write"><code>io.write (···)</code></a></h3>
7754
7755
7756	<p>
7757	Equivalent to <code>io.output():write</code>.
7758
7759
7760
7761
7762	<p>
7763	<hr><h3><a name="pdf-file:close"><code>file:close ()</code></a></h3>
7764
7765
7766	<p>
7767	Closes <code>file</code>.
7768	Note that files are automatically closed when
7769	their handles are garbage collected,
7770	but that takes an unpredictable amount of time to happen.
7771
7772
7773
7774
7775	<p>
7776	<hr><h3><a name="pdf-file:flush"><code>file:flush ()</code></a></h3>
7777
7778
7779	<p>
7780	Saves any written data to <code>file</code>.
7781
7782
7783
7784
7785	<p>
7786	<hr><h3><a name="pdf-file:lines"><code>file:lines ()</code></a></h3>
7787
7788
7789	<p>
7790	Returns an iterator function that,
7791	each time it is called,
7792	returns a new line from the file.
7793	Therefore, the construction
7794
7795	<pre>
7796	for line in file:lines() do <em>body</em> end
7797	</pre><p>
7798	will iterate over all lines of the file.
7799	(Unlike <a href="#pdf-io.lines"><code>io.lines</code></a>, this function does not close the file
7800	when the loop ends.)
7801
7802
7803
7804
7805	<p>
7806	<hr><h3><a name="pdf-file:read"><code>file:read (···)</code></a></h3>
7807
7808
7809	<p>
7810	Reads the file <code>file</code>,
7811	according to the given formats, which specify what to read.
7812	For each format,
7813	the function returns a string (or a number) with the characters read,
7814	or <b>nil</b> if it cannot read data with the specified format.
7815	When called without formats,
7816	it uses a default format that reads the entire next line
7817	(see below).
7818
7819
7820	<p>
7821	The available formats are
7822
7823	<ul>
7824
7825	<li><b>"*n":</b>
7826	reads a number;
7827	this is the only format that returns a number instead of a string.
7828	</li>
7829
7830	<li><b>"*a":</b>
7831	reads the whole file, starting at the current position.
7832	On end of file, it returns the empty string.
7833	</li>
7834
7835	<li><b>"*l":</b>
7836	reads the next line (skipping the end of line),
7837	returning <b>nil</b> on end of file.
7838	This is the default format.
7839	</li>
7840
7841	<li><b><em>number</em>:</b>
7842	reads a string with up to this number of characters,
7843	returning <b>nil</b> on end of file.
7844	If number is zero,
7845	it reads nothing and returns an empty string,
7846	or <b>nil</b> on end of file.
7847	</li>
7848
7849	</ul>
7850
7851
7852
7853	<p>
7854	<hr><h3><a name="pdf-file:seek"><code>file:seek ([whence] [, offset])</code></a></h3>
7855
7856
7857	<p>
7858	Sets and gets the file position,
7859	measured from the beginning of the file,
7860	to the position given by <code>offset</code> plus a base
7861	specified by the string <code>whence</code>, as follows:
7862
7863	<ul>
7864	<li><b>"set":</b> base is position 0 (beginning of the file);</li>
7865	<li><b>"cur":</b> base is current position;</li>
7866	<li><b>"end":</b> base is end of file;</li>
7867	</ul><p>
7868	In case of success, function <code>seek</code> returns the final file position,
7869	measured in bytes from the beginning of the file.
7870	If this function fails, it returns <b>nil</b>,
7871	plus a string describing the error.
7872
7873
7874	<p>
7875	The default value for <code>whence</code> is <code>"cur"</code>,
7876	and for <code>offset</code> is 0.
7877	Therefore, the call <code>file:seek()</code> returns the current
7878	file position, without changing it;
7879	the call <code>file:seek("set")</code> sets the position to the
7880	beginning of the file (and returns 0);
7881	and the call <code>file:seek("end")</code> sets the position to the
7882	end of the file, and returns its size.
7883
7884
7885
7886
7887	<p>
7888	<hr><h3><a name="pdf-file:setvbuf"><code>file:setvbuf (mode [, size])</code></a></h3>
7889
7890
7891	<p>
7892	Sets the buffering mode for an output file.
7893	There are three available modes:
7894
7895	<ul>
7896
7897	<li><b>"no":</b>
7898	no buffering; the result of any output operation appears immediately.
7899	</li>
7900
7901	<li><b>"full":</b>
7902	full buffering; output operation is performed only
7903	when the buffer is full (or when you explicitly <code>flush</code> the file
7904	(see <a href="#pdf-io.flush"><code>io.flush</code></a>)).
7905	</li>
7906
7907	<li><b>"line":</b>
7908	line buffering; output is buffered until a newline is output
7909	or there is any input from some special files
7910	(such as a terminal device).
7911	</li>
7912
7913	</ul><p>
7914	For the last two cases, <code>size</code>
7915	specifies the size of the buffer, in bytes.
7916	The default is an appropriate size.
7917
7918
7919
7920
7921	<p>
7922	<hr><h3><a name="pdf-file:write"><code>file:write (···)</code></a></h3>
7923
7924
7925	<p>
7926	Writes the value of each of its arguments to
7927	the <code>file</code>.
7928	The arguments must be strings or numbers.
7929	To write other values,
7930	use <a href="#pdf-tostring"><code>tostring</code></a> or <a href="#pdf-string.format"><code>string.format</code></a> before <code>write</code>.
7931
7932
7933
7934
7935
7936
7937
7938	<h2>5.8 - <a name="5.8">Operating System Facilities</a></h2>
7939
7940	<p>
7941	This library is implemented through table <a name="pdf-os"><code>os</code></a>.
7942
7943
7944	<p>
7945	<hr><h3><a name="pdf-os.clock"><code>os.clock ()</code></a></h3>
7946
7947
7948	<p>
7949	Returns an approximation of the amount in seconds of CPU time
7950	used by the program.
7951
7952
7953
7954
7955	<p>
7956	<hr><h3><a name="pdf-os.date"><code>os.date ([format [, time]])</code></a></h3>
7957
7958
7959	<p>
7960	Returns a string or a table containing date and time,
7961	formatted according to the given string <code>format</code>.
7962
7963
7964	<p>
7965	If the <code>time</code> argument is present,
7966	this is the time to be formatted
7967	(see the <a href="#pdf-os.time"><code>os.time</code></a> function for a description of this value).
7968	Otherwise, <code>date</code> formats the current time.
7969
7970
7971	<p>
7972	If <code>format</code> starts with '<code>!</code>',
7973	then the date is formatted in Coordinated Universal Time.
7974	After this optional character,
7975	if <code>format</code> is the string "<code>*t</code>",
7976	then <code>date</code> returns a table with the following fields:
7977	<code>year</code> (four digits), <code>month</code> (1--12), <code>day</code> (1--31),
7978	<code>hour</code> (0--23), <code>min</code> (0--59), <code>sec</code> (0--61),
7979	<code>wday</code> (weekday, Sunday is 1),
7980	<code>yday</code> (day of the year),
7981	and <code>isdst</code> (daylight saving flag, a boolean).
7982
7983
7984	<p>
7985	If <code>format</code> is not "<code>*t</code>",
7986	then <code>date</code> returns the date as a string,
7987	formatted according to the same rules as the C function <code>strftime</code>.
7988
7989
7990	<p>
7991	When called without arguments,
7992	<code>date</code> returns a reasonable date and time representation that depends on
7993	the host system and on the current locale
7994	(that is, <code>os.date()</code> is equivalent to <code>os.date("%c")</code>).
7995
7996
7997
7998
7999	<p>
8000	<hr><h3><a name="pdf-os.difftime"><code>os.difftime (t2, t1)</code></a></h3>
8001
8002
8003	<p>
8004	Returns the number of seconds from time <code>t1</code> to time <code>t2</code>.
8005	In POSIX, Windows, and some other systems,
8006	this value is exactly <code>t2</code><em>-</em><code>t1</code>.
8007
8008
8009
8010
8011	<p>
8012	<hr><h3><a name="pdf-os.execute"><code>os.execute ([command])</code></a></h3>
8013
8014
8015	<p>
8016	This function is equivalent to the C function <code>system</code>.
8017	It passes <code>command</code> to be executed by an operating system shell.
8018	It returns a status code, which is system-dependent.
8019	If <code>command</code> is absent, then it returns nonzero if a shell is available
8020	and zero otherwise.
8021
8022
8023
8024
8025	<p>
8026	<hr><h3><a name="pdf-os.exit"><code>os.exit ([code])</code></a></h3>
8027
8028
8029	<p>
8030	Calls the C function <code>exit</code>,
8031	with an optional <code>code</code>,
8032	to terminate the host program.
8033	The default value for <code>code</code> is the success code.
8034
8035
8036
8037
8038	<p>
8039	<hr><h3><a name="pdf-os.getenv"><code>os.getenv (varname)</code></a></h3>
8040
8041
8042	<p>
8043	Returns the value of the process environment variable <code>varname</code>,
8044	or <b>nil</b> if the variable is not defined.
8045
8046
8047
8048
8049	<p>
8050	<hr><h3><a name="pdf-os.remove"><code>os.remove (filename)</code></a></h3>
8051
8052
8053	<p>
8054	Deletes the file or directory with the given name.
8055	Directories must be empty to be removed.
8056	If this function fails, it returns <b>nil</b>,
8057	plus a string describing the error.
8058
8059
8060
8061
8062	<p>
8063	<hr><h3><a name="pdf-os.rename"><code>os.rename (oldname, newname)</code></a></h3>
8064
8065
8066	<p>
8067	Renames file or directory named <code>oldname</code> to <code>newname</code>.
8068	If this function fails, it returns <b>nil</b>,
8069	plus a string describing the error.
8070
8071
8072
8073
8074	<p>
8075	<hr><h3><a name="pdf-os.setlocale"><code>os.setlocale (locale [, category])</code></a></h3>
8076
8077
8078	<p>
8079	Sets the current locale of the program.
8080	<code>locale</code> is a string specifying a locale;
8081	<code>category</code> is an optional string describing which category to change:
8082	<code>"all"</code>, <code>"collate"</code>, <code>"ctype"</code>,
8083	<code>"monetary"</code>, <code>"numeric"</code>, or <code>"time"</code>;
8084	the default category is <code>"all"</code>.
8085	The function returns the name of the new locale,
8086	or <b>nil</b> if the request cannot be honored.
8087
8088
8089	<p>
8090	If <code>locale</code> is the empty string,
8091	the current locale is set to an implementation-defined native locale.
8092	If <code>locale</code> is the string "<code>C</code>",
8093	the current locale is set to the standard C locale.
8094
8095
8096	<p>
8097	When called with <b>nil</b> as the first argument,
8098	this function only returns the name of the current locale
8099	for the given category.
8100
8101
8102
8103
8104	<p>
8105	<hr><h3><a name="pdf-os.time"><code>os.time ([table])</code></a></h3>
8106
8107
8108	<p>
8109	Returns the current time when called without arguments,
8110	or a time representing the date and time specified by the given table.
8111	This table must have fields <code>year</code>, <code>month</code>, and <code>day</code>,
8112	and may have fields <code>hour</code>, <code>min</code>, <code>sec</code>, and <code>isdst</code>
8113	(for a description of these fields, see the <a href="#pdf-os.date"><code>os.date</code></a> function).
8114
8115
8116	<p>
8117	The returned value is a number, whose meaning depends on your system.
8118	In POSIX, Windows, and some other systems, this number counts the number
8119	of seconds since some given start time (the "epoch").
8120	In other systems, the meaning is not specified,
8121	and the number returned by <code>time</code> can be used only as an argument to
8122	<code>date</code> and <code>difftime</code>.
8123
8124
8125
8126
8127	<p>
8128	<hr><h3><a name="pdf-os.tmpname"><code>os.tmpname ()</code></a></h3>
8129
8130
8131	<p>
8132	Returns a string with a file name that can
8133	be used for a temporary file.
8134	The file must be explicitly opened before its use
8135	and explicitly removed when no longer needed.
8136
8137
8138	<p>
8139	On some systems (POSIX),
8140	this function also creates a file with that name,
8141	to avoid security risks.
8142	(Someone else might create the file with wrong permissions
8143	in the time between getting the name and creating the file.)
8144	You still have to open the file to use it
8145	and to remove it (even if you do not use it).
8146
8147
8148	<p>
8149	When possible,
8150	you may prefer to use <a href="#pdf-io.tmpfile"><code>io.tmpfile</code></a>,
8151	which automatically removes the file when the program ends.
8152
8153
8154
8155
8156
8157
8158
8159	<h2>5.9 - <a name="5.9">The Debug Library</a></h2>
8160
8161	<p>
8162	This library provides
8163	the functionality of the debug interface to Lua programs.
8164	You should exert care when using this library.
8165	The functions provided here should be used exclusively for debugging
8166	and similar tasks, such as profiling.
8167	Please resist the temptation to use them as a
8168	usual programming tool:
8169	they can be very slow.
8170	Moreover, several of these functions
8171	violate some assumptions about Lua code
8172	(e.g., that variables local to a function
8173	cannot be accessed from outside or
8174	that userdata metatables cannot be changed by Lua code)
8175	and therefore can compromise otherwise secure code.
8176
8177
8178	<p>
8179	All functions in this library are provided
8180	inside the <a name="pdf-debug"><code>debug</code></a> table.
8181	All functions that operate over a thread
8182	have an optional first argument which is the
8183	thread to operate over.
8184	The default is always the current thread.
8185
8186
8187	<p>
8188	<hr><h3><a name="pdf-debug.debug"><code>debug.debug ()</code></a></h3>
8189
8190
8191	<p>
8192	Enters an interactive mode with the user,
8193	running each string that the user enters.
8194	Using simple commands and other debug facilities,
8195	the user can inspect global and local variables,
8196	change their values, evaluate expressions, and so on.
8197	A line containing only the word <code>cont</code> finishes this function,
8198	so that the caller continues its execution.
8199
8200
8201	<p>
8202	Note that commands for <code>debug.debug</code> are not lexically nested
8203	within any function, and so have no direct access to local variables.
8204
8205
8206
8207
8208	<p>
8209	<hr><h3><a name="pdf-debug.getfenv"><code>debug.getfenv (o)</code></a></h3>
8210	Returns the environment of object <code>o</code>.
8211
8212
8213
8214
8215	<p>
8216	<hr><h3><a name="pdf-debug.gethook"><code>debug.gethook ([thread])</code></a></h3>
8217
8218
8219	<p>
8220	Returns the current hook settings of the thread, as three values:
8221	the current hook function, the current hook mask,
8222	and the current hook count
8223	(as set by the <a href="#pdf-debug.sethook"><code>debug.sethook</code></a> function).
8224
8225
8226
8227
8228	<p>
8229	<hr><h3><a name="pdf-debug.getinfo"><code>debug.getinfo ([thread,] function [, what])</code></a></h3>
8230
8231
8232	<p>
8233	Returns a table with information about a function.
8234	You can give the function directly,
8235	or you can give a number as the value of <code>function</code>,
8236	which means the function running at level <code>function</code> of the call stack
8237	of the given thread:
8238	level 0 is the current function (<code>getinfo</code> itself);
8239	level 1 is the function that called <code>getinfo</code>;
8240	and so on.
8241	If <code>function</code> is a number larger than the number of active functions,
8242	then <code>getinfo</code> returns <b>nil</b>.
8243
8244
8245	<p>
8246	The returned table can contain all the fields returned by <a href="#lua_getinfo"><code>lua_getinfo</code></a>,
8247	with the string <code>what</code> describing which fields to fill in.
8248	The default for <code>what</code> is to get all information available,
8249	except the table of valid lines.
8250	If present,
8251	the option '<code>f</code>'
8252	adds a field named <code>func</code> with the function itself.
8253	If present,
8254	the option '<code>L</code>'
8255	adds a field named <code>activelines</code> with the table of
8256	valid lines.
8257
8258
8259	<p>
8260	For instance, the expression <code>debug.getinfo(1,"n").name</code> returns
8261	a table with a name for the current function,
8262	if a reasonable name can be found,
8263	and the expression <code>debug.getinfo(print)</code>
8264	returns a table with all available information
8265	about the <a href="#pdf-print"><code>print</code></a> function.
8266
8267
8268
8269
8270	<p>
8271	<hr><h3><a name="pdf-debug.getlocal"><code>debug.getlocal ([thread,] level, local)</code></a></h3>
8272
8273
8274	<p>
8275	This function returns the name and the value of the local variable
8276	with index <code>local</code> of the function at level <code>level</code> of the stack.
8277	(The first parameter or local variable has index 1, and so on,
8278	until the last active local variable.)
8279	The function returns <b>nil</b> if there is no local
8280	variable with the given index,
8281	and raises an error when called with a <code>level</code> out of range.
8282	(You can call <a href="#pdf-debug.getinfo"><code>debug.getinfo</code></a> to check whether the level is valid.)
8283
8284
8285	<p>
8286	Variable names starting with '<code>(</code>' (open parentheses)
8287	represent internal variables
8288	(loop control variables, temporaries, and C function locals).
8289
8290
8291
8292
8293	<p>
8294	<hr><h3><a name="pdf-debug.getmetatable"><code>debug.getmetatable (object)</code></a></h3>
8295
8296
8297	<p>
8298	Returns the metatable of the given <code>object</code>
8299	or <b>nil</b> if it does not have a metatable.
8300
8301
8302
8303
8304	<p>
8305	<hr><h3><a name="pdf-debug.getregistry"><code>debug.getregistry ()</code></a></h3>
8306
8307
8308	<p>
8309	Returns the registry table (see <a href="#3.5">§3.5</a>).
8310
8311
8312
8313
8314	<p>
8315	<hr><h3><a name="pdf-debug.getupvalue"><code>debug.getupvalue (func, up)</code></a></h3>
8316
8317
8318	<p>
8319	This function returns the name and the value of the upvalue
8320	with index <code>up</code> of the function <code>func</code>.
8321	The function returns <b>nil</b> if there is no upvalue with the given index.
8322
8323
8324
8325
8326	<p>
8327	<hr><h3><a name="pdf-debug.setfenv"><code>debug.setfenv (object, table)</code></a></h3>
8328
8329
8330	<p>
8331	Sets the environment of the given <code>object</code> to the given <code>table</code>.
8332	Returns <code>object</code>.
8333
8334
8335
8336
8337	<p>
8338	<hr><h3><a name="pdf-debug.sethook"><code>debug.sethook ([thread,] hook, mask [, count])</code></a></h3>
8339
8340
8341	<p>
8342	Sets the given function as a hook.
8343	The string <code>mask</code> and the number <code>count</code> describe
8344	when the hook will be called.
8345	The string mask may have the following characters,
8346	with the given meaning:
8347
8348	<ul>
8349	<li><b><code>"c"</code>:</b> the hook is called every time Lua calls a function;</li>
8350	<li><b><code>"r"</code>:</b> the hook is called every time Lua returns from a function;</li>
8351	<li><b><code>"l"</code>:</b> the hook is called every time Lua enters a new line of code.</li>
8352	</ul><p>
8353	With a <code>count</code> different from zero,
8354	the hook is called after every <code>count</code> instructions.
8355
8356
8357	<p>
8358	When called without arguments,
8359	<a href="#pdf-debug.sethook"><code>debug.sethook</code></a> turns off the hook.
8360
8361
8362	<p>
8363	When the hook is called, its first parameter is a string
8364	describing the event that has triggered its call:
8365	<code>"call"</code>, <code>"return"</code> (or <code>"tail return"</code>,
8366	when simulating a return from a tail call),
8367	<code>"line"</code>, and <code>"count"</code>.
8368	For line events,
8369	the hook also gets the new line number as its second parameter.
8370	Inside a hook,
8371	you can call <code>getinfo</code> with level 2 to get more information about
8372	the running function
8373	(level 0 is the <code>getinfo</code> function,
8374	and level 1 is the hook function),
8375	unless the event is <code>"tail return"</code>.
8376	In this case, Lua is only simulating the return,
8377	and a call to <code>getinfo</code> will return invalid data.
8378
8379
8380
8381
8382	<p>
8383	<hr><h3><a name="pdf-debug.setlocal"><code>debug.setlocal ([thread,] level, local, value)</code></a></h3>
8384
8385
8386	<p>
8387	This function assigns the value <code>value</code> to the local variable
8388	with index <code>local</code> of the function at level <code>level</code> of the stack.
8389	The function returns <b>nil</b> if there is no local
8390	variable with the given index,
8391	and raises an error when called with a <code>level</code> out of range.
8392	(You can call <code>getinfo</code> to check whether the level is valid.)
8393	Otherwise, it returns the name of the local variable.
8394
8395
8396
8397
8398	<p>
8399	<hr><h3><a name="pdf-debug.setmetatable"><code>debug.setmetatable (object, table)</code></a></h3>
8400
8401
8402	<p>
8403	Sets the metatable for the given <code>object</code> to the given <code>table</code>
8404	(which can be <b>nil</b>).
8405
8406
8407
8408
8409	<p>
8410	<hr><h3><a name="pdf-debug.setupvalue"><code>debug.setupvalue (func, up, value)</code></a></h3>
8411
8412
8413	<p>
8414	This function assigns the value <code>value</code> to the upvalue
8415	with index <code>up</code> of the function <code>func</code>.
8416	The function returns <b>nil</b> if there is no upvalue
8417	with the given index.
8418	Otherwise, it returns the name of the upvalue.
8419
8420
8421
8422
8423	<p>
8424	<hr><h3><a name="pdf-debug.traceback"><code>debug.traceback ([thread,] [message] [, level])</code></a></h3>
8425
8426
8427	<p>
8428	Returns a string with a traceback of the call stack.
8429	An optional <code>message</code> string is appended
8430	at the beginning of the traceback.
8431	An optional <code>level</code> number tells at which level
8432	to start the traceback
8433	(default is 1, the function calling <code>traceback</code>).
8434
8435
8436
8437
8438
8439
8440
8441	<h1>6 - <a name="6">Lua Stand-alone</a></h1>
8442
8443	<p>
8444	Although Lua has been designed as an extension language,
8445	to be embedded in a host C program,
8446	it is also frequently used as a stand-alone language.
8447	An interpreter for Lua as a stand-alone language,
8448	called simply <code>lua</code>,
8449	is provided with the standard distribution.
8450	The stand-alone interpreter includes
8451	all standard libraries, including the debug library.
8452	Its usage is:
8453
8454	<pre>
8455	lua [options] [script [args]]
8456	</pre><p>
8457	The options are:
8458
8459	<ul>
8460	<li><b><code>-e <em>stat</em></code>:</b> executes string <em>stat</em>;</li>
8461	<li><b><code>-l <em>mod</em></code>:</b> "requires" <em>mod</em>;</li>
8462	<li><b><code>-i</code>:</b> enters interactive mode after running <em>script</em>;</li>
8463	<li><b><code>-v</code>:</b> prints version information;</li>
8464	<li><b><code>--</code>:</b> stops handling options;</li>
8465	<li><b><code>-</code>:</b> executes <code>stdin</code> as a file and stops handling options.</li>
8466	</ul><p>
8467	After handling its options, <code>lua</code> runs the given <em>script</em>,
8468	passing to it the given <em>args</em> as string arguments.
8469	When called without arguments,
8470	<code>lua</code> behaves as <code>lua -v -i</code>
8471	when the standard input (<code>stdin</code>) is a terminal,
8472	and as <code>lua -</code> otherwise.
8473
8474
8475	<p>
8476	Before running any argument,
8477	the interpreter checks for an environment variable <a name="pdf-LUA_INIT"><code>LUA_INIT</code></a>.
8478	If its format is <code>@<em>filename</em></code>,
8479	then <code>lua</code> executes the file.
8480	Otherwise, <code>lua</code> executes the string itself.
8481
8482
8483	<p>
8484	All options are handled in order, except <code>-i</code>.
8485	For instance, an invocation like
8486
8487	<pre>
8488	$ lua -e'a=1' -e 'print(a)' script.lua
8489	</pre><p>
8490	will first set <code>a</code> to 1, then print the value of <code>a</code> (which is '<code>1</code>'),
8491	and finally run the file <code>script.lua</code> with no arguments.
8492	(Here <code>$</code> is the shell prompt. Your prompt may be different.)
8493
8494
8495	<p>
8496	Before starting to run the script,
8497	<code>lua</code> collects all arguments in the command line
8498	in a global table called <code>arg</code>.
8499	The script name is stored at index 0,
8500	the first argument after the script name goes to index 1,
8501	and so on.
8502	Any arguments before the script name
8503	(that is, the interpreter name plus the options)
8504	go to negative indices.
8505	For instance, in the call
8506
8507	<pre>
8508	$ lua -la b.lua t1 t2
8509	</pre><p>
8510	the interpreter first runs the file <code>a.lua</code>,
8511	then creates a table
8512
8513	<pre>
8514	arg = { [-2] = "lua", [-1] = "-la",
8515	[0] = "b.lua",
8516	[1] = "t1", [2] = "t2" }
8517	</pre><p>
8518	and finally runs the file <code>b.lua</code>.
8519	The script is called with <code>arg[1]</code>, <code>arg[2]</code>, ···
8520	as arguments;
8521	it can also access these arguments with the vararg expression '<code>...</code>'.
8522
8523
8524	<p>
8525	In interactive mode,
8526	if you write an incomplete statement,
8527	the interpreter waits for its completion
8528	by issuing a different prompt.
8529
8530
8531	<p>
8532	If the global variable <a name="pdf-_PROMPT"><code>_PROMPT</code></a> contains a string,
8533	then its value is used as the prompt.
8534	Similarly, if the global variable <a name="pdf-_PROMPT2"><code>_PROMPT2</code></a> contains a string,
8535	its value is used as the secondary prompt
8536	(issued during incomplete statements).
8537	Therefore, both prompts can be changed directly on the command line
8538	or in any Lua programs by assigning to <code>_PROMPT</code>.
8539	See the next example:
8540
8541	<pre>
8542	$ lua -e"_PROMPT='myprompt> '" -i
8543	</pre><p>
8544	(The outer pair of quotes is for the shell,
8545	the inner pair is for Lua.)
8546	Note the use of <code>-i</code> to enter interactive mode;
8547	otherwise,
8548	the program would just end silently
8549	right after the assignment to <code>_PROMPT</code>.
8550
8551
8552	<p>
8553	To allow the use of Lua as a
8554	script interpreter in Unix systems,
8555	the stand-alone interpreter skips
8556	the first line of a chunk if it starts with <code>#</code>.
8557	Therefore, Lua scripts can be made into executable programs
8558	by using <code>chmod +x</code> and the <code>#!</code> form,
8559	as in
8560
8561	<pre>
8562	#!/usr/local/bin/lua
8563	</pre><p>
8564	(Of course,
8565	the location of the Lua interpreter may be different in your machine.
8566	If <code>lua</code> is in your <code>PATH</code>,
8567	then
8568
8569	<pre>
8570	#!/usr/bin/env lua
8571	</pre><p>
8572	is a more portable solution.)
8573
8574
8575
8576	<h1>7 - <a name="7">Incompatibilities with the Previous Version</a></h1>
8577
8578	<p>
8579	Here we list the incompatibilities that you may find when moving a program
8580	from Lua 5.0 to Lua 5.1.
8581	You can avoid most of the incompatibilities compiling Lua with
8582	appropriate options (see file <code>luaconf.h</code>).
8583	However,
8584	all these compatibility options will be removed in the next version of Lua.
8585
8586
8587
8588	<h2>7.1 - <a name="7.1">Changes in the Language</a></h2>
8589	<ul>
8590
8591	<li>
8592	The vararg system changed from the pseudo-argument <code>arg</code> with a
8593	table with the extra arguments to the vararg expression.
8594	(See compile-time option <code>LUA_COMPAT_VARARG</code> in <code>luaconf.h</code>.)
8595	</li>
8596
8597	<li>
8598	There was a subtle change in the scope of the implicit
8599	variables of the <b>for</b> statement and for the <b>repeat</b> statement.
8600	</li>
8601
8602	<li>
8603	The long string/long comment syntax (<code>[[<em>string</em>]]</code>)
8604	does not allow nesting.
8605	You can use the new syntax (<code>[=[<em>string</em>]=]</code>) in these cases.
8606	(See compile-time option <code>LUA_COMPAT_LSTR</code> in <code>luaconf.h</code>.)
8607	</li>
8608
8609	</ul>
8610
8611
8612
8613
8614	<h2>7.2 - <a name="7.2">Changes in the Libraries</a></h2>
8615	<ul>
8616
8617	<li>
8618	Function <code>string.gfind</code> was renamed <a href="#pdf-string.gmatch"><code>string.gmatch</code></a>.
8619	(See compile-time option <code>LUA_COMPAT_GFIND</code> in <code>luaconf.h</code>.)
8620	</li>
8621
8622	<li>
8623	When <a href="#pdf-string.gsub"><code>string.gsub</code></a> is called with a function as its
8624	third argument,
8625	whenever this function returns <b>nil</b> or <b>false</b> the
8626	replacement string is the whole match,
8627	instead of the empty string.
8628	</li>
8629
8630	<li>
8631	Function <code>table.setn</code> was deprecated.
8632	Function <code>table.getn</code> corresponds
8633	to the new length operator (<code>#</code>);
8634	use the operator instead of the function.
8635	(See compile-time option <code>LUA_COMPAT_GETN</code> in <code>luaconf.h</code>.)
8636	</li>
8637
8638	<li>
8639	Function <code>loadlib</code> was renamed <a href="#pdf-package.loadlib"><code>package.loadlib</code></a>.
8640	(See compile-time option <code>LUA_COMPAT_LOADLIB</code> in <code>luaconf.h</code>.)
8641	</li>
8642
8643	<li>
8644	Function <code>math.mod</code> was renamed <a href="#pdf-math.fmod"><code>math.fmod</code></a>.
8645	(See compile-time option <code>LUA_COMPAT_MOD</code> in <code>luaconf.h</code>.)
8646	</li>
8647
8648	<li>
8649	Functions <code>table.foreach</code> and <code>table.foreachi</code> are deprecated.
8650	You can use a for loop with <code>pairs</code> or <code>ipairs</code> instead.
8651	</li>
8652
8653	<li>
8654	There were substantial changes in function <a href="#pdf-require"><code>require</code></a> due to
8655	the new module system.
8656	However, the new behavior is mostly compatible with the old,
8657	but <code>require</code> gets the path from <a href="#pdf-package.path"><code>package.path</code></a> instead
8658	of from <code>LUA_PATH</code>.
8659	</li>
8660
8661	<li>
8662	Function <a href="#pdf-collectgarbage"><code>collectgarbage</code></a> has different arguments.
8663	Function <code>gcinfo</code> is deprecated;
8664	use <code>collectgarbage("count")</code> instead.
8665	</li>
8666
8667	</ul>
8668
8669
8670
8671
8672	<h2>7.3 - <a name="7.3">Changes in the API</a></h2>
8673	<ul>
8674
8675	<li>
8676	The <code>luaopen_*</code> functions (to open libraries)
8677	cannot be called directly,
8678	like a regular C function.
8679	They must be called through Lua,
8680	like a Lua function.
8681	</li>
8682
8683	<li>
8684	Function <code>lua_open</code> was replaced by <a href="#lua_newstate"><code>lua_newstate</code></a> to
8685	allow the user to set a memory-allocation function.
8686	You can use <a href="#luaL_newstate"><code>luaL_newstate</code></a> from the standard library to
8687	create a state with a standard allocation function
8688	(based on <code>realloc</code>).
8689	</li>
8690
8691	<li>
8692	Functions <code>luaL_getn</code> and <code>luaL_setn</code>
8693	(from the auxiliary library) are deprecated.
8694	Use <a href="#lua_objlen"><code>lua_objlen</code></a> instead of <code>luaL_getn</code>
8695	and nothing instead of <code>luaL_setn</code>.
8696	</li>
8697
8698	<li>
8699	Function <code>luaL_openlib</code> was replaced by <a href="#luaL_register"><code>luaL_register</code></a>.
8700	</li>
8701
8702	<li>
8703	Function <code>luaL_checkudata</code> now throws an error when the given value
8704	is not a userdata of the expected type.
8705	(In Lua 5.0 it returned <code>NULL</code>.)
8706	</li>
8707
8708	</ul>
8709
8710
8711
8712
8713	<h1>8 - <a name="8">The Complete Syntax of Lua</a></h1>
8714
8715	<p>
8716	Here is the complete syntax of Lua in extended BNF.
8717	(It does not describe operator precedences.)
8718
8719
8720
8721
8722	<pre>
8723
8724	chunk ::= {stat [`<b>;</b>´]} [laststat [`<b>;</b>´]]
8725
8726	block ::= chunk
8727
8728	stat ::= varlist `<b>=</b>´ explist \|
8729	functioncall \|
8730	<b>do</b> block <b>end</b> \|
8731	<b>while</b> exp <b>do</b> block <b>end</b> \|
8732	<b>repeat</b> block <b>until</b> exp \|
8733	<b>if</b> exp <b>then</b> block {<b>elseif</b> exp <b>then</b> block} [<b>else</b> block] <b>end</b> \|
8734	<b>for</b> Name `<b>=</b>´ exp `<b>,</b>´ exp [`<b>,</b>´ exp] <b>do</b> block <b>end</b> \|
8735	<b>for</b> namelist <b>in</b> explist <b>do</b> block <b>end</b> \|
8736	<b>function</b> funcname funcbody \|
8737	<b>local</b> <b>function</b> Name funcbody \|
8738	<b>local</b> namelist [`<b>=</b>´ explist]
8739
8740	laststat ::= <b>return</b> [explist] \| <b>break</b>
8741
8742	funcname ::= Name {`<b>.</b>´ Name} [`<b>:</b>´ Name]
8743
8744	varlist ::= var {`<b>,</b>´ var}
8745
8746	var ::= Name \| prefixexp `<b>[</b>´ exp `<b>]</b>´ \| prefixexp `<b>.</b>´ Name
8747
8748	namelist ::= Name {`<b>,</b>´ Name}
8749
8750	explist ::= {exp `<b>,</b>´} exp
8751
8752	exp ::= <b>nil</b> \| <b>false</b> \| <b>true</b> \| Number \| String \| `<b>...</b>´ \| function \|
8753	prefixexp \| tableconstructor \| exp binop exp \| unop exp
8754
8755	prefixexp ::= var \| functioncall \| `<b>(</b>´ exp `<b>)</b>´
8756
8757	functioncall ::= prefixexp args \| prefixexp `<b>:</b>´ Name args
8758
8759	args ::= `<b>(</b>´ [explist] `<b>)</b>´ \| tableconstructor \| String
8760
8761	function ::= <b>function</b> funcbody
8762
8763	funcbody ::= `<b>(</b>´ [parlist] `<b>)</b>´ block <b>end</b>
8764
8765	parlist ::= namelist [`<b>,</b>´ `<b>...</b>´] \| `<b>...</b>´
8766
8767	tableconstructor ::= `<b>{</b>´ [fieldlist] `<b>}</b>´
8768
8769	fieldlist ::= field {fieldsep field} [fieldsep]
8770
8771	field ::= `<b>[</b>´ exp `<b>]</b>´ `<b>=</b>´ exp \| Name `<b>=</b>´ exp \| exp
8772
8773	fieldsep ::= `<b>,</b>´ \| `<b>;</b>´
8774
8775	binop ::= `<b>+</b>´ \| `<b>-</b>´ \| `<b>*</b>´ \| `<b>/</b>´ \| `<b>^</b>´ \| `<b>%</b>´ \| `<b>..</b>´ \|
8776	`<b><</b>´ \| `<b><=</b>´ \| `<b>></b>´ \| `<b>>=</b>´ \| `<b>==</b>´ \| `<b>~=</b>´ \|
8777	<b>and</b> \| <b>or</b>
8778
8779	unop ::= `<b>-</b>´ \| <b>not</b> \| `<b>#</b>´
8780
8781	</pre>
8782
8783	<p>
8784
8785
8786
8787
8788
8789
8790
8791	<HR>
8792	<SMALL>
8793	Last update:
8794	Mon Aug 18 13:25:46 BRT 2008
8795	</SMALL>
8796	<!--
8797	Last change: revised for Lua 5.1.4
8798	-->
8799
8800	</body></html>
8801