git.saurik.com Git - redis.git/blame_incremental

... / ...

Commit	Line	Data
	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