repo/luan: website/src/manual.html annotate

annotate website/src/manual.html @ 373:571057b1666b

work on manual

author	Franklin Schmidt <fschmidt@gmail.com>
date	Fri, 17 Apr 2015 15:14:44 -0600
parents	f08cefa4594c
children	6c6c3537035e

rev	line source
372 f08cefa4594c start editing manual Franklin Schmidt <fschmidt@gmail.com> parents: 371 diff changeset	1 <!DOCTYPE html>
f08cefa4594c start editing manual Franklin Schmidt <fschmidt@gmail.com> parents: 371 diff changeset	2 <html lang="en">
f08cefa4594c start editing manual Franklin Schmidt <fschmidt@gmail.com> parents: 371 diff changeset	3 <head>
f08cefa4594c start editing manual Franklin Schmidt <fschmidt@gmail.com> parents: 371 diff changeset	4 <meta charset="utf-8">
f08cefa4594c start editing manual Franklin Schmidt <fschmidt@gmail.com> parents: 371 diff changeset	5 <meta name="viewport" content="width=device-width, initial-scale=1">
f08cefa4594c start editing manual Franklin Schmidt <fschmidt@gmail.com> parents: 371 diff changeset	6
f08cefa4594c start editing manual Franklin Schmidt <fschmidt@gmail.com> parents: 371 diff changeset	7 <title>Luan Reference Manual</title>
f08cefa4594c start editing manual Franklin Schmidt <fschmidt@gmail.com> parents: 371 diff changeset	8
f08cefa4594c start editing manual Franklin Schmidt <fschmidt@gmail.com> parents: 371 diff changeset	9 <link href="http://www.simplyhtml.org/assets/bootstrap/css/bootstrap.min.css" rel="stylesheet">
f08cefa4594c start editing manual Franklin Schmidt <fschmidt@gmail.com> parents: 371 diff changeset	10 <link rel="stylesheet" href="http://www.simplyhtml.org/assets/font-awesome/css/font-awesome.min.css">
f08cefa4594c start editing manual Franklin Schmidt <fschmidt@gmail.com> parents: 371 diff changeset	11 <script src="http://www.simplyhtml.org/assets/jquery/jquery.min.js"></script>
f08cefa4594c start editing manual Franklin Schmidt <fschmidt@gmail.com> parents: 371 diff changeset	12
f08cefa4594c start editing manual Franklin Schmidt <fschmidt@gmail.com> parents: 371 diff changeset	13 <link href="http://www.simplyhtml.org/assets/simplyhtml/simplyhtml.css" rel="stylesheet"/>
f08cefa4594c start editing manual Franklin Schmidt <fschmidt@gmail.com> parents: 371 diff changeset	14 <script src="http://www.simplyhtml.org/assets/simplyhtml/simplyhtml.js"></script>
f08cefa4594c start editing manual Franklin Schmidt <fschmidt@gmail.com> parents: 371 diff changeset	15 </head>
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	16
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	17 <body>
372 f08cefa4594c start editing manual Franklin Schmidt <fschmidt@gmail.com> parents: 371 diff changeset	18 <div container>
f08cefa4594c start editing manual Franklin Schmidt <fschmidt@gmail.com> parents: 371 diff changeset	19 <div><small><a href="/">Luan</a></small></div>
f08cefa4594c start editing manual Franklin Schmidt <fschmidt@gmail.com> parents: 371 diff changeset	20
f08cefa4594c start editing manual Franklin Schmidt <fschmidt@gmail.com> parents: 371 diff changeset	21 <h1>Luan Reference Manual</h1>
f08cefa4594c start editing manual Franklin Schmidt <fschmidt@gmail.com> parents: 371 diff changeset	22
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	23 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	24 <small>
372 f08cefa4594c start editing manual Franklin Schmidt <fschmidt@gmail.com> parents: 371 diff changeset	25 Original copyright © 2015 Lua.org, PUC-Rio.
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	26 Freely available under the terms of the
372 f08cefa4594c start editing manual Franklin Schmidt <fschmidt@gmail.com> parents: 371 diff changeset	27 <a href="http://www.lua.org/license.html">Lua license</a>.
f08cefa4594c start editing manual Franklin Schmidt <fschmidt@gmail.com> parents: 371 diff changeset	28 Modified for Luan.
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	29 </small>
372 f08cefa4594c start editing manual Franklin Schmidt <fschmidt@gmail.com> parents: 371 diff changeset	30 </p>
f08cefa4594c start editing manual Franklin Schmidt <fschmidt@gmail.com> parents: 371 diff changeset	31
f08cefa4594c start editing manual Franklin Schmidt <fschmidt@gmail.com> parents: 371 diff changeset	32 <hr/>
f08cefa4594c start editing manual Franklin Schmidt <fschmidt@gmail.com> parents: 371 diff changeset	33
f08cefa4594c start editing manual Franklin Schmidt <fschmidt@gmail.com> parents: 371 diff changeset	34 <h2>Contents</h2>
f08cefa4594c start editing manual Franklin Schmidt <fschmidt@gmail.com> parents: 371 diff changeset	35
f08cefa4594c start editing manual Franklin Schmidt <fschmidt@gmail.com> parents: 371 diff changeset	36 <div margin-bottom="1em"><a href="#intro">Introduction</a></div>
f08cefa4594c start editing manual Franklin Schmidt <fschmidt@gmail.com> parents: 371 diff changeset	37
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	38 <div margin-bottom="1em">
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	39 <a href="#basic">Basic Concepts</a>
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	40 <ul>
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	41 <li><a href="#types">Values and Types</a></li>
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	42 <li><a href="#env">Environments</a></li>
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	43 <li><a href="#error">Error Handling</a></li>
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	44 <li><a href="#meta">Metatables and Metamethods</a></li>
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	45 </ul>
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	46 </div>
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	47
372 f08cefa4594c start editing manual Franklin Schmidt <fschmidt@gmail.com> parents: 371 diff changeset	48 <hr/>
f08cefa4594c start editing manual Franklin Schmidt <fschmidt@gmail.com> parents: 371 diff changeset	49
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	50
372 f08cefa4594c start editing manual Franklin Schmidt <fschmidt@gmail.com> parents: 371 diff changeset	51 <h2 margin-top="1em"><a name="intro">Introduction</a></h2>
f08cefa4594c start editing manual Franklin Schmidt <fschmidt@gmail.com> parents: 371 diff changeset	52
f08cefa4594c start editing manual Franklin Schmidt <fschmidt@gmail.com> parents: 371 diff changeset	53 <p>Luan is a high level programming language based on <a href="http://www.lua.org">Lua</a>. A great strength of Lua is its simplicity and Luan takes this even further, being even simpler than Lua. The goal is to provide a simple programming language for the casual programmer with as few concepts as possible so that one can quickly learn the language and then easily understand any code written in Luan.</p>
f08cefa4594c start editing manual Franklin Schmidt <fschmidt@gmail.com> parents: 371 diff changeset	54
f08cefa4594c start editing manual Franklin Schmidt <fschmidt@gmail.com> parents: 371 diff changeset	55 <p>Luan is implemented in Java and is tightly coupled with Java. So it makes a great scripting language for Java programmers.</p>
f08cefa4594c start editing manual Franklin Schmidt <fschmidt@gmail.com> parents: 371 diff changeset	56
f08cefa4594c start editing manual Franklin Schmidt <fschmidt@gmail.com> parents: 371 diff changeset	57 <p>Unlike Lua which is meant to be embedded, Luan is meant to be a full scripting language. This done not by adding feature to Luan, but rather by providing a complete set of libraries.</p>
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	58
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	59
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	60 <h2 margin-top="1em"><a name="basic">Basic Concepts</a></h2>
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	61
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	62 <p>This section describes the basic concepts of the language.</p>
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	63
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	64 <h3 margin-top="1em"><a name="types">Values and Types</a></h3>
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	65
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	66 <p>
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	67 Luan is a <i>dynamically typed language</i>.
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	68 This means that
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	69 variables do not have types; only values do.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	70 There are no type definitions in the language.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	71 All values carry their own type.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	72
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	73
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	74 <p>
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	75 All values in Luan are <i>first-class values</i>.
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	76 This means that all values can be stored in variables,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	77 passed as arguments to other functions, and returned as results.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	78
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	79
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	80 <p>
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	81 There are eight basic types in Luan:
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	82 <i>nil</i>, <i>boolean</i>, <i>number</i>,
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	83 <i>string</i>, <i>binary</i>, <i>function</i>, <i>userdata</i>,
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	84 and <i>table</i>.
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	85 <i>Nil</i> is the type of the value <b>nil</b>,
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	86 whose main property is to be different from any other value;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	87 it usually represents the absence of a useful value.
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	88 <i>Nil</i> is implemented as the Java value <i>null</i>.
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	89 <i>Boolean</i> is the type of the values <b>false</b> and <b>true</b>.
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	90 <i>Boolean</i> is implemented as the Java class <i>Boolean</i>.
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	91 <i>Number</i> represents both
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	92 integer numbers and real (floating-point) numbers.
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	93 <i>Number</i> is implemented as the Java class <i>Number</i>. Any Java subclass of <i>Number</i> is allowed and this is invisible to the Luan user. Operations on numbers follow the same rules of
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	94 the underlying Java implementation.
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	95
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	96 <i>String</i> is implemented as the Java class <i>String</i>.
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	97 <i>Binary</i> is implemented as the Java type <i>byte[]</i>.
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	98
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	99
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	100 <p>
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	101 Luan can call (and manipulate) functions written in Luan and
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	102 functions written in Java (see <a href="#3.4.10">§3.4.10</a>).
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	103 Both are represented by the type <i>function</i>.
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	104
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	105
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	106 <p>
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	107 The type <i>userdata</i> is provided to allow arbitrary Java objects to
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	108 be stored in Luan variables.
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	109 A userdata value is a Java object that isn't one of the standard Luan types.
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	110 Userdata has no predefined operations in Luan,
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	111 except assignment and identity test.
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	112 Userdata is useful then Java access is enabled in Luan
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	113
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	114
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	115
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	116 <p>
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	117 The type <i>table</i> implements associative arrays,
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	118 that is, arrays that can be indexed not only with numbers,
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	119 but with any Luan value except <b>nil</b>.
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	120 Tables can be <i>heterogeneous</i>;
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	121 that is, they can contain values of all types (except <b>nil</b>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	122 Any key with value <b>nil</b> is not considered part of the table.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	123 Conversely, any key that is not part of a table has
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	124 an associated value <b>nil</b>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	125
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	126
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	127 <p>
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	128 Tables are the sole data-structuring mechanism in Luan;
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	129 they can be used to represent ordinary arrays, sequences,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	130 symbol tables, sets, records, graphs, trees, etc.
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	131 To represent records, Luan uses the field name as an index.
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	132 The language supports this representation by
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	133 providing <tt>a.name</tt> as syntactic sugar for <tt>a["name"]</tt>.
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	134 There are several convenient ways to create tables in Luan
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	135 (see <a href="#3.4.9">§3.4.9</a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	136
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	137
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	138 <p>
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	139 We use the term <i>sequence</i> to denote a table where
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	140 the set of all positive numeric keys is equal to {1..<i>n</i>}
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	141 for some non-negative integer <i>n</i>,
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	142 which is called the length of the sequence (see <a href="#3.4.7">§3.4.7</a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	143
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	144
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	145 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	146 Like indices,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	147 the values of table fields can be of any type.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	148 In particular,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	149 because functions are first-class values,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	150 table fields can contain functions.
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	151 Thus tables can also carry <i>methods</i> (see <a href="#3.4.11">§3.4.11</a>).
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	152
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	153
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	154 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	155 The indexing of tables follows
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	156 the definition of raw equality in the language.
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	157 The expressions <tt>a[i]</tt> and <tt>a[j]</tt>
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	158 denote the same table element
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	159 if and only if <tt>i</tt> and <tt>j</tt> are raw equal
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	160 (that is, equal without metamethods).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	161 In particular, floats with integral values
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	162 are equal to their respective integers
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	163 (e.g., <tt>1.0 == 1</tt>).
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	164
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	165
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	166 <p>
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	167 Luan values are <i>objects</i>:
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	168 variables do not actually <i>contain</i> values,
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	169 only <i>references</i> to them.
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	170 Assignment, parameter passing, and function returns
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	171 always manipulate references to values;
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	172 these operations do not imply any kind of copy.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	173
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	174
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	175 <p>
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	176 The library function <a href="#pdf-type"><tt>Luan.type</tt></a> returns a string describing the type
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	177 of a given value (see <a href="#6.1">§6.1</a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	178
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	179
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	180
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	181
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	182
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	183 <h3 margin-top="1em"><a name="env">Environments</a></h3>
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	184
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	185 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	186 As will be discussed in <a href="#3.2">§3.2</a> and <a href="#3.3.3">§3.3.3</a>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	187 any reference to a free name
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	188 (that is, a name not bound to any declaration) <tt>var</tt>
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	189 is syntactically translated to <tt>_ENV.var</tt>.
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	190 Moreover, every chunk is compiled in the scope of
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	191 an external local variable named <tt>_ENV</tt> (see <a href="#3.3.2">§3.3.2</a>),
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	192 so <tt>_ENV</tt> itself is never a free name in a chunk.
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	193
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	194
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	195 <p>
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	196 Despite the existence of this external <tt>_ENV</tt> variable and
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	197 the translation of free names,
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	198 <tt>_ENV</tt> is a completely regular name.
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	199 In particular,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	200 you can define new variables and parameters with that name.
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	201 Each reference to a free name uses the <tt>_ENV</tt> that is
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	202 visible at that point in the program,
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	203 following the usual visibility rules of Luan (see <a href="#3.5">§3.5</a>).
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	204
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	205
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	206 <p>
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	207 Any table used as the value of <tt>_ENV</tt> is called an <i>environment</i>.
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	208
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	209
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	210 <p>
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	211 When Luan loads a chunk,
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	212 the default value for its <tt>_ENV</tt> is an empty table.
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	213
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	214 <p>
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	215 Luan also provides all chunks with two other local values: <tt>require</tt> and <tt>java</tt>. These are functions used to load and access libraries and other modules.
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	216
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	217
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	218
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	219
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	220 <h3 margin-top="1em"><a name="error">Error Handling</a></h3>
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	221
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	222 <p>
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	223 Luan code can explicitly generate an error by calling the
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	224 <a href="#pdf-error"><tt>error</tt></a> function.
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	225 If you need to catch errors in Luan,
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	226 you can use <a href="#pdf-pcall"><tt>pcall</tt></a> or <a href="#pdf-xpcall"><tt>try</tt></a>
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	227 to call a given function in <i>protected mode</i>.
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	228
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	229
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	230 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	231 Whenever there is an error,
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	232 an <i>error object</i> (also called an <i>error message</i>)
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	233 is propagated with information about the error.
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	234 Luan itself only generates errors whose error object is a string,
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	235 but programs may generate errors with
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	236 any value as the error object.
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	237 It is up to the Luan program or its host to handle such error objects.
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	238
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	239
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	240
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	241
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	242
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	243 <h3 margin-top="1em"><a name="meta">Metatables and Metamethods</a></h3>
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	244
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	245 <p>
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	246 Every table in Luan can have a <i>metatable</i>.
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	247 This <i>metatable</i> is an ordinary Luan table
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	248 that defines the behavior of the original value
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	249 under certain special operations.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	250 You can change several aspects of the behavior
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	251 of operations over a value by setting specific fields in its metatable.
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	252 For instance, when a table is the operand of an addition,
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	253 Luan checks for a function in the field "<tt>__add</tt>" of the table's metatable.
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	254 If it finds one,
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	255 Luan calls this function to perform the addition.
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	256
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	257
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	258 <p>
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	259 The keys in a metatable are derived from the <i>event</i> names;
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	260 the corresponding values are called <ii>metamethods</i>.
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	261 In the previous example, the event is <tt>"add"</tt>
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	262 and the metamethod is the function that performs the addition.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	263
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	264
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	265 <p>
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	266 You can query the metatable of any table
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	267 using the <a href="#pdf-getmetatable"><tt>get_metatable</tt></a> function.
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	268
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	269
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	270 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	271 You can replace the metatable of tables
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	272 using the <a href="#pdf-setmetatable"><tt>set_metatable</tt></a> function.
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	273
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	274
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	275 <p>
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	276 A metatable controls how a table behaves in
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	277 arithmetic operations, bitwise operations,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	278 order comparisons, concatenation, length operation, calls, and indexing.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	279
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	280
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	281 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	282 A detailed list of events controlled by metatables is given next.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	283 Each operation is identified by its corresponding event name.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	284 The key for each event is a string with its name prefixed by
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	285 two underscores, '<tt>__</tt>';
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	286 for instance, the key for operation "add" is the
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	287 string "<tt>__add</tt>".
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	288 Note that queries for metamethods are always raw;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	289 the access to a metamethod does not invoke other metamethods.
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	290 You can emulate how Luan queries a metamethod for an object <tt>obj</tt>
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	291 with the following code:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	292
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	293 <tt><pre>
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	294 raw_get(get_metatable(obj) or {}, "__" .. event_name)
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	295
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	296 </pre></tt>
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	297
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	298 <p>
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	299 Here are the events:
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	300
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	301 <ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	302
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	303 <li><b>"add": </b>
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	304 the <tt>+</tt> operation.
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	305
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	306 If any operand for an addition is a table,
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	307 Luan will try to call a metamethod.
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	308 First, Luan will check the first operand (even if it is valid).
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	309 If that operand does not define a metamethod for the "<tt>__add</tt>" event,
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	310 then Luan will check the second operand.
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	311 If Luan can find a metamethod,
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	312 it calls the metamethod with the two operands as arguments,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	313 and the result of the call
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	314 (adjusted to one value)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	315 is the result of the operation.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	316 Otherwise,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	317 it raises an error.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	318 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	319
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	320 <li><b>"sub": </b>
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	321 the <tt>-</tt> operation.
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	322
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	323 Behavior similar to the "add" operation.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	324 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	325
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	326 <li><b>"mul": </b>
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	327 the <tt>*</tt> operation.
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	328
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	329 Behavior similar to the "add" operation.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	330 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	331
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	332 <li><b>"div": </b>
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	333 the <tt>/</tt> operation.
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	334
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	335 Behavior similar to the "add" operation.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	336 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	337
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	338 <li><b>"mod": </b>
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	339 the <tt>%</tt> operation.
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	340
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	341 Behavior similar to the "add" operation.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	342 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	343
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	344 <li><b>"pow": </b>
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	345 the <tt>^</tt> (exponentiation) operation.
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	346
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	347 Behavior similar to the "add" operation.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	348 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	349
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	350 <li><b>"unm": </b>
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	351 the <tt>-</tt> (unary minus) operation.
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	352
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	353 Behavior similar to the "add" operation.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	354 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	355
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	356 <li><b>"concat": </b>
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	357 the <tt>..</tt> (concatenation) operation.
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	358
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	359 Behavior similar to the "add" operation.
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	360 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	361
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	362 <li><b>"len": </b>
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	363 the <tt>#</tt> (length) operation.
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	364
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	365 If there is a metamethod,
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	366 Luan calls it with the object as argument,
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	367 and the result of the call
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	368 (always adjusted to one value)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	369 is the result of the operation.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	370 If there is no metamethod but the object is a table,
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	371 then Luan uses the table length operation (see <a href="#3.4.7">§3.4.7</a>).
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	372 Otherwise, Luan raises an error.
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	373 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	374
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	375 <li><b>"eq": </b>
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	376 the <tt>==</tt> (equal) operation.
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	377
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	378 Behavior similar to the "add" operation,
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	379 except that Luan will try a metamethod only when the values
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	380 being compared are both tables
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	381 and they are not primitively equal.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	382 The result of the call is always converted to a boolean.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	383 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	384
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	385 <li><b>"lt": </b>
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	386 the <tt><</tt> (less than) operation.
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	387
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	388 Behavior similar to the "add" operation.
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	389 The result of the call is always converted to a boolean.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	390 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	391
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	392 <li><b>"le": </b>
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	393 the <tt><=</tt> (less equal) operation.
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	394
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	395 Unlike other operations,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	396 The less-equal operation can use two different events.
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	397 First, Luan looks for the "<tt>__le</tt>" metamethod in both operands,
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	398 like in the "lt" operation.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	399 If it cannot find such a metamethod,
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	400 then it will try the "<tt>__lt</tt>" event,
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	401 assuming that <tt>a <= b</tt> is equivalent to <tt>not (b < a)</tt>.
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	402 As with the other comparison operators,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	403 the result is always a boolean.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	404 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	405
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	406 <li><b>"index": </b>
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	407 The indexing access <tt>table[key]</tt>.
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	408
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	409 This event happens
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	410 when <tt>key</tt> is not present in <tt>table</tt>.
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	411 The metamethod is looked up in <tt>table</tt>.
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	412
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	413
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	414 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	415 Despite the name,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	416 the metamethod for this event can be either a function or a table.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	417 If it is a function,
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	418 it is called with <tt>table</tt> and <tt>key</tt> as arguments.
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	419 If it is a table,
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	420 the final result is the result of indexing this table with <tt>key</tt>.
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	421 (This indexing is regular, not raw,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	422 and therefore can trigger another metamethod.)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	423 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	424
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	425 <li><b>"newindex": </b>
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	426 The indexing assignment <tt>table[key] = value</tt>.
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	427
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	428 Like the index event,
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	429 this event happens when
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	430 when <tt>key</tt> is not present in <tt>table</tt>.
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	431 The metamethod is looked up in <tt>table</tt>.
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	432
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	433
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	434 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	435 Like with indexing,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	436 the metamethod for this event can be either a function or a table.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	437 If it is a function,
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	438 it is called with <tt>table</tt>, <tt>key</tt>, and <tt>value</tt> as arguments.
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	439 If it is a table,
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	440 Luan does an indexing assignment to this table with the same key and value.
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	441 (This assignment is regular, not raw,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	442 and therefore can trigger another metamethod.)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	443
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	444
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	445 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	446 Whenever there is a "newindex" metamethod,
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	447 Luan does not perform the primitive assignment.
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	448 (If necessary,
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	449 the metamethod itself can call <a href="#pdf-rawset"><tt>raw_set</tt></a>
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	450 to do the assignment.)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	451 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	452
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	453 <li><b>"call": </b>
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	454 The call operation <tt>func(args)</tt>.
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	455
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	456 This event happens when Luan tries to call a table.
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	457 The metamethod is looked up in <tt>func</tt>.
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	458 If present,
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	459 the metamethod is called with <tt>func</tt> as its first argument,
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	460 followed by the arguments of the original call (<tt>args</tt>).
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	461 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	462
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	463 </ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	464
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	465
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	466
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	467
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	468 <h2>2.5 – <a name="2.5">Garbage Collection</a></h2>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	469
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	470 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	471 Lua performs automatic memory management.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	472 This means that
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	473 you do not have to worry about allocating memory for new objects
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	474 or freeing it when the objects are no longer needed.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	475 Lua manages memory automatically by running
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	476 a <em>garbage collector</em> to collect all <em>dead objects</em>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	477 (that is, objects that are no longer accessible from Lua).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	478 All memory used by Lua is subject to automatic management:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	479 strings, tables, userdata, functions, threads, internal structures, etc.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	480
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	481
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	482 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	483 Lua implements an incremental mark-and-sweep collector.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	484 It uses two numbers to control its garbage-collection cycles:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	485 the <em>garbage-collector pause</em> and
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	486 the <em>garbage-collector step multiplier</em>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	487 Both use percentage points as units
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	488 (e.g., a value of 100 means an internal value of 1).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	489
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	490
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	491 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	492 The garbage-collector pause
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	493 controls how long the collector waits before starting a new cycle.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	494 Larger values make the collector less aggressive.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	495 Values smaller than 100 mean the collector will not wait to
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	496 start a new cycle.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	497 A value of 200 means that the collector waits for the total memory in use
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	498 to double before starting a new cycle.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	499
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	500
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	501 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	502 The garbage-collector step multiplier
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	503 controls the relative speed of the collector relative to
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	504 memory allocation.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	505 Larger values make the collector more aggressive but also increase
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	506 the size of each incremental step.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	507 You should not use values smaller than 100,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	508 because they make the collector too slow and
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	509 can result in the collector never finishing a cycle.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	510 The default is 200,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	511 which means that the collector runs at "twice"
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	512 the speed of memory allocation.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	513
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	514
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	515 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	516 If you set the step multiplier to a very large number
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	517 (larger than 10% of the maximum number of
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	518 bytes that the program may use),
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	519 the collector behaves like a stop-the-world collector.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	520 If you then set the pause to 200,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	521 the collector behaves as in old Lua versions,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	522 doing a complete collection every time Lua doubles its
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	523 memory usage.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	524
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	525
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	526 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	527 You can change these numbers by calling <a href="#lua_gc"><code>lua_gc</code></a> in C
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	528 or <a href="#pdf-collectgarbage"><code>collectgarbage</code></a> in Lua.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	529 You can also use these functions to control
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	530 the collector directly (e.g., stop and restart it).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	531
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	532
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	533
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	534 <h3>2.5.1 – <a name="2.5.1">Garbage-Collection Metamethods</a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	535
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	536 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	537 You can set garbage-collector metamethods for tables
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	538 and, using the C API,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	539 for full userdata (see <a href="#2.4">§2.4</a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	540 These metamethods are also called <em>finalizers</em>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	541 Finalizers allow you to coordinate Lua's garbage collection
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	542 with external resource management
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	543 (such as closing files, network or database connections,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	544 or freeing your own memory).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	545
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	546
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	547 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	548 For an object (table or userdata) to be finalized when collected,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	549 you must <em>mark</em> it for finalization.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	550
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	551 You mark an object for finalization when you set its metatable
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	552 and the metatable has a field indexed by the string "<code>__gc</code>".
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	553 Note that if you set a metatable without a <code>__gc</code> field
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	554 and later create that field in the metatable,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	555 the object will not be marked for finalization.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	556 However, after an object has been marked,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	557 you can freely change the <code>__gc</code> field of its metatable.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	558
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	559
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	560 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	561 When a marked object becomes garbage,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	562 it is not collected immediately by the garbage collector.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	563 Instead, Lua puts it in a list.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	564 After the collection,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	565 Lua goes through that list.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	566 For each object in the list,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	567 it checks the object's <code>__gc</code> metamethod:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	568 If it is a function,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	569 Lua calls it with the object as its single argument;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	570 if the metamethod is not a function,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	571 Lua simply ignores it.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	572
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	573
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	574 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	575 At the end of each garbage-collection cycle,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	576 the finalizers for objects are called in
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	577 the reverse order that the objects were marked for finalization,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	578 among those collected in that cycle;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	579 that is, the first finalizer to be called is the one associated
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	580 with the object marked last in the program.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	581 The execution of each finalizer may occur at any point during
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	582 the execution of the regular code.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	583
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	584
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	585 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	586 Because the object being collected must still be used by the finalizer,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	587 that object (and other objects accessible only through it)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	588 must be <em>resurrected</em> by Lua.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	589 Usually, this resurrection is transient,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	590 and the object memory is freed in the next garbage-collection cycle.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	591 However, if the finalizer stores the object in some global place
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	592 (e.g., a global variable),
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	593 then the resurrection is permanent.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	594 Moreover, if the finalizer marks a finalizing object for finalization again,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	595 its finalizer will be called again in the next cycle where the
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	596 object is unreachable.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	597 In any case,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	598 the object memory is freed only in the GC cycle where
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	599 the object is unreachable and not marked for finalization.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	600
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	601
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	602 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	603 When you close a state (see <a href="#lua_close"><code>lua_close</code></a>),
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	604 Lua calls the finalizers of all objects marked for finalization,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	605 following the reverse order that they were marked.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	606 If any finalizer marks objects for collection during that phase,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	607 these marks have no effect.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	608
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	609
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	610
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	611
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	612
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	613 <h3>2.5.2 – <a name="2.5.2">Weak Tables</a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	614
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	615 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	616 A <em>weak table</em> is a table whose elements are
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	617 <em>weak references</em>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	618 A weak reference is ignored by the garbage collector.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	619 In other words,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	620 if the only references to an object are weak references,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	621 then the garbage collector will collect that object.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	622
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	623
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	624 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	625 A weak table can have weak keys, weak values, or both.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	626 A table with weak keys allows the collection of its keys,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	627 but prevents the collection of its values.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	628 A table with both weak keys and weak values allows the collection of
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	629 both keys and values.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	630 In any case, if either the key or the value is collected,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	631 the whole pair is removed from the table.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	632 The weakness of a table is controlled by the
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	633 <code>__mode</code> field of its metatable.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	634 If the <code>__mode</code> field is a string containing the character '<code>k</code>',
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	635 the keys in the table are weak.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	636 If <code>__mode</code> contains '<code>v</code>',
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	637 the values in the table are weak.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	638
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	639
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	640 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	641 A table with weak keys and strong values
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	642 is also called an <em>ephemeron table</em>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	643 In an ephemeron table,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	644 a value is considered reachable only if its key is reachable.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	645 In particular,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	646 if the only reference to a key comes through its value,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	647 the pair is removed.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	648
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	649
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	650 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	651 Any change in the weakness of a table may take effect only
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	652 at the next collect cycle.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	653 In particular, if you change the weakness to a stronger mode,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	654 Lua may still collect some items from that table
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	655 before the change takes effect.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	656
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	657
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	658 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	659 Only objects that have an explicit construction
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	660 are removed from weak tables.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	661 Values, such as numbers and light C functions,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	662 are not subject to garbage collection,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	663 and therefore are not removed from weak tables
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	664 (unless their associated values are collected).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	665 Although strings are subject to garbage collection,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	666 they do not have an explicit construction,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	667 and therefore are not removed from weak tables.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	668
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	669
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	670 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	671 Resurrected objects
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	672 (that is, objects being finalized
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	673 and objects accessible only through objects being finalized)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	674 have a special behavior in weak tables.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	675 They are removed from weak values before running their finalizers,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	676 but are removed from weak keys only in the next collection
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	677 after running their finalizers, when such objects are actually freed.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	678 This behavior allows the finalizer to access properties
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	679 associated with the object through weak tables.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	680
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	681
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	682 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	683 If a weak table is among the resurrected objects in a collection cycle,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	684 it may not be properly cleared until the next cycle.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	685
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	686
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	687
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	688
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	689
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	690
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	691
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	692 <h2>2.6 – <a name="2.6">Coroutines</a></h2>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	693
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	694 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	695 Lua supports coroutines,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	696 also called <em>collaborative multithreading</em>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	697 A coroutine in Lua represents an independent thread of execution.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	698 Unlike threads in multithread systems, however,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	699 a coroutine only suspends its execution by explicitly calling
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	700 a yield function.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	701
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	702
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	703 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	704 You create a coroutine by calling <a href="#pdf-coroutine.create"><code>coroutine.create</code></a>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	705 Its sole argument is a function
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	706 that is the main function of the coroutine.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	707 The <code>create</code> function only creates a new coroutine and
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	708 returns a handle to it (an object of type <em>thread</em>);
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	709 it does not start the coroutine.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	710
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	711
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	712 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	713 You execute a coroutine by calling <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	714 When you first call <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	715 passing as its first argument
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	716 a thread returned by <a href="#pdf-coroutine.create"><code>coroutine.create</code></a>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	717 the coroutine starts its execution,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	718 at the first line of its main function.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	719 Extra arguments passed to <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a> are passed
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	720 as arguments to the coroutine's main function.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	721 After the coroutine starts running,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	722 it runs until it terminates or <em>yields</em>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	723
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	724
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	725 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	726 A coroutine can terminate its execution in two ways:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	727 normally, when its main function returns
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	728 (explicitly or implicitly, after the last instruction);
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	729 and abnormally, if there is an unprotected error.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	730 In case of normal termination,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	731 <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a> returns <b>true</b>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	732 plus any values returned by the coroutine main function.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	733 In case of errors, <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a> returns <b>false</b>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	734 plus an error message.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	735
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	736
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	737 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	738 A coroutine yields by calling <a href="#pdf-coroutine.yield"><code>coroutine.yield</code></a>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	739 When a coroutine yields,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	740 the corresponding <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a> returns immediately,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	741 even if the yield happens inside nested function calls
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	742 (that is, not in the main function,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	743 but in a function directly or indirectly called by the main function).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	744 In the case of a yield, <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a> also returns <b>true</b>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	745 plus any values passed to <a href="#pdf-coroutine.yield"><code>coroutine.yield</code></a>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	746 The next time you resume the same coroutine,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	747 it continues its execution from the point where it yielded,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	748 with the call to <a href="#pdf-coroutine.yield"><code>coroutine.yield</code></a> returning any extra
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	749 arguments passed to <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	750
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	751
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	752 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	753 Like <a href="#pdf-coroutine.create"><code>coroutine.create</code></a>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	754 the <a href="#pdf-coroutine.wrap"><code>coroutine.wrap</code></a> function also creates a coroutine,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	755 but instead of returning the coroutine itself,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	756 it returns a function that, when called, resumes the coroutine.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	757 Any arguments passed to this function
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	758 go as extra arguments to <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	759 <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>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	760 except the first one (the boolean error code).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	761 Unlike <a href="#pdf-coroutine.resume"><code>coroutine.resume</code></a>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	762 <a href="#pdf-coroutine.wrap"><code>coroutine.wrap</code></a> does not catch errors;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	763 any error is propagated to the caller.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	764
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	765
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	766 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	767 As an example of how coroutines work,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	768 consider the following code:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	769
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	770 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	771 function foo (a)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	772 print("foo", a)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	773 return coroutine.yield(2*a)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	774 end
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	775
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	776 co = coroutine.create(function (a,b)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	777 print("co-body", a, b)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	778 local r = foo(a+1)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	779 print("co-body", r)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	780 local r, s = coroutine.yield(a+b, a-b)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	781 print("co-body", r, s)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	782 return b, "end"
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	783 end)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	784
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	785 print("main", coroutine.resume(co, 1, 10))
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	786 print("main", coroutine.resume(co, "r"))
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	787 print("main", coroutine.resume(co, "x", "y"))
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	788 print("main", coroutine.resume(co, "x", "y"))
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	789 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	790 When you run it, it produces the following output:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	791
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	792 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	793 co-body 1 10
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	794 foo 2
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	795 main true 4
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	796 co-body r
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	797 main true 11 -9
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	798 co-body x y
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	799 main true 10 end
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	800 main false cannot resume dead coroutine
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	801 </pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	802
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	803 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	804 You can also create and manipulate coroutines through the C API:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	805 see functions <a href="#lua_newthread"><code>lua_newthread</code></a>, <a href="#lua_resume"><code>lua_resume</code></a>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	806 and <a href="#lua_yield"><code>lua_yield</code></a>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	807
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	808
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	809
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	810
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	811
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	812 <h1>3 – <a name="3">The Language</a></h1>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	813
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	814 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	815 This section describes the lexis, the syntax, and the semantics of Lua.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	816 In other words,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	817 this section describes
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	818 which tokens are valid,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	819 how they can be combined,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	820 and what their combinations mean.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	821
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	822
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	823 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	824 Language constructs will be explained using the usual extended BNF notation,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	825 in which
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	826 {<em>a</em>} means 0 or more <em>a</em>'s, and
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	827 [<em>a</em>] means an optional <em>a</em>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	828 Non-terminals are shown like non-terminal,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	829 keywords are shown like <b>kword</b>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	830 and other terminal symbols are shown like ‘<b>=</b>’.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	831 The complete syntax of Lua can be found in <a href="#9">§9</a>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	832 at the end of this manual.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	833
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	834
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	835
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	836 <h2>3.1 – <a name="3.1">Lexical Conventions</a></h2>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	837
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	838 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	839 Lua is a free-form language.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	840 It ignores spaces (including new lines) and comments
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	841 between lexical elements (tokens),
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	842 except as delimiters between names and keywords.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	843
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	844
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	845 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	846 <em>Names</em>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	847 (also called <em>identifiers</em>)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	848 in Lua can be any string of letters,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	849 digits, and underscores,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	850 not beginning with a digit.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	851 Identifiers are used to name variables, table fields, and labels.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	852
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	853
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	854 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	855 The following <em>keywords</em> are reserved
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	856 and cannot be used as names:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	857
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	858
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	859 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	860 and break do else elseif end
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	861 false for function goto if in
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	862 local nil not or repeat return
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	863 then true until while
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	864 </pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	865
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	866 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	867 Lua is a case-sensitive language:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	868 <code>and</code> is a reserved word, but <code>And</code> and <code>AND</code>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	869 are two different, valid names.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	870 As a convention,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	871 programs should avoid creating
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	872 names that start with an underscore followed by
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	873 one or more uppercase letters (such as <a href="#pdf-_VERSION"><code>_VERSION</code></a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	874
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	875
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	876 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	877 The following strings denote other tokens:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	878
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	879 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	880 + - * / % ^ #
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	881 & ~ \| << >> //
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	882 == ~= <= >= < > =
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	883 ( ) { } [ ] ::
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	884 ; : , . .. ...
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	885 </pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	886
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	887 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	888 <em>Literal strings</em>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	889 can be delimited by matching single or double quotes,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	890 and can contain the following C-like escape sequences:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	891 '<code>\a</code>' (bell),
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	892 '<code>\b</code>' (backspace),
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	893 '<code>\f</code>' (form feed),
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	894 '<code>\n</code>' (newline),
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	895 '<code>\r</code>' (carriage return),
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	896 '<code>\t</code>' (horizontal tab),
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	897 '<code>\v</code>' (vertical tab),
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	898 '<code>\\</code>' (backslash),
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	899 '<code>\"</code>' (quotation mark [double quote]),
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	900 and '<code>\'</code>' (apostrophe [single quote]).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	901 A backslash followed by a real newline
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	902 results in a newline in the string.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	903 The escape sequence '<code>\z</code>' skips the following span
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	904 of white-space characters,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	905 including line breaks;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	906 it is particularly useful to break and indent a long literal string
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	907 into multiple lines without adding the newlines and spaces
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	908 into the string contents.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	909
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	910
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	911 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	912 Strings in Lua can contain any 8-bit value, including embedded zeros,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	913 which can be specified as '<code>\0</code>'.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	914 More generally,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	915 we can specify any byte in a literal string by its numerical value.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	916 This can be done
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	917 with the escape sequence <code>\x<em>XX</em></code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	918 where <em>XX</em> is a sequence of exactly two hexadecimal digits,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	919 or with the escape sequence <code>\<em>ddd</em></code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	920 where <em>ddd</em> is a sequence of up to three decimal digits.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	921 (Note that if a decimal escape sequence is to be followed by a digit,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	922 it must be expressed using exactly three digits.)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	923
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	924
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	925 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	926 The UTF-8 encoding of a Unicode character
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	927 can be inserted in a literal string with
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	928 the escape sequence <code>\u{<em>XXX</em>}</code>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	929 (note the mandatory enclosing brackets),
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	930 where <em>XXX</em> is a sequence of one or more hexadecimal digits
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	931 representing the character code point.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	932
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	933
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	934 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	935 Literal strings can also be defined using a long format
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	936 enclosed by <em>long brackets</em>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	937 We define an <em>opening long bracket of level <em>n</em></em> as an opening
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	938 square bracket followed by <em>n</em> equal signs followed by another
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	939 opening square bracket.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	940 So, an opening long bracket of level 0 is written as <code>[[</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	941 an opening long bracket of level 1 is written as <code>[=[</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	942 and so on.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	943 A <em>closing long bracket</em> is defined similarly;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	944 for instance,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	945 a closing long bracket of level 4 is written as <code>]====]</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	946 A <em>long literal</em> starts with an opening long bracket of any level and
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	947 ends at the first closing long bracket of the same level.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	948 It can contain any text except a closing bracket of the same level.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	949 Literals in this bracketed form can run for several lines,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	950 do not interpret any escape sequences,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	951 and ignore long brackets of any other level.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	952 Any kind of end-of-line sequence
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	953 (carriage return, newline, carriage return followed by newline,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	954 or newline followed by carriage return)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	955 is converted to a simple newline.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	956
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	957
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	958 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	959 Any byte in a literal string not
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	960 explicitly affected by the previous rules represents itself.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	961 However, Lua opens files for parsing in text mode,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	962 and the system file functions may have problems with
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	963 some control characters.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	964 So, it is safer to represent
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	965 non-text data as a quoted literal with
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	966 explicit escape sequences for non-text characters.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	967
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	968
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	969 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	970 For convenience,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	971 when the opening long bracket is immediately followed by a newline,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	972 the newline is not included in the string.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	973 As an example, in a system using ASCII
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	974 (in which '<code>a</code>' is coded as 97,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	975 newline is coded as 10, and '<code>1</code>' is coded as 49),
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	976 the five literal strings below denote the same string:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	977
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	978 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	979 a = 'alo\n123"'
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	980 a = "alo\n123\""
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	981 a = '\97lo\10\04923"'
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	982 a = [[alo
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	983 123"]]
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	984 a = [==[
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	985 alo
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	986 123"]==]
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	987 </pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	988
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	989 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	990 A <em>numerical constant</em> (or <em>numeral</em>)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	991 can be written with an optional fractional part
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	992 and an optional decimal exponent,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	993 marked by a letter '<code>e</code>' or '<code>E</code>'.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	994 Lua also accepts hexadecimal constants,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	995 which start with <code>0x</code> or <code>0X</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	996 Hexadecimal constants also accept an optional fractional part
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	997 plus an optional binary exponent,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	998 marked by a letter '<code>p</code>' or '<code>P</code>'.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	999 A numeric constant with a fractional dot or an exponent
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1000 denotes a float;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1001 otherwise it denotes an integer.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1002 Examples of valid integer constants are
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1003
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1004 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1005 3 345 0xff 0xBEBADA
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1006 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1007 Examples of valid float constants are
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1008
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1009 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1010 3.0 3.1416 314.16e-2 0.31416E1 34e1
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1011 0x0.1E 0xA23p-4 0X1.921FB54442D18P+1
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1012 </pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1013
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1014 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1015 A <em>comment</em> starts with a double hyphen (<code>--</code>)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1016 anywhere outside a string.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1017 If the text immediately after <code>--</code> is not an opening long bracket,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1018 the comment is a <em>short comment</em>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1019 which runs until the end of the line.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1020 Otherwise, it is a <em>long comment</em>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1021 which runs until the corresponding closing long bracket.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1022 Long comments are frequently used to disable code temporarily.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1023
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1024
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1025
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1026
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1027
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1028 <h2>3.2 – <a name="3.2">Variables</a></h2>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1029
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1030 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1031 Variables are places that store values.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1032 There are three kinds of variables in Lua:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1033 global variables, local variables, and table fields.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1034
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1035
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1036 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1037 A single name can denote a global variable or a local variable
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1038 (or a function's formal parameter,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1039 which is a particular kind of local variable):
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1040
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1041 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1042 var ::= Name
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1043 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1044 Name denotes identifiers, as defined in <a href="#3.1">§3.1</a>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1045
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1046
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1047 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1048 Any variable name is assumed to be global unless explicitly declared
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1049 as a local (see <a href="#3.3.7">§3.3.7</a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1050 Local variables are <em>lexically scoped</em>:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1051 local variables can be freely accessed by functions
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1052 defined inside their scope (see <a href="#3.5">§3.5</a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1053
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1054
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1055 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1056 Before the first assignment to a variable, its value is <b>nil</b>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1057
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1058
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1059 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1060 Square brackets are used to index a table:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1061
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1062 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1063 var ::= prefixexp ‘<b>[</b>’ exp ‘<b>]</b>’
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1064 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1065 The meaning of accesses to table fields can be changed via metatables.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1066 An access to an indexed variable <code>t[i]</code> is equivalent to
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1067 a call <code>gettable_event(t,i)</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1068 (See <a href="#2.4">§2.4</a> for a complete description of the
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1069 <code>gettable_event</code> function.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1070 This function is not defined or callable in Lua.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1071 We use it here only for explanatory purposes.)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1072
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1073
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1074 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1075 The syntax <code>var.Name</code> is just syntactic sugar for
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1076 <code>var["Name"]</code>:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1077
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1078 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1079 var ::= prefixexp ‘<b>.</b>’ Name
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1080 </pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1081
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1082 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1083 An access to a global variable <code>x</code>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1084 is equivalent to <code>_ENV.x</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1085 Due to the way that chunks are compiled,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1086 <code>_ENV</code> is never a global name (see <a href="#2.2">§2.2</a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1087
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1088
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1089
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1090
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1091
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1092 <h2>3.3 – <a name="3.3">Statements</a></h2>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1093
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1094 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1095 Lua supports an almost conventional set of statements,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1096 similar to those in Pascal or C.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1097 This set includes
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1098 assignments, control structures, function calls,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1099 and variable declarations.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1100
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1101
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1102
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1103 <h3>3.3.1 – <a name="3.3.1">Blocks</a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1104
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1105 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1106 A block is a list of statements,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1107 which are executed sequentially:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1108
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1109 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1110 block ::= {stat}
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1111 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1112 Lua has <em>empty statements</em>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1113 that allow you to separate statements with semicolons,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1114 start a block with a semicolon
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1115 or write two semicolons in sequence:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1116
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1117 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1118 stat ::= ‘<b>;</b>’
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1119 </pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1120
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1121 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1122 Function calls and assignments
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1123 can start with an open parenthesis.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1124 This possibility leads to an ambiguity in Lua's grammar.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1125 Consider the following fragment:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1126
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1127 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1128 a = b + c
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1129 (print or io.write)('done')
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1130 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1131 The grammar could see it in two ways:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1132
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1133 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1134 a = b + c(print or io.write)('done')
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1135
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1136 a = b + c; (print or io.write)('done')
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1137 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1138 The current parser always sees such constructions
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1139 in the first way,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1140 interpreting the open parenthesis
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1141 as the start of the arguments to a call.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1142 To avoid this ambiguity,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1143 it is a good practice to always precede with a semicolon
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1144 statements that start with a parenthesis:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1145
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1146 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1147 ;(print or io.write)('done')
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1148 </pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1149
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1150 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1151 A block can be explicitly delimited to produce a single statement:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1152
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1153 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1154 stat ::= <b>do</b> block <b>end</b>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1155 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1156 Explicit blocks are useful
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1157 to control the scope of variable declarations.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1158 Explicit blocks are also sometimes used to
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1159 add a <b>return</b> statement in the middle
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1160 of another block (see <a href="#3.3.4">§3.3.4</a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1161
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1162
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1163
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1164
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1165
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1166 <h3>3.3.2 – <a name="3.3.2">Chunks</a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1167
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1168 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1169 The unit of compilation of Lua is called a <em>chunk</em>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1170 Syntactically,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1171 a chunk is simply a block:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1172
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1173 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1174 chunk ::= block
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1175 </pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1176
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1177 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1178 Lua handles a chunk as the body of an anonymous function
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1179 with a variable number of arguments
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1180 (see <a href="#3.4.11">§3.4.11</a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1181 As such, chunks can define local variables,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1182 receive arguments, and return values.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1183 Moreover, such anonymous function is compiled as in the
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1184 scope of an external local variable called <code>_ENV</code> (see <a href="#2.2">§2.2</a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1185 The resulting function always has <code>_ENV</code> as its only upvalue,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1186 even if it does not use that variable.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1187
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1188
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1189 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1190 A chunk can be stored in a file or in a string inside the host program.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1191 To execute a chunk,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1192 Lua first <em>loads</em> it,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1193 precompiling the chunk's code into instructions for a virtual machine,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1194 and then Lua executes the compiled code
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1195 with an interpreter for the virtual machine.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1196
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1197
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1198 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1199 Chunks can also be precompiled into binary form;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1200 see program <code>luac</code> and function <a href="#pdf-string.dump"><code>string.dump</code></a> for details.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1201 Programs in source and compiled forms are interchangeable;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1202 Lua automatically detects the file type and acts accordingly (see <a href="#pdf-load"><code>load</code></a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1203
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1204
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1205
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1206
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1207
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1208 <h3>3.3.3 – <a name="3.3.3">Assignment</a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1209
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1210 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1211 Lua allows multiple assignments.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1212 Therefore, the syntax for assignment
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1213 defines a list of variables on the left side
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1214 and a list of expressions on the right side.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1215 The elements in both lists are separated by commas:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1216
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1217 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1218 stat ::= varlist ‘<b>=</b>’ explist
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1219 varlist ::= var {‘<b>,</b>’ var}
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1220 explist ::= exp {‘<b>,</b>’ exp}
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1221 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1222 Expressions are discussed in <a href="#3.4">§3.4</a>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1223
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1224
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1225 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1226 Before the assignment,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1227 the list of values is <em>adjusted</em> to the length of
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1228 the list of variables.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1229 If there are more values than needed,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1230 the excess values are thrown away.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1231 If there are fewer values than needed,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1232 the list is extended with as many <b>nil</b>'s as needed.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1233 If the list of expressions ends with a function call,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1234 then all values returned by that call enter the list of values,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1235 before the adjustment
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1236 (except when the call is enclosed in parentheses; see <a href="#3.4">§3.4</a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1237
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1238
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1239 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1240 The assignment statement first evaluates all its expressions
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1241 and only then the assignments are performed.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1242 Thus the code
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1243
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1244 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1245 i = 3
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1246 i, a[i] = i+1, 20
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1247 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1248 sets <code>a[3]</code> to 20, without affecting <code>a[4]</code>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1249 because the <code>i</code> in <code>a[i]</code> is evaluated (to 3)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1250 before it is assigned 4.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1251 Similarly, the line
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1252
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1253 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1254 x, y = y, x
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1255 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1256 exchanges the values of <code>x</code> and <code>y</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1257 and
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1258
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1259 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1260 x, y, z = y, z, x
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1261 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1262 cyclically permutes the values of <code>x</code>, <code>y</code>, and <code>z</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1263
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1264
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1265 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1266 The meaning of assignments to global variables
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1267 and table fields can be changed via metatables.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1268 An assignment to an indexed variable <code>t[i] = val</code> is equivalent to
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1269 <code>settable_event(t,i,val)</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1270 (See <a href="#2.4">§2.4</a> for a complete description of the
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1271 <code>settable_event</code> function.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1272 This function is not defined or callable in Lua.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1273 We use it here only for explanatory purposes.)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1274
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1275
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1276 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1277 An assignment to a global name <code>x = val</code>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1278 is equivalent to the assignment
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1279 <code>_ENV.x = val</code> (see <a href="#2.2">§2.2</a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1280
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1281
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1282
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1283
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1284
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1285 <h3>3.3.4 – <a name="3.3.4">Control Structures</a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1286 The control structures
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1287 <b>if</b>, <b>while</b>, and <b>repeat</b> have the usual meaning and
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1288 familiar syntax:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1289
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1290
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1291
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1292
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1293 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1294 stat ::= <b>while</b> exp <b>do</b> block <b>end</b>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1295 stat ::= <b>repeat</b> block <b>until</b> exp
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1296 stat ::= <b>if</b> exp <b>then</b> block {<b>elseif</b> exp <b>then</b> block} [<b>else</b> block] <b>end</b>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1297 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1298 Lua also has a <b>for</b> statement, in two flavors (see <a href="#3.3.5">§3.3.5</a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1299
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1300
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1301 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1302 The condition expression of a
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1303 control structure can return any value.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1304 Both <b>false</b> and <b>nil</b> are considered false.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1305 All values different from <b>nil</b> and <b>false</b> are considered true
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1306 (in particular, the number 0 and the empty string are also true).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1307
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1308
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1309 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1310 In the <b>repeat</b>–<b>until</b> loop,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1311 the inner block does not end at the <b>until</b> keyword,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1312 but only after the condition.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1313 So, the condition can refer to local variables
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1314 declared inside the loop block.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1315
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1316
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1317 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1318 The <b>goto</b> statement transfers the program control to a label.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1319 For syntactical reasons,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1320 labels in Lua are considered statements too:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1321
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1322
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1323
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1324 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1325 stat ::= <b>goto</b> Name
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1326 stat ::= label
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1327 label ::= ‘<b>::</b>’ Name ‘<b>::</b>’
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1328 </pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1329
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1330 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1331 A label is visible in the entire block where it is defined,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1332 except
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1333 inside nested blocks where a label with the same name is defined and
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1334 inside nested functions.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1335 A goto may jump to any visible label as long as it does not
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1336 enter into the scope of a local variable.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1337
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1338
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1339 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1340 Labels and empty statements are called <em>void statements</em>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1341 as they perform no actions.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1342
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1343
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1344 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1345 The <b>break</b> statement terminates the execution of a
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1346 <b>while</b>, <b>repeat</b>, or <b>for</b> loop,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1347 skipping to the next statement after the loop:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1348
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1349
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1350 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1351 stat ::= <b>break</b>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1352 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1353 A <b>break</b> ends the innermost enclosing loop.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1354
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1355
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1356 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1357 The <b>return</b> statement is used to return values
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1358 from a function or a chunk
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1359 (which is an anonymous function).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1360
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1361 Functions can return more than one value,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1362 so the syntax for the <b>return</b> statement is
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1363
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1364 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1365 stat ::= <b>return</b> [explist] [‘<b>;</b>’]
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1366 </pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1367
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1368 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1369 The <b>return</b> statement can only be written
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1370 as the last statement of a block.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1371 If it is really necessary to <b>return</b> in the middle of a block,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1372 then an explicit inner block can be used,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1373 as in the idiom <code>do return end</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1374 because now <b>return</b> is the last statement in its (inner) block.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1375
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1376
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1377
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1378
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1379
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1380 <h3>3.3.5 – <a name="3.3.5">For Statement</a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1381
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1382 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1383
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1384 The <b>for</b> statement has two forms:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1385 one numeric and one generic.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1386
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1387
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1388 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1389 The numeric <b>for</b> loop repeats a block of code while a
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1390 control variable runs through an arithmetic progression.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1391 It has the following syntax:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1392
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1393 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1394 stat ::= <b>for</b> Name ‘<b>=</b>’ exp ‘<b>,</b>’ exp [‘<b>,</b>’ exp] <b>do</b> block <b>end</b>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1395 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1396 The <em>block</em> is repeated for <em>name</em> starting at the value of
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1397 the first <em>exp</em>, until it passes the second <em>exp</em> by steps of the
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1398 third <em>exp</em>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1399 More precisely, a <b>for</b> statement like
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1400
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1401 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1402 for v = <em>e1</em>, <em>e2</em>, <em>e3</em> do <em>block</em> end
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1403 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1404 is equivalent to the code:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1405
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1406 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1407 do
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1408 local <em>var</em>, <em>limit</em>, <em>step</em> = tonumber(<em>e1</em>), tonumber(<em>e2</em>), tonumber(<em>e3</em>)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1409 if not (<em>var</em> and <em>limit</em> and <em>step</em>) then error() end
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1410 <em>var</em> = <em>var</em> - <em>step</em>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1411 while true do
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1412 <em>var</em> = <em>var</em> + <em>step</em>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1413 if (<em>step</em> >= 0 and <em>var</em> > <em>limit</em>) or (<em>step</em> < 0 and <em>var</em> < <em>limit</em>) then
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1414 break
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1415 end
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1416 local v = <em>var</em>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1417 <em>block</em>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1418 end
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1419 end
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1420 </pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1421
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1422 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1423 Note the following:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1424
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1425 <ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1426
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1427 <li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1428 All three control expressions are evaluated only once,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1429 before the loop starts.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1430 They must all result in numbers.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1431 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1432
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1433 <li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1434 <code><em>var</em></code>, <code><em>limit</em></code>, and <code><em>step</em></code> are invisible variables.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1435 The names shown here are for explanatory purposes only.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1436 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1437
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1438 <li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1439 If the third expression (the step) is absent,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1440 then a step of 1 is used.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1441 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1442
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1443 <li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1444 You can use <b>break</b> and <b>goto</b> to exit a <b>for</b> loop.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1445 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1446
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1447 <li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1448 The loop variable <code>v</code> is local to the loop body.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1449 If you need its value after the loop,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1450 assign it to another variable before exiting the loop.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1451 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1452
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1453 </ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1454
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1455 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1456 The generic <b>for</b> statement works over functions,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1457 called <em>iterators</em>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1458 On each iteration, the iterator function is called to produce a new value,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1459 stopping when this new value is <b>nil</b>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1460 The generic <b>for</b> loop has the following syntax:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1461
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1462 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1463 stat ::= <b>for</b> namelist <b>in</b> explist <b>do</b> block <b>end</b>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1464 namelist ::= Name {‘<b>,</b>’ Name}
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1465 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1466 A <b>for</b> statement like
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1467
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1468 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1469 for <em>var_1</em>, ···, <em>var_n</em> in <em>explist</em> do <em>block</em> end
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1470 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1471 is equivalent to the code:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1472
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1473 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1474 do
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1475 local <em>f</em>, <em>s</em>, <em>var</em> = <em>explist</em>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1476 while true do
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1477 local <em>var_1</em>, ···, <em>var_n</em> = <em>f</em>(<em>s</em>, <em>var</em>)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1478 if <em>var_1</em> == nil then break end
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1479 <em>var</em> = <em>var_1</em>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1480 <em>block</em>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1481 end
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1482 end
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1483 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1484 Note the following:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1485
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1486 <ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1487
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1488 <li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1489 <code><em>explist</em></code> is evaluated only once.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1490 Its results are an <em>iterator</em> function,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1491 a <em>state</em>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1492 and an initial value for the first <em>iterator variable</em>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1493 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1494
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1495 <li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1496 <code><em>f</em></code>, <code><em>s</em></code>, and <code><em>var</em></code> are invisible variables.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1497 The names are here for explanatory purposes only.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1498 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1499
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1500 <li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1501 You can use <b>break</b> to exit a <b>for</b> loop.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1502 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1503
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1504 <li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1505 The loop variables <code><em>var_i</em></code> are local to the loop;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1506 you cannot use their values after the <b>for</b> ends.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1507 If you need these values,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1508 then assign them to other variables before breaking or exiting the loop.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1509 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1510
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1511 </ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1512
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1513
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1514
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1515
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1516 <h3>3.3.6 – <a name="3.3.6">Function Calls as Statements</a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1517 To allow possible side-effects,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1518 function calls can be executed as statements:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1519
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1520 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1521 stat ::= functioncall
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1522 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1523 In this case, all returned values are thrown away.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1524 Function calls are explained in <a href="#3.4.10">§3.4.10</a>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1525
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1526
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1527
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1528
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1529
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1530 <h3>3.3.7 – <a name="3.3.7">Local Declarations</a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1531 Local variables can be declared anywhere inside a block.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1532 The declaration can include an initial assignment:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1533
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1534 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1535 stat ::= <b>local</b> namelist [‘<b>=</b>’ explist]
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1536 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1537 If present, an initial assignment has the same semantics
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1538 of a multiple assignment (see <a href="#3.3.3">§3.3.3</a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1539 Otherwise, all variables are initialized with <b>nil</b>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1540
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1541
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1542 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1543 A chunk is also a block (see <a href="#3.3.2">§3.3.2</a>),
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1544 and so local variables can be declared in a chunk outside any explicit block.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1545
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1546
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1547 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1548 The visibility rules for local variables are explained in <a href="#3.5">§3.5</a>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1549
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1550
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1551
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1552
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1553
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1554
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1555
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1556 <h2>3.4 – <a name="3.4">Expressions</a></h2>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1557
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1558 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1559 The basic expressions in Lua are the following:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1560
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1561 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1562 exp ::= prefixexp
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1563 exp ::= <b>nil</b> \| <b>false</b> \| <b>true</b>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1564 exp ::= Numeral
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1565 exp ::= LiteralString
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1566 exp ::= functiondef
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1567 exp ::= tableconstructor
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1568 exp ::= ‘<b>...</b>’
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1569 exp ::= exp binop exp
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1570 exp ::= unop exp
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1571 prefixexp ::= var \| functioncall \| ‘<b>(</b>’ exp ‘<b>)</b>’
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1572 </pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1573
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1574 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1575 Numerals and literal strings are explained in <a href="#3.1">§3.1</a>;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1576 variables are explained in <a href="#3.2">§3.2</a>;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1577 function definitions are explained in <a href="#3.4.11">§3.4.11</a>;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1578 function calls are explained in <a href="#3.4.10">§3.4.10</a>;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1579 table constructors are explained in <a href="#3.4.9">§3.4.9</a>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1580 Vararg expressions,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1581 denoted by three dots ('<code>...</code>'), can only be used when
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1582 directly inside a vararg function;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1583 they are explained in <a href="#3.4.11">§3.4.11</a>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1584
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1585
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1586 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1587 Binary operators comprise arithmetic operators (see <a href="#3.4.1">§3.4.1</a>),
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1588 bitwise operators (see <a href="#3.4.2">§3.4.2</a>),
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1589 relational operators (see <a href="#3.4.4">§3.4.4</a>), logical operators (see <a href="#3.4.5">§3.4.5</a>),
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1590 and the concatenation operator (see <a href="#3.4.6">§3.4.6</a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1591 Unary operators comprise the unary minus (see <a href="#3.4.1">§3.4.1</a>),
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1592 the unary bitwise not (see <a href="#3.4.2">§3.4.2</a>),
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1593 the unary logical <b>not</b> (see <a href="#3.4.5">§3.4.5</a>),
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1594 and the unary <em>length operator</em> (see <a href="#3.4.7">§3.4.7</a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1595
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1596
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1597 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1598 Both function calls and vararg expressions can result in multiple values.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1599 If a function call is used as a statement (see <a href="#3.3.6">§3.3.6</a>),
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1600 then its return list is adjusted to zero elements,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1601 thus discarding all returned values.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1602 If an expression is used as the last (or the only) element
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1603 of a list of expressions,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1604 then no adjustment is made
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1605 (unless the expression is enclosed in parentheses).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1606 In all other contexts,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1607 Lua adjusts the result list to one element,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1608 either discarding all values except the first one
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1609 or adding a single <b>nil</b> if there are no values.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1610
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1611
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1612 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1613 Here are some examples:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1614
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1615 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1616 f() -- adjusted to 0 results
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1617 g(f(), x) -- f() is adjusted to 1 result
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1618 g(x, f()) -- g gets x plus all results from f()
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1619 a,b,c = f(), x -- f() is adjusted to 1 result (c gets nil)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1620 a,b = ... -- a gets the first vararg parameter, b gets
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1621 -- the second (both a and b can get nil if there
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1622 -- is no corresponding vararg parameter)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1623
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1624 a,b,c = x, f() -- f() is adjusted to 2 results
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1625 a,b,c = f() -- f() is adjusted to 3 results
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1626 return f() -- returns all results from f()
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1627 return ... -- returns all received vararg parameters
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1628 return x,y,f() -- returns x, y, and all results from f()
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1629 {f()} -- creates a list with all results from f()
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1630 {...} -- creates a list with all vararg parameters
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1631 {f(), nil} -- f() is adjusted to 1 result
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1632 </pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1633
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1634 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1635 Any expression enclosed in parentheses always results in only one value.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1636 Thus,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1637 <code>(f(x,y,z))</code> is always a single value,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1638 even if <code>f</code> returns several values.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1639 (The value of <code>(f(x,y,z))</code> is the first value returned by <code>f</code>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1640 or <b>nil</b> if <code>f</code> does not return any values.)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1641
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1642
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1643
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1644 <h3>3.4.1 – <a name="3.4.1">Arithmetic Operators</a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1645 Lua supports the following arithmetic operators:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1646
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1647 <ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1648 <li><b><code>+</code>: </b>addition</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1649 <li><b><code>-</code>: </b>subtraction</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1650 <li><b><code>*</code>: </b>multiplication</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1651 <li><b><code>/</code>: </b>float division</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1652 <li><b><code>//</code>: </b>floor division</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1653 <li><b><code>%</code>: </b>modulo</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1654 <li><b><code>^</code>: </b>exponentiation</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1655 <li><b><code>-</code>: </b>unary minus</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1656 </ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1657
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1658 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1659 With the exception of exponentiation and float division,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1660 the arithmetic operators work as follows:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1661 If both operands are integers,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1662 the operation is performed over integers and the result is an integer.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1663 Otherwise, if both operands are numbers
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1664 or strings that can be converted to
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1665 numbers (see <a href="#3.4.3">§3.4.3</a>),
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1666 then they are converted to floats,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1667 the operation is performed following the usual rules
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1668 for floating-point arithmetic
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1669 (usually the IEEE 754 standard),
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1670 and the result is a float.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1671
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1672
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1673 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1674 Exponentiation and float division (<code>/</code>)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1675 always convert their operands to floats
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1676 and the result is always a float.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1677 Exponentiation uses the ISO C function <code>pow</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1678 so that it works for non-integer exponents too.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1679
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1680
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1681 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1682 Floor division (<code>//</code>) is a division
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1683 that rounds the quotient towards minus infinite,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1684 that is, the floor of the division of its operands.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1685
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1686
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1687 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1688 Modulo is defined as the remainder of a division
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1689 that rounds the quotient towards minus infinite (floor division).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1690
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1691
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1692 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1693 In case of overflows in integer arithmetic,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1694 all operations <em>wrap around</em>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1695 according to the usual rules of two-complement arithmetic.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1696 (In other words,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1697 they return the unique representable integer
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1698 that is equal modulo <em>2<sup>64</sup></em> to the mathematical result.)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1699
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1700
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1701
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1702 <h3>3.4.2 – <a name="3.4.2">Bitwise Operators</a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1703 Lua supports the following bitwise operators:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1704
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1705 <ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1706 <li><b><code>&</code>: </b>bitwise and</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1707 <li><b><code>\|</code>: </b>bitwise or</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1708 <li><b><code>~</code>: </b>bitwise exclusive or</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1709 <li><b><code>>></code>: </b>right shift</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1710 <li><b><code><<</code>: </b>left shift</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1711 <li><b><code>~</code>: </b>unary bitwise not</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1712 </ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1713
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1714 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1715 All bitwise operations convert its operands to integers
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1716 (see <a href="#3.4.3">§3.4.3</a>),
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1717 operate on all bits of those integers,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1718 and result in an integer.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1719
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1720
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1721 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1722 Both right and left shifts fill the vacant bits with zeros.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1723 Negative displacements shift to the other direction;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1724 displacements with absolute values equal to or higher than
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1725 the number of bits in an integer
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1726 result in zero (as all bits are shifted out).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1727
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1728
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1729
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1730
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1731
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1732 <h3>3.4.3 – <a name="3.4.3">Coercions and Conversions</a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1733 Lua provides some automatic conversions between some
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1734 types and representations at run time.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1735 Bitwise operators always convert float operands to integers.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1736 Exponentiation and float division
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1737 always convert integer operands to floats.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1738 All other arithmetic operations applied to mixed numbers
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1739 (integers and floats) convert the integer operand to a float;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1740 this is called the <em>usual rule</em>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1741 The C API also converts both integers to floats and
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1742 floats to integers, as needed.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1743 Moreover, string concatenation accepts numbers as arguments,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1744 besides strings.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1745
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1746
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1747 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1748 Lua also converts strings to numbers,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1749 whenever a number is expected.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1750
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1751
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1752 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1753 In a conversion from integer to float,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1754 if the integer value has an exact representation as a float,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1755 that is the result.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1756 Otherwise,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1757 the conversion gets the nearest higher or
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1758 the nearest lower representable value.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1759 This kind of conversion never fails.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1760
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1761
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1762 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1763 The conversion from float to integer
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1764 checks whether the float has an exact representation as an integer
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1765 (that is, the float has an integral value and
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1766 it is in the range of integer representation).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1767 If it does, that representation is the result.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1768 Otherwise, the conversion fails.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1769
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1770
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1771 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1772 The conversion from strings to numbers goes as follows:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1773 First, the string is converted to an integer or a float,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1774 following its syntax and the rules of the Lua lexer.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1775 (The string may have also leading and trailing spaces and a sign.)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1776 Then, the resulting number is converted to the required type
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1777 (float or integer) according to the previous rules.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1778
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1779
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1780 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1781 The conversion from numbers to strings uses a
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1782 non-specified human-readable format.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1783 For complete control over how numbers are converted to strings,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1784 use the <code>format</code> function from the string library
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1785 (see <a href="#pdf-string.format"><code>string.format</code></a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1786
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1787
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1788
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1789
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1790
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1791 <h3>3.4.4 – <a name="3.4.4">Relational Operators</a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1792 Lua supports the following relational operators:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1793
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1794 <ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1795 <li><b><code>==</code>: </b>equality</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1796 <li><b><code>~=</code>: </b>inequality</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1797 <li><b><code><</code>: </b>less than</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1798 <li><b><code>></code>: </b>greater than</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1799 <li><b><code><=</code>: </b>less or equal</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1800 <li><b><code>>=</code>: </b>greater or equal</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1801 </ul><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1802 These operators always result in <b>false</b> or <b>true</b>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1803
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1804
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1805 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1806 Equality (<code>==</code>) first compares the type of its operands.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1807 If the types are different, then the result is <b>false</b>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1808 Otherwise, the values of the operands are compared.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1809 Strings are compared in the obvious way.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1810 Numbers follow the usual rule for binary operations:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1811 if both operands are integers,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1812 they are compared as integers;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1813 otherwise, they are converted to floats
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1814 and compared as such.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1815
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1816
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1817 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1818 Tables, userdata, and threads
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1819 are compared by reference:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1820 two objects are considered equal only if they are the same object.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1821 Every time you create a new object
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1822 (a table, userdata, or thread),
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1823 this new object is different from any previously existing object.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1824 Closures with the same reference are always equal.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1825 Closures with any detectable difference
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1826 (different behavior, different definition) are always different.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1827
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1828
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1829 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1830 You can change the way that Lua compares tables and userdata
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1831 by using the "eq" metamethod (see <a href="#2.4">§2.4</a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1832
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1833
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1834 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1835 Equality comparisons do not convert strings to numbers
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1836 or vice versa.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1837 Thus, <code>"0"==0</code> evaluates to <b>false</b>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1838 and <code>t[0]</code> and <code>t["0"]</code> denote different
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1839 entries in a table.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1840
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1841
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1842 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1843 The operator <code>~=</code> is exactly the negation of equality (<code>==</code>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1844
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1845
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1846 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1847 The order operators work as follows.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1848 If both arguments are numbers,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1849 then they are compared following
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1850 the usual rule for binary operations.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1851 Otherwise, if both arguments are strings,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1852 then their values are compared according to the current locale.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1853 Otherwise, Lua tries to call the "lt" or the "le"
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1854 metamethod (see <a href="#2.4">§2.4</a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1855 A comparison <code>a > b</code> is translated to <code>b < a</code>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1856 and <code>a >= b</code> is translated to <code>b <= a</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1857
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1858
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1859
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1860
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1861
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1862 <h3>3.4.5 – <a name="3.4.5">Logical Operators</a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1863 The logical operators in Lua are
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1864 <b>and</b>, <b>or</b>, and <b>not</b>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1865 Like the control structures (see <a href="#3.3.4">§3.3.4</a>),
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1866 all logical operators consider both <b>false</b> and <b>nil</b> as false
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1867 and anything else as true.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1868
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1869
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1870 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1871 The negation operator <b>not</b> always returns <b>false</b> or <b>true</b>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1872 The conjunction operator <b>and</b> returns its first argument
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1873 if this value is <b>false</b> or <b>nil</b>;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1874 otherwise, <b>and</b> returns its second argument.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1875 The disjunction operator <b>or</b> returns its first argument
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1876 if this value is different from <b>nil</b> and <b>false</b>;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1877 otherwise, <b>or</b> returns its second argument.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1878 Both <b>and</b> and <b>or</b> use short-circuit evaluation;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1879 that is,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1880 the second operand is evaluated only if necessary.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1881 Here are some examples:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1882
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1883 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1884 10 or 20 --> 10
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1885 10 or error() --> 10
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1886 nil or "a" --> "a"
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1887 nil and 10 --> nil
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1888 false and error() --> false
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1889 false and nil --> false
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1890 false or nil --> nil
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1891 10 and 20 --> 20
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1892 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1893 (In this manual,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1894 <code>--></code> indicates the result of the preceding expression.)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1895
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1896
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1897
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1898
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1899
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1900 <h3>3.4.6 – <a name="3.4.6">Concatenation</a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1901 The string concatenation operator in Lua is
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1902 denoted by two dots ('<code>..</code>').
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1903 If both operands are strings or numbers, then they are converted to
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1904 strings according to the rules described in <a href="#3.4.3">§3.4.3</a>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1905 Otherwise, the <code>__concat</code> metamethod is called (see <a href="#2.4">§2.4</a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1906
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1907
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1908
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1909
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1910
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1911 <h3>3.4.7 – <a name="3.4.7">The Length Operator</a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1912
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1913 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1914 The length operator is denoted by the unary prefix operator <code>#</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1915 The length of a string is its number of bytes
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1916 (that is, the usual meaning of string length when each
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1917 character is one byte).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1918
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1919
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1920 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1921 A program can modify the behavior of the length operator for
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1922 any value but strings through the <code>__len</code> metamethod (see <a href="#2.4">§2.4</a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1923
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1924
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1925 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1926 Unless a <code>__len</code> metamethod is given,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1927 the length of a table <code>t</code> is only defined if the
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1928 table is a <em>sequence</em>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1929 that is,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1930 the set of its positive numeric keys is equal to <em>{1..n}</em>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1931 for some non-negative integer <em>n</em>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1932 In that case, <em>n</em> is its length.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1933 Note that a table like
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1934
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1935 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1936 {10, 20, nil, 40}
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1937 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1938 is not a sequence, because it has the key <code>4</code>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1939 but does not have the key <code>3</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1940 (So, there is no <em>n</em> such that the set <em>{1..n}</em> is equal
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1941 to the set of positive numeric keys of that table.)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1942 Note, however, that non-numeric keys do not interfere
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1943 with whether a table is a sequence.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1944
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1945
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1946
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1947
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1948
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1949 <h3>3.4.8 – <a name="3.4.8">Precedence</a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1950 Operator precedence in Lua follows the table below,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1951 from lower to higher priority:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1952
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1953 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1954 or
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1955 and
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1956 < > <= >= ~= ==
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1957 \|
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1958 ~
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1959 &
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1960 << >>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1961 ..
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1962 + -
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1963 * / // %
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1964 unary operators (not # - ~)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1965 ^
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1966 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1967 As usual,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1968 you can use parentheses to change the precedences of an expression.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1969 The concatenation ('<code>..</code>') and exponentiation ('<code>^</code>')
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1970 operators are right associative.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1971 All other binary operators are left associative.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1972
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1973
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1974
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1975
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1976
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1977 <h3>3.4.9 – <a name="3.4.9">Table Constructors</a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1978 Table constructors are expressions that create tables.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1979 Every time a constructor is evaluated, a new table is created.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1980 A constructor can be used to create an empty table
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1981 or to create a table and initialize some of its fields.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1982 The general syntax for constructors is
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1983
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1984 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1985 tableconstructor ::= ‘<b>{</b>’ [fieldlist] ‘<b>}</b>’
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1986 fieldlist ::= field {fieldsep field} [fieldsep]
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1987 field ::= ‘<b>[</b>’ exp ‘<b>]</b>’ ‘<b>=</b>’ exp \| Name ‘<b>=</b>’ exp \| exp
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1988 fieldsep ::= ‘<b>,</b>’ \| ‘<b>;</b>’
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1989 </pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1990
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1991 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1992 Each field of the form <code>[exp1] = exp2</code> adds to the new table an entry
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1993 with key <code>exp1</code> and value <code>exp2</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1994 A field of the form <code>name = exp</code> is equivalent to
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1995 <code>["name"] = exp</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1996 Finally, fields of the form <code>exp</code> are equivalent to
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1997 <code>[i] = exp</code>, where <code>i</code> are consecutive integers
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1998 starting with 1.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1999 Fields in the other formats do not affect this counting.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2000 For example,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2001
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2002 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2003 a = { [f(1)] = g; "x", "y"; x = 1, f(x), [30] = 23; 45 }
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2004 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2005 is equivalent to
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2006
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2007 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2008 do
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2009 local t = {}
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2010 t[f(1)] = g
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2011 t[1] = "x" -- 1st exp
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2012 t[2] = "y" -- 2nd exp
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2013 t.x = 1 -- t["x"] = 1
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2014 t[3] = f(x) -- 3rd exp
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2015 t[30] = 23
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2016 t[4] = 45 -- 4th exp
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2017 a = t
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2018 end
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2019 </pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2020
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2021 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2022 The order of the assignments in a constructor is undefined.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2023 (This order would be relevant only when there are repeated keys.)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2024
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2025
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2026 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2027 If the last field in the list has the form <code>exp</code>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2028 and the expression is a function call or a vararg expression,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2029 then all values returned by this expression enter the list consecutively
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2030 (see <a href="#3.4.10">§3.4.10</a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2031
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2032
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2033 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2034 The field list can have an optional trailing separator,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2035 as a convenience for machine-generated code.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2036
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2037
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2038
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2039
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2040
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2041 <h3>3.4.10 – <a name="3.4.10">Function Calls</a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2042 A function call in Lua has the following syntax:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2043
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2044 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2045 functioncall ::= prefixexp args
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2046 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2047 In a function call,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2048 first prefixexp and args are evaluated.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2049 If the value of prefixexp has type <em>function</em>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2050 then this function is called
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2051 with the given arguments.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2052 Otherwise, the prefixexp "call" metamethod is called,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2053 having as first parameter the value of prefixexp,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2054 followed by the original call arguments
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2055 (see <a href="#2.4">§2.4</a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2056
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2057
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2058 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2059 The form
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2060
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2061 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2062 functioncall ::= prefixexp ‘<b>:</b>’ Name args
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2063 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2064 can be used to call "methods".
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2065 A call <code>v:name(<em>args</em>)</code>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2066 is syntactic sugar for <code>v.name(v,<em>args</em>)</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2067 except that <code>v</code> is evaluated only once.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2068
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2069
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2070 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2071 Arguments have the following syntax:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2072
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2073 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2074 args ::= ‘<b>(</b>’ [explist] ‘<b>)</b>’
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2075 args ::= tableconstructor
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2076 args ::= LiteralString
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2077 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2078 All argument expressions are evaluated before the call.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2079 A call of the form <code>f{<em>fields</em>}</code> is
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2080 syntactic sugar for <code>f({<em>fields</em>})</code>;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2081 that is, the argument list is a single new table.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2082 A call of the form <code>f'<em>string</em>'</code>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2083 (or <code>f"<em>string</em>"</code> or <code>f[[<em>string</em>]]</code>)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2084 is syntactic sugar for <code>f('<em>string</em>')</code>;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2085 that is, the argument list is a single literal string.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2086
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2087
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2088 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2089 A call of the form <code>return <em>functioncall</em></code> is called
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2090 a <em>tail call</em>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2091 Lua implements <em>proper tail calls</em>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2092 (or <em>proper tail recursion</em>):
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2093 in a tail call,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2094 the called function reuses the stack entry of the calling function.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2095 Therefore, there is no limit on the number of nested tail calls that
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2096 a program can execute.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2097 However, a tail call erases any debug information about the
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2098 calling function.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2099 Note that a tail call only happens with a particular syntax,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2100 where the <b>return</b> has one single function call as argument;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2101 this syntax makes the calling function return exactly
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2102 the returns of the called function.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2103 So, none of the following examples are tail calls:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2104
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2105 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2106 return (f(x)) -- results adjusted to 1
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2107 return 2 * f(x)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2108 return x, f(x) -- additional results
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2109 f(x); return -- results discarded
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2110 return x or f(x) -- results adjusted to 1
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2111 </pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2112
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2113
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2114
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2115
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2116 <h3>3.4.11 – <a name="3.4.11">Function Definitions</a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2117
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2118 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2119 The syntax for function definition is
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2120
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2121 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2122 functiondef ::= <b>function</b> funcbody
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2123 funcbody ::= ‘<b>(</b>’ [parlist] ‘<b>)</b>’ block <b>end</b>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2124 </pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2125
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2126 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2127 The following syntactic sugar simplifies function definitions:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2128
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2129 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2130 stat ::= <b>function</b> funcname funcbody
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2131 stat ::= <b>local</b> <b>function</b> Name funcbody
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2132 funcname ::= Name {‘<b>.</b>’ Name} [‘<b>:</b>’ Name]
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2133 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2134 The statement
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2135
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2136 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2137 function f () <em>body</em> end
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2138 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2139 translates to
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2140
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2141 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2142 f = function () <em>body</em> end
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2143 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2144 The statement
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2145
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2146 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2147 function t.a.b.c.f () <em>body</em> end
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2148 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2149 translates to
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2150
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2151 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2152 t.a.b.c.f = function () <em>body</em> end
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2153 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2154 The statement
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2155
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2156 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2157 local function f () <em>body</em> end
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2158 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2159 translates to
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2160
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2161 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2162 local f; f = function () <em>body</em> end
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2163 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2164 not to
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2165
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2166 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2167 local f = function () <em>body</em> end
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2168 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2169 (This only makes a difference when the body of the function
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2170 contains references to <code>f</code>.)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2171
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2172
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2173 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2174 A function definition is an executable expression,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2175 whose value has type <em>function</em>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2176 When Lua precompiles a chunk,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2177 all its function bodies are precompiled too.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2178 Then, whenever Lua executes the function definition,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2179 the function is <em>instantiated</em> (or <em>closed</em>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2180 This function instance (or <em>closure</em>)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2181 is the final value of the expression.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2182
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2183
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2184 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2185 Parameters act as local variables that are
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2186 initialized with the argument values:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2187
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2188 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2189 parlist ::= namelist [‘<b>,</b>’ ‘<b>...</b>’] \| ‘<b>...</b>’
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2190 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2191 When a function is called,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2192 the list of arguments is adjusted to
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2193 the length of the list of parameters,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2194 unless the function is a <em>vararg function</em>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2195 which is indicated by three dots ('<code>...</code>')
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2196 at the end of its parameter list.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2197 A vararg function does not adjust its argument list;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2198 instead, it collects all extra arguments and supplies them
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2199 to the function through a <em>vararg expression</em>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2200 which is also written as three dots.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2201 The value of this expression is a list of all actual extra arguments,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2202 similar to a function with multiple results.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2203 If a vararg expression is used inside another expression
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2204 or in the middle of a list of expressions,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2205 then its return list is adjusted to one element.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2206 If the expression is used as the last element of a list of expressions,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2207 then no adjustment is made
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2208 (unless that last expression is enclosed in parentheses).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2209
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2210
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2211 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2212 As an example, consider the following definitions:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2213
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2214 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2215 function f(a, b) end
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2216 function g(a, b, ...) end
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2217 function r() return 1,2,3 end
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2218 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2219 Then, we have the following mapping from arguments to parameters and
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2220 to the vararg expression:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2221
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2222 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2223 CALL PARAMETERS
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2224
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2225 f(3) a=3, b=nil
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2226 f(3, 4) a=3, b=4
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2227 f(3, 4, 5) a=3, b=4
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2228 f(r(), 10) a=1, b=10
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2229 f(r()) a=1, b=2
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2230
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2231 g(3) a=3, b=nil, ... --> (nothing)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2232 g(3, 4) a=3, b=4, ... --> (nothing)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2233 g(3, 4, 5, 8) a=3, b=4, ... --> 5 8
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2234 g(5, r()) a=5, b=1, ... --> 2 3
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2235 </pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2236
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2237 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2238 Results are returned using the <b>return</b> statement (see <a href="#3.3.4">§3.3.4</a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2239 If control reaches the end of a function
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2240 without encountering a <b>return</b> statement,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2241 then the function returns with no results.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2242
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2243
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2244 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2245
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2246 There is a system-dependent limit on the number of values
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2247 that a function may return.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2248 This limit is guaranteed to be larger than 1000.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2249
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2250
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2251 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2252 The <em>colon</em> syntax
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2253 is used for defining <em>methods</em>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2254 that is, functions that have an implicit extra parameter <code>self</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2255 Thus, the statement
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2256
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2257 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2258 function t.a.b.c:f (<em>params</em>) <em>body</em> end
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2259 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2260 is syntactic sugar for
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2261
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2262 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2263 t.a.b.c.f = function (self, <em>params</em>) <em>body</em> end
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2264 </pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2265
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2266
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2267
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2268
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2269
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2270
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2271 <h2>3.5 – <a name="3.5">Visibility Rules</a></h2>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2272
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2273 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2274
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2275 Lua is a lexically scoped language.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2276 The scope of a local variable begins at the first statement after
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2277 its declaration and lasts until the last non-void statement
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2278 of the innermost block that includes the declaration.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2279 Consider the following example:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2280
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2281 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2282 x = 10 -- global variable
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2283 do -- new block
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2284 local x = x -- new 'x', with value 10
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2285 print(x) --> 10
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2286 x = x+1
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2287 do -- another block
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2288 local x = x+1 -- another 'x'
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2289 print(x) --> 12
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2290 end
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2291 print(x) --> 11
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2292 end
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2293 print(x) --> 10 (the global one)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2294 </pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2295
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2296 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2297 Notice that, in a declaration like <code>local x = x</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2298 the new <code>x</code> being declared is not in scope yet,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2299 and so the second <code>x</code> refers to the outside variable.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2300
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2301
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2302 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2303 Because of the lexical scoping rules,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2304 local variables can be freely accessed by functions
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2305 defined inside their scope.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2306 A local variable used by an inner function is called
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2307 an <em>upvalue</em>, or <em>external local variable</em>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2308 inside the inner function.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2309
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2310
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2311 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2312 Notice that each execution of a <b>local</b> statement
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2313 defines new local variables.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2314 Consider the following example:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2315
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2316 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2317 a = {}
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2318 local x = 20
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2319 for i=1,10 do
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2320 local y = 0
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2321 a[i] = function () y=y+1; return x+y end
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2322 end
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2323 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2324 The loop creates ten closures
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2325 (that is, ten instances of the anonymous function).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2326 Each of these closures uses a different <code>y</code> variable,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2327 while all of them share the same <code>x</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2328
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2329
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2330
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2331
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2332
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2333 <h1>4 – <a name="4">The Application Program Interface</a></h1>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2334
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2335 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2336
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2337 This section describes the C API for Lua, that is,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2338 the set of C functions available to the host program to communicate
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2339 with Lua.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2340 All API functions and related types and constants
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2341 are declared in the header file <a name="pdf-lua.h"><code>lua.h</code></a>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2342
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2343
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2344 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2345 Even when we use the term "function",
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2346 any facility in the API may be provided as a macro instead.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2347 Except where stated otherwise,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2348 all such macros use each of their arguments exactly once
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2349 (except for the first argument, which is always a Lua state),
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2350 and so do not generate any hidden side-effects.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2351
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2352
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2353 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2354 As in most C libraries,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2355 the Lua API functions do not check their arguments for validity or consistency.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2356 However, you can change this behavior by compiling Lua
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2357 with the macro <a name="pdf-LUA_USE_APICHECK"><code>LUA_USE_APICHECK</code></a> defined.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2358
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2359
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2360
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2361 <h2>4.1 – <a name="4.1">The Stack</a></h2>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2362
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2363 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2364 Lua uses a <em>virtual stack</em> to pass values to and from C.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2365 Each element in this stack represents a Lua value
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2366 (<b>nil</b>, number, string, etc.).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2367
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2368
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2369 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2370 Whenever Lua calls C, the called function gets a new stack,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2371 which is independent of previous stacks and of stacks of
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2372 C functions that are still active.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2373 This stack initially contains any arguments to the C function
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2374 and it is where the C function pushes its results
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2375 to be returned to the caller (see <a href="#lua_CFunction"><code>lua_CFunction</code></a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2376
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2377
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2378 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2379 For convenience,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2380 most query operations in the API do not follow a strict stack discipline.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2381 Instead, they can refer to any element in the stack
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2382 by using an <em>index</em>:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2383 A positive index represents an absolute stack position
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2384 (starting at 1);
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2385 a negative index represents an offset relative to the top of the stack.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2386 More specifically, if the stack has <em>n</em> elements,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2387 then index 1 represents the first element
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2388 (that is, the element that was pushed onto the stack first)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2389 and
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2390 index <em>n</em> represents the last element;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2391 index -1 also represents the last element
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2392 (that is, the element at the top)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2393 and index <em>-n</em> represents the first element.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2394
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2395
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2396
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2397
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2398
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2399 <h2>4.2 – <a name="4.2">Stack Size</a></h2>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2400
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2401 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2402 When you interact with the Lua API,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2403 you are responsible for ensuring consistency.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2404 In particular,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2405 <em>you are responsible for controlling stack overflow</em>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2406 You can use the function <a href="#lua_checkstack"><code>lua_checkstack</code></a>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2407 to ensure that the stack has enough space for pushing new elements.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2408
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2409
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2410 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2411 Whenever Lua calls C,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2412 it ensures that the stack has space for
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2413 at least <a name="pdf-LUA_MINSTACK"><code>LUA_MINSTACK</code></a> extra slots.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2414 <code>LUA_MINSTACK</code> is defined as 20,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2415 so that usually you do not have to worry about stack space
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2416 unless your code has loops pushing elements onto the stack.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2417
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2418
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2419 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2420 When you call a Lua function
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2421 without a fixed number of results (see <a href="#lua_call"><code>lua_call</code></a>),
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2422 Lua ensures that the stack has enough space for all results,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2423 but it does not ensure any extra space.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2424 So, before pushing anything in the stack after such a call
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2425 you should use <a href="#lua_checkstack"><code>lua_checkstack</code></a>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2426
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2427
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2428
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2429
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2430
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2431 <h2>4.3 – <a name="4.3">Valid and Acceptable Indices</a></h2>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2432
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2433 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2434 Any function in the API that receives stack indices
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2435 works only with <em>valid indices</em> or <em>acceptable indices</em>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2436
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2437
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2438 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2439 A <em>valid index</em> is an index that refers to a
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2440 real position within the stack, that is,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2441 its position lies between 1 and the stack top
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2442 (<code>1 ≤ abs(index) ≤ top</code>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2443
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2444 Usually, functions that can modify the value at an index
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2445 require valid indices.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2446
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2447
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2448 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2449 Unless otherwise noted,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2450 any function that accepts valid indices also accepts <em>pseudo-indices</em>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2451 which represent some Lua values that are accessible to C code
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2452 but which are not in the stack.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2453 Pseudo-indices are used to access the registry
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2454 and the upvalues of a C function (see <a href="#4.4">§4.4</a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2455
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2456
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2457 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2458 Functions that do not need a specific stack position,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2459 but only a value in the stack (e.g., query functions),
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2460 can be called with acceptable indices.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2461 An <em>acceptable index</em> can be any valid index,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2462 including the pseudo-indices,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2463 but it also can be any positive index after the stack top
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2464 within the space allocated for the stack,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2465 that is, indices up to the stack size.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2466 (Note that 0 is never an acceptable index.)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2467 Except when noted otherwise,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2468 functions in the API work with acceptable indices.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2469
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2470
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2471 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2472 Acceptable indices serve to avoid extra tests
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2473 against the stack top when querying the stack.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2474 For instance, a C function can query its third argument
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2475 without the need to first check whether there is a third argument,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2476 that is, without the need to check whether 3 is a valid index.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2477
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2478
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2479 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2480 For functions that can be called with acceptable indices,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2481 any non-valid index is treated as if it
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2482 contains a value of a virtual type <a name="pdf-LUA_TNONE"><code>LUA_TNONE</code></a>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2483 which behaves like a nil value.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2484
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2485
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2486
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2487
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2488
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2489 <h2>4.4 – <a name="4.4">C Closures</a></h2>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2490
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2491 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2492 When a C function is created,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2493 it is possible to associate some values with it,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2494 thus creating a <em>C closure</em>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2495 (see <a href="#lua_pushcclosure"><code>lua_pushcclosure</code></a>);
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2496 these values are called <em>upvalues</em> and are
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2497 accessible to the function whenever it is called.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2498
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2499
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2500 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2501 Whenever a C function is called,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2502 its upvalues are located at specific pseudo-indices.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2503 These pseudo-indices are produced by the macro
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2504 <a href="#lua_upvalueindex"><code>lua_upvalueindex</code></a>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2505 The first value associated with a function is at position
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2506 <code>lua_upvalueindex(1)</code>, and so on.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2507 Any access to <code>lua_upvalueindex(<em>n</em>)</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2508 where <em>n</em> is greater than the number of upvalues of the
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2509 current function (but not greater than 256),
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2510 produces an acceptable but invalid index.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2511
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2512
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2513
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2514
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2515
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2516 <h2>4.5 – <a name="4.5">Registry</a></h2>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2517
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2518 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2519 Lua provides a <em>registry</em>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2520 a predefined table that can be used by any C code to
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2521 store whatever Lua values it needs to store.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2522 The registry table is always located at pseudo-index
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2523 <a name="pdf-LUA_REGISTRYINDEX"><code>LUA_REGISTRYINDEX</code></a>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2524 which is a valid index.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2525 Any C library can store data into this table,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2526 but it must take care to choose keys
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2527 that are different from those used
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2528 by other libraries, to avoid collisions.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2529 Typically, you should use as key a string containing your library name,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2530 or a light userdata with the address of a C object in your code,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2531 or any Lua object created by your code.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2532 As with variable names,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2533 string keys starting with an underscore followed by
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2534 uppercase letters are reserved for Lua.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2535
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2536
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2537 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2538 The integer keys in the registry are used
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2539 by the reference mechanism (see <a href="#luaL_ref"><code>luaL_ref</code></a>)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2540 and by some predefined values.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2541 Therefore, integer keys must not be used for other purposes.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2542
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2543
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2544 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2545 When you create a new Lua state,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2546 its registry comes with some predefined values.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2547 These predefined values are indexed with integer keys
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2548 defined as constants in <code>lua.h</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2549 The following constants are defined:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2550
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2551 <ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2552 <li><b><a name="pdf-LUA_RIDX_MAINTHREAD"><code>LUA_RIDX_MAINTHREAD</code></a>: </b> At this index the registry has
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2553 the main thread of the state.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2554 (The main thread is the one created together with the state.)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2555 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2556
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2557 <li><b><a name="pdf-LUA_RIDX_GLOBALS"><code>LUA_RIDX_GLOBALS</code></a>: </b> At this index the registry has
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2558 the global environment.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2559 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2560 </ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2561
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2562
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2563
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2564
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2565 <h2>4.6 – <a name="4.6">Error Handling in C</a></h2>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2566
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2567 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2568 Internally, Lua uses the C <code>longjmp</code> facility to handle errors.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2569 (Lua will use exceptions if you compile it as C++;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2570 search for <code>LUAI_THROW</code> in the source code for details.)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2571 When Lua faces any error
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2572 (such as a memory allocation error, type errors, syntax errors,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2573 and runtime errors)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2574 it <em>raises</em> an error;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2575 that is, it does a long jump.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2576 A <em>protected environment</em> uses <code>setjmp</code>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2577 to set a recovery point;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2578 any error jumps to the most recent active recovery point.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2579
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2580
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2581 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2582 If an error happens outside any protected environment,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2583 Lua calls a <em>panic function</em> (see <a href="#lua_atpanic"><code>lua_atpanic</code></a>)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2584 and then calls <code>abort</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2585 thus exiting the host application.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2586 Your panic function can avoid this exit by
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2587 never returning
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2588 (e.g., doing a long jump to your own recovery point outside Lua).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2589
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2590
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2591 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2592 The panic function runs as if it were a message handler (see <a href="#2.3">§2.3</a>);
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2593 in particular, the error message is at the top of the stack.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2594 However, there is no guarantee about stack space.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2595 To push anything on the stack,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2596 the panic function must first check the available space (see <a href="#4.2">§4.2</a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2597
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2598
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2599 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2600 Most functions in the API can raise an error,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2601 for instance due to a memory allocation error.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2602 The documentation for each function indicates whether
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2603 it can raise errors.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2604
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2605
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2606 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2607 Inside a C function you can raise an error by calling <a href="#lua_error"><code>lua_error</code></a>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2608
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2609
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2610
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2611
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2612
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2613 <h2>4.7 – <a name="4.7">Handling Yields in C</a></h2>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2614
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2615 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2616 Internally, Lua uses the C <code>longjmp</code> facility to yield a coroutine.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2617 Therefore, if a C function <code>foo</code> calls an API function
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2618 and this API function yields
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2619 (directly or indirectly by calling another function that yields),
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2620 Lua cannot return to <code>foo</code> any more,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2621 because the <code>longjmp</code> removes its frame from the C stack.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2622
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2623
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2624 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2625 To avoid this kind of problem,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2626 Lua raises an error whenever it tries to yield across an API call,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2627 except for three functions:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2628 <a href="#lua_yieldk"><code>lua_yieldk</code></a>, <a href="#lua_callk"><code>lua_callk</code></a>, and <a href="#lua_pcallk"><code>lua_pcallk</code></a>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2629 All those functions receive a <em>continuation function</em>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2630 (as a parameter named <code>k</code>) to continue execution after a yield.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2631
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2632
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2633 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2634 We need to set some terminology to explain continuations.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2635 We have a C function called from Lua which we will call
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2636 the <em>original function</em>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2637 This original function then calls one of those three functions in the C API,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2638 which we will call the <em>callee function</em>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2639 that then yields the current thread.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2640 (This can happen when the callee function is <a href="#lua_yieldk"><code>lua_yieldk</code></a>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2641 or when the callee function is either <a href="#lua_callk"><code>lua_callk</code></a> or <a href="#lua_pcallk"><code>lua_pcallk</code></a>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2642 and the function called by them yields.)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2643
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2644
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2645 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2646 Suppose the running thread yields while executing the callee function.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2647 After the thread resumes,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2648 it eventually will finish running the callee function.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2649 However,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2650 the callee function cannot return to the original function,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2651 because its frame in the C stack was destroyed by the yield.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2652 Instead, Lua calls a <em>continuation function</em>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2653 which was given as an argument to the callee function.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2654 As the name implies,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2655 the continuation function should continue the task
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2656 of the original function.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2657
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2658
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2659 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2660 As an illustration, consider the following function:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2661
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2662 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2663 int original_function (lua_State *L) {
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2664 ... /* code 1 */
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2665 status = lua_pcall(L, n, m, h); /* calls Lua */
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2666 ... /* code 2 */
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2667 }
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2668 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2669 Now we want to allow
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2670 the Lua code being run by <a href="#lua_pcall"><code>lua_pcall</code></a> to yield.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2671 First, we can rewrite our function like here:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2672
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2673 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2674 int k (lua_State *L, int status, lua_KContext ctx) {
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2675 ... /* code 2 */
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2676 }
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2677
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2678 int original_function (lua_State *L) {
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2679 ... /* code 1 */
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2680 return k(L, lua_pcall(L, n, m, h), ctx);
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2681 }
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2682 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2683 In the above code,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2684 the new function <code>k</code> is a
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2685 <em>continuation function</em> (with type <a href="#lua_KFunction"><code>lua_KFunction</code></a>),
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2686 which should do all the work that the original function
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2687 was doing after calling <a href="#lua_pcall"><code>lua_pcall</code></a>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2688 Now, we must inform Lua that it must call <code>k</code> if the Lua code
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2689 being executed by <a href="#lua_pcall"><code>lua_pcall</code></a> gets interrupted in some way
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2690 (errors or yielding),
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2691 so we rewrite the code as here,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2692 replacing <a href="#lua_pcall"><code>lua_pcall</code></a> by <a href="#lua_pcallk"><code>lua_pcallk</code></a>:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2693
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2694 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2695 int original_function (lua_State *L) {
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2696 ... /* code 1 */
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2697 return k(L, lua_pcallk(L, n, m, h, ctx2, k), ctx1);
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2698 }
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2699 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2700 Note the external, explicit call to the continuation:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2701 Lua will call the continuation only if needed, that is,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2702 in case of errors or resuming after a yield.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2703 If the called function returns normally without ever yielding,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2704 <a href="#lua_pcallk"><code>lua_pcallk</code></a> (and <a href="#lua_callk"><code>lua_callk</code></a>) will also return normally.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2705 (Of course, instead of calling the continuation in that case,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2706 you can do the equivalent work directly inside the original function.)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2707
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2708
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2709 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2710 Besides the Lua state,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2711 the continuation function has two other parameters:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2712 the final status of the call plus the context value (<code>ctx</code>) that
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2713 was passed originally to <a href="#lua_pcallk"><code>lua_pcallk</code></a>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2714 (Lua does not use this context value;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2715 it only passes this value from the original function to the
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2716 continuation function.)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2717 For <a href="#lua_pcallk"><code>lua_pcallk</code></a>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2718 the status is the same value that would be returned by <a href="#lua_pcallk"><code>lua_pcallk</code></a>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2719 except that it is <a href="#pdf-LUA_YIELD"><code>LUA_YIELD</code></a> when being executed after a yield
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2720 (instead of <a href="#pdf-LUA_OK"><code>LUA_OK</code></a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2721 For <a href="#lua_yieldk"><code>lua_yieldk</code></a> and <a href="#lua_callk"><code>lua_callk</code></a>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2722 the status is always <a href="#pdf-LUA_YIELD"><code>LUA_YIELD</code></a> when Lua calls the continuation.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2723 (For these two functions,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2724 Lua will not call the continuation in case of errors,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2725 because they do not handle errors.)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2726 Similarly, when using <a href="#lua_callk"><code>lua_callk</code></a>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2727 you should call the continuation function
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2728 with <a href="#pdf-LUA_OK"><code>LUA_OK</code></a> as the status.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2729 (For <a href="#lua_yieldk"><code>lua_yieldk</code></a>, there is not much point in calling
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2730 directly the continuation function,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2731 because <a href="#lua_yieldk"><code>lua_yieldk</code></a> usually does not return.)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2732
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2733
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2734 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2735 Lua treats the continuation function as if it were the original function.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2736 The continuation function receives the same Lua stack
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2737 from the original function,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2738 in the same state it would be if the callee function had returned.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2739 (For instance,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2740 after a <a href="#lua_callk"><code>lua_callk</code></a> the function and its arguments are
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2741 removed from the stack and replaced by the results from the call.)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2742 It also has the same upvalues.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2743 Whatever it returns is handled by Lua as if it were the return
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2744 of the original function.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2745
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2746
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2747
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2748
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2749
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2750 <h2>4.8 – <a name="4.8">Functions and Types</a></h2>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2751
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2752 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2753 Here we list all functions and types from the C API in
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2754 alphabetical order.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2755 Each function has an indicator like this:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2756 <span class="apii">[-o, +p, <em>x</em>]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2757
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2758
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2759 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2760 The first field, <code>o</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2761 is how many elements the function pops from the stack.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2762 The second field, <code>p</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2763 is how many elements the function pushes onto the stack.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2764 (Any function always pushes its results after popping its arguments.)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2765 A field in the form <code>x\|y</code> means the function can push (or pop)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2766 <code>x</code> or <code>y</code> elements,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2767 depending on the situation;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2768 an interrogation mark '<code>?</code>' means that
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2769 we cannot know how many elements the function pops/pushes
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2770 by looking only at its arguments
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2771 (e.g., they may depend on what is on the stack).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2772 The third field, <code>x</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2773 tells whether the function may raise errors:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2774 '<code>-</code>' means the function never raises any error;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2775 '<code>e</code>' means the function may raise errors;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2776 '<code>v</code>' means the function may raise an error on purpose.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2777
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2778
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2779
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2780 <hr><h3><a name="lua_absindex"><code>lua_absindex</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2781 <span class="apii">[-0, +0, –]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2782 <pre>int lua_absindex (lua_State *L, int idx);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2783
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2784 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2785 Converts the acceptable index <code>idx</code> into an absolute index
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2786 (that is, one that does not depend on the stack top).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2787
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2788
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2789
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2790
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2791
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2792 <hr><h3><a name="lua_Alloc"><code>lua_Alloc</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2793 <pre>typedef void * (lua_Alloc) (void ud,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2794 void *ptr,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2795 size_t osize,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2796 size_t nsize);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2797
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2798 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2799 The type of the memory-allocation function used by Lua states.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2800 The allocator function must provide a
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2801 functionality similar to <code>realloc</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2802 but not exactly the same.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2803 Its arguments are
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2804 <code>ud</code>, an opaque pointer passed to <a href="#lua_newstate"><code>lua_newstate</code></a>;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2805 <code>ptr</code>, a pointer to the block being allocated/reallocated/freed;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2806 <code>osize</code>, the original size of the block or some code about what
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2807 is being allocated;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2808 and <code>nsize</code>, the new size of the block.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2809
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2810
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2811 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2812 When <code>ptr</code> is not <code>NULL</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2813 <code>osize</code> is the size of the block pointed by <code>ptr</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2814 that is, the size given when it was allocated or reallocated.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2815
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2816
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2817 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2818 When <code>ptr</code> is <code>NULL</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2819 <code>osize</code> encodes the kind of object that Lua is allocating.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2820 <code>osize</code> is any of
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2821 <a href="#pdf-LUA_TSTRING"><code>LUA_TSTRING</code></a>, <a href="#pdf-LUA_TTABLE"><code>LUA_TTABLE</code></a>, <a href="#pdf-LUA_TFUNCTION"><code>LUA_TFUNCTION</code></a>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2822 <a href="#pdf-LUA_TUSERDATA"><code>LUA_TUSERDATA</code></a>, or <a href="#pdf-LUA_TTHREAD"><code>LUA_TTHREAD</code></a> when (and only when)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2823 Lua is creating a new object of that type.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2824 When <code>osize</code> is some other value,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2825 Lua is allocating memory for something else.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2826
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2827
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2828 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2829 Lua assumes the following behavior from the allocator function:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2830
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2831
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2832 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2833 When <code>nsize</code> is zero,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2834 the allocator must behave like <code>free</code>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2835 and return <code>NULL</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2836
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2837
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2838 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2839 When <code>nsize</code> is not zero,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2840 the allocator must behave like <code>realloc</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2841 The allocator returns <code>NULL</code>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2842 if and only if it cannot fulfill the request.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2843 Lua assumes that the allocator never fails when
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2844 <code>osize >= nsize</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2845
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2846
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2847 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2848 Here is a simple implementation for the allocator function.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2849 It is used in the auxiliary library by <a href="#luaL_newstate"><code>luaL_newstate</code></a>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2850
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2851 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2852 static void l_alloc (void ud, void *ptr, size_t osize,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2853 size_t nsize) {
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2854 (void)ud; (void)osize; /* not used */
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2855 if (nsize == 0) {
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2856 free(ptr);
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2857 return NULL;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2858 }
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2859 else
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2860 return realloc(ptr, nsize);
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2861 }
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2862 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2863 Note that Standard C ensures
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2864 that <code>free(NULL)</code> has no effect and that
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2865 <code>realloc(NULL,size)</code> is equivalent to <code>malloc(size)</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2866 This code assumes that <code>realloc</code> does not fail when shrinking a block.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2867 (Although Standard C does not ensure this behavior,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2868 it seems to be a safe assumption.)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2869
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2870
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2871
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2872
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2873
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2874 <hr><h3><a name="lua_arith"><code>lua_arith</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2875 <span class="apii">[-(2\|1), +1, <em>e</em>]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2876 <pre>void lua_arith (lua_State *L, int op);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2877
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2878 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2879 Performs an arithmetic or bitwise operation over the two values
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2880 (or one, in the case of negations)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2881 at the top of the stack,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2882 with the value at the top being the second operand,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2883 pops these values, and pushes the result of the operation.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2884 The function follows the semantics of the corresponding Lua operator
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2885 (that is, it may call metamethods).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2886
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2887
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2888 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2889 The value of <code>op</code> must be one of the following constants:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2890
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2891 <ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2892
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2893 <li><b><a name="pdf-LUA_OPADD"><code>LUA_OPADD</code></a>: </b> performs addition (<code>+</code>)</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2894 <li><b><a name="pdf-LUA_OPSUB"><code>LUA_OPSUB</code></a>: </b> performs subtraction (<code>-</code>)</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2895 <li><b><a name="pdf-LUA_OPMUL"><code>LUA_OPMUL</code></a>: </b> performs multiplication (<code>*</code>)</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2896 <li><b><a name="pdf-LUA_OPDIV"><code>LUA_OPDIV</code></a>: </b> performs float division (<code>/</code>)</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2897 <li><b><a name="pdf-LUA_OPIDIV"><code>LUA_OPIDIV</code></a>: </b> performs floor division (<code>//</code>)</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2898 <li><b><a name="pdf-LUA_OPMOD"><code>LUA_OPMOD</code></a>: </b> performs modulo (<code>%</code>)</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2899 <li><b><a name="pdf-LUA_OPPOW"><code>LUA_OPPOW</code></a>: </b> performs exponentiation (<code>^</code>)</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2900 <li><b><a name="pdf-LUA_OPUNM"><code>LUA_OPUNM</code></a>: </b> performs mathematical negation (unary <code>-</code>)</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2901 <li><b><a name="pdf-LUA_OPBNOT"><code>LUA_OPBNOT</code></a>: </b> performs bitwise negation (<code>~</code>)</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2902 <li><b><a name="pdf-LUA_OPBAND"><code>LUA_OPBAND</code></a>: </b> performs bitwise and (<code>&</code>)</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2903 <li><b><a name="pdf-LUA_OPBOR"><code>LUA_OPBOR</code></a>: </b> performs bitwise or (<code>\|</code>)</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2904 <li><b><a name="pdf-LUA_OPBXOR"><code>LUA_OPBXOR</code></a>: </b> performs bitwise exclusive or (<code>~</code>)</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2905 <li><b><a name="pdf-LUA_OPSHL"><code>LUA_OPSHL</code></a>: </b> performs left shift (<code><<</code>)</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2906 <li><b><a name="pdf-LUA_OPSHR"><code>LUA_OPSHR</code></a>: </b> performs right shift (<code>>></code>)</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2907
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2908 </ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2909
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2910
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2911
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2912
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2913 <hr><h3><a name="lua_atpanic"><code>lua_atpanic</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2914 <span class="apii">[-0, +0, –]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2915 <pre>lua_CFunction lua_atpanic (lua_State *L, lua_CFunction panicf);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2916
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2917 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2918 Sets a new panic function and returns the old one (see <a href="#4.6">§4.6</a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2919
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2920
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2921
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2922
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2923
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2924 <hr><h3><a name="lua_call"><code>lua_call</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2925 <span class="apii">[-(nargs+1), +nresults, <em>e</em>]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2926 <pre>void lua_call (lua_State *L, int nargs, int nresults);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2927
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2928 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2929 Calls a function.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2930
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2931
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2932 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2933 To call a function you must use the following protocol:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2934 first, the function to be called is pushed onto the stack;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2935 then, the arguments to the function are pushed
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2936 in direct order;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2937 that is, the first argument is pushed first.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2938 Finally you call <a href="#lua_call"><code>lua_call</code></a>;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2939 <code>nargs</code> is the number of arguments that you pushed onto the stack.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2940 All arguments and the function value are popped from the stack
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2941 when the function is called.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2942 The function results are pushed onto the stack when the function returns.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2943 The number of results is adjusted to <code>nresults</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2944 unless <code>nresults</code> is <a name="pdf-LUA_MULTRET"><code>LUA_MULTRET</code></a>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2945 In this case, all results from the function are pushed.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2946 Lua takes care that the returned values fit into the stack space.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2947 The function results are pushed onto the stack in direct order
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2948 (the first result is pushed first),
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2949 so that after the call the last result is on the top of the stack.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2950
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2951
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2952 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2953 Any error inside the called function is propagated upwards
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2954 (with a <code>longjmp</code>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2955
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2956
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2957 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2958 The following example shows how the host program can do the
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2959 equivalent to this Lua code:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2960
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2961 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2962 a = f("how", t.x, 14)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2963 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2964 Here it is in C:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2965
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2966 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2967 lua_getglobal(L, "f"); /* function to be called */
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2968 lua_pushliteral(L, "how"); /* 1st argument */
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2969 lua_getglobal(L, "t"); /* table to be indexed */
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2970 lua_getfield(L, -1, "x"); /* push result of t.x (2nd arg) */
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2971 lua_remove(L, -2); /* remove 't' from the stack */
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2972 lua_pushinteger(L, 14); /* 3rd argument */
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2973 lua_call(L, 3, 1); /* call 'f' with 3 arguments and 1 result */
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2974 lua_setglobal(L, "a"); /* set global 'a' */
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2975 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2976 Note that the code above is <em>balanced</em>:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2977 at its end, the stack is back to its original configuration.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2978 This is considered good programming practice.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2979
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2980
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2981
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2982
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2983
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2984 <hr><h3><a name="lua_callk"><code>lua_callk</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2985 <span class="apii">[-(nargs + 1), +nresults, <em>e</em>]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2986 <pre>void lua_callk (lua_State *L,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2987 int nargs,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2988 int nresults,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2989 lua_KContext ctx,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2990 lua_KFunction k);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2991
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2992 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2993 This function behaves exactly like <a href="#lua_call"><code>lua_call</code></a>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2994 but allows the called function to yield (see <a href="#4.7">§4.7</a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2995
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2996
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2997
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2998
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2999
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3000 <hr><h3><a name="lua_CFunction"><code>lua_CFunction</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3001 <pre>typedef int (lua_CFunction) (lua_State L);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3002
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3003 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3004 Type for C functions.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3005
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3006
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3007 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3008 In order to communicate properly with Lua,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3009 a C function must use the following protocol,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3010 which defines the way parameters and results are passed:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3011 a C function receives its arguments from Lua in its stack
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3012 in direct order (the first argument is pushed first).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3013 So, when the function starts,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3014 <code>lua_gettop(L)</code> returns the number of arguments received by the function.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3015 The first argument (if any) is at index 1
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3016 and its last argument is at index <code>lua_gettop(L)</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3017 To return values to Lua, a C function just pushes them onto the stack,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3018 in direct order (the first result is pushed first),
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3019 and returns the number of results.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3020 Any other value in the stack below the results will be properly
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3021 discarded by Lua.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3022 Like a Lua function, a C function called by Lua can also return
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3023 many results.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3024
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3025
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3026 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3027 As an example, the following function receives a variable number
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3028 of numerical arguments and returns their average and their sum:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3029
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3030 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3031 static int foo (lua_State *L) {
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3032 int n = lua_gettop(L); /* number of arguments */
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3033 lua_Number sum = 0.0;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3034 int i;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3035 for (i = 1; i <= n; i++) {
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3036 if (!lua_isnumber(L, i)) {
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3037 lua_pushliteral(L, "incorrect argument");
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3038 lua_error(L);
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3039 }
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3040 sum += lua_tonumber(L, i);
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3041 }
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3042 lua_pushnumber(L, sum/n); /* first result */
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3043 lua_pushnumber(L, sum); /* second result */
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3044 return 2; /* number of results */
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3045 }
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3046 </pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3047
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3048
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3049
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3050
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3051 <hr><h3><a name="lua_checkstack"><code>lua_checkstack</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3052 <span class="apii">[-0, +0, –]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3053 <pre>int lua_checkstack (lua_State *L, int n);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3054
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3055 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3056 Ensures that the stack has space for at least <code>n</code> extra slots.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3057 It returns false if it cannot fulfill the request,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3058 either because it would cause the stack
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3059 to be larger than a fixed maximum size
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3060 (typically at least several thousand elements) or
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3061 because it cannot allocate memory for the extra space.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3062 This function never shrinks the stack;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3063 if the stack is already larger than the new size,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3064 it is left unchanged.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3065
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3066
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3067
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3068
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3069
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3070 <hr><h3><a name="lua_close"><code>lua_close</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3071 <span class="apii">[-0, +0, –]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3072 <pre>void lua_close (lua_State *L);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3073
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3074 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3075 Destroys all objects in the given Lua state
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3076 (calling the corresponding garbage-collection metamethods, if any)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3077 and frees all dynamic memory used by this state.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3078 On several platforms, you may not need to call this function,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3079 because all resources are naturally released when the host program ends.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3080 On the other hand, long-running programs that create multiple states,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3081 such as daemons or web servers,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3082 will probably need to close states as soon as they are not needed.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3083
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3084
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3085
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3086
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3087
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3088 <hr><h3><a name="lua_compare"><code>lua_compare</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3089 <span class="apii">[-0, +0, <em>e</em>]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3090 <pre>int lua_compare (lua_State *L, int index1, int index2, int op);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3091
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3092 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3093 Compares two Lua values.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3094 Returns 1 if the value at index <code>index1</code> satisfies <code>op</code>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3095 when compared with the value at index <code>index2</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3096 following the semantics of the corresponding Lua operator
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3097 (that is, it may call metamethods).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3098 Otherwise returns 0.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3099 Also returns 0 if any of the indices is not valid.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3100
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3101
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3102 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3103 The value of <code>op</code> must be one of the following constants:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3104
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3105 <ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3106
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3107 <li><b><a name="pdf-LUA_OPEQ"><code>LUA_OPEQ</code></a>: </b> compares for equality (<code>==</code>)</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3108 <li><b><a name="pdf-LUA_OPLT"><code>LUA_OPLT</code></a>: </b> compares for less than (<code><</code>)</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3109 <li><b><a name="pdf-LUA_OPLE"><code>LUA_OPLE</code></a>: </b> compares for less or equal (<code><=</code>)</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3110
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3111 </ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3112
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3113
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3114
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3115
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3116 <hr><h3><a name="lua_concat"><code>lua_concat</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3117 <span class="apii">[-n, +1, <em>e</em>]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3118 <pre>void lua_concat (lua_State *L, int n);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3119
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3120 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3121 Concatenates the <code>n</code> values at the top of the stack,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3122 pops them, and leaves the result at the top.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3123 If <code>n</code> is 1, the result is the single value on the stack
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3124 (that is, the function does nothing);
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3125 if <code>n</code> is 0, the result is the empty string.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3126 Concatenation is performed following the usual semantics of Lua
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3127 (see <a href="#3.4.6">§3.4.6</a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3128
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3129
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3130
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3131
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3132
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3133 <hr><h3><a name="lua_copy"><code>lua_copy</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3134 <span class="apii">[-0, +0, –]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3135 <pre>void lua_copy (lua_State *L, int fromidx, int toidx);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3136
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3137 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3138 Copies the element at index <code>fromidx</code>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3139 into the valid index <code>toidx</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3140 replacing the value at that position.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3141 Values at other positions are not affected.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3142
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3143
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3144
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3145
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3146
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3147 <hr><h3><a name="lua_createtable"><code>lua_createtable</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3148 <span class="apii">[-0, +1, <em>e</em>]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3149 <pre>void lua_createtable (lua_State *L, int narr, int nrec);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3150
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3151 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3152 Creates a new empty table and pushes it onto the stack.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3153 Parameter <code>narr</code> is a hint for how many elements the table
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3154 will have as a sequence;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3155 parameter <code>nrec</code> is a hint for how many other elements
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3156 the table will have.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3157 Lua may use these hints to preallocate memory for the new table.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3158 This pre-allocation is useful for performance when you know in advance
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3159 how many elements the table will have.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3160 Otherwise you can use the function <a href="#lua_newtable"><code>lua_newtable</code></a>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3161
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3162
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3163
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3164
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3165
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3166 <hr><h3><a name="lua_dump"><code>lua_dump</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3167 <span class="apii">[-0, +0, <em>e</em>]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3168 <pre>int lua_dump (lua_State *L,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3169 lua_Writer writer,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3170 void *data,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3171 int strip);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3172
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3173 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3174 Dumps a function as a binary chunk.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3175 Receives a Lua function on the top of the stack
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3176 and produces a binary chunk that,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3177 if loaded again,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3178 results in a function equivalent to the one dumped.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3179 As it produces parts of the chunk,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3180 <a href="#lua_dump"><code>lua_dump</code></a> calls function <code>writer</code> (see <a href="#lua_Writer"><code>lua_Writer</code></a>)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3181 with the given <code>data</code>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3182 to write them.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3183
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3184
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3185 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3186 If <code>strip</code> is true,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3187 the binary representation is created without debug information
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3188 about the function.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3189
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3190
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3191 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3192 The value returned is the error code returned by the last
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3193 call to the writer;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3194 0 means no errors.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3195
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3196
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3197 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3198 This function does not pop the Lua function from the stack.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3199
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3200
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3201
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3202
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3203
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3204 <hr><h3><a name="lua_error"><code>lua_error</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3205 <span class="apii">[-1, +0, <em>v</em>]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3206 <pre>int lua_error (lua_State *L);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3207
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3208 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3209 Generates a Lua error,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3210 using the value at the top of the stack as the error object.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3211 This function does a long jump,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3212 and therefore never returns
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3213 (see <a href="#luaL_error"><code>luaL_error</code></a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3214
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3215
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3216
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3217
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3218
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3219 <hr><h3><a name="lua_gc"><code>lua_gc</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3220 <span class="apii">[-0, +0, <em>e</em>]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3221 <pre>int lua_gc (lua_State *L, int what, int data);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3222
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3223 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3224 Controls the garbage collector.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3225
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3226
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3227 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3228 This function performs several tasks,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3229 according to the value of the parameter <code>what</code>:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3230
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3231 <ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3232
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3233 <li><b><code>LUA_GCSTOP</code>: </b>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3234 stops the garbage collector.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3235 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3236
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3237 <li><b><code>LUA_GCRESTART</code>: </b>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3238 restarts the garbage collector.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3239 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3240
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3241 <li><b><code>LUA_GCCOLLECT</code>: </b>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3242 performs a full garbage-collection cycle.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3243 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3244
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3245 <li><b><code>LUA_GCCOUNT</code>: </b>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3246 returns the current amount of memory (in Kbytes) in use by Lua.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3247 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3248
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3249 <li><b><code>LUA_GCCOUNTB</code>: </b>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3250 returns the remainder of dividing the current amount of bytes of
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3251 memory in use by Lua by 1024.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3252 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3253
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3254 <li><b><code>LUA_GCSTEP</code>: </b>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3255 performs an incremental step of garbage collection.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3256 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3257
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3258 <li><b><code>LUA_GCSETPAUSE</code>: </b>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3259 sets <code>data</code> as the new value
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3260 for the <em>pause</em> of the collector (see <a href="#2.5">§2.5</a>)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3261 and returns the previous value of the pause.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3262 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3263
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3264 <li><b><code>LUA_GCSETSTEPMUL</code>: </b>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3265 sets <code>data</code> as the new value for the <em>step multiplier</em> of
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3266 the collector (see <a href="#2.5">§2.5</a>)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3267 and returns the previous value of the step multiplier.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3268 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3269
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3270 <li><b><code>LUA_GCISRUNNING</code>: </b>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3271 returns a boolean that tells whether the collector is running
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3272 (i.e., not stopped).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3273 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3274
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3275 </ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3276
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3277 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3278 For more details about these options,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3279 see <a href="#pdf-collectgarbage"><code>collectgarbage</code></a>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3280
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3281
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3282
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3283
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3284
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3285 <hr><h3><a name="lua_getallocf"><code>lua_getallocf</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3286 <span class="apii">[-0, +0, –]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3287 <pre>lua_Alloc lua_getallocf (lua_State L, void *ud);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3288
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3289 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3290 Returns the memory-allocation function of a given state.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3291 If <code>ud</code> is not <code>NULL</code>, Lua stores in <code>*ud</code> the
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3292 opaque pointer given when the memory-allocator function was set.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3293
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3294
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3295
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3296
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3297
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3298 <hr><h3><a name="lua_getfield"><code>lua_getfield</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3299 <span class="apii">[-0, +1, <em>e</em>]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3300 <pre>int lua_getfield (lua_State L, int index, const char k);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3301
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3302 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3303 Pushes onto the stack the value <code>t[k]</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3304 where <code>t</code> is the value at the given index.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3305 As in Lua, this function may trigger a metamethod
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3306 for the "index" event (see <a href="#2.4">§2.4</a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3307
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3308
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3309 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3310 Returns the type of the pushed value.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3311
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3312
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3313
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3314
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3315
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3316 <hr><h3><a name="lua_getextraspace"><code>lua_getextraspace</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3317 <span class="apii">[-0, +0, –]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3318 <pre>void lua_getextraspace (lua_State L);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3319
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3320 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3321 Returns a pointer to a raw memory area associated with the
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3322 given Lua state.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3323 The application can use this area for any purpose;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3324 Lua does not use it for anything.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3325
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3326
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3327 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3328 Each new thread has this area initialized with a copy
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3329 of the area of the main thread.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3330
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3331
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3332 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3333 By default, this area has the size of a pointer to void,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3334 but you can recompile Lua with a different size for this area.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3335 (See <code>LUA_EXTRASPACE</code> in <code>luaconf.h</code>.)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3336
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3337
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3338
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3339
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3340
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3341 <hr><h3><a name="lua_getglobal"><code>lua_getglobal</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3342 <span class="apii">[-0, +1, <em>e</em>]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3343 <pre>int lua_getglobal (lua_State L, const char name);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3344
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3345 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3346 Pushes onto the stack the value of the global <code>name</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3347 Returns the type of that value.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3348
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3349
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3350
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3351
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3352
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3353 <hr><h3><a name="lua_geti"><code>lua_geti</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3354 <span class="apii">[-0, +1, <em>e</em>]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3355 <pre>int lua_geti (lua_State *L, int index, lua_Integer i);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3356
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3357 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3358 Pushes onto the stack the value <code>t[i]</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3359 where <code>t</code> is the value at the given index.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3360 As in Lua, this function may trigger a metamethod
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3361 for the "index" event (see <a href="#2.4">§2.4</a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3362
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3363
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3364 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3365 Returns the type of the pushed value.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3366
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3367
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3368
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3369
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3370
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3371 <hr><h3><a name="lua_getmetatable"><code>lua_getmetatable</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3372 <span class="apii">[-0, +(0\|1), –]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3373 <pre>int lua_getmetatable (lua_State *L, int index);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3374
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3375 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3376 If the value at the given index has a metatable,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3377 the function pushes that metatable onto the stack and returns 1.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3378 Otherwise,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3379 the function returns 0 and pushes nothing on the stack.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3380
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3381
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3382
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3383
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3384
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3385 <hr><h3><a name="lua_gettable"><code>lua_gettable</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3386 <span class="apii">[-1, +1, <em>e</em>]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3387 <pre>int lua_gettable (lua_State *L, int index);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3388
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3389 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3390 Pushes onto the stack the value <code>t[k]</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3391 where <code>t</code> is the value at the given index
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3392 and <code>k</code> is the value at the top of the stack.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3393
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3394
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3395 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3396 This function pops the key from the stack,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3397 pushing the resulting value in its place.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3398 As in Lua, this function may trigger a metamethod
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3399 for the "index" event (see <a href="#2.4">§2.4</a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3400
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3401
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3402 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3403 Returns the type of the pushed value.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3404
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3405
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3406
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3407
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3408
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3409 <hr><h3><a name="lua_gettop"><code>lua_gettop</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3410 <span class="apii">[-0, +0, –]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3411 <pre>int lua_gettop (lua_State *L);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3412
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3413 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3414 Returns the index of the top element in the stack.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3415 Because indices start at 1,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3416 this result is equal to the number of elements in the stack;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3417 in particular, 0 means an empty stack.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3418
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3419
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3420
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3421
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3422
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3423 <hr><h3><a name="lua_getuservalue"><code>lua_getuservalue</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3424 <span class="apii">[-0, +1, –]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3425 <pre>int lua_getuservalue (lua_State *L, int index);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3426
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3427 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3428 Pushes onto the stack the Lua value associated with the userdata
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3429 at the given index.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3430
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3431
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3432 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3433 Returns the type of the pushed value.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3434
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3435
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3436
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3437
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3438
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3439 <hr><h3><a name="lua_insert"><code>lua_insert</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3440 <span class="apii">[-1, +1, –]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3441 <pre>void lua_insert (lua_State *L, int index);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3442
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3443 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3444 Moves the top element into the given valid index,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3445 shifting up the elements above this index to open space.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3446 This function cannot be called with a pseudo-index,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3447 because a pseudo-index is not an actual stack position.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3448
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3449
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3450
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3451
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3452
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3453 <hr><h3><a name="lua_Integer"><code>lua_Integer</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3454 <pre>typedef ... lua_Integer;</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3455
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3456 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3457 The type of integers in Lua.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3458
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3459
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3460 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3461 By default this type is <code>long long</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3462 (usually a 64-bit two-complement integer),
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3463 but that can be changed to <code>long</code> or <code>int</code>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3464 (usually a 32-bit two-complement integer).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3465 (See <code>LUA_INT</code> in <code>luaconf.h</code>.)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3466
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3467
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3468 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3469 Lua also defines the constants
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3470 <a name="pdf-LUA_MININTEGER"><code>LUA_MININTEGER</code></a> and <a name="pdf-LUA_MAXINTEGER"><code>LUA_MAXINTEGER</code></a>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3471 with the minimum and the maximum values that fit in this type.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3472
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3473
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3474
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3475
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3476
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3477 <hr><h3><a name="lua_isboolean"><code>lua_isboolean</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3478 <span class="apii">[-0, +0, –]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3479 <pre>int lua_isboolean (lua_State *L, int index);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3480
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3481 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3482 Returns 1 if the value at the given index is a boolean,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3483 and 0 otherwise.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3484
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3485
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3486
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3487
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3488
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3489 <hr><h3><a name="lua_iscfunction"><code>lua_iscfunction</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3490 <span class="apii">[-0, +0, –]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3491 <pre>int lua_iscfunction (lua_State *L, int index);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3492
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3493 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3494 Returns 1 if the value at the given index is a C function,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3495 and 0 otherwise.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3496
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3497
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3498
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3499
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3500
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3501 <hr><h3><a name="lua_isfunction"><code>lua_isfunction</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3502 <span class="apii">[-0, +0, –]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3503 <pre>int lua_isfunction (lua_State *L, int index);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3504
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3505 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3506 Returns 1 if the value at the given index is a function
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3507 (either C or Lua), and 0 otherwise.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3508
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3509
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3510
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3511
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3512
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3513 <hr><h3><a name="lua_isinteger"><code>lua_isinteger</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3514 <span class="apii">[-0, +0, –]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3515 <pre>int lua_isinteger (lua_State *L, int index);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3516
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3517 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3518 Returns 1 if the value at the given index is an integer
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3519 (that is, the value is a number and is represented as an integer),
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3520 and 0 otherwise.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3521
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3522
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3523
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3524
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3525
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3526 <hr><h3><a name="lua_islightuserdata"><code>lua_islightuserdata</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3527 <span class="apii">[-0, +0, –]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3528 <pre>int lua_islightuserdata (lua_State *L, int index);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3529
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3530 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3531 Returns 1 if the value at the given index is a light userdata,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3532 and 0 otherwise.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3533
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3534
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3535
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3536
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3537
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3538 <hr><h3><a name="lua_isnil"><code>lua_isnil</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3539 <span class="apii">[-0, +0, –]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3540 <pre>int lua_isnil (lua_State *L, int index);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3541
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3542 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3543 Returns 1 if the value at the given index is <b>nil</b>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3544 and 0 otherwise.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3545
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3546
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3547
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3548
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3549
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3550 <hr><h3><a name="lua_isnone"><code>lua_isnone</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3551 <span class="apii">[-0, +0, –]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3552 <pre>int lua_isnone (lua_State *L, int index);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3553
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3554 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3555 Returns 1 if the given index is not valid,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3556 and 0 otherwise.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3557
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3558
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3559
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3560
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3561
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3562 <hr><h3><a name="lua_isnoneornil"><code>lua_isnoneornil</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3563 <span class="apii">[-0, +0, –]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3564 <pre>int lua_isnoneornil (lua_State *L, int index);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3565
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3566 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3567 Returns 1 if the given index is not valid
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3568 or if the value at this index is <b>nil</b>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3569 and 0 otherwise.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3570
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3571
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3572
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3573
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3574
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3575 <hr><h3><a name="lua_isnumber"><code>lua_isnumber</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3576 <span class="apii">[-0, +0, –]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3577 <pre>int lua_isnumber (lua_State *L, int index);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3578
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3579 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3580 Returns 1 if the value at the given index is a number
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3581 or a string convertible to a number,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3582 and 0 otherwise.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3583
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3584
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3585
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3586
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3587
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3588 <hr><h3><a name="lua_isstring"><code>lua_isstring</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3589 <span class="apii">[-0, +0, –]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3590 <pre>int lua_isstring (lua_State *L, int index);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3591
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3592 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3593 Returns 1 if the value at the given index is a string
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3594 or a number (which is always convertible to a string),
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3595 and 0 otherwise.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3596
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3597
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3598
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3599
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3600
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3601 <hr><h3><a name="lua_istable"><code>lua_istable</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3602 <span class="apii">[-0, +0, –]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3603 <pre>int lua_istable (lua_State *L, int index);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3604
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3605 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3606 Returns 1 if the value at the given index is a table,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3607 and 0 otherwise.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3608
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3609
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3610
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3611
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3612
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3613 <hr><h3><a name="lua_isthread"><code>lua_isthread</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3614 <span class="apii">[-0, +0, –]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3615 <pre>int lua_isthread (lua_State *L, int index);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3616
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3617 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3618 Returns 1 if the value at the given index is a thread,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3619 and 0 otherwise.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3620
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3621
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3622
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3623
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3624
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3625 <hr><h3><a name="lua_isuserdata"><code>lua_isuserdata</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3626 <span class="apii">[-0, +0, –]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3627 <pre>int lua_isuserdata (lua_State *L, int index);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3628
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3629 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3630 Returns 1 if the value at the given index is a userdata
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3631 (either full or light), and 0 otherwise.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3632
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3633
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3634
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3635
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3636
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3637 <hr><h3><a name="lua_isyieldable"><code>lua_isyieldable</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3638 <span class="apii">[-0, +0, –]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3639 <pre>int lua_isyieldable (lua_State *L);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3640
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3641 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3642 Returns 1 if the given coroutine can yield,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3643 and 0 otherwise.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3644
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3645
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3646
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3647
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3648
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3649 <hr><h3><a name="lua_KContext"><code>lua_KContext</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3650 <pre>typedef ... lua_KContext;</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3651
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3652 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3653 The type for continuation-function contexts.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3654 It must be a numerical type.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3655 This type is defined as <code>intptr_t</code>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3656 when <code>intptr_t</code> is available,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3657 so that it can store pointers too.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3658 Otherwise, it is defined as <code>ptrdiff_t</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3659
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3660
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3661
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3662
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3663
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3664 <hr><h3><a name="lua_KFunction"><code>lua_KFunction</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3665 <pre>typedef int (lua_KFunction) (lua_State L, int status, lua_KContext ctx);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3666
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3667 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3668 Type for continuation functions (see <a href="#4.7">§4.7</a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3669
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3670
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3671
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3672
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3673
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3674 <hr><h3><a name="lua_len"><code>lua_len</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3675 <span class="apii">[-0, +1, <em>e</em>]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3676 <pre>void lua_len (lua_State *L, int index);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3677
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3678 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3679 Returns the length of the value at the given index.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3680 It is equivalent to the '<code>#</code>' operator in Lua (see <a href="#3.4.7">§3.4.7</a>) and
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3681 may trigger a metamethod for the "length" event (see <a href="#2.4">§2.4</a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3682 The result is pushed on the stack.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3683
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3684
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3685
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3686
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3687
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3688 <hr><h3><a name="lua_load"><code>lua_load</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3689 <span class="apii">[-0, +1, –]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3690 <pre>int lua_load (lua_State *L,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3691 lua_Reader reader,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3692 void *data,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3693 const char *chunkname,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3694 const char *mode);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3695
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3696 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3697 Loads a Lua chunk without running it.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3698 If there are no errors,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3699 <code>lua_load</code> pushes the compiled chunk as a Lua
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3700 function on top of the stack.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3701 Otherwise, it pushes an error message.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3702
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3703
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3704 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3705 The return values of <code>lua_load</code> are:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3706
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3707 <ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3708
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3709 <li><b><a href="#pdf-LUA_OK"><code>LUA_OK</code></a>: </b> no errors;</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3710
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3711 <li><b><a name="pdf-LUA_ERRSYNTAX"><code>LUA_ERRSYNTAX</code></a>: </b>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3712 syntax error during precompilation;</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3713
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3714 <li><b><a href="#pdf-LUA_ERRMEM"><code>LUA_ERRMEM</code></a>: </b>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3715 memory allocation error;</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3716
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3717 <li><b><a href="#pdf-LUA_ERRGCMM"><code>LUA_ERRGCMM</code></a>: </b>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3718 error while running a <code>__gc</code> metamethod.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3719 (This error has no relation with the chunk being loaded.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3720 It is generated by the garbage collector.)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3721 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3722
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3723 </ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3724
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3725 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3726 The <code>lua_load</code> function uses a user-supplied <code>reader</code> function
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3727 to read the chunk (see <a href="#lua_Reader"><code>lua_Reader</code></a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3728 The <code>data</code> argument is an opaque value passed to the reader function.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3729
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3730
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3731 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3732 The <code>chunkname</code> argument gives a name to the chunk,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3733 which is used for error messages and in debug information (see <a href="#4.9">§4.9</a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3734
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3735
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3736 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3737 <code>lua_load</code> automatically detects whether the chunk is text or binary
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3738 and loads it accordingly (see program <code>luac</code>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3739 The string <code>mode</code> works as in function <a href="#pdf-load"><code>load</code></a>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3740 with the addition that
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3741 a <code>NULL</code> value is equivalent to the string "<code>bt</code>".
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3742
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3743
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3744 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3745 <code>lua_load</code> uses the stack internally,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3746 so the reader function must always leave the stack
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3747 unmodified when returning.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3748
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3749
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3750 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3751 If the resulting function has upvalues,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3752 its first upvalue is set to the value of the global environment
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3753 stored at index <code>LUA_RIDX_GLOBALS</code> in the registry (see <a href="#4.5">§4.5</a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3754 When loading main chunks,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3755 this upvalue will be the <code>_ENV</code> variable (see <a href="#2.2">§2.2</a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3756 Other upvalues are initialized with <b>nil</b>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3757
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3758
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3759
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3760
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3761
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3762 <hr><h3><a name="lua_newstate"><code>lua_newstate</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3763 <span class="apii">[-0, +0, –]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3764 <pre>lua_State lua_newstate (lua_Alloc f, void ud);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3765
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3766 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3767 Creates a new thread running in a new, independent state.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3768 Returns <code>NULL</code> if it cannot create the thread or the state
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3769 (due to lack of memory).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3770 The argument <code>f</code> is the allocator function;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3771 Lua does all memory allocation for this state through this function.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3772 The second argument, <code>ud</code>, is an opaque pointer that Lua
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3773 passes to the allocator in every call.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3774
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3775
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3776
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3777
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3778
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3779 <hr><h3><a name="lua_newtable"><code>lua_newtable</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3780 <span class="apii">[-0, +1, <em>e</em>]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3781 <pre>void lua_newtable (lua_State *L);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3782
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3783 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3784 Creates a new empty table and pushes it onto the stack.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3785 It is equivalent to <code>lua_createtable(L, 0, 0)</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3786
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3787
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3788
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3789
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3790
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3791 <hr><h3><a name="lua_newthread"><code>lua_newthread</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3792 <span class="apii">[-0, +1, <em>e</em>]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3793 <pre>lua_State lua_newthread (lua_State L);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3794
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3795 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3796 Creates a new thread, pushes it on the stack,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3797 and returns a pointer to a <a href="#lua_State"><code>lua_State</code></a> that represents this new thread.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3798 The new thread returned by this function shares with the original thread
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3799 its global environment,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3800 but has an independent execution stack.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3801
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3802
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3803 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3804 There is no explicit function to close or to destroy a thread.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3805 Threads are subject to garbage collection,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3806 like any Lua object.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3807
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3808
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3809
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3810
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3811
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3812 <hr><h3><a name="lua_newuserdata"><code>lua_newuserdata</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3813 <span class="apii">[-0, +1, <em>e</em>]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3814 <pre>void lua_newuserdata (lua_State L, size_t size);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3815
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3816 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3817 This function allocates a new block of memory with the given size,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3818 pushes onto the stack a new full userdata with the block address,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3819 and returns this address.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3820 The host program can freely use this memory.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3821
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3822
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3823
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3824
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3825
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3826 <hr><h3><a name="lua_next"><code>lua_next</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3827 <span class="apii">[-1, +(2\|0), <em>e</em>]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3828 <pre>int lua_next (lua_State *L, int index);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3829
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3830 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3831 Pops a key from the stack,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3832 and pushes a key–value pair from the table at the given index
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3833 (the "next" pair after the given key).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3834 If there are no more elements in the table,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3835 then <a href="#lua_next"><code>lua_next</code></a> returns 0 (and pushes nothing).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3836
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3837
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3838 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3839 A typical traversal looks like this:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3840
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3841 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3842 /* table is in the stack at index 't' */
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3843 lua_pushnil(L); /* first key */
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3844 while (lua_next(L, t) != 0) {
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3845 /* uses 'key' (at index -2) and 'value' (at index -1) */
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3846 printf("%s - %s\n",
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3847 lua_typename(L, lua_type(L, -2)),
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3848 lua_typename(L, lua_type(L, -1)));
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3849 /* removes 'value'; keeps 'key' for next iteration */
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3850 lua_pop(L, 1);
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3851 }
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3852 </pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3853
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3854 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3855 While traversing a table,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3856 do not call <a href="#lua_tolstring"><code>lua_tolstring</code></a> directly on a key,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3857 unless you know that the key is actually a string.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3858 Recall that <a href="#lua_tolstring"><code>lua_tolstring</code></a> may change
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3859 the value at the given index;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3860 this confuses the next call to <a href="#lua_next"><code>lua_next</code></a>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3861
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3862
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3863 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3864 See function <a href="#pdf-next"><code>next</code></a> for the caveats of modifying
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3865 the table during its traversal.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3866
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3867
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3868
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3869
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3870
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3871 <hr><h3><a name="lua_Number"><code>lua_Number</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3872 <pre>typedef double lua_Number;</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3873
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3874 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3875 The type of floats in Lua.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3876
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3877
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3878 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3879 By default this type is double,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3880 but that can be changed to a single float.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3881 (See <code>LUA_REAL</code> in <code>luaconf.h</code>.)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3882
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3883
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3884
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3885
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3886
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3887 <hr><h3><a name="lua_numbertointeger"><code>lua_numbertointeger</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3888 <pre>int lua_numbertointeger (lua_Number n, lua_Integer *p);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3889
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3890 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3891 Converts a Lua float to a Lua integer.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3892 This macro assumes that <code>n</code> has an integral value.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3893 If that value is within the range of Lua integers,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3894 it is converted to an integer and assigned to <code>*p</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3895 The macro results in a boolean indicating whether the
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3896 conversion was successful.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3897 (Note that this range test can be tricky to do
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3898 correctly without this macro,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3899 due to roundings.)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3900
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3901
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3902 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3903 This macro may evaluate its arguments more than once.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3904
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3905
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3906
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3907
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3908
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3909 <hr><h3><a name="lua_pcall"><code>lua_pcall</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3910 <span class="apii">[-(nargs + 1), +(nresults\|1), –]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3911 <pre>int lua_pcall (lua_State *L, int nargs, int nresults, int msgh);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3912
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3913 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3914 Calls a function in protected mode.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3915
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3916
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3917 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3918 Both <code>nargs</code> and <code>nresults</code> have the same meaning as
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3919 in <a href="#lua_call"><code>lua_call</code></a>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3920 If there are no errors during the call,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3921 <a href="#lua_pcall"><code>lua_pcall</code></a> behaves exactly like <a href="#lua_call"><code>lua_call</code></a>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3922 However, if there is any error,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3923 <a href="#lua_pcall"><code>lua_pcall</code></a> catches it,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3924 pushes a single value on the stack (the error message),
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3925 and returns an error code.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3926 Like <a href="#lua_call"><code>lua_call</code></a>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3927 <a href="#lua_pcall"><code>lua_pcall</code></a> always removes the function
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3928 and its arguments from the stack.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3929
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3930
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3931 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3932 If <code>msgh</code> is 0,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3933 then the error message returned on the stack
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3934 is exactly the original error message.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3935 Otherwise, <code>msgh</code> is the stack index of a
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3936 <em>message handler</em>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3937 (In the current implementation, this index cannot be a pseudo-index.)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3938 In case of runtime errors,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3939 this function will be called with the error message
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3940 and its return value will be the message
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3941 returned on the stack by <a href="#lua_pcall"><code>lua_pcall</code></a>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3942
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3943
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3944 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3945 Typically, the message handler is used to add more debug
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3946 information to the error message, such as a stack traceback.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3947 Such information cannot be gathered after the return of <a href="#lua_pcall"><code>lua_pcall</code></a>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3948 since by then the stack has unwound.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3949
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3950
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3951 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3952 The <a href="#lua_pcall"><code>lua_pcall</code></a> function returns one of the following constants
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3953 (defined in <code>lua.h</code>):
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3954
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3955 <ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3956
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3957 <li><b><a name="pdf-LUA_OK"><code>LUA_OK</code></a> (0): </b>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3958 success.</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3959
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3960 <li><b><a name="pdf-LUA_ERRRUN"><code>LUA_ERRRUN</code></a>: </b>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3961 a runtime error.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3962 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3963
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3964 <li><b><a name="pdf-LUA_ERRMEM"><code>LUA_ERRMEM</code></a>: </b>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3965 memory allocation error.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3966 For such errors, Lua does not call the message handler.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3967 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3968
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3969 <li><b><a name="pdf-LUA_ERRERR"><code>LUA_ERRERR</code></a>: </b>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3970 error while running the message handler.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3971 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3972
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3973 <li><b><a name="pdf-LUA_ERRGCMM"><code>LUA_ERRGCMM</code></a>: </b>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3974 error while running a <code>__gc</code> metamethod.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3975 (This error typically has no relation with the function being called.)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3976 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3977
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3978 </ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3979
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3980
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3981
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3982
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3983 <hr><h3><a name="lua_pcallk"><code>lua_pcallk</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3984 <span class="apii">[-(nargs + 1), +(nresults\|1), –]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3985 <pre>int lua_pcallk (lua_State *L,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3986 int nargs,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3987 int nresults,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3988 int msgh,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3989 lua_KContext ctx,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3990 lua_KFunction k);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3991
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3992 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3993 This function behaves exactly like <a href="#lua_pcall"><code>lua_pcall</code></a>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3994 but allows the called function to yield (see <a href="#4.7">§4.7</a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3995
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3996
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3997
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3998
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3999
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4000 <hr><h3><a name="lua_pop"><code>lua_pop</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4001 <span class="apii">[-n, +0, –]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4002 <pre>void lua_pop (lua_State *L, int n);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4003
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4004 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4005 Pops <code>n</code> elements from the stack.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4006
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4007
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4008
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4009
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4010
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4011 <hr><h3><a name="lua_pushboolean"><code>lua_pushboolean</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4012 <span class="apii">[-0, +1, –]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4013 <pre>void lua_pushboolean (lua_State *L, int b);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4014
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4015 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4016 Pushes a boolean value with value <code>b</code> onto the stack.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4017
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4018
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4019
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4020
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4021
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4022 <hr><h3><a name="lua_pushcclosure"><code>lua_pushcclosure</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4023 <span class="apii">[-n, +1, <em>e</em>]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4024 <pre>void lua_pushcclosure (lua_State *L, lua_CFunction fn, int n);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4025
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4026 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4027 Pushes a new C closure onto the stack.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4028
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4029
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4030 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4031 When a C function is created,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4032 it is possible to associate some values with it,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4033 thus creating a C closure (see <a href="#4.4">§4.4</a>);
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4034 these values are then accessible to the function whenever it is called.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4035 To associate values with a C function,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4036 first these values must be pushed onto the stack
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4037 (when there are multiple values, the first value is pushed first).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4038 Then <a href="#lua_pushcclosure"><code>lua_pushcclosure</code></a>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4039 is called to create and push the C function onto the stack,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4040 with the argument <code>n</code> telling how many values will be
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4041 associated with the function.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4042 <a href="#lua_pushcclosure"><code>lua_pushcclosure</code></a> also pops these values from the stack.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4043
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4044
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4045 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4046 The maximum value for <code>n</code> is 255.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4047
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4048
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4049 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4050 When <code>n</code> is zero,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4051 this function creates a <em>light C function</em>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4052 which is just a pointer to the C function.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4053 In that case, it never raises a memory error.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4054
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4055
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4056
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4057
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4058
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4059 <hr><h3><a name="lua_pushcfunction"><code>lua_pushcfunction</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4060 <span class="apii">[-0, +1, –]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4061 <pre>void lua_pushcfunction (lua_State *L, lua_CFunction f);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4062
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4063 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4064 Pushes a C function onto the stack.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4065 This function receives a pointer to a C function
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4066 and pushes onto the stack a Lua value of type <code>function</code> that,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4067 when called, invokes the corresponding C function.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4068
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4069
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4070 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4071 Any function to be registered in Lua must
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4072 follow the correct protocol to receive its parameters
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4073 and return its results (see <a href="#lua_CFunction"><code>lua_CFunction</code></a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4074
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4075
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4076 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4077 <code>lua_pushcfunction</code> is defined as a macro:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4078
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4079 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4080 #define lua_pushcfunction(L,f) lua_pushcclosure(L,f,0)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4081 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4082 Note that <code>f</code> is used twice.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4083
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4084
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4085
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4086
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4087
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4088 <hr><h3><a name="lua_pushfstring"><code>lua_pushfstring</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4089 <span class="apii">[-0, +1, <em>e</em>]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4090 <pre>const char lua_pushfstring (lua_State L, const char *fmt, ...);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4091
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4092 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4093 Pushes onto the stack a formatted string
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4094 and returns a pointer to this string.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4095 It is similar to the ISO C function <code>sprintf</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4096 but has some important differences:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4097
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4098 <ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4099
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4100 <li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4101 You do not have to allocate space for the result:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4102 the result is a Lua string and Lua takes care of memory allocation
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4103 (and deallocation, through garbage collection).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4104 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4105
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4106 <li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4107 The conversion specifiers are quite restricted.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4108 There are no flags, widths, or precisions.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4109 The conversion specifiers can only be
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4110 '<code>%%</code>' (inserts the character '<code>%</code>'),
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4111 '<code>%s</code>' (inserts a zero-terminated string, with no size restrictions),
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4112 '<code>%f</code>' (inserts a <a href="#lua_Number"><code>lua_Number</code></a>),
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4113 '<code>%L</code>' (inserts a <a href="#lua_Integer"><code>lua_Integer</code></a>),
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4114 '<code>%p</code>' (inserts a pointer as a hexadecimal numeral),
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4115 '<code>%d</code>' (inserts an <code>int</code>),
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4116 '<code>%c</code>' (inserts an <code>int</code> as a one-byte character), and
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4117 '<code>%U</code>' (inserts a <code>long int</code> as a UTF-8 byte sequence).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4118 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4119
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4120 </ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4121
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4122
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4123
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4124
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4125 <hr><h3><a name="lua_pushglobaltable"><code>lua_pushglobaltable</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4126 <span class="apii">[-0, +1, –]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4127 <pre>void lua_pushglobaltable (lua_State *L);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4128
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4129 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4130 Pushes the global environment onto the stack.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4131
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4132
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4133
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4134
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4135
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4136 <hr><h3><a name="lua_pushinteger"><code>lua_pushinteger</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4137 <span class="apii">[-0, +1, –]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4138 <pre>void lua_pushinteger (lua_State *L, lua_Integer n);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4139
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4140 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4141 Pushes an integer with value <code>n</code> onto the stack.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4142
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4143
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4144
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4145
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4146
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4147 <hr><h3><a name="lua_pushlightuserdata"><code>lua_pushlightuserdata</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4148 <span class="apii">[-0, +1, –]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4149 <pre>void lua_pushlightuserdata (lua_State L, void p);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4150
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4151 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4152 Pushes a light userdata onto the stack.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4153
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4154
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4155 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4156 Userdata represent C values in Lua.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4157 A <em>light userdata</em> represents a pointer, a <code>void*</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4158 It is a value (like a number):
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4159 you do not create it, it has no individual metatable,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4160 and it is not collected (as it was never created).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4161 A light userdata is equal to "any"
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4162 light userdata with the same C address.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4163
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4164
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4165
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4166
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4167
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4168 <hr><h3><a name="lua_pushliteral"><code>lua_pushliteral</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4169 <span class="apii">[-0, +1, <em>e</em>]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4170 <pre>const char lua_pushliteral (lua_State L, const char *s);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4171
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4172 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4173 This macro is equivalent to <a href="#lua_pushlstring"><code>lua_pushlstring</code></a>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4174 but can be used only when <code>s</code> is a literal string.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4175 It automatically provides the string length.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4176
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4177
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4178
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4179
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4180
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4181 <hr><h3><a name="lua_pushlstring"><code>lua_pushlstring</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4182 <span class="apii">[-0, +1, <em>e</em>]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4183 <pre>const char lua_pushlstring (lua_State L, const char *s, size_t len);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4184
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4185 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4186 Pushes the string pointed to by <code>s</code> with size <code>len</code>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4187 onto the stack.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4188 Lua makes (or reuses) an internal copy of the given string,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4189 so the memory at <code>s</code> can be freed or reused immediately after
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4190 the function returns.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4191 The string can contain any binary data,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4192 including embedded zeros.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4193
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4194
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4195 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4196 Returns a pointer to the internal copy of the string.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4197
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4198
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4199
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4200
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4201
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4202 <hr><h3><a name="lua_pushnil"><code>lua_pushnil</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4203 <span class="apii">[-0, +1, –]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4204 <pre>void lua_pushnil (lua_State *L);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4205
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4206 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4207 Pushes a nil value onto the stack.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4208
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4209
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4210
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4211
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4212
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4213 <hr><h3><a name="lua_pushnumber"><code>lua_pushnumber</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4214 <span class="apii">[-0, +1, –]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4215 <pre>void lua_pushnumber (lua_State *L, lua_Number n);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4216
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4217 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4218 Pushes a float with value <code>n</code> onto the stack.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4219
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4220
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4221
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4222
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4223
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4224 <hr><h3><a name="lua_pushstring"><code>lua_pushstring</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4225 <span class="apii">[-0, +1, <em>e</em>]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4226 <pre>const char lua_pushstring (lua_State L, const char *s);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4227
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4228 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4229 Pushes the zero-terminated string pointed to by <code>s</code>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4230 onto the stack.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4231 Lua makes (or reuses) an internal copy of the given string,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4232 so the memory at <code>s</code> can be freed or reused immediately after
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4233 the function returns.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4234
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4235
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4236 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4237 Returns a pointer to the internal copy of the string.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4238
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4239
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4240 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4241 If <code>s</code> is <code>NULL</code>, pushes <b>nil</b> and returns <code>NULL</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4242
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4243
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4244
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4245
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4246
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4247 <hr><h3><a name="lua_pushthread"><code>lua_pushthread</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4248 <span class="apii">[-0, +1, –]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4249 <pre>int lua_pushthread (lua_State *L);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4250
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4251 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4252 Pushes the thread represented by <code>L</code> onto the stack.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4253 Returns 1 if this thread is the main thread of its state.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4254
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4255
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4256
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4257
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4258
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4259 <hr><h3><a name="lua_pushvalue"><code>lua_pushvalue</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4260 <span class="apii">[-0, +1, –]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4261 <pre>void lua_pushvalue (lua_State *L, int index);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4262
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4263 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4264 Pushes a copy of the element at the given index
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4265 onto the stack.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4266
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4267
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4268
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4269
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4270
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4271 <hr><h3><a name="lua_pushvfstring"><code>lua_pushvfstring</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4272 <span class="apii">[-0, +1, <em>e</em>]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4273 <pre>const char lua_pushvfstring (lua_State L,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4274 const char *fmt,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4275 va_list argp);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4276
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4277 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4278 Equivalent to <a href="#lua_pushfstring"><code>lua_pushfstring</code></a>, except that it receives a <code>va_list</code>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4279 instead of a variable number of arguments.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4280
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4281
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4282
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4283
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4284
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4285 <hr><h3><a name="lua_rawequal"><code>lua_rawequal</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4286 <span class="apii">[-0, +0, –]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4287 <pre>int lua_rawequal (lua_State *L, int index1, int index2);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4288
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4289 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4290 Returns 1 if the two values in indices <code>index1</code> and
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4291 <code>index2</code> are primitively equal
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4292 (that is, without calling metamethods).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4293 Otherwise returns 0.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4294 Also returns 0 if any of the indices are not valid.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4295
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4296
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4297
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4298
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4299
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4300 <hr><h3><a name="lua_rawget"><code>lua_rawget</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4301 <span class="apii">[-1, +1, –]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4302 <pre>int lua_rawget (lua_State *L, int index);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4303
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4304 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4305 Similar to <a href="#lua_gettable"><code>lua_gettable</code></a>, but does a raw access
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4306 (i.e., without metamethods).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4307
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4308
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4309
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4310
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4311
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4312 <hr><h3><a name="lua_rawgeti"><code>lua_rawgeti</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4313 <span class="apii">[-0, +1, –]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4314 <pre>int lua_rawgeti (lua_State *L, int index, lua_Integer n);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4315
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4316 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4317 Pushes onto the stack the value <code>t[n]</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4318 where <code>t</code> is the table at the given index.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4319 The access is raw;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4320 that is, it does not invoke metamethods.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4321
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4322
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4323 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4324 Returns the type of the pushed value.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4325
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4326
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4327
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4328
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4329
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4330 <hr><h3><a name="lua_rawgetp"><code>lua_rawgetp</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4331 <span class="apii">[-0, +1, –]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4332 <pre>int lua_rawgetp (lua_State L, int index, const void p);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4333
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4334 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4335 Pushes onto the stack the value <code>t[k]</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4336 where <code>t</code> is the table at the given index and
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4337 <code>k</code> is the pointer <code>p</code> represented as a light userdata.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4338 The access is raw;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4339 that is, it does not invoke metamethods.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4340
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4341
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4342 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4343 Returns the type of the pushed value.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4344
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4345
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4346
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4347
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4348
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4349 <hr><h3><a name="lua_rawlen"><code>lua_rawlen</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4350 <span class="apii">[-0, +0, –]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4351 <pre>size_t lua_rawlen (lua_State *L, int index);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4352
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4353 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4354 Returns the raw "length" of the value at the given index:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4355 for strings, this is the string length;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4356 for tables, this is the result of the length operator ('<code>#</code>')
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4357 with no metamethods;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4358 for userdata, this is the size of the block of memory allocated
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4359 for the userdata;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4360 for other values, it is 0.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4361
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4362
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4363
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4364
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4365
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4366 <hr><h3><a name="lua_rawset"><code>lua_rawset</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4367 <span class="apii">[-2, +0, <em>e</em>]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4368 <pre>void lua_rawset (lua_State *L, int index);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4369
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4370 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4371 Similar to <a href="#lua_settable"><code>lua_settable</code></a>, but does a raw assignment
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4372 (i.e., without metamethods).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4373
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4374
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4375
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4376
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4377
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4378 <hr><h3><a name="lua_rawseti"><code>lua_rawseti</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4379 <span class="apii">[-1, +0, <em>e</em>]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4380 <pre>void lua_rawseti (lua_State *L, int index, lua_Integer i);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4381
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4382 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4383 Does the equivalent of <code>t[i] = v</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4384 where <code>t</code> is the table at the given index
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4385 and <code>v</code> is the value at the top of the stack.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4386
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4387
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4388 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4389 This function pops the value from the stack.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4390 The assignment is raw;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4391 that is, it does not invoke metamethods.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4392
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4393
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4394
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4395
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4396
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4397 <hr><h3><a name="lua_rawsetp"><code>lua_rawsetp</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4398 <span class="apii">[-1, +0, <em>e</em>]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4399 <pre>void lua_rawsetp (lua_State L, int index, const void p);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4400
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4401 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4402 Does the equivalent of <code>t[k] = v</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4403 where <code>t</code> is the table at the given index,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4404 <code>k</code> is the pointer <code>p</code> represented as a light userdata,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4405 and <code>v</code> is the value at the top of the stack.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4406
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4407
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4408 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4409 This function pops the value from the stack.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4410 The assignment is raw;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4411 that is, it does not invoke metamethods.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4412
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4413
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4414
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4415
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4416
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4417 <hr><h3><a name="lua_Reader"><code>lua_Reader</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4418 <pre>typedef const char * (lua_Reader) (lua_State L,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4419 void *data,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4420 size_t *size);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4421
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4422 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4423 The reader function used by <a href="#lua_load"><code>lua_load</code></a>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4424 Every time it needs another piece of the chunk,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4425 <a href="#lua_load"><code>lua_load</code></a> calls the reader,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4426 passing along its <code>data</code> parameter.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4427 The reader must return a pointer to a block of memory
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4428 with a new piece of the chunk
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4429 and set <code>size</code> to the block size.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4430 The block must exist until the reader function is called again.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4431 To signal the end of the chunk,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4432 the reader must return <code>NULL</code> or set <code>size</code> to zero.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4433 The reader function may return pieces of any size greater than zero.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4434
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4435
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4436
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4437
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4438
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4439 <hr><h3><a name="lua_register"><code>lua_register</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4440 <span class="apii">[-0, +0, <em>e</em>]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4441 <pre>void lua_register (lua_State L, const char name, lua_CFunction f);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4442
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4443 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4444 Sets the C function <code>f</code> as the new value of global <code>name</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4445 It is defined as a macro:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4446
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4447 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4448 #define lua_register(L,n,f) \
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4449 (lua_pushcfunction(L, f), lua_setglobal(L, n))
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4450 </pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4451
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4452
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4453
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4454
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4455 <hr><h3><a name="lua_remove"><code>lua_remove</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4456 <span class="apii">[-1, +0, –]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4457 <pre>void lua_remove (lua_State *L, int index);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4458
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4459 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4460 Removes the element at the given valid index,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4461 shifting down the elements above this index to fill the gap.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4462 This function cannot be called with a pseudo-index,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4463 because a pseudo-index is not an actual stack position.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4464
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4465
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4466
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4467
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4468
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4469 <hr><h3><a name="lua_replace"><code>lua_replace</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4470 <span class="apii">[-1, +0, –]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4471 <pre>void lua_replace (lua_State *L, int index);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4472
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4473 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4474 Moves the top element into the given valid index
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4475 without shifting any element
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4476 (therefore replacing the value at the given index),
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4477 and then pops the top element.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4478
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4479
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4480
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4481
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4482
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4483 <hr><h3><a name="lua_resume"><code>lua_resume</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4484 <span class="apii">[-?, +?, –]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4485 <pre>int lua_resume (lua_State L, lua_State from, int nargs);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4486
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4487 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4488 Starts and resumes a coroutine in a given thread.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4489
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4490
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4491 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4492 To start a coroutine,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4493 you push onto the thread stack the main function plus any arguments;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4494 then you call <a href="#lua_resume"><code>lua_resume</code></a>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4495 with <code>nargs</code> being the number of arguments.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4496 This call returns when the coroutine suspends or finishes its execution.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4497 When it returns, the stack contains all values passed to <a href="#lua_yield"><code>lua_yield</code></a>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4498 or all values returned by the body function.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4499 <a href="#lua_resume"><code>lua_resume</code></a> returns
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4500 <a href="#pdf-LUA_YIELD"><code>LUA_YIELD</code></a> if the coroutine yields,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4501 <a href="#pdf-LUA_OK"><code>LUA_OK</code></a> if the coroutine finishes its execution
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4502 without errors,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4503 or an error code in case of errors (see <a href="#lua_pcall"><code>lua_pcall</code></a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4504
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4505
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4506 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4507 In case of errors,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4508 the stack is not unwound,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4509 so you can use the debug API over it.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4510 The error message is on the top of the stack.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4511
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4512
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4513 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4514 To resume a coroutine,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4515 you remove any results from the last <a href="#lua_yield"><code>lua_yield</code></a>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4516 put on its stack only the values to
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4517 be passed as results from <code>yield</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4518 and then call <a href="#lua_resume"><code>lua_resume</code></a>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4519
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4520
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4521 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4522 The parameter <code>from</code> represents the coroutine that is resuming <code>L</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4523 If there is no such coroutine,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4524 this parameter can be <code>NULL</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4525
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4526
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4527
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4528
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4529
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4530 <hr><h3><a name="lua_rotate"><code>lua_rotate</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4531 <span class="apii">[-0, +0, –]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4532 <pre>void lua_rotate (lua_State *L, int idx, int n);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4533
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4534 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4535 Rotates the stack elements from <code>idx</code> to the top <code>n</code> positions
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4536 in the direction of the top, for a positive <code>n</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4537 or <code>-n</code> positions in the direction of the bottom,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4538 for a negative <code>n</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4539 The absolute value of <code>n</code> must not be greater than the size
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4540 of the slice being rotated.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4541
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4542
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4543
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4544
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4545
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4546 <hr><h3><a name="lua_setallocf"><code>lua_setallocf</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4547 <span class="apii">[-0, +0, –]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4548 <pre>void lua_setallocf (lua_State L, lua_Alloc f, void ud);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4549
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4550 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4551 Changes the allocator function of a given state to <code>f</code>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4552 with user data <code>ud</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4553
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4554
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4555
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4556
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4557
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4558 <hr><h3><a name="lua_setfield"><code>lua_setfield</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4559 <span class="apii">[-1, +0, <em>e</em>]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4560 <pre>void lua_setfield (lua_State L, int index, const char k);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4561
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4562 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4563 Does the equivalent to <code>t[k] = v</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4564 where <code>t</code> is the value at the given index
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4565 and <code>v</code> is the value at the top of the stack.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4566
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4567
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4568 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4569 This function pops the value from the stack.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4570 As in Lua, this function may trigger a metamethod
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4571 for the "newindex" event (see <a href="#2.4">§2.4</a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4572
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4573
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4574
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4575
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4576
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4577 <hr><h3><a name="lua_setglobal"><code>lua_setglobal</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4578 <span class="apii">[-1, +0, <em>e</em>]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4579 <pre>void lua_setglobal (lua_State L, const char name);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4580
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4581 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4582 Pops a value from the stack and
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4583 sets it as the new value of global <code>name</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4584
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4585
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4586
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4587
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4588
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4589 <hr><h3><a name="lua_seti"><code>lua_seti</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4590 <span class="apii">[-1, +0, <em>e</em>]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4591 <pre>void lua_seti (lua_State *L, int index, lua_Integer n);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4592
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4593 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4594 Does the equivalent to <code>t[n] = v</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4595 where <code>t</code> is the value at the given index
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4596 and <code>v</code> is the value at the top of the stack.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4597
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4598
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4599 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4600 This function pops the value from the stack.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4601 As in Lua, this function may trigger a metamethod
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4602 for the "newindex" event (see <a href="#2.4">§2.4</a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4603
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4604
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4605
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4606
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4607
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4608 <hr><h3><a name="lua_setmetatable"><code>lua_setmetatable</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4609 <span class="apii">[-1, +0, –]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4610 <pre>void lua_setmetatable (lua_State *L, int index);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4611
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4612 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4613 Pops a table from the stack and
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4614 sets it as the new metatable for the value at the given index.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4615
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4616
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4617
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4618
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4619
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4620 <hr><h3><a name="lua_settable"><code>lua_settable</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4621 <span class="apii">[-2, +0, <em>e</em>]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4622 <pre>void lua_settable (lua_State *L, int index);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4623
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4624 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4625 Does the equivalent to <code>t[k] = v</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4626 where <code>t</code> is the value at the given index,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4627 <code>v</code> is the value at the top of the stack,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4628 and <code>k</code> is the value just below the top.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4629
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4630
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4631 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4632 This function pops both the key and the value from the stack.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4633 As in Lua, this function may trigger a metamethod
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4634 for the "newindex" event (see <a href="#2.4">§2.4</a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4635
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4636
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4637
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4638
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4639
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4640 <hr><h3><a name="lua_settop"><code>lua_settop</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4641 <span class="apii">[-?, +?, –]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4642 <pre>void lua_settop (lua_State *L, int index);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4643
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4644 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4645 Accepts any index, or 0,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4646 and sets the stack top to this index.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4647 If the new top is larger than the old one,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4648 then the new elements are filled with <b>nil</b>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4649 If <code>index</code> is 0, then all stack elements are removed.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4650
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4651
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4652
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4653
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4654
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4655 <hr><h3><a name="lua_setuservalue"><code>lua_setuservalue</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4656 <span class="apii">[-1, +0, –]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4657 <pre>void lua_setuservalue (lua_State *L, int index);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4658
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4659 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4660 Pops a value from the stack and sets it as
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4661 the new value associated to the userdata at the given index.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4662
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4663
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4664
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4665
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4666
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4667 <hr><h3><a name="lua_State"><code>lua_State</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4668 <pre>typedef struct lua_State lua_State;</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4669
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4670 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4671 An opaque structure that points to a thread and indirectly
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4672 (through the thread) to the whole state of a Lua interpreter.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4673 The Lua library is fully reentrant:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4674 it has no global variables.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4675 All information about a state is accessible through this structure.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4676
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4677
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4678 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4679 A pointer to this structure must be passed as the first argument to
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4680 every function in the library, except to <a href="#lua_newstate"><code>lua_newstate</code></a>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4681 which creates a Lua state from scratch.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4682
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4683
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4684
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4685
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4686
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4687 <hr><h3><a name="lua_status"><code>lua_status</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4688 <span class="apii">[-0, +0, –]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4689 <pre>int lua_status (lua_State *L);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4690
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4691 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4692 Returns the status of the thread <code>L</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4693
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4694
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4695 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4696 The status can be 0 (<a href="#pdf-LUA_OK"><code>LUA_OK</code></a>) for a normal thread,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4697 an error code if the thread finished the execution
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4698 of a <a href="#lua_resume"><code>lua_resume</code></a> with an error,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4699 or <a name="pdf-LUA_YIELD"><code>LUA_YIELD</code></a> if the thread is suspended.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4700
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4701
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4702 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4703 You can only call functions in threads with status <a href="#pdf-LUA_OK"><code>LUA_OK</code></a>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4704 You can resume threads with status <a href="#pdf-LUA_OK"><code>LUA_OK</code></a>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4705 (to start a new coroutine) or <a href="#pdf-LUA_YIELD"><code>LUA_YIELD</code></a>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4706 (to resume a coroutine).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4707
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4708
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4709
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4710
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4711
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4712 <hr><h3><a name="lua_stringtonumber"><code>lua_stringtonumber</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4713 <span class="apii">[-0, +1, –]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4714 <pre>size_t lua_stringtonumber (lua_State L, const char s);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4715
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4716 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4717 Converts the zero-terminated string <code>s</code> to a number,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4718 pushes that number into the stack,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4719 and returns the total size of the string,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4720 that is, its length plus one.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4721 The conversion can result in an integer or a float,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4722 according to the lexical conventions of Lua (see <a href="#3.1">§3.1</a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4723 The string may have leading and trailing spaces and a sign.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4724 If the string is not a valid numeral,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4725 returns 0 and pushes nothing.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4726 (Note that the result can be used as a boolean,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4727 true if the conversion succeeds.)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4728
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4729
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4730
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4731
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4732
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4733 <hr><h3><a name="lua_toboolean"><code>lua_toboolean</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4734 <span class="apii">[-0, +0, –]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4735 <pre>int lua_toboolean (lua_State *L, int index);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4736
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4737 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4738 Converts the Lua value at the given index to a C boolean
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4739 value (0 or 1).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4740 Like all tests in Lua,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4741 <a href="#lua_toboolean"><code>lua_toboolean</code></a> returns true for any Lua value
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4742 different from <b>false</b> and <b>nil</b>;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4743 otherwise it returns false.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4744 (If you want to accept only actual boolean values,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4745 use <a href="#lua_isboolean"><code>lua_isboolean</code></a> to test the value's type.)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4746
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4747
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4748
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4749
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4750
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4751 <hr><h3><a name="lua_tocfunction"><code>lua_tocfunction</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4752 <span class="apii">[-0, +0, –]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4753 <pre>lua_CFunction lua_tocfunction (lua_State *L, int index);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4754
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4755 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4756 Converts a value at the given index to a C function.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4757 That value must be a C function;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4758 otherwise, returns <code>NULL</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4759
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4760
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4761
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4762
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4763
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4764 <hr><h3><a name="lua_tointeger"><code>lua_tointeger</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4765 <span class="apii">[-0, +0, –]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4766 <pre>lua_Integer lua_tointeger (lua_State *L, int index);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4767
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4768 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4769 Equivalent to <a href="#lua_tointegerx"><code>lua_tointegerx</code></a> with <code>isnum</code> equal to <code>NULL</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4770
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4771
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4772
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4773
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4774
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4775 <hr><h3><a name="lua_tointegerx"><code>lua_tointegerx</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4776 <span class="apii">[-0, +0, –]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4777 <pre>lua_Integer lua_tointegerx (lua_State L, int index, int isnum);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4778
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4779 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4780 Converts the Lua value at the given index
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4781 to the signed integral type <a href="#lua_Integer"><code>lua_Integer</code></a>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4782 The Lua value must be an integer,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4783 or a number or string convertible to an integer (see <a href="#3.4.3">§3.4.3</a>);
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4784 otherwise, <code>lua_tointegerx</code> returns 0.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4785
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4786
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4787 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4788 If <code>isnum</code> is not <code>NULL</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4789 its referent is assigned a boolean value that
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4790 indicates whether the operation succeeded.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4791
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4792
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4793
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4794
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4795
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4796 <hr><h3><a name="lua_tolstring"><code>lua_tolstring</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4797 <span class="apii">[-0, +0, <em>e</em>]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4798 <pre>const char lua_tolstring (lua_State L, int index, size_t *len);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4799
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4800 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4801 Converts the Lua value at the given index to a C string.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4802 If <code>len</code> is not <code>NULL</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4803 it also sets <code>*len</code> with the string length.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4804 The Lua value must be a string or a number;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4805 otherwise, the function returns <code>NULL</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4806 If the value is a number,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4807 then <code>lua_tolstring</code> also
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4808 <em>changes the actual value in the stack to a string</em>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4809 (This change confuses <a href="#lua_next"><code>lua_next</code></a>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4810 when <code>lua_tolstring</code> is applied to keys during a table traversal.)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4811
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4812
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4813 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4814 <code>lua_tolstring</code> returns a fully aligned pointer
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4815 to a string inside the Lua state.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4816 This string always has a zero ('<code>\0</code>')
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4817 after its last character (as in C),
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4818 but can contain other zeros in its body.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4819
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4820
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4821 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4822 Because Lua has garbage collection,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4823 there is no guarantee that the pointer returned by <code>lua_tolstring</code>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4824 will be valid after the corresponding Lua value is removed from the stack.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4825
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4826
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4827
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4828
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4829
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4830 <hr><h3><a name="lua_tonumber"><code>lua_tonumber</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4831 <span class="apii">[-0, +0, –]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4832 <pre>lua_Number lua_tonumber (lua_State *L, int index);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4833
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4834 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4835 Equivalent to <a href="#lua_tonumberx"><code>lua_tonumberx</code></a> with <code>isnum</code> equal to <code>NULL</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4836
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4837
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4838
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4839
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4840
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4841 <hr><h3><a name="lua_tonumberx"><code>lua_tonumberx</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4842 <span class="apii">[-0, +0, –]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4843 <pre>lua_Number lua_tonumberx (lua_State L, int index, int isnum);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4844
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4845 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4846 Converts the Lua value at the given index
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4847 to the C type <a href="#lua_Number"><code>lua_Number</code></a> (see <a href="#lua_Number"><code>lua_Number</code></a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4848 The Lua value must be a number or a string convertible to a number
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4849 (see <a href="#3.4.3">§3.4.3</a>);
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4850 otherwise, <a href="#lua_tonumberx"><code>lua_tonumberx</code></a> returns 0.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4851
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4852
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4853 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4854 If <code>isnum</code> is not <code>NULL</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4855 its referent is assigned a boolean value that
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4856 indicates whether the operation succeeded.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4857
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4858
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4859
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4860
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4861
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4862 <hr><h3><a name="lua_topointer"><code>lua_topointer</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4863 <span class="apii">[-0, +0, –]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4864 <pre>const void lua_topointer (lua_State L, int index);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4865
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4866 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4867 Converts the value at the given index to a generic
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4868 C pointer (<code>void*</code>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4869 The value can be a userdata, a table, a thread, or a function;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4870 otherwise, <code>lua_topointer</code> returns <code>NULL</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4871 Different objects will give different pointers.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4872 There is no way to convert the pointer back to its original value.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4873
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4874
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4875 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4876 Typically this function is used only for debug information.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4877
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4878
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4879
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4880
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4881
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4882 <hr><h3><a name="lua_tostring"><code>lua_tostring</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4883 <span class="apii">[-0, +0, <em>e</em>]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4884 <pre>const char lua_tostring (lua_State L, int index);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4885
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4886 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4887 Equivalent to <a href="#lua_tolstring"><code>lua_tolstring</code></a> with <code>len</code> equal to <code>NULL</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4888
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4889
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4890
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4891
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4892
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4893 <hr><h3><a name="lua_tothread"><code>lua_tothread</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4894 <span class="apii">[-0, +0, –]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4895 <pre>lua_State lua_tothread (lua_State L, int index);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4896
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4897 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4898 Converts the value at the given index to a Lua thread
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4899 (represented as <code>lua_State*</code>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4900 This value must be a thread;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4901 otherwise, the function returns <code>NULL</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4902
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4903
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4904
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4905
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4906
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4907 <hr><h3><a name="lua_touserdata"><code>lua_touserdata</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4908 <span class="apii">[-0, +0, –]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4909 <pre>void lua_touserdata (lua_State L, int index);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4910
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4911 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4912 If the value at the given index is a full userdata,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4913 returns its block address.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4914 If the value is a light userdata,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4915 returns its pointer.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4916 Otherwise, returns <code>NULL</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4917
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4918
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4919
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4920
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4921
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4922 <hr><h3><a name="lua_type"><code>lua_type</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4923 <span class="apii">[-0, +0, –]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4924 <pre>int lua_type (lua_State *L, int index);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4925
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4926 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4927 Returns the type of the value in the given valid index,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4928 or <code>LUA_TNONE</code> for a non-valid (but acceptable) index.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4929 The types returned by <a href="#lua_type"><code>lua_type</code></a> are coded by the following constants
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4930 defined in <code>lua.h</code>:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4931 <a name="pdf-LUA_TNIL"><code>LUA_TNIL</code></a>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4932 <a name="pdf-LUA_TNUMBER"><code>LUA_TNUMBER</code></a>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4933 <a name="pdf-LUA_TBOOLEAN"><code>LUA_TBOOLEAN</code></a>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4934 <a name="pdf-LUA_TSTRING"><code>LUA_TSTRING</code></a>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4935 <a name="pdf-LUA_TTABLE"><code>LUA_TTABLE</code></a>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4936 <a name="pdf-LUA_TFUNCTION"><code>LUA_TFUNCTION</code></a>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4937 <a name="pdf-LUA_TUSERDATA"><code>LUA_TUSERDATA</code></a>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4938 <a name="pdf-LUA_TTHREAD"><code>LUA_TTHREAD</code></a>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4939 and
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4940 <a name="pdf-LUA_TLIGHTUSERDATA"><code>LUA_TLIGHTUSERDATA</code></a>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4941
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4942
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4943
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4944
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4945
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4946 <hr><h3><a name="lua_typename"><code>lua_typename</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4947 <span class="apii">[-0, +0, –]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4948 <pre>const char lua_typename (lua_State L, int tp);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4949
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4950 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4951 Returns the name of the type encoded by the value <code>tp</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4952 which must be one the values returned by <a href="#lua_type"><code>lua_type</code></a>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4953
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4954
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4955
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4956
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4957
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4958 <hr><h3><a name="lua_Unsigned"><code>lua_Unsigned</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4959 <pre>typedef ... lua_Unsigned;</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4960
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4961 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4962 The unsigned version of <a href="#lua_Integer"><code>lua_Integer</code></a>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4963
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4964
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4965
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4966
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4967
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4968 <hr><h3><a name="lua_upvalueindex"><code>lua_upvalueindex</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4969 <span class="apii">[-0, +0, –]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4970 <pre>int lua_upvalueindex (int i);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4971
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4972 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4973 Returns the pseudo-index that represents the <code>i</code>-th upvalue of
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4974 the running function (see <a href="#4.4">§4.4</a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4975
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4976
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4977
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4978
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4979
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4980 <hr><h3><a name="lua_version"><code>lua_version</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4981 <span class="apii">[-0, +0, <em>v</em>]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4982 <pre>const lua_Number lua_version (lua_State L);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4983
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4984 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4985 Returns the address of the version number stored in the Lua core.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4986 When called with a valid <a href="#lua_State"><code>lua_State</code></a>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4987 returns the address of the version used to create that state.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4988 When called with <code>NULL</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4989 returns the address of the version running the call.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4990
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4991
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4992
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4993
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4994
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4995 <hr><h3><a name="lua_Writer"><code>lua_Writer</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4996 <pre>typedef int (lua_Writer) (lua_State L,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4997 const void* p,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4998 size_t sz,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4999 void* ud);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5000
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5001 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5002 The type of the writer function used by <a href="#lua_dump"><code>lua_dump</code></a>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5003 Every time it produces another piece of chunk,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5004 <a href="#lua_dump"><code>lua_dump</code></a> calls the writer,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5005 passing along the buffer to be written (<code>p</code>),
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5006 its size (<code>sz</code>),
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5007 and the <code>data</code> parameter supplied to <a href="#lua_dump"><code>lua_dump</code></a>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5008
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5009
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5010 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5011 The writer returns an error code:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5012 0 means no errors;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5013 any other value means an error and stops <a href="#lua_dump"><code>lua_dump</code></a> from
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5014 calling the writer again.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5015
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5016
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5017
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5018
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5019
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5020 <hr><h3><a name="lua_xmove"><code>lua_xmove</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5021 <span class="apii">[-?, +?, –]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5022 <pre>void lua_xmove (lua_State from, lua_State to, int n);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5023
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5024 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5025 Exchange values between different threads of the same state.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5026
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5027
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5028 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5029 This function pops <code>n</code> values from the stack <code>from</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5030 and pushes them onto the stack <code>to</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5031
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5032
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5033
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5034
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5035
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5036 <hr><h3><a name="lua_yield"><code>lua_yield</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5037 <span class="apii">[-?, +?, <em>e</em>]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5038 <pre>int lua_yield (lua_State *L, int nresults);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5039
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5040 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5041 This function is equivalent to <a href="#lua_yieldk"><code>lua_yieldk</code></a>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5042 but it has no continuation (see <a href="#4.7">§4.7</a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5043 Therefore, when the thread resumes,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5044 it continues the function that called
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5045 the function calling <code>lua_yield</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5046
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5047
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5048
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5049
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5050
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5051 <hr><h3><a name="lua_yieldk"><code>lua_yieldk</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5052 <span class="apii">[-?, +?, <em>e</em>]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5053 <pre>int lua_yieldk (lua_State *L,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5054 int nresults,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5055 lua_KContext ctx,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5056 lua_KFunction k);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5057
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5058 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5059 Yields a coroutine (thread).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5060
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5061
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5062 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5063 When a C function calls <a href="#lua_yieldk"><code>lua_yieldk</code></a>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5064 the running coroutine suspends its execution,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5065 and the call to <a href="#lua_resume"><code>lua_resume</code></a> that started this coroutine returns.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5066 The parameter <code>nresults</code> is the number of values from the stack
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5067 that will be passed as results to <a href="#lua_resume"><code>lua_resume</code></a>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5068
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5069
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5070 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5071 When the coroutine is resumed again,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5072 Lua calls the given continuation function <code>k</code> to continue
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5073 the execution of the C function that yielded (see <a href="#4.7">§4.7</a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5074 This continuation function receives the same stack
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5075 from the previous function,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5076 with the <code>n</code> results removed and
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5077 replaced by the arguments passed to <a href="#lua_resume"><code>lua_resume</code></a>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5078 Moreover,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5079 the continuation function receives the value <code>ctx</code>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5080 that was passed to <a href="#lua_yieldk"><code>lua_yieldk</code></a>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5081
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5082
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5083 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5084 Usually, this function does not return;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5085 when the coroutine eventually resumes,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5086 it continues executing the continuation function.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5087 However, there is one special case,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5088 which is when this function is called
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5089 from inside a line hook (see <a href="#4.9">§4.9</a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5090 In that case, <code>lua_yieldk</code> should be called with no continuation
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5091 (probably in the form of <a href="#lua_yield"><code>lua_yield</code></a>),
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5092 and the hook should return immediately after the call.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5093 Lua will yield and,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5094 when the coroutine resumes again,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5095 it will continue the normal execution
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5096 of the (Lua) function that triggered the hook.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5097
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5098
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5099 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5100 This function can raise an error if it is called from a thread
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5101 with a pending C call with no continuation function,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5102 or it is called from a thread that is not running inside a resume
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5103 (e.g., the main thread).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5104
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5105
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5106
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5107
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5108
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5109
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5110
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5111 <h2>4.9 – <a name="4.9">The Debug Interface</a></h2>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5112
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5113 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5114 Lua has no built-in debugging facilities.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5115 Instead, it offers a special interface
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5116 by means of functions and <em>hooks</em>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5117 This interface allows the construction of different
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5118 kinds of debuggers, profilers, and other tools
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5119 that need "inside information" from the interpreter.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5120
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5121
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5122
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5123 <hr><h3><a name="lua_Debug"><code>lua_Debug</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5124 <pre>typedef struct lua_Debug {
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5125 int event;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5126 const char name; / (n) */
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5127 const char namewhat; / (n) */
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5128 const char what; / (S) */
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5129 const char source; / (S) */
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5130 int currentline; /* (l) */
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5131 int linedefined; /* (S) */
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5132 int lastlinedefined; /* (S) */
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5133 unsigned char nups; /* (u) number of upvalues */
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5134 unsigned char nparams; /* (u) number of parameters */
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5135 char isvararg; /* (u) */
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5136 char istailcall; /* (t) */
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5137 char short_src[LUA_IDSIZE]; /* (S) */
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5138 /* private part */
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5139 <em>other fields</em>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5140 } lua_Debug;</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5141
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5142 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5143 A structure used to carry different pieces of
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5144 information about a function or an activation record.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5145 <a href="#lua_getstack"><code>lua_getstack</code></a> fills only the private part
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5146 of this structure, for later use.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5147 To fill the other fields of <a href="#lua_Debug"><code>lua_Debug</code></a> with useful information,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5148 call <a href="#lua_getinfo"><code>lua_getinfo</code></a>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5149
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5150
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5151 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5152 The fields of <a href="#lua_Debug"><code>lua_Debug</code></a> have the following meaning:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5153
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5154 <ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5155
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5156 <li><b><code>source</code>: </b>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5157 the name of the chunk that created the function.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5158 If <code>source</code> starts with a '<code>@</code>',
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5159 it means that the function was defined in a file where
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5160 the file name follows the '<code>@</code>'.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5161 If <code>source</code> starts with a '<code>=</code>',
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5162 the remainder of its contents describe the source in a user-dependent manner.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5163 Otherwise,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5164 the function was defined in a string where
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5165 <code>source</code> is that string.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5166 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5167
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5168 <li><b><code>short_src</code>: </b>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5169 a "printable" version of <code>source</code>, to be used in error messages.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5170 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5171
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5172 <li><b><code>linedefined</code>: </b>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5173 the line number where the definition of the function starts.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5174 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5175
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5176 <li><b><code>lastlinedefined</code>: </b>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5177 the line number where the definition of the function ends.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5178 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5179
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5180 <li><b><code>what</code>: </b>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5181 the string <code>"Lua"</code> if the function is a Lua function,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5182 <code>"C"</code> if it is a C function,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5183 <code>"main"</code> if it is the main part of a chunk.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5184 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5185
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5186 <li><b><code>currentline</code>: </b>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5187 the current line where the given function is executing.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5188 When no line information is available,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5189 <code>currentline</code> is set to -1.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5190 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5191
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5192 <li><b><code>name</code>: </b>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5193 a reasonable name for the given function.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5194 Because functions in Lua are first-class values,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5195 they do not have a fixed name:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5196 some functions can be the value of multiple global variables,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5197 while others can be stored only in a table field.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5198 The <code>lua_getinfo</code> function checks how the function was
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5199 called to find a suitable name.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5200 If it cannot find a name,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5201 then <code>name</code> is set to <code>NULL</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5202 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5203
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5204 <li><b><code>namewhat</code>: </b>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5205 explains the <code>name</code> field.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5206 The value of <code>namewhat</code> can be
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5207 <code>"global"</code>, <code>"local"</code>, <code>"method"</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5208 <code>"field"</code>, <code>"upvalue"</code>, or <code>""</code> (the empty string),
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5209 according to how the function was called.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5210 (Lua uses the empty string when no other option seems to apply.)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5211 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5212
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5213 <li><b><code>istailcall</code>: </b>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5214 true if this function invocation was called by a tail call.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5215 In this case, the caller of this level is not in the stack.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5216 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5217
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5218 <li><b><code>nups</code>: </b>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5219 the number of upvalues of the function.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5220 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5221
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5222 <li><b><code>nparams</code>: </b>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5223 the number of fixed parameters of the function
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5224 (always 0 for C functions).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5225 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5226
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5227 <li><b><code>isvararg</code>: </b>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5228 true if the function is a vararg function
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5229 (always true for C functions).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5230 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5231
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5232 </ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5233
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5234
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5235
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5236
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5237 <hr><h3><a name="lua_gethook"><code>lua_gethook</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5238 <span class="apii">[-0, +0, –]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5239 <pre>lua_Hook lua_gethook (lua_State *L);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5240
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5241 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5242 Returns the current hook function.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5243
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5244
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5245
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5246
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5247
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5248 <hr><h3><a name="lua_gethookcount"><code>lua_gethookcount</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5249 <span class="apii">[-0, +0, –]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5250 <pre>int lua_gethookcount (lua_State *L);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5251
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5252 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5253 Returns the current hook count.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5254
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5255
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5256
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5257
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5258
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5259 <hr><h3><a name="lua_gethookmask"><code>lua_gethookmask</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5260 <span class="apii">[-0, +0, –]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5261 <pre>int lua_gethookmask (lua_State *L);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5262
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5263 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5264 Returns the current hook mask.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5265
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5266
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5267
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5268
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5269
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5270 <hr><h3><a name="lua_getinfo"><code>lua_getinfo</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5271 <span class="apii">[-(0\|1), +(0\|1\|2), <em>e</em>]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5272 <pre>int lua_getinfo (lua_State L, const char what, lua_Debug *ar);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5273
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5274 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5275 Gets information about a specific function or function invocation.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5276
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5277
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5278 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5279 To get information about a function invocation,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5280 the parameter <code>ar</code> must be a valid activation record that was
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5281 filled by a previous call to <a href="#lua_getstack"><code>lua_getstack</code></a> or
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5282 given as argument to a hook (see <a href="#lua_Hook"><code>lua_Hook</code></a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5283
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5284
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5285 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5286 To get information about a function you push it onto the stack
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5287 and start the <code>what</code> string with the character '<code>></code>'.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5288 (In that case,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5289 <code>lua_getinfo</code> pops the function from the top of the stack.)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5290 For instance, to know in which line a function <code>f</code> was defined,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5291 you can write the following code:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5292
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5293 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5294 lua_Debug ar;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5295 lua_getglobal(L, "f"); /* get global 'f' */
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5296 lua_getinfo(L, ">S", &ar);
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5297 printf("%d\n", ar.linedefined);
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5298 </pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5299
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5300 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5301 Each character in the string <code>what</code>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5302 selects some fields of the structure <code>ar</code> to be filled or
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5303 a value to be pushed on the stack:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5304
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5305 <ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5306
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5307 <li><b>'<code>n</code>': </b> fills in the field <code>name</code> and <code>namewhat</code>;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5308 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5309
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5310 <li><b>'<code>S</code>': </b>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5311 fills in the fields <code>source</code>, <code>short_src</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5312 <code>linedefined</code>, <code>lastlinedefined</code>, and <code>what</code>;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5313 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5314
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5315 <li><b>'<code>l</code>': </b> fills in the field <code>currentline</code>;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5316 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5317
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5318 <li><b>'<code>t</code>': </b> fills in the field <code>istailcall</code>;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5319 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5320
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5321 <li><b>'<code>u</code>': </b> fills in the fields
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5322 <code>nups</code>, <code>nparams</code>, and <code>isvararg</code>;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5323 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5324
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5325 <li><b>'<code>f</code>': </b>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5326 pushes onto the stack the function that is
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5327 running at the given level;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5328 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5329
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5330 <li><b>'<code>L</code>': </b>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5331 pushes onto the stack a table whose indices are the
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5332 numbers of the lines that are valid on the function.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5333 (A <em>valid line</em> is a line with some associated code,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5334 that is, a line where you can put a break point.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5335 Non-valid lines include empty lines and comments.)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5336
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5337
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5338 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5339 If this option is given together with option '<code>f</code>',
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5340 its table is pushed after the function.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5341 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5342
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5343 </ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5344
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5345 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5346 This function returns 0 on error
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5347 (for instance, an invalid option in <code>what</code>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5348
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5349
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5350
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5351
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5352
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5353 <hr><h3><a name="lua_getlocal"><code>lua_getlocal</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5354 <span class="apii">[-0, +(0\|1), –]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5355 <pre>const char lua_getlocal (lua_State L, const lua_Debug *ar, int n);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5356
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5357 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5358 Gets information about a local variable of
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5359 a given activation record or a given function.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5360
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5361
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5362 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5363 In the first case,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5364 the parameter <code>ar</code> must be a valid activation record that was
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5365 filled by a previous call to <a href="#lua_getstack"><code>lua_getstack</code></a> or
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5366 given as argument to a hook (see <a href="#lua_Hook"><code>lua_Hook</code></a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5367 The index <code>n</code> selects which local variable to inspect;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5368 see <a href="#pdf-debug.getlocal"><code>debug.getlocal</code></a> for details about variable indices
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5369 and names.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5370
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5371
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5372 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5373 <a href="#lua_getlocal"><code>lua_getlocal</code></a> pushes the variable's value onto the stack
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5374 and returns its name.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5375
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5376
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5377 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5378 In the second case, <code>ar</code> must be <code>NULL</code> and the function
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5379 to be inspected must be at the top of the stack.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5380 In this case, only parameters of Lua functions are visible
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5381 (as there is no information about what variables are active)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5382 and no values are pushed onto the stack.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5383
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5384
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5385 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5386 Returns <code>NULL</code> (and pushes nothing)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5387 when the index is greater than
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5388 the number of active local variables.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5389
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5390
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5391
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5392
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5393
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5394 <hr><h3><a name="lua_getstack"><code>lua_getstack</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5395 <span class="apii">[-0, +0, –]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5396 <pre>int lua_getstack (lua_State L, int level, lua_Debug ar);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5397
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5398 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5399 Gets information about the interpreter runtime stack.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5400
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5401
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5402 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5403 This function fills parts of a <a href="#lua_Debug"><code>lua_Debug</code></a> structure with
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5404 an identification of the <em>activation record</em>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5405 of the function executing at a given level.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5406 Level 0 is the current running function,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5407 whereas level <em>n+1</em> is the function that has called level <em>n</em>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5408 (except for tail calls, which do not count on the stack).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5409 When there are no errors, <a href="#lua_getstack"><code>lua_getstack</code></a> returns 1;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5410 when called with a level greater than the stack depth,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5411 it returns 0.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5412
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5413
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5414
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5415
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5416
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5417 <hr><h3><a name="lua_getupvalue"><code>lua_getupvalue</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5418 <span class="apii">[-0, +(0\|1), –]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5419 <pre>const char lua_getupvalue (lua_State L, int funcindex, int n);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5420
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5421 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5422 Gets information about a closure's upvalue.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5423 (For Lua functions,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5424 upvalues are the external local variables that the function uses,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5425 and that are consequently included in its closure.)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5426 <a href="#lua_getupvalue"><code>lua_getupvalue</code></a> gets the index <code>n</code> of an upvalue,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5427 pushes the upvalue's value onto the stack,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5428 and returns its name.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5429 <code>funcindex</code> points to the closure in the stack.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5430 (Upvalues have no particular order,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5431 as they are active through the whole function.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5432 So, they are numbered in an arbitrary order.)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5433
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5434
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5435 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5436 Returns <code>NULL</code> (and pushes nothing)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5437 when the index is greater than the number of upvalues.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5438 For C functions, this function uses the empty string <code>""</code>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5439 as a name for all upvalues.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5440
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5441
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5442
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5443
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5444
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5445 <hr><h3><a name="lua_Hook"><code>lua_Hook</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5446 <pre>typedef void (lua_Hook) (lua_State L, lua_Debug *ar);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5447
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5448 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5449 Type for debugging hook functions.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5450
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5451
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5452 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5453 Whenever a hook is called, its <code>ar</code> argument has its field
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5454 <code>event</code> set to the specific event that triggered the hook.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5455 Lua identifies these events with the following constants:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5456 <a name="pdf-LUA_HOOKCALL"><code>LUA_HOOKCALL</code></a>, <a name="pdf-LUA_HOOKRET"><code>LUA_HOOKRET</code></a>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5457 <a name="pdf-LUA_HOOKTAILCALL"><code>LUA_HOOKTAILCALL</code></a>, <a name="pdf-LUA_HOOKLINE"><code>LUA_HOOKLINE</code></a>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5458 and <a name="pdf-LUA_HOOKCOUNT"><code>LUA_HOOKCOUNT</code></a>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5459 Moreover, for line events, the field <code>currentline</code> is also set.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5460 To get the value of any other field in <code>ar</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5461 the hook must call <a href="#lua_getinfo"><code>lua_getinfo</code></a>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5462
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5463
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5464 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5465 For call events, <code>event</code> can be <code>LUA_HOOKCALL</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5466 the normal value, or <code>LUA_HOOKTAILCALL</code>, for a tail call;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5467 in this case, there will be no corresponding return event.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5468
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5469
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5470 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5471 While Lua is running a hook, it disables other calls to hooks.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5472 Therefore, if a hook calls back Lua to execute a function or a chunk,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5473 this execution occurs without any calls to hooks.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5474
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5475
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5476 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5477 Hook functions cannot have continuations,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5478 that is, they cannot call <a href="#lua_yieldk"><code>lua_yieldk</code></a>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5479 <a href="#lua_pcallk"><code>lua_pcallk</code></a>, or <a href="#lua_callk"><code>lua_callk</code></a> with a non-null <code>k</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5480
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5481
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5482 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5483 Hook functions can yield under the following conditions:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5484 Only count and line events can yield
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5485 and they cannot yield any value;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5486 to yield a hook function must finish its execution
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5487 calling <a href="#lua_yield"><code>lua_yield</code></a> with <code>nresults</code> equal to zero.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5488
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5489
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5490
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5491
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5492
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5493 <hr><h3><a name="lua_sethook"><code>lua_sethook</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5494 <span class="apii">[-0, +0, –]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5495 <pre>void lua_sethook (lua_State *L, lua_Hook f, int mask, int count);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5496
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5497 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5498 Sets the debugging hook function.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5499
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5500
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5501 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5502 Argument <code>f</code> is the hook function.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5503 <code>mask</code> specifies on which events the hook will be called:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5504 it is formed by a bitwise or of the constants
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5505 <a name="pdf-LUA_MASKCALL"><code>LUA_MASKCALL</code></a>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5506 <a name="pdf-LUA_MASKRET"><code>LUA_MASKRET</code></a>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5507 <a name="pdf-LUA_MASKLINE"><code>LUA_MASKLINE</code></a>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5508 and <a name="pdf-LUA_MASKCOUNT"><code>LUA_MASKCOUNT</code></a>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5509 The <code>count</code> argument is only meaningful when the mask
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5510 includes <code>LUA_MASKCOUNT</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5511 For each event, the hook is called as explained below:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5512
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5513 <ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5514
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5515 <li><b>The call hook: </b> is called when the interpreter calls a function.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5516 The hook is called just after Lua enters the new function,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5517 before the function gets its arguments.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5518 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5519
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5520 <li><b>The return hook: </b> is called when the interpreter returns from a function.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5521 The hook is called just before Lua leaves the function.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5522 There is no standard way to access the values
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5523 to be returned by the function.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5524 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5525
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5526 <li><b>The line hook: </b> is called when the interpreter is about to
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5527 start the execution of a new line of code,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5528 or when it jumps back in the code (even to the same line).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5529 (This event only happens while Lua is executing a Lua function.)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5530 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5531
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5532 <li><b>The count hook: </b> is called after the interpreter executes every
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5533 <code>count</code> instructions.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5534 (This event only happens while Lua is executing a Lua function.)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5535 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5536
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5537 </ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5538
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5539 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5540 A hook is disabled by setting <code>mask</code> to zero.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5541
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5542
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5543
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5544
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5545
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5546 <hr><h3><a name="lua_setlocal"><code>lua_setlocal</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5547 <span class="apii">[-(0\|1), +0, –]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5548 <pre>const char lua_setlocal (lua_State L, const lua_Debug *ar, int n);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5549
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5550 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5551 Sets the value of a local variable of a given activation record.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5552 Parameters <code>ar</code> and <code>n</code> are as in <a href="#lua_getlocal"><code>lua_getlocal</code></a>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5553 (see <a href="#lua_getlocal"><code>lua_getlocal</code></a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5554 <a href="#lua_setlocal"><code>lua_setlocal</code></a> assigns the value at the top of the stack
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5555 to the variable and returns its name.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5556 It also pops the value from the stack.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5557
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5558
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5559 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5560 Returns <code>NULL</code> (and pops nothing)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5561 when the index is greater than
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5562 the number of active local variables.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5563
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5564
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5565
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5566
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5567
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5568 <hr><h3><a name="lua_setupvalue"><code>lua_setupvalue</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5569 <span class="apii">[-(0\|1), +0, –]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5570 <pre>const char lua_setupvalue (lua_State L, int funcindex, int n);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5571
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5572 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5573 Sets the value of a closure's upvalue.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5574 It assigns the value at the top of the stack
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5575 to the upvalue and returns its name.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5576 It also pops the value from the stack.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5577 Parameters <code>funcindex</code> and <code>n</code> are as in the <a href="#lua_getupvalue"><code>lua_getupvalue</code></a>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5578 (see <a href="#lua_getupvalue"><code>lua_getupvalue</code></a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5579
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5580
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5581 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5582 Returns <code>NULL</code> (and pops nothing)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5583 when the index is greater than the number of upvalues.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5584
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5585
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5586
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5587
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5588
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5589 <hr><h3><a name="lua_upvalueid"><code>lua_upvalueid</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5590 <span class="apii">[-0, +0, –]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5591 <pre>void lua_upvalueid (lua_State L, int funcindex, int n);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5592
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5593 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5594 Returns a unique identifier for the upvalue numbered <code>n</code>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5595 from the closure at index <code>funcindex</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5596 Parameters <code>funcindex</code> and <code>n</code> are as in the <a href="#lua_getupvalue"><code>lua_getupvalue</code></a>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5597 (see <a href="#lua_getupvalue"><code>lua_getupvalue</code></a>)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5598 (but <code>n</code> cannot be greater than the number of upvalues).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5599
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5600
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5601 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5602 These unique identifiers allow a program to check whether different
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5603 closures share upvalues.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5604 Lua closures that share an upvalue
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5605 (that is, that access a same external local variable)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5606 will return identical ids for those upvalue indices.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5607
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5608
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5609
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5610
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5611
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5612 <hr><h3><a name="lua_upvaluejoin"><code>lua_upvaluejoin</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5613 <span class="apii">[-0, +0, –]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5614 <pre>void lua_upvaluejoin (lua_State *L, int funcindex1, int n1,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5615 int funcindex2, int n2);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5616
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5617 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5618 Make the <code>n1</code>-th upvalue of the Lua closure at index <code>funcindex1</code>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5619 refer to the <code>n2</code>-th upvalue of the Lua closure at index <code>funcindex2</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5620
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5621
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5622
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5623
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5624
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5625
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5626
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5627 <h1>5 – <a name="5">The Auxiliary Library</a></h1>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5628
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5629 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5630
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5631 The <em>auxiliary library</em> provides several convenient functions
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5632 to interface C with Lua.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5633 While the basic API provides the primitive functions for all
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5634 interactions between C and Lua,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5635 the auxiliary library provides higher-level functions for some
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5636 common tasks.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5637
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5638
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5639 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5640 All functions and types from the auxiliary library
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5641 are defined in header file <code>lauxlib.h</code> and
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5642 have a prefix <code>luaL_</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5643
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5644
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5645 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5646 All functions in the auxiliary library are built on
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5647 top of the basic API,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5648 and so they provide nothing that cannot be done with that API.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5649 Nevertheless, the use of the auxiliary library ensures
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5650 more consistency to your code.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5651
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5652
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5653 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5654 Several functions in the auxiliary library use internally some
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5655 extra stack slots.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5656 When a function in the auxiliary library uses less than five slots,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5657 it does not check the stack size;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5658 it simply assumes that there are enough slots.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5659
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5660
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5661 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5662 Several functions in the auxiliary library are used to
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5663 check C function arguments.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5664 Because the error message is formatted for arguments
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5665 (e.g., "<code>bad argument #1</code>"),
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5666 you should not use these functions for other stack values.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5667
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5668
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5669 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5670 Functions called <code>luaL_check*</code>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5671 always raise an error if the check is not satisfied.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5672
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5673
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5674
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5675 <h2>5.1 – <a name="5.1">Functions and Types</a></h2>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5676
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5677 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5678 Here we list all functions and types from the auxiliary library
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5679 in alphabetical order.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5680
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5681
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5682
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5683 <hr><h3><a name="luaL_addchar"><code>luaL_addchar</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5684 <span class="apii">[-?, +?, <em>e</em>]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5685 <pre>void luaL_addchar (luaL_Buffer *B, char c);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5686
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5687 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5688 Adds the byte <code>c</code> to the buffer <code>B</code>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5689 (see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5690
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5691
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5692
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5693
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5694
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5695 <hr><h3><a name="luaL_addlstring"><code>luaL_addlstring</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5696 <span class="apii">[-?, +?, <em>e</em>]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5697 <pre>void luaL_addlstring (luaL_Buffer B, const char s, size_t l);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5698
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5699 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5700 Adds the string pointed to by <code>s</code> with length <code>l</code> to
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5701 the buffer <code>B</code>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5702 (see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5703 The string can contain embedded zeros.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5704
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5705
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5706
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5707
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5708
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5709 <hr><h3><a name="luaL_addsize"><code>luaL_addsize</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5710 <span class="apii">[-?, +?, <em>e</em>]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5711 <pre>void luaL_addsize (luaL_Buffer *B, size_t n);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5712
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5713 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5714 Adds to the buffer <code>B</code> (see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5715 a string of length <code>n</code> previously copied to the
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5716 buffer area (see <a href="#luaL_prepbuffer"><code>luaL_prepbuffer</code></a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5717
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5718
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5719
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5720
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5721
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5722 <hr><h3><a name="luaL_addstring"><code>luaL_addstring</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5723 <span class="apii">[-?, +?, <em>e</em>]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5724 <pre>void luaL_addstring (luaL_Buffer B, const char s);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5725
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5726 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5727 Adds the zero-terminated string pointed to by <code>s</code>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5728 to the buffer <code>B</code>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5729 (see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5730
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5731
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5732
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5733
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5734
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5735 <hr><h3><a name="luaL_addvalue"><code>luaL_addvalue</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5736 <span class="apii">[-1, +?, <em>e</em>]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5737 <pre>void luaL_addvalue (luaL_Buffer *B);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5738
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5739 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5740 Adds the value at the top of the stack
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5741 to the buffer <code>B</code>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5742 (see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5743 Pops the value.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5744
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5745
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5746 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5747 This is the only function on string buffers that can (and must)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5748 be called with an extra element on the stack,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5749 which is the value to be added to the buffer.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5750
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5751
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5752
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5753
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5754
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5755 <hr><h3><a name="luaL_argcheck"><code>luaL_argcheck</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5756 <span class="apii">[-0, +0, <em>v</em>]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5757 <pre>void luaL_argcheck (lua_State *L,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5758 int cond,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5759 int arg,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5760 const char *extramsg);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5761
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5762 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5763 Checks whether <code>cond</code> is true.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5764 If it is not, raises an error with a standard message (see <a href="#luaL_argerror"><code>luaL_argerror</code></a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5765
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5766
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5767
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5768
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5769
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5770 <hr><h3><a name="luaL_argerror"><code>luaL_argerror</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5771 <span class="apii">[-0, +0, <em>v</em>]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5772 <pre>int luaL_argerror (lua_State L, int arg, const char extramsg);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5773
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5774 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5775 Raises an error reporting a problem with argument <code>arg</code>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5776 of the C function that called it,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5777 using a standard message
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5778 that includes <code>extramsg</code> as a comment:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5779
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5780 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5781 bad argument #<em>arg</em> to '<em>funcname</em>' (<em>extramsg</em>)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5782 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5783 This function never returns.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5784
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5785
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5786
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5787
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5788
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5789 <hr><h3><a name="luaL_Buffer"><code>luaL_Buffer</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5790 <pre>typedef struct luaL_Buffer luaL_Buffer;</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5791
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5792 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5793 Type for a <em>string buffer</em>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5794
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5795
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5796 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5797 A string buffer allows C code to build Lua strings piecemeal.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5798 Its pattern of use is as follows:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5799
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5800 <ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5801
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5802 <li>First declare a variable <code>b</code> of type <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>.</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5803
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5804 <li>Then initialize it with a call <code>luaL_buffinit(L, &b)</code>.</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5805
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5806 <li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5807 Then add string pieces to the buffer calling any of
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5808 the <code>luaL_add*</code> functions.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5809 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5810
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5811 <li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5812 Finish by calling <code>luaL_pushresult(&b)</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5813 This call leaves the final string on the top of the stack.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5814 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5815
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5816 </ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5817
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5818 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5819 If you know beforehand the total size of the resulting string,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5820 you can use the buffer like this:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5821
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5822 <ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5823
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5824 <li>First declare a variable <code>b</code> of type <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>.</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5825
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5826 <li>Then initialize it and preallocate a space of
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5827 size <code>sz</code> with a call <code>luaL_buffinitsize(L, &b, sz)</code>.</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5828
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5829 <li>Then copy the string into that space.</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5830
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5831 <li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5832 Finish by calling <code>luaL_pushresultsize(&b, sz)</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5833 where <code>sz</code> is the total size of the resulting string
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5834 copied into that space.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5835 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5836
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5837 </ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5838
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5839 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5840 During its normal operation,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5841 a string buffer uses a variable number of stack slots.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5842 So, while using a buffer, you cannot assume that you know where
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5843 the top of the stack is.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5844 You can use the stack between successive calls to buffer operations
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5845 as long as that use is balanced;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5846 that is,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5847 when you call a buffer operation,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5848 the stack is at the same level
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5849 it was immediately after the previous buffer operation.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5850 (The only exception to this rule is <a href="#luaL_addvalue"><code>luaL_addvalue</code></a>.)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5851 After calling <a href="#luaL_pushresult"><code>luaL_pushresult</code></a> the stack is back to its
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5852 level when the buffer was initialized,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5853 plus the final string on its top.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5854
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5855
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5856
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5857
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5858
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5859 <hr><h3><a name="luaL_buffinit"><code>luaL_buffinit</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5860 <span class="apii">[-0, +0, –]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5861 <pre>void luaL_buffinit (lua_State L, luaL_Buffer B);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5862
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5863 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5864 Initializes a buffer <code>B</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5865 This function does not allocate any space;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5866 the buffer must be declared as a variable
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5867 (see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5868
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5869
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5870
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5871
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5872
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5873 <hr><h3><a name="luaL_buffinitsize"><code>luaL_buffinitsize</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5874 <span class="apii">[-?, +?, <em>e</em>]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5875 <pre>char luaL_buffinitsize (lua_State L, luaL_Buffer *B, size_t sz);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5876
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5877 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5878 Equivalent to the sequence
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5879 <a href="#luaL_buffinit"><code>luaL_buffinit</code></a>, <a href="#luaL_prepbuffsize"><code>luaL_prepbuffsize</code></a>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5880
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5881
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5882
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5883
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5884
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5885 <hr><h3><a name="luaL_callmeta"><code>luaL_callmeta</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5886 <span class="apii">[-0, +(0\|1), <em>e</em>]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5887 <pre>int luaL_callmeta (lua_State L, int obj, const char e);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5888
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5889 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5890 Calls a metamethod.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5891
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5892
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5893 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5894 If the object at index <code>obj</code> has a metatable and this
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5895 metatable has a field <code>e</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5896 this function calls this field passing the object as its only argument.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5897 In this case this function returns true and pushes onto the
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5898 stack the value returned by the call.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5899 If there is no metatable or no metamethod,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5900 this function returns false (without pushing any value on the stack).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5901
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5902
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5903
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5904
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5905
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5906 <hr><h3><a name="luaL_checkany"><code>luaL_checkany</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5907 <span class="apii">[-0, +0, <em>v</em>]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5908 <pre>void luaL_checkany (lua_State *L, int arg);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5909
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5910 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5911 Checks whether the function has an argument
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5912 of any type (including <b>nil</b>) at position <code>arg</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5913
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5914
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5915
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5916
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5917
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5918 <hr><h3><a name="luaL_checkinteger"><code>luaL_checkinteger</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5919 <span class="apii">[-0, +0, <em>v</em>]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5920 <pre>lua_Integer luaL_checkinteger (lua_State *L, int arg);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5921
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5922 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5923 Checks whether the function argument <code>arg</code> is an integer
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5924 (or can be converted to an integer)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5925 and returns this integer cast to a <a href="#lua_Integer"><code>lua_Integer</code></a>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5926
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5927
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5928
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5929
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5930
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5931 <hr><h3><a name="luaL_checklstring"><code>luaL_checklstring</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5932 <span class="apii">[-0, +0, <em>v</em>]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5933 <pre>const char luaL_checklstring (lua_State L, int arg, size_t *l);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5934
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5935 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5936 Checks whether the function argument <code>arg</code> is a string
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5937 and returns this string;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5938 if <code>l</code> is not <code>NULL</code> fills <code>*l</code>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5939 with the string's length.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5940
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5941
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5942 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5943 This function uses <a href="#lua_tolstring"><code>lua_tolstring</code></a> to get its result,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5944 so all conversions and caveats of that function apply here.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5945
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5946
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5947
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5948
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5949
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5950 <hr><h3><a name="luaL_checknumber"><code>luaL_checknumber</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5951 <span class="apii">[-0, +0, <em>v</em>]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5952 <pre>lua_Number luaL_checknumber (lua_State *L, int arg);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5953
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5954 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5955 Checks whether the function argument <code>arg</code> is a number
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5956 and returns this number.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5957
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5958
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5959
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5960
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5961
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5962 <hr><h3><a name="luaL_checkoption"><code>luaL_checkoption</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5963 <span class="apii">[-0, +0, <em>v</em>]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5964 <pre>int luaL_checkoption (lua_State *L,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5965 int arg,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5966 const char *def,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5967 const char *const lst[]);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5968
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5969 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5970 Checks whether the function argument <code>arg</code> is a string and
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5971 searches for this string in the array <code>lst</code>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5972 (which must be NULL-terminated).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5973 Returns the index in the array where the string was found.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5974 Raises an error if the argument is not a string or
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5975 if the string cannot be found.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5976
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5977
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5978 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5979 If <code>def</code> is not <code>NULL</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5980 the function uses <code>def</code> as a default value when
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5981 there is no argument <code>arg</code> or when this argument is <b>nil</b>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5982
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5983
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5984 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5985 This is a useful function for mapping strings to C enums.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5986 (The usual convention in Lua libraries is
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5987 to use strings instead of numbers to select options.)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5988
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5989
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5990
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5991
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5992
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5993 <hr><h3><a name="luaL_checkstack"><code>luaL_checkstack</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5994 <span class="apii">[-0, +0, <em>v</em>]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5995 <pre>void luaL_checkstack (lua_State L, int sz, const char msg);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5996
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5997 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5998 Grows the stack size to <code>top + sz</code> elements,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5999 raising an error if the stack cannot grow to that size.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6000 <code>msg</code> is an additional text to go into the error message
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6001 (or <code>NULL</code> for no additional text).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6002
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6003
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6004
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6005
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6006
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6007 <hr><h3><a name="luaL_checkstring"><code>luaL_checkstring</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6008 <span class="apii">[-0, +0, <em>v</em>]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6009 <pre>const char luaL_checkstring (lua_State L, int arg);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6010
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6011 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6012 Checks whether the function argument <code>arg</code> is a string
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6013 and returns this string.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6014
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6015
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6016 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6017 This function uses <a href="#lua_tolstring"><code>lua_tolstring</code></a> to get its result,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6018 so all conversions and caveats of that function apply here.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6019
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6020
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6021
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6022
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6023
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6024 <hr><h3><a name="luaL_checktype"><code>luaL_checktype</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6025 <span class="apii">[-0, +0, <em>v</em>]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6026 <pre>void luaL_checktype (lua_State *L, int arg, int t);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6027
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6028 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6029 Checks whether the function argument <code>arg</code> has type <code>t</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6030 See <a href="#lua_type"><code>lua_type</code></a> for the encoding of types for <code>t</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6031
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6032
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6033
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6034
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6035
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6036 <hr><h3><a name="luaL_checkudata"><code>luaL_checkudata</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6037 <span class="apii">[-0, +0, <em>v</em>]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6038 <pre>void luaL_checkudata (lua_State L, int arg, const char *tname);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6039
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6040 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6041 Checks whether the function argument <code>arg</code> is a userdata
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6042 of the type <code>tname</code> (see <a href="#luaL_newmetatable"><code>luaL_newmetatable</code></a>) and
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6043 returns the userdata address (see <a href="#lua_touserdata"><code>lua_touserdata</code></a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6044
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6045
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6046
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6047
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6048
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6049 <hr><h3><a name="luaL_checkversion"><code>luaL_checkversion</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6050 <span class="apii">[-0, +0, –]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6051 <pre>void luaL_checkversion (lua_State *L);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6052
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6053 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6054 Checks whether the core running the call,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6055 the core that created the Lua state,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6056 and the code making the call are all using the same version of Lua.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6057 Also checks whether the core running the call
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6058 and the core that created the Lua state
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6059 are using the same address space.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6060
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6061
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6062
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6063
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6064
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6065 <hr><h3><a name="luaL_dofile"><code>luaL_dofile</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6066 <span class="apii">[-0, +?, <em>e</em>]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6067 <pre>int luaL_dofile (lua_State L, const char filename);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6068
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6069 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6070 Loads and runs the given file.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6071 It is defined as the following macro:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6072
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6073 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6074 (luaL_loadfile(L, filename) \|\| lua_pcall(L, 0, LUA_MULTRET, 0))
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6075 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6076 It returns false if there are no errors
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6077 or true in case of errors.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6078
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6079
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6080
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6081
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6082
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6083 <hr><h3><a name="luaL_dostring"><code>luaL_dostring</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6084 <span class="apii">[-0, +?, –]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6085 <pre>int luaL_dostring (lua_State L, const char str);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6086
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6087 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6088 Loads and runs the given string.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6089 It is defined as the following macro:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6090
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6091 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6092 (luaL_loadstring(L, str) \|\| lua_pcall(L, 0, LUA_MULTRET, 0))
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6093 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6094 It returns false if there are no errors
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6095 or true in case of errors.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6096
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6097
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6098
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6099
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6100
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6101 <hr><h3><a name="luaL_error"><code>luaL_error</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6102 <span class="apii">[-0, +0, <em>v</em>]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6103 <pre>int luaL_error (lua_State L, const char fmt, ...);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6104
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6105 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6106 Raises an error.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6107 The error message format is given by <code>fmt</code>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6108 plus any extra arguments,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6109 following the same rules of <a href="#lua_pushfstring"><code>lua_pushfstring</code></a>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6110 It also adds at the beginning of the message the file name and
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6111 the line number where the error occurred,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6112 if this information is available.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6113
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6114
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6115 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6116 This function never returns,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6117 but it is an idiom to use it in C functions
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6118 as <code>return luaL_error(<em>args</em>)</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6119
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6120
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6121
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6122
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6123
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6124 <hr><h3><a name="luaL_execresult"><code>luaL_execresult</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6125 <span class="apii">[-0, +3, <em>e</em>]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6126 <pre>int luaL_execresult (lua_State *L, int stat);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6127
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6128 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6129 This function produces the return values for
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6130 process-related functions in the standard library
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6131 (<a href="#pdf-os.execute"><code>os.execute</code></a> and <a href="#pdf-io.close"><code>io.close</code></a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6132
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6133
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6134
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6135
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6136
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6137 <hr><h3><a name="luaL_fileresult"><code>luaL_fileresult</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6138 <span class="apii">[-0, +(1\|3), <em>e</em>]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6139 <pre>int luaL_fileresult (lua_State L, int stat, const char fname);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6140
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6141 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6142 This function produces the return values for
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6143 file-related functions in the standard library
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6144 (<a href="#pdf-io.open"><code>io.open</code></a>, <a href="#pdf-os.rename"><code>os.rename</code></a>, <a href="#pdf-file:seek"><code>file:seek</code></a>, etc.).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6145
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6146
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6147
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6148
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6149
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6150 <hr><h3><a name="luaL_getmetafield"><code>luaL_getmetafield</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6151 <span class="apii">[-0, +(0\|1), <em>e</em>]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6152 <pre>int luaL_getmetafield (lua_State L, int obj, const char e);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6153
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6154 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6155 Pushes onto the stack the field <code>e</code> from the metatable
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6156 of the object at index <code>obj</code> and returns the type of pushed value.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6157 If the object does not have a metatable,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6158 or if the metatable does not have this field,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6159 pushes nothing and returns <code>LUA_TNIL</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6160
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6161
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6162
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6163
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6164
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6165 <hr><h3><a name="luaL_getmetatable"><code>luaL_getmetatable</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6166 <span class="apii">[-0, +1, –]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6167 <pre>int luaL_getmetatable (lua_State L, const char tname);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6168
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6169 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6170 Pushes onto the stack the metatable associated with name <code>tname</code>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6171 in the registry (see <a href="#luaL_newmetatable"><code>luaL_newmetatable</code></a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6172 If there is no metatable associated with <code>tname</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6173 returns false and pushes <b>nil</b>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6174
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6175
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6176
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6177
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6178
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6179 <hr><h3><a name="luaL_getsubtable"><code>luaL_getsubtable</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6180 <span class="apii">[-0, +1, <em>e</em>]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6181 <pre>int luaL_getsubtable (lua_State L, int idx, const char fname);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6182
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6183 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6184 Ensures that the value <code>t[fname]</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6185 where <code>t</code> is the value at index <code>idx</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6186 is a table,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6187 and pushes that table onto the stack.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6188 Returns true if it finds a previous table there
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6189 and false if it creates a new table.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6190
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6191
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6192
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6193
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6194
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6195 <hr><h3><a name="luaL_gsub"><code>luaL_gsub</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6196 <span class="apii">[-0, +1, <em>e</em>]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6197 <pre>const char luaL_gsub (lua_State L,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6198 const char *s,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6199 const char *p,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6200 const char *r);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6201
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6202 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6203 Creates a copy of string <code>s</code> by replacing
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6204 any occurrence of the string <code>p</code>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6205 with the string <code>r</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6206 Pushes the resulting string on the stack and returns it.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6207
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6208
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6209
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6210
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6211
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6212 <hr><h3><a name="luaL_len"><code>luaL_len</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6213 <span class="apii">[-0, +0, <em>e</em>]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6214 <pre>lua_Integer luaL_len (lua_State *L, int index);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6215
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6216 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6217 Returns the "length" of the value at the given index
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6218 as a number;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6219 it is equivalent to the '<code>#</code>' operator in Lua (see <a href="#3.4.7">§3.4.7</a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6220 Raises an error if the result of the operation is not an integer.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6221 (This case only can happen through metamethods.)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6222
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6223
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6224
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6225
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6226
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6227 <hr><h3><a name="luaL_loadbuffer"><code>luaL_loadbuffer</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6228 <span class="apii">[-0, +1, –]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6229 <pre>int luaL_loadbuffer (lua_State *L,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6230 const char *buff,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6231 size_t sz,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6232 const char *name);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6233
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6234 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6235 Equivalent to <a href="#luaL_loadbufferx"><code>luaL_loadbufferx</code></a> with <code>mode</code> equal to <code>NULL</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6236
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6237
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6238
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6239
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6240
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6241 <hr><h3><a name="luaL_loadbufferx"><code>luaL_loadbufferx</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6242 <span class="apii">[-0, +1, –]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6243 <pre>int luaL_loadbufferx (lua_State *L,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6244 const char *buff,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6245 size_t sz,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6246 const char *name,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6247 const char *mode);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6248
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6249 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6250 Loads a buffer as a Lua chunk.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6251 This function uses <a href="#lua_load"><code>lua_load</code></a> to load the chunk in the
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6252 buffer pointed to by <code>buff</code> with size <code>sz</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6253
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6254
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6255 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6256 This function returns the same results as <a href="#lua_load"><code>lua_load</code></a>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6257 <code>name</code> is the chunk name,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6258 used for debug information and error messages.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6259 The string <code>mode</code> works as in function <a href="#lua_load"><code>lua_load</code></a>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6260
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6261
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6262
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6263
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6264
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6265 <hr><h3><a name="luaL_loadfile"><code>luaL_loadfile</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6266 <span class="apii">[-0, +1, <em>e</em>]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6267 <pre>int luaL_loadfile (lua_State L, const char filename);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6268
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6269 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6270 Equivalent to <a href="#luaL_loadfilex"><code>luaL_loadfilex</code></a> with <code>mode</code> equal to <code>NULL</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6271
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6272
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6273
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6274
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6275
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6276 <hr><h3><a name="luaL_loadfilex"><code>luaL_loadfilex</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6277 <span class="apii">[-0, +1, <em>e</em>]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6278 <pre>int luaL_loadfilex (lua_State L, const char filename,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6279 const char *mode);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6280
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6281 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6282 Loads a file as a Lua chunk.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6283 This function uses <a href="#lua_load"><code>lua_load</code></a> to load the chunk in the file
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6284 named <code>filename</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6285 If <code>filename</code> is <code>NULL</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6286 then it loads from the standard input.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6287 The first line in the file is ignored if it starts with a <code>#</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6288
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6289
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6290 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6291 The string <code>mode</code> works as in function <a href="#lua_load"><code>lua_load</code></a>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6292
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6293
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6294 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6295 This function returns the same results as <a href="#lua_load"><code>lua_load</code></a>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6296 but it has an extra error code <a name="pdf-LUA_ERRFILE"><code>LUA_ERRFILE</code></a>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6297 if it cannot open/read the file or the file has a wrong mode.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6298
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6299
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6300 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6301 As <a href="#lua_load"><code>lua_load</code></a>, this function only loads the chunk;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6302 it does not run it.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6303
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6304
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6305
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6306
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6307
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6308 <hr><h3><a name="luaL_loadstring"><code>luaL_loadstring</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6309 <span class="apii">[-0, +1, –]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6310 <pre>int luaL_loadstring (lua_State L, const char s);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6311
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6312 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6313 Loads a string as a Lua chunk.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6314 This function uses <a href="#lua_load"><code>lua_load</code></a> to load the chunk in
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6315 the zero-terminated string <code>s</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6316
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6317
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6318 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6319 This function returns the same results as <a href="#lua_load"><code>lua_load</code></a>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6320
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6321
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6322 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6323 Also as <a href="#lua_load"><code>lua_load</code></a>, this function only loads the chunk;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6324 it does not run it.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6325
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6326
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6327
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6328
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6329
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6330 <hr><h3><a name="luaL_newlib"><code>luaL_newlib</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6331 <span class="apii">[-0, +1, <em>e</em>]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6332 <pre>void luaL_newlib (lua_State *L, const luaL_Reg l[]);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6333
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6334 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6335 Creates a new table and registers there
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6336 the functions in list <code>l</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6337
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6338
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6339 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6340 It is implemented as the following macro:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6341
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6342 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6343 (luaL_newlibtable(L,l), luaL_setfuncs(L,l,0))
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6344 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6345 The array <code>l</code> must be the actual array,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6346 not a pointer to it.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6347
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6348
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6349
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6350
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6351
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6352 <hr><h3><a name="luaL_newlibtable"><code>luaL_newlibtable</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6353 <span class="apii">[-0, +1, <em>e</em>]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6354 <pre>void luaL_newlibtable (lua_State *L, const luaL_Reg l[]);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6355
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6356 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6357 Creates a new table with a size optimized
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6358 to store all entries in the array <code>l</code>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6359 (but does not actually store them).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6360 It is intended to be used in conjunction with <a href="#luaL_setfuncs"><code>luaL_setfuncs</code></a>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6361 (see <a href="#luaL_newlib"><code>luaL_newlib</code></a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6362
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6363
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6364 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6365 It is implemented as a macro.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6366 The array <code>l</code> must be the actual array,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6367 not a pointer to it.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6368
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6369
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6370
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6371
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6372
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6373 <hr><h3><a name="luaL_newmetatable"><code>luaL_newmetatable</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6374 <span class="apii">[-0, +1, <em>e</em>]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6375 <pre>int luaL_newmetatable (lua_State L, const char tname);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6376
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6377 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6378 If the registry already has the key <code>tname</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6379 returns 0.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6380 Otherwise,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6381 creates a new table to be used as a metatable for userdata,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6382 adds to this new table the pair <code>__name = tname</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6383 adds to the registry the pair <code>[tname] = new table</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6384 and returns 1.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6385 (The entry <code>__name</code> is used by some error-reporting functions.)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6386
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6387
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6388 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6389 In both cases pushes onto the stack the final value associated
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6390 with <code>tname</code> in the registry.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6391
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6392
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6393
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6394
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6395
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6396 <hr><h3><a name="luaL_newstate"><code>luaL_newstate</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6397 <span class="apii">[-0, +0, –]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6398 <pre>lua_State *luaL_newstate (void);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6399
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6400 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6401 Creates a new Lua state.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6402 It calls <a href="#lua_newstate"><code>lua_newstate</code></a> with an
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6403 allocator based on the standard C <code>realloc</code> function
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6404 and then sets a panic function (see <a href="#4.6">§4.6</a>) that prints
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6405 an error message to the standard error output in case of fatal
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6406 errors.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6407
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6408
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6409 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6410 Returns the new state,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6411 or <code>NULL</code> if there is a memory allocation error.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6412
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6413
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6414
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6415
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6416
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6417 <hr><h3><a name="luaL_openlibs"><code>luaL_openlibs</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6418 <span class="apii">[-0, +0, <em>e</em>]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6419 <pre>void luaL_openlibs (lua_State *L);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6420
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6421 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6422 Opens all standard Lua libraries into the given state.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6423
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6424
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6425
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6426
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6427
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6428 <hr><h3><a name="luaL_optinteger"><code>luaL_optinteger</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6429 <span class="apii">[-0, +0, <em>v</em>]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6430 <pre>lua_Integer luaL_optinteger (lua_State *L,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6431 int arg,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6432 lua_Integer d);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6433
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6434 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6435 If the function argument <code>arg</code> is an integer
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6436 (or convertible to an integer),
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6437 returns this integer.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6438 If this argument is absent or is <b>nil</b>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6439 returns <code>d</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6440 Otherwise, raises an error.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6441
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6442
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6443
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6444
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6445
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6446 <hr><h3><a name="luaL_optlstring"><code>luaL_optlstring</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6447 <span class="apii">[-0, +0, <em>v</em>]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6448 <pre>const char luaL_optlstring (lua_State L,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6449 int arg,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6450 const char *d,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6451 size_t *l);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6452
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6453 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6454 If the function argument <code>arg</code> is a string,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6455 returns this string.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6456 If this argument is absent or is <b>nil</b>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6457 returns <code>d</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6458 Otherwise, raises an error.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6459
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6460
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6461 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6462 If <code>l</code> is not <code>NULL</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6463 fills the position <code>*l</code> with the result's length.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6464
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6465
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6466
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6467
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6468
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6469 <hr><h3><a name="luaL_optnumber"><code>luaL_optnumber</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6470 <span class="apii">[-0, +0, <em>v</em>]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6471 <pre>lua_Number luaL_optnumber (lua_State *L, int arg, lua_Number d);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6472
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6473 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6474 If the function argument <code>arg</code> is a number,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6475 returns this number.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6476 If this argument is absent or is <b>nil</b>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6477 returns <code>d</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6478 Otherwise, raises an error.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6479
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6480
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6481
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6482
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6483
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6484 <hr><h3><a name="luaL_optstring"><code>luaL_optstring</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6485 <span class="apii">[-0, +0, <em>v</em>]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6486 <pre>const char luaL_optstring (lua_State L,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6487 int arg,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6488 const char *d);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6489
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6490 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6491 If the function argument <code>arg</code> is a string,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6492 returns this string.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6493 If this argument is absent or is <b>nil</b>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6494 returns <code>d</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6495 Otherwise, raises an error.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6496
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6497
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6498
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6499
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6500
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6501 <hr><h3><a name="luaL_prepbuffer"><code>luaL_prepbuffer</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6502 <span class="apii">[-?, +?, <em>e</em>]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6503 <pre>char luaL_prepbuffer (luaL_Buffer B);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6504
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6505 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6506 Equivalent to <a href="#luaL_prepbuffsize"><code>luaL_prepbuffsize</code></a>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6507 with the predefined size <a name="pdf-LUAL_BUFFERSIZE"><code>LUAL_BUFFERSIZE</code></a>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6508
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6509
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6510
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6511
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6512
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6513 <hr><h3><a name="luaL_prepbuffsize"><code>luaL_prepbuffsize</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6514 <span class="apii">[-?, +?, <em>e</em>]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6515 <pre>char luaL_prepbuffsize (luaL_Buffer B, size_t sz);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6516
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6517 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6518 Returns an address to a space of size <code>sz</code>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6519 where you can copy a string to be added to buffer <code>B</code>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6520 (see <a href="#luaL_Buffer"><code>luaL_Buffer</code></a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6521 After copying the string into this space you must call
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6522 <a href="#luaL_addsize"><code>luaL_addsize</code></a> with the size of the string to actually add
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6523 it to the buffer.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6524
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6525
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6526
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6527
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6528
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6529 <hr><h3><a name="luaL_pushresult"><code>luaL_pushresult</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6530 <span class="apii">[-?, +1, <em>e</em>]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6531 <pre>void luaL_pushresult (luaL_Buffer *B);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6532
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6533 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6534 Finishes the use of buffer <code>B</code> leaving the final string on
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6535 the top of the stack.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6536
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6537
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6538
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6539
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6540
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6541 <hr><h3><a name="luaL_pushresultsize"><code>luaL_pushresultsize</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6542 <span class="apii">[-?, +1, <em>e</em>]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6543 <pre>void luaL_pushresultsize (luaL_Buffer *B, size_t sz);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6544
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6545 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6546 Equivalent to the sequence <a href="#luaL_addsize"><code>luaL_addsize</code></a>, <a href="#luaL_pushresult"><code>luaL_pushresult</code></a>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6547
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6548
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6549
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6550
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6551
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6552 <hr><h3><a name="luaL_ref"><code>luaL_ref</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6553 <span class="apii">[-1, +0, <em>e</em>]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6554 <pre>int luaL_ref (lua_State *L, int t);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6555
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6556 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6557 Creates and returns a <em>reference</em>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6558 in the table at index <code>t</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6559 for the object at the top of the stack (and pops the object).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6560
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6561
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6562 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6563 A reference is a unique integer key.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6564 As long as you do not manually add integer keys into table <code>t</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6565 <a href="#luaL_ref"><code>luaL_ref</code></a> ensures the uniqueness of the key it returns.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6566 You can retrieve an object referred by reference <code>r</code>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6567 by calling <code>lua_rawgeti(L, t, r)</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6568 Function <a href="#luaL_unref"><code>luaL_unref</code></a> frees a reference and its associated object.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6569
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6570
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6571 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6572 If the object at the top of the stack is <b>nil</b>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6573 <a href="#luaL_ref"><code>luaL_ref</code></a> returns the constant <a name="pdf-LUA_REFNIL"><code>LUA_REFNIL</code></a>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6574 The constant <a name="pdf-LUA_NOREF"><code>LUA_NOREF</code></a> is guaranteed to be different
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6575 from any reference returned by <a href="#luaL_ref"><code>luaL_ref</code></a>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6576
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6577
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6578
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6579
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6580
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6581 <hr><h3><a name="luaL_Reg"><code>luaL_Reg</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6582 <pre>typedef struct luaL_Reg {
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6583 const char *name;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6584 lua_CFunction func;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6585 } luaL_Reg;</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6586
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6587 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6588 Type for arrays of functions to be registered by
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6589 <a href="#luaL_setfuncs"><code>luaL_setfuncs</code></a>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6590 <code>name</code> is the function name and <code>func</code> is a pointer to
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6591 the function.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6592 Any array of <a href="#luaL_Reg"><code>luaL_Reg</code></a> must end with a sentinel entry
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6593 in which both <code>name</code> and <code>func</code> are <code>NULL</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6594
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6595
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6596
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6597
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6598
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6599 <hr><h3><a name="luaL_requiref"><code>luaL_requiref</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6600 <span class="apii">[-0, +1, <em>e</em>]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6601 <pre>void luaL_requiref (lua_State L, const char modname,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6602 lua_CFunction openf, int glb);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6603
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6604 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6605 If <code>modname</code> is not already present in <a href="#pdf-package.loaded"><code>package.loaded</code></a>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6606 calls function <code>openf</code> with string <code>modname</code> as an argument
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6607 and sets the call result in <code>package.loaded[modname]</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6608 as if that function has been called through <a href="#pdf-require"><code>require</code></a>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6609
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6610
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6611 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6612 If <code>glb</code> is true,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6613 also stores the module into global <code>modname</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6614
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6615
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6616 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6617 Leaves a copy of the module on the stack.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6618
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6619
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6620
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6621
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6622
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6623 <hr><h3><a name="luaL_setfuncs"><code>luaL_setfuncs</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6624 <span class="apii">[-nup, +0, <em>e</em>]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6625 <pre>void luaL_setfuncs (lua_State L, const luaL_Reg l, int nup);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6626
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6627 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6628 Registers all functions in the array <code>l</code>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6629 (see <a href="#luaL_Reg"><code>luaL_Reg</code></a>) into the table on the top of the stack
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6630 (below optional upvalues, see next).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6631
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6632
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6633 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6634 When <code>nup</code> is not zero,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6635 all functions are created sharing <code>nup</code> upvalues,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6636 which must be previously pushed on the stack
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6637 on top of the library table.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6638 These values are popped from the stack after the registration.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6639
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6640
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6641
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6642
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6643
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6644 <hr><h3><a name="luaL_setmetatable"><code>luaL_setmetatable</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6645 <span class="apii">[-0, +0, –]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6646 <pre>void luaL_setmetatable (lua_State L, const char tname);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6647
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6648 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6649 Sets the metatable of the object at the top of the stack
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6650 as the metatable associated with name <code>tname</code>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6651 in the registry (see <a href="#luaL_newmetatable"><code>luaL_newmetatable</code></a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6652
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6653
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6654
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6655
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6656
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6657 <hr><h3><a name="luaL_Stream"><code>luaL_Stream</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6658 <pre>typedef struct luaL_Stream {
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6659 FILE *f;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6660 lua_CFunction closef;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6661 } luaL_Stream;</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6662
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6663 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6664 The standard representation for file handles,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6665 which is used by the standard I/O library.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6666
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6667
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6668 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6669 A file handle is implemented as a full userdata,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6670 with a metatable called <code>LUA_FILEHANDLE</code>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6671 (where <code>LUA_FILEHANDLE</code> is a macro with the actual metatable's name).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6672 The metatable is created by the I/O library
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6673 (see <a href="#luaL_newmetatable"><code>luaL_newmetatable</code></a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6674
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6675
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6676 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6677 This userdata must start with the structure <code>luaL_Stream</code>;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6678 it can contain other data after this initial structure.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6679 Field <code>f</code> points to the corresponding C stream
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6680 (or it can be <code>NULL</code> to indicate an incompletely created handle).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6681 Field <code>closef</code> points to a Lua function
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6682 that will be called to close the stream
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6683 when the handle is closed or collected;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6684 this function receives the file handle as its sole argument and
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6685 must return either <b>true</b> (in case of success)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6686 or <b>nil</b> plus an error message (in case of error).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6687 Once Lua calls this field,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6688 the field value is changed to <code>NULL</code>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6689 to signal that the handle is closed.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6690
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6691
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6692
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6693
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6694
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6695 <hr><h3><a name="luaL_testudata"><code>luaL_testudata</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6696 <span class="apii">[-0, +0, <em>e</em>]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6697 <pre>void luaL_testudata (lua_State L, int arg, const char *tname);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6698
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6699 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6700 This function works like <a href="#luaL_checkudata"><code>luaL_checkudata</code></a>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6701 except that, when the test fails,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6702 it returns <code>NULL</code> instead of raising an error.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6703
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6704
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6705
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6706
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6707
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6708 <hr><h3><a name="luaL_tolstring"><code>luaL_tolstring</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6709 <span class="apii">[-0, +1, <em>e</em>]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6710 <pre>const char luaL_tolstring (lua_State L, int idx, size_t *len);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6711
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6712 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6713 Converts any Lua value at the given index to a C string
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6714 in a reasonable format.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6715 The resulting string is pushed onto the stack and also
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6716 returned by the function.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6717 If <code>len</code> is not <code>NULL</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6718 the function also sets <code>*len</code> with the string length.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6719
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6720
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6721 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6722 If the value has a metatable with a <code>"__tostring"</code> field,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6723 then <code>luaL_tolstring</code> calls the corresponding metamethod
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6724 with the value as argument,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6725 and uses the result of the call as its result.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6726
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6727
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6728
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6729
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6730
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6731 <hr><h3><a name="luaL_traceback"><code>luaL_traceback</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6732 <span class="apii">[-0, +1, <em>e</em>]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6733 <pre>void luaL_traceback (lua_State L, lua_State L1, const char *msg,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6734 int level);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6735
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6736 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6737 Creates and pushes a traceback of the stack <code>L1</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6738 If <code>msg</code> is not <code>NULL</code> it is appended
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6739 at the beginning of the traceback.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6740 The <code>level</code> parameter tells at which level
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6741 to start the traceback.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6742
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6743
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6744
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6745
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6746
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6747 <hr><h3><a name="luaL_typename"><code>luaL_typename</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6748 <span class="apii">[-0, +0, –]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6749 <pre>const char luaL_typename (lua_State L, int index);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6750
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6751 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6752 Returns the name of the type of the value at the given index.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6753
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6754
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6755
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6756
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6757
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6758 <hr><h3><a name="luaL_unref"><code>luaL_unref</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6759 <span class="apii">[-0, +0, –]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6760 <pre>void luaL_unref (lua_State *L, int t, int ref);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6761
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6762 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6763 Releases reference <code>ref</code> from the table at index <code>t</code>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6764 (see <a href="#luaL_ref"><code>luaL_ref</code></a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6765 The entry is removed from the table,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6766 so that the referred object can be collected.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6767 The reference <code>ref</code> is also freed to be used again.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6768
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6769
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6770 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6771 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>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6772 <a href="#luaL_unref"><code>luaL_unref</code></a> does nothing.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6773
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6774
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6775
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6776
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6777
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6778 <hr><h3><a name="luaL_where"><code>luaL_where</code></a></h3><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6779 <span class="apii">[-0, +1, <em>e</em>]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6780 <pre>void luaL_where (lua_State *L, int lvl);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6781
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6782 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6783 Pushes onto the stack a string identifying the current position
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6784 of the control at level <code>lvl</code> in the call stack.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6785 Typically this string has the following format:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6786
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6787 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6788 <em>chunkname</em>:<em>currentline</em>:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6789 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6790 Level 0 is the running function,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6791 level 1 is the function that called the running function,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6792 etc.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6793
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6794
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6795 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6796 This function is used to build a prefix for error messages.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6797
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6798
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6799
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6800
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6801
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6802
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6803
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6804 <h1>6 – <a name="6">Standard Libraries</a></h1>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6805
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6806 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6807 The standard Lua libraries provide useful functions
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6808 that are implemented directly through the C API.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6809 Some of these functions provide essential services to the language
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6810 (e.g., <a href="#pdf-type"><code>type</code></a> and <a href="#pdf-getmetatable"><code>getmetatable</code></a>);
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6811 others provide access to "outside" services (e.g., I/O);
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6812 and others could be implemented in Lua itself,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6813 but are quite useful or have critical performance requirements that
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6814 deserve an implementation in C (e.g., <a href="#pdf-table.sort"><code>table.sort</code></a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6815
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6816
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6817 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6818 All libraries are implemented through the official C API
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6819 and are provided as separate C modules.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6820 Currently, Lua has the following standard libraries:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6821
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6822 <ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6823
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6824 <li>basic library (<a href="#6.1">§6.1</a>);</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6825
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6826 <li>coroutine library (<a href="#6.2">§6.2</a>);</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6827
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6828 <li>package library (<a href="#6.3">§6.3</a>);</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6829
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6830 <li>string manipulation (<a href="#6.4">§6.4</a>);</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6831
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6832 <li>basic UTF-8 support (<a href="#6.5">§6.5</a>);</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6833
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6834 <li>table manipulation (<a href="#6.6">§6.6</a>);</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6835
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6836 <li>mathematical functions (<a href="#6.7">§6.7</a>) (sin, log, etc.);</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6837
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6838 <li>input and output (<a href="#6.8">§6.8</a>);</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6839
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6840 <li>operating system facilities (<a href="#6.9">§6.9</a>);</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6841
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6842 <li>debug facilities (<a href="#6.10">§6.10</a>).</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6843
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6844 </ul><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6845 Except for the basic and the package libraries,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6846 each library provides all its functions as fields of a global table
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6847 or as methods of its objects.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6848
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6849
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6850 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6851 To have access to these libraries,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6852 the C host program should call the <a href="#luaL_openlibs"><code>luaL_openlibs</code></a> function,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6853 which opens all standard libraries.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6854 Alternatively,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6855 the host program can open them individually by using
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6856 <a href="#luaL_requiref"><code>luaL_requiref</code></a> to call
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6857 <a name="pdf-luaopen_base"><code>luaopen_base</code></a> (for the basic library),
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6858 <a name="pdf-luaopen_package"><code>luaopen_package</code></a> (for the package library),
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6859 <a name="pdf-luaopen_coroutine"><code>luaopen_coroutine</code></a> (for the coroutine library),
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6860 <a name="pdf-luaopen_string"><code>luaopen_string</code></a> (for the string library),
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6861 <a name="pdf-luaopen_utf8"><code>luaopen_utf8</code></a> (for the UTF8 library),
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6862 <a name="pdf-luaopen_table"><code>luaopen_table</code></a> (for the table library),
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6863 <a name="pdf-luaopen_math"><code>luaopen_math</code></a> (for the mathematical library),
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6864 <a name="pdf-luaopen_io"><code>luaopen_io</code></a> (for the I/O library),
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6865 <a name="pdf-luaopen_os"><code>luaopen_os</code></a> (for the operating system library),
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6866 and <a name="pdf-luaopen_debug"><code>luaopen_debug</code></a> (for the debug library).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6867 These functions are declared in <a name="pdf-lualib.h"><code>lualib.h</code></a>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6868
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6869
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6870
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6871 <h2>6.1 – <a name="6.1">Basic Functions</a></h2>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6872
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6873 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6874 The basic library provides core functions to Lua.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6875 If you do not include this library in your application,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6876 you should check carefully whether you need to provide
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6877 implementations for some of its facilities.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6878
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6879
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6880 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6881 <hr><h3><a name="pdf-assert"><code>assert (v [, message])</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6882
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6883
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6884 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6885 Calls <a href="#pdf-error"><code>error</code></a> if
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6886 the value of its argument <code>v</code> is false (i.e., <b>nil</b> or <b>false</b>);
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6887 otherwise, returns all its arguments.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6888 In case of error,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6889 <code>message</code> is the error object;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6890 when absent, it defaults to "<code>assertion failed!</code>"
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6891
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6892
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6893
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6894
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6895 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6896 <hr><h3><a name="pdf-collectgarbage"><code>collectgarbage ([opt [, arg]])</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6897
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6898
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6899 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6900 This function is a generic interface to the garbage collector.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6901 It performs different functions according to its first argument, <code>opt</code>:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6902
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6903 <ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6904
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6905 <li><b>"<code>collect</code>": </b>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6906 performs a full garbage-collection cycle.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6907 This is the default option.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6908 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6909
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6910 <li><b>"<code>stop</code>": </b>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6911 stops automatic execution of the garbage collector.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6912 The collector will run only when explicitly invoked,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6913 until a call to restart it.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6914 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6915
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6916 <li><b>"<code>restart</code>": </b>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6917 restarts automatic execution of the garbage collector.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6918 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6919
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6920 <li><b>"<code>count</code>": </b>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6921 returns the total memory in use by Lua in Kbytes.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6922 The value has a fractional part,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6923 so that it multiplied by 1024
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6924 gives the exact number of bytes in use by Lua
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6925 (except for overflows).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6926 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6927
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6928 <li><b>"<code>step</code>": </b>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6929 performs a garbage-collection step.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6930 The step "size" is controlled by <code>arg</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6931 With a zero value,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6932 the collector will perform one basic (indivisible) step.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6933 For non-zero values,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6934 the collector will perform as if that amount of memory
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6935 (in KBytes) had been allocated by Lua.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6936 Returns <b>true</b> if the step finished a collection cycle.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6937 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6938
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6939 <li><b>"<code>setpause</code>": </b>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6940 sets <code>arg</code> as the new value for the <em>pause</em> of
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6941 the collector (see <a href="#2.5">§2.5</a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6942 Returns the previous value for <em>pause</em>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6943 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6944
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6945 <li><b>"<code>setstepmul</code>": </b>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6946 sets <code>arg</code> as the new value for the <em>step multiplier</em> of
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6947 the collector (see <a href="#2.5">§2.5</a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6948 Returns the previous value for <em>step</em>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6949 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6950
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6951 <li><b>"<code>isrunning</code>": </b>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6952 returns a boolean that tells whether the collector is running
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6953 (i.e., not stopped).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6954 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6955
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6956 </ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6957
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6958
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6959
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6960 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6961 <hr><h3><a name="pdf-dofile"><code>dofile ([filename])</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6962 Opens the named file and executes its contents as a Lua chunk.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6963 When called without arguments,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6964 <code>dofile</code> executes the contents of the standard input (<code>stdin</code>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6965 Returns all values returned by the chunk.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6966 In case of errors, <code>dofile</code> propagates the error
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6967 to its caller (that is, <code>dofile</code> does not run in protected mode).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6968
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6969
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6970
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6971
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6972 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6973 <hr><h3><a name="pdf-error"><code>error (message [, level])</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6974 Terminates the last protected function called
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6975 and returns <code>message</code> as the error object.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6976 Function <code>error</code> never returns.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6977
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6978
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6979 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6980 Usually, <code>error</code> adds some information about the error position
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6981 at the beginning of the message, if the message is a string.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6982 The <code>level</code> argument specifies how to get the error position.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6983 With level 1 (the default), the error position is where the
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6984 <code>error</code> function was called.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6985 Level 2 points the error to where the function
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6986 that called <code>error</code> was called; and so on.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6987 Passing a level 0 avoids the addition of error position information
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6988 to the message.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6989
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6990
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6991
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6992
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6993 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6994 <hr><h3><a name="pdf-_G"><code>_G</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6995 A global variable (not a function) that
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6996 holds the global environment (see <a href="#2.2">§2.2</a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6997 Lua itself does not use this variable;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6998 changing its value does not affect any environment,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6999 nor vice versa.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7000
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7001
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7002
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7003
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7004 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7005 <hr><h3><a name="pdf-getmetatable"><code>getmetatable (object)</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7006
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7007
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7008 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7009 If <code>object</code> does not have a metatable, returns <b>nil</b>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7010 Otherwise,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7011 if the object's metatable has a <code>"__metatable"</code> field,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7012 returns the associated value.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7013 Otherwise, returns the metatable of the given object.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7014
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7015
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7016
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7017
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7018 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7019 <hr><h3><a name="pdf-ipairs"><code>ipairs (t)</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7020
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7021
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7022 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7023 Returns three values (an iterator function, the table <code>t</code>, and 0)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7024 so that the construction
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7025
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7026 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7027 for i,v in ipairs(t) do <em>body</em> end
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7028 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7029 will iterate over the key–value pairs
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7030 (<code>1,t[1]</code>), (<code>2,t[2]</code>), ...,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7031 up to the first nil value.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7032
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7033
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7034
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7035
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7036 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7037 <hr><h3><a name="pdf-load"><code>load (chunk [, chunkname [, mode [, env]]])</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7038
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7039
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7040 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7041 Loads a chunk.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7042
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7043
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7044 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7045 If <code>chunk</code> is a string, the chunk is this string.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7046 If <code>chunk</code> is a function,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7047 <code>load</code> calls it repeatedly to get the chunk pieces.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7048 Each call to <code>chunk</code> must return a string that concatenates
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7049 with previous results.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7050 A return of an empty string, <b>nil</b>, or no value signals the end of the chunk.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7051
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7052
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7053 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7054 If there are no syntactic errors,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7055 returns the compiled chunk as a function;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7056 otherwise, returns <b>nil</b> plus the error message.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7057
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7058
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7059 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7060 If the resulting function has upvalues,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7061 the first upvalue is set to the value of <code>env</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7062 if that parameter is given,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7063 or to the value of the global environment.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7064 Other upvalues are initialized with <b>nil</b>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7065 (When you load a main chunk,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7066 the resulting function will always have exactly one upvalue,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7067 the <code>_ENV</code> variable (see <a href="#2.2">§2.2</a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7068 However,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7069 when you load a binary chunk created from a function (see <a href="#pdf-string.dump"><code>string.dump</code></a>),
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7070 the resulting function can have an arbitrary number of upvalues.)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7071 All upvalues are fresh, that is,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7072 they are not shared with any other function.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7073
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7074
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7075 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7076 <code>chunkname</code> is used as the name of the chunk for error messages
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7077 and debug information (see <a href="#4.9">§4.9</a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7078 When absent,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7079 it defaults to <code>chunk</code>, if <code>chunk</code> is a string,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7080 or to "<code>=(load)</code>" otherwise.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7081
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7082
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7083 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7084 The string <code>mode</code> controls whether the chunk can be text or binary
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7085 (that is, a precompiled chunk).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7086 It may be the string "<code>b</code>" (only binary chunks),
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7087 "<code>t</code>" (only text chunks),
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7088 or "<code>bt</code>" (both binary and text).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7089 The default is "<code>bt</code>".
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7090
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7091
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7092 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7093 Lua does not check the consistency of binary chunks.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7094 Maliciously crafted binary chunks can crash
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7095 the interpreter.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7096
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7097
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7098
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7099
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7100 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7101 <hr><h3><a name="pdf-loadfile"><code>loadfile ([filename [, mode [, env]]])</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7102
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7103
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7104 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7105 Similar to <a href="#pdf-load"><code>load</code></a>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7106 but gets the chunk from file <code>filename</code>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7107 or from the standard input,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7108 if no file name is given.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7109
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7110
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7111
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7112
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7113 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7114 <hr><h3><a name="pdf-next"><code>next (table [, index])</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7115
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7116
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7117 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7118 Allows a program to traverse all fields of a table.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7119 Its first argument is a table and its second argument
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7120 is an index in this table.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7121 <code>next</code> returns the next index of the table
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7122 and its associated value.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7123 When called with <b>nil</b> as its second argument,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7124 <code>next</code> returns an initial index
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7125 and its associated value.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7126 When called with the last index,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7127 or with <b>nil</b> in an empty table,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7128 <code>next</code> returns <b>nil</b>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7129 If the second argument is absent, then it is interpreted as <b>nil</b>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7130 In particular,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7131 you can use <code>next(t)</code> to check whether a table is empty.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7132
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7133
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7134 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7135 The order in which the indices are enumerated is not specified,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7136 <em>even for numeric indices</em>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7137 (To traverse a table in numeric order,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7138 use a numerical <b>for</b>.)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7139
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7140
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7141 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7142 The behavior of <code>next</code> is undefined if,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7143 during the traversal,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7144 you assign any value to a non-existent field in the table.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7145 You may however modify existing fields.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7146 In particular, you may clear existing fields.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7147
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7148
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7149
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7150
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7151 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7152 <hr><h3><a name="pdf-pairs"><code>pairs (t)</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7153
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7154
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7155 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7156 If <code>t</code> has a metamethod <code>__pairs</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7157 calls it with <code>t</code> as argument and returns the first three
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7158 results from the call.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7159
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7160
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7161 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7162 Otherwise,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7163 returns three values: the <a href="#pdf-next"><code>next</code></a> function, the table <code>t</code>, and <b>nil</b>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7164 so that the construction
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7165
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7166 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7167 for k,v in pairs(t) do <em>body</em> end
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7168 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7169 will iterate over all key–value pairs of table <code>t</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7170
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7171
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7172 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7173 See function <a href="#pdf-next"><code>next</code></a> for the caveats of modifying
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7174 the table during its traversal.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7175
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7176
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7177
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7178
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7179 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7180 <hr><h3><a name="pdf-pcall"><code>pcall (f [, arg1, ···])</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7181
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7182
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7183 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7184 Calls function <code>f</code> with
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7185 the given arguments in <em>protected mode</em>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7186 This means that any error inside <code>f</code> is not propagated;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7187 instead, <code>pcall</code> catches the error
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7188 and returns a status code.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7189 Its first result is the status code (a boolean),
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7190 which is true if the call succeeds without errors.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7191 In such case, <code>pcall</code> also returns all results from the call,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7192 after this first result.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7193 In case of any error, <code>pcall</code> returns <b>false</b> plus the error message.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7194
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7195
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7196
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7197
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7198 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7199 <hr><h3><a name="pdf-print"><code>print (···)</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7200 Receives any number of arguments
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7201 and prints their values to <code>stdout</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7202 using the <a href="#pdf-tostring"><code>tostring</code></a> function to convert each argument to a string.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7203 <code>print</code> is not intended for formatted output,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7204 but only as a quick way to show a value,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7205 for instance for debugging.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7206 For complete control over the output,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7207 use <a href="#pdf-string.format"><code>string.format</code></a> and <a href="#pdf-io.write"><code>io.write</code></a>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7208
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7209
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7210
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7211
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7212 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7213 <hr><h3><a name="pdf-rawequal"><code>rawequal (v1, v2)</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7214 Checks whether <code>v1</code> is equal to <code>v2</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7215 without invoking any metamethod.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7216 Returns a boolean.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7217
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7218
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7219
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7220
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7221 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7222 <hr><h3><a name="pdf-rawget"><code>rawget (table, index)</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7223 Gets the real value of <code>table[index]</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7224 without invoking any metamethod.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7225 <code>table</code> must be a table;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7226 <code>index</code> may be any value.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7227
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7228
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7229
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7230
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7231 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7232 <hr><h3><a name="pdf-rawlen"><code>rawlen (v)</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7233 Returns the length of the object <code>v</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7234 which must be a table or a string,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7235 without invoking any metamethod.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7236 Returns an integer.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7237
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7238
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7239
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7240
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7241 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7242 <hr><h3><a name="pdf-rawset"><code>rawset (table, index, value)</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7243 Sets the real value of <code>table[index]</code> to <code>value</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7244 without invoking any metamethod.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7245 <code>table</code> must be a table,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7246 <code>index</code> any value different from <b>nil</b> and NaN,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7247 and <code>value</code> any Lua value.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7248
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7249
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7250 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7251 This function returns <code>table</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7252
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7253
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7254
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7255
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7256 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7257 <hr><h3><a name="pdf-select"><code>select (index, ···)</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7258
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7259
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7260 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7261 If <code>index</code> is a number,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7262 returns all arguments after argument number <code>index</code>;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7263 a negative number indexes from the end (-1 is the last argument).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7264 Otherwise, <code>index</code> must be the string <code>"#"</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7265 and <code>select</code> returns the total number of extra arguments it received.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7266
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7267
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7268
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7269
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7270 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7271 <hr><h3><a name="pdf-setmetatable"><code>setmetatable (table, metatable)</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7272
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7273
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7274 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7275 Sets the metatable for the given table.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7276 (You cannot change the metatable of other types from Lua, only from C.)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7277 If <code>metatable</code> is <b>nil</b>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7278 removes the metatable of the given table.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7279 If the original metatable has a <code>"__metatable"</code> field,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7280 raises an error.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7281
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7282
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7283 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7284 This function returns <code>table</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7285
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7286
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7287
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7288
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7289 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7290 <hr><h3><a name="pdf-tonumber"><code>tonumber (e [, base])</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7291
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7292
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7293 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7294 When called with no <code>base</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7295 <code>tonumber</code> tries to convert its argument to a number.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7296 If the argument is already a number or
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7297 a string convertible to a number,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7298 then <code>tonumber</code> returns this number;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7299 otherwise, it returns <b>nil</b>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7300
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7301
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7302 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7303 The conversion of strings can result in integers or floats,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7304 according to the lexical conventions of Lua (see <a href="#3.1">§3.1</a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7305 (The string may have leading and trailing spaces and a sign.)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7306
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7307
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7308 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7309 When called with <code>base</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7310 then <code>e</code> must be a string to be interpreted as
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7311 an integer numeral in that base.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7312 The base may be any integer between 2 and 36, inclusive.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7313 In bases above 10, the letter '<code>A</code>' (in either upper or lower case)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7314 represents 10, '<code>B</code>' represents 11, and so forth,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7315 with '<code>Z</code>' representing 35.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7316 If the string <code>e</code> is not a valid numeral in the given base,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7317 the function returns <b>nil</b>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7318
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7319
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7320
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7321
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7322 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7323 <hr><h3><a name="pdf-tostring"><code>tostring (v)</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7324 Receives a value of any type and
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7325 converts it to a string in a human-readable format.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7326 Floats always produce strings with some
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7327 floating-point indication (either a decimal dot or an exponent).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7328 (For complete control of how numbers are converted,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7329 use <a href="#pdf-string.format"><code>string.format</code></a>.)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7330
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7331
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7332 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7333 If the metatable of <code>v</code> has a <code>"__tostring"</code> field,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7334 then <code>tostring</code> calls the corresponding value
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7335 with <code>v</code> as argument,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7336 and uses the result of the call as its result.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7337
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7338
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7339
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7340
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7341 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7342 <hr><h3><a name="pdf-type"><code>type (v)</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7343 Returns the type of its only argument, coded as a string.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7344 The possible results of this function are
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7345 "<code>nil</code>" (a string, not the value <b>nil</b>),
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7346 "<code>number</code>",
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7347 "<code>string</code>",
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7348 "<code>boolean</code>",
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7349 "<code>table</code>",
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7350 "<code>function</code>",
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7351 "<code>thread</code>",
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7352 and "<code>userdata</code>".
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7353
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7354
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7355
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7356
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7357 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7358 <hr><h3><a name="pdf-_VERSION"><code>_VERSION</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7359 A global variable (not a function) that
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7360 holds a string containing the current interpreter version.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7361 The current value of this variable is "<code>Lua 5.3</code>".
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7362
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7363
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7364
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7365
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7366 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7367 <hr><h3><a name="pdf-xpcall"><code>xpcall (f, msgh [, arg1, ···])</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7368
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7369
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7370 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7371 This function is similar to <a href="#pdf-pcall"><code>pcall</code></a>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7372 except that it sets a new message handler <code>msgh</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7373
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7374
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7375
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7376
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7377
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7378
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7379
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7380 <h2>6.2 – <a name="6.2">Coroutine Manipulation</a></h2>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7381
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7382 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7383 The operations related to coroutines comprise a sub-library of
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7384 the basic library and come inside the table <a name="pdf-coroutine"><code>coroutine</code></a>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7385 See <a href="#2.6">§2.6</a> for a general description of coroutines.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7386
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7387
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7388 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7389 <hr><h3><a name="pdf-coroutine.create"><code>coroutine.create (f)</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7390
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7391
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7392 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7393 Creates a new coroutine, with body <code>f</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7394 <code>f</code> must be a Lua function.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7395 Returns this new coroutine,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7396 an object with type <code>"thread"</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7397
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7398
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7399
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7400
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7401 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7402 <hr><h3><a name="pdf-coroutine.isyieldable"><code>coroutine.isyieldable ()</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7403
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7404
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7405 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7406 Returns true when the running coroutine can yield.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7407
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7408
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7409 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7410 A running coroutine is yieldable if it is not the main thread and
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7411 it is not inside a non-yieldable C function.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7412
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7413
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7414
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7415
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7416 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7417 <hr><h3><a name="pdf-coroutine.resume"><code>coroutine.resume (co [, val1, ···])</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7418
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7419
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7420 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7421 Starts or continues the execution of coroutine <code>co</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7422 The first time you resume a coroutine,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7423 it starts running its body.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7424 The values <code>val1</code>, ... are passed
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7425 as the arguments to the body function.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7426 If the coroutine has yielded,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7427 <code>resume</code> restarts it;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7428 the values <code>val1</code>, ... are passed
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7429 as the results from the yield.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7430
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7431
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7432 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7433 If the coroutine runs without any errors,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7434 <code>resume</code> returns <b>true</b> plus any values passed to <code>yield</code>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7435 (when the coroutine yields) or any values returned by the body function
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7436 (when the coroutine terminates).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7437 If there is any error,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7438 <code>resume</code> returns <b>false</b> plus the error message.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7439
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7440
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7441
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7442
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7443 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7444 <hr><h3><a name="pdf-coroutine.running"><code>coroutine.running ()</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7445
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7446
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7447 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7448 Returns the running coroutine plus a boolean,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7449 true when the running coroutine is the main one.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7450
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7451
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7452
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7453
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7454 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7455 <hr><h3><a name="pdf-coroutine.status"><code>coroutine.status (co)</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7456
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7457
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7458 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7459 Returns the status of coroutine <code>co</code>, as a string:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7460 <code>"running"</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7461 if the coroutine is running (that is, it called <code>status</code>);
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7462 <code>"suspended"</code>, if the coroutine is suspended in a call to <code>yield</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7463 or if it has not started running yet;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7464 <code>"normal"</code> if the coroutine is active but not running
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7465 (that is, it has resumed another coroutine);
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7466 and <code>"dead"</code> if the coroutine has finished its body function,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7467 or if it has stopped with an error.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7468
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7469
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7470
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7471
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7472 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7473 <hr><h3><a name="pdf-coroutine.wrap"><code>coroutine.wrap (f)</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7474
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7475
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7476 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7477 Creates a new coroutine, with body <code>f</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7478 <code>f</code> must be a Lua function.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7479 Returns a function that resumes the coroutine each time it is called.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7480 Any arguments passed to the function behave as the
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7481 extra arguments to <code>resume</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7482 Returns the same values returned by <code>resume</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7483 except the first boolean.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7484 In case of error, propagates the error.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7485
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7486
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7487
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7488
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7489 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7490 <hr><h3><a name="pdf-coroutine.yield"><code>coroutine.yield (···)</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7491
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7492
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7493 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7494 Suspends the execution of the calling coroutine.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7495 Any arguments to <code>yield</code> are passed as extra results to <code>resume</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7496
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7497
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7498
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7499
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7500
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7501
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7502
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7503 <h2>6.3 – <a name="6.3">Modules</a></h2>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7504
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7505 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7506 The package library provides basic
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7507 facilities for loading modules in Lua.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7508 It exports one function directly in the global environment:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7509 <a href="#pdf-require"><code>require</code></a>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7510 Everything else is exported in a table <a name="pdf-package"><code>package</code></a>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7511
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7512
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7513 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7514 <hr><h3><a name="pdf-require"><code>require (modname)</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7515
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7516
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7517 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7518 Loads the given module.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7519 The function starts by looking into the <a href="#pdf-package.loaded"><code>package.loaded</code></a> table
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7520 to determine whether <code>modname</code> is already loaded.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7521 If it is, then <code>require</code> returns the value stored
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7522 at <code>package.loaded[modname]</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7523 Otherwise, it tries to find a <em>loader</em> for the module.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7524
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7525
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7526 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7527 To find a loader,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7528 <code>require</code> is guided by the <a href="#pdf-package.searchers"><code>package.searchers</code></a> sequence.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7529 By changing this sequence,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7530 we can change how <code>require</code> looks for a module.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7531 The following explanation is based on the default configuration
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7532 for <a href="#pdf-package.searchers"><code>package.searchers</code></a>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7533
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7534
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7535 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7536 First <code>require</code> queries <code>package.preload[modname]</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7537 If it has a value,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7538 this value (which must be a function) is the loader.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7539 Otherwise <code>require</code> searches for a Lua loader using the
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7540 path stored in <a href="#pdf-package.path"><code>package.path</code></a>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7541 If that also fails, it searches for a C loader using the
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7542 path stored in <a href="#pdf-package.cpath"><code>package.cpath</code></a>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7543 If that also fails,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7544 it tries an <em>all-in-one</em> loader (see <a href="#pdf-package.searchers"><code>package.searchers</code></a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7545
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7546
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7547 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7548 Once a loader is found,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7549 <code>require</code> calls the loader with two arguments:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7550 <code>modname</code> and an extra value dependent on how it got the loader.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7551 (If the loader came from a file,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7552 this extra value is the file name.)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7553 If the loader returns any non-nil value,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7554 <code>require</code> assigns the returned value to <code>package.loaded[modname]</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7555 If the loader does not return a non-nil value and
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7556 has not assigned any value to <code>package.loaded[modname]</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7557 then <code>require</code> assigns <b>true</b> to this entry.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7558 In any case, <code>require</code> returns the
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7559 final value of <code>package.loaded[modname]</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7560
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7561
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7562 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7563 If there is any error loading or running the module,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7564 or if it cannot find any loader for the module,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7565 then <code>require</code> raises an error.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7566
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7567
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7568
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7569
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7570 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7571 <hr><h3><a name="pdf-package.config"><code>package.config</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7572
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7573
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7574 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7575 A string describing some compile-time configurations for packages.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7576 This string is a sequence of lines:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7577
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7578 <ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7579
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7580 <li>The first line is the directory separator string.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7581 Default is '<code>\</code>' for Windows and '<code>/</code>' for all other systems.</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7582
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7583 <li>The second line is the character that separates templates in a path.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7584 Default is '<code>;</code>'.</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7585
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7586 <li>The third line is the string that marks the
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7587 substitution points in a template.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7588 Default is '<code>?</code>'.</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7589
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7590 <li>The fourth line is a string that, in a path in Windows,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7591 is replaced by the executable's directory.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7592 Default is '<code>!</code>'.</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7593
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7594 <li>The fifth line is a mark to ignore all text after it
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7595 when building the <code>luaopen_</code> function name.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7596 Default is '<code>-</code>'.</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7597
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7598 </ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7599
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7600
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7601
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7602 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7603 <hr><h3><a name="pdf-package.cpath"><code>package.cpath</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7604
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7605
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7606 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7607 The path used by <a href="#pdf-require"><code>require</code></a> to search for a C loader.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7608
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7609
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7610 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7611 Lua initializes the C path <a href="#pdf-package.cpath"><code>package.cpath</code></a> in the same way
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7612 it initializes the Lua path <a href="#pdf-package.path"><code>package.path</code></a>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7613 using the environment variable <a name="pdf-LUA_CPATH_5_3"><code>LUA_CPATH_5_3</code></a>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7614 or the environment variable <a name="pdf-LUA_CPATH"><code>LUA_CPATH</code></a>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7615 or a default path defined in <code>luaconf.h</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7616
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7617
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7618
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7619
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7620 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7621 <hr><h3><a name="pdf-package.loaded"><code>package.loaded</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7622
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7623
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7624 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7625 A table used by <a href="#pdf-require"><code>require</code></a> to control which
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7626 modules are already loaded.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7627 When you require a module <code>modname</code> and
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7628 <code>package.loaded[modname]</code> is not false,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7629 <a href="#pdf-require"><code>require</code></a> simply returns the value stored there.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7630
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7631
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7632 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7633 This variable is only a reference to the real table;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7634 assignments to this variable do not change the
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7635 table used by <a href="#pdf-require"><code>require</code></a>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7636
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7637
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7638
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7639
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7640 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7641 <hr><h3><a name="pdf-package.loadlib"><code>package.loadlib (libname, funcname)</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7642
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7643
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7644 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7645 Dynamically links the host program with the C library <code>libname</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7646
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7647
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7648 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7649 If <code>funcname</code> is "<code>*</code>",
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7650 then it only links with the library,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7651 making the symbols exported by the library
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7652 available to other dynamically linked libraries.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7653 Otherwise,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7654 it looks for a function <code>funcname</code> inside the library
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7655 and returns this function as a C function.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7656 So, <code>funcname</code> must follow the <a href="#lua_CFunction"><code>lua_CFunction</code></a> prototype
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7657 (see <a href="#lua_CFunction"><code>lua_CFunction</code></a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7658
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7659
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7660 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7661 This is a low-level function.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7662 It completely bypasses the package and module system.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7663 Unlike <a href="#pdf-require"><code>require</code></a>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7664 it does not perform any path searching and
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7665 does not automatically adds extensions.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7666 <code>libname</code> must be the complete file name of the C library,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7667 including if necessary a path and an extension.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7668 <code>funcname</code> must be the exact name exported by the C library
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7669 (which may depend on the C compiler and linker used).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7670
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7671
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7672 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7673 This function is not supported by Standard C.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7674 As such, it is only available on some platforms
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7675 (Windows, Linux, Mac OS X, Solaris, BSD,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7676 plus other Unix systems that support the <code>dlfcn</code> standard).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7677
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7678
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7679
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7680
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7681 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7682 <hr><h3><a name="pdf-package.path"><code>package.path</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7683
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7684
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7685 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7686 The path used by <a href="#pdf-require"><code>require</code></a> to search for a Lua loader.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7687
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7688
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7689 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7690 At start-up, Lua initializes this variable with
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7691 the value of the environment variable <a name="pdf-LUA_PATH_5_3"><code>LUA_PATH_5_3</code></a> or
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7692 the environment variable <a name="pdf-LUA_PATH"><code>LUA_PATH</code></a> or
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7693 with a default path defined in <code>luaconf.h</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7694 if those environment variables are not defined.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7695 Any "<code>;;</code>" in the value of the environment variable
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7696 is replaced by the default path.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7697
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7698
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7699
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7700
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7701 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7702 <hr><h3><a name="pdf-package.preload"><code>package.preload</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7703
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7704
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7705 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7706 A table to store loaders for specific modules
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7707 (see <a href="#pdf-require"><code>require</code></a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7708
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7709
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7710 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7711 This variable is only a reference to the real table;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7712 assignments to this variable do not change the
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7713 table used by <a href="#pdf-require"><code>require</code></a>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7714
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7715
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7716
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7717
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7718 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7719 <hr><h3><a name="pdf-package.searchers"><code>package.searchers</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7720
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7721
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7722 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7723 A table used by <a href="#pdf-require"><code>require</code></a> to control how to load modules.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7724
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7725
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7726 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7727 Each entry in this table is a <em>searcher function</em>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7728 When looking for a module,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7729 <a href="#pdf-require"><code>require</code></a> calls each of these searchers in ascending order,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7730 with the module name (the argument given to <a href="#pdf-require"><code>require</code></a>) as its
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7731 sole parameter.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7732 The function can return another function (the module <em>loader</em>)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7733 plus an extra value that will be passed to that loader,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7734 or a string explaining why it did not find that module
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7735 (or <b>nil</b> if it has nothing to say).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7736
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7737
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7738 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7739 Lua initializes this table with four searcher functions.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7740
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7741
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7742 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7743 The first searcher simply looks for a loader in the
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7744 <a href="#pdf-package.preload"><code>package.preload</code></a> table.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7745
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7746
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7747 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7748 The second searcher looks for a loader as a Lua library,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7749 using the path stored at <a href="#pdf-package.path"><code>package.path</code></a>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7750 The search is done as described in function <a href="#pdf-package.searchpath"><code>package.searchpath</code></a>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7751
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7752
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7753 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7754 The third searcher looks for a loader as a C library,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7755 using the path given by the variable <a href="#pdf-package.cpath"><code>package.cpath</code></a>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7756 Again,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7757 the search is done as described in function <a href="#pdf-package.searchpath"><code>package.searchpath</code></a>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7758 For instance,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7759 if the C path is the string
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7760
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7761 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7762 "./?.so;./?.dll;/usr/local/?/init.so"
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7763 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7764 the searcher for module <code>foo</code>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7765 will try to open the files <code>./foo.so</code>, <code>./foo.dll</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7766 and <code>/usr/local/foo/init.so</code>, in that order.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7767 Once it finds a C library,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7768 this searcher first uses a dynamic link facility to link the
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7769 application with the library.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7770 Then it tries to find a C function inside the library to
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7771 be used as the loader.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7772 The name of this C function is the string "<code>luaopen_</code>"
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7773 concatenated with a copy of the module name where each dot
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7774 is replaced by an underscore.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7775 Moreover, if the module name has a hyphen,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7776 its suffix after (and including) the first hyphen is removed.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7777 For instance, if the module name is <code>a.b.c-v2.1</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7778 the function name will be <code>luaopen_a_b_c</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7779
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7780
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7781 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7782 The fourth searcher tries an <em>all-in-one loader</em>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7783 It searches the C path for a library for
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7784 the root name of the given module.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7785 For instance, when requiring <code>a.b.c</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7786 it will search for a C library for <code>a</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7787 If found, it looks into it for an open function for
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7788 the submodule;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7789 in our example, that would be <code>luaopen_a_b_c</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7790 With this facility, a package can pack several C submodules
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7791 into one single library,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7792 with each submodule keeping its original open function.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7793
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7794
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7795 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7796 All searchers except the first one (preload) return as the extra value
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7797 the file name where the module was found,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7798 as returned by <a href="#pdf-package.searchpath"><code>package.searchpath</code></a>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7799 The first searcher returns no extra value.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7800
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7801
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7802
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7803
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7804 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7805 <hr><h3><a name="pdf-package.searchpath"><code>package.searchpath (name, path [, sep [, rep]])</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7806
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7807
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7808 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7809 Searches for the given <code>name</code> in the given <code>path</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7810
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7811
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7812 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7813 A path is a string containing a sequence of
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7814 <em>templates</em> separated by semicolons.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7815 For each template,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7816 the function replaces each interrogation mark (if any)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7817 in the template with a copy of <code>name</code>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7818 wherein all occurrences of <code>sep</code>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7819 (a dot, by default)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7820 were replaced by <code>rep</code>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7821 (the system's directory separator, by default),
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7822 and then tries to open the resulting file name.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7823
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7824
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7825 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7826 For instance, if the path is the string
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7827
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7828 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7829 "./?.lua;./?.lc;/usr/local/?/init.lua"
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7830 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7831 the search for the name <code>foo.a</code>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7832 will try to open the files
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7833 <code>./foo/a.lua</code>, <code>./foo/a.lc</code>, and
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7834 <code>/usr/local/foo/a/init.lua</code>, in that order.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7835
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7836
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7837 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7838 Returns the resulting name of the first file that it can
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7839 open in read mode (after closing the file),
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7840 or <b>nil</b> plus an error message if none succeeds.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7841 (This error message lists all file names it tried to open.)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7842
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7843
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7844
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7845
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7846
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7847
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7848
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7849 <h2>6.4 – <a name="6.4">String Manipulation</a></h2>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7850
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7851 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7852 This library provides generic functions for string manipulation,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7853 such as finding and extracting substrings, and pattern matching.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7854 When indexing a string in Lua, the first character is at position 1
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7855 (not at 0, as in C).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7856 Indices are allowed to be negative and are interpreted as indexing backwards,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7857 from the end of the string.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7858 Thus, the last character is at position -1, and so on.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7859
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7860
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7861 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7862 The string library provides all its functions inside the table
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7863 <a name="pdf-string"><code>string</code></a>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7864 It also sets a metatable for strings
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7865 where the <code>__index</code> field points to the <code>string</code> table.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7866 Therefore, you can use the string functions in object-oriented style.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7867 For instance, <code>string.byte(s,i)</code>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7868 can be written as <code>s:byte(i)</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7869
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7870
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7871 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7872 The string library assumes one-byte character encodings.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7873
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7874
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7875 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7876 <hr><h3><a name="pdf-string.byte"><code>string.byte (s [, i [, j]])</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7877 Returns the internal numerical codes of the characters <code>s[i]</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7878 <code>s[i+1]</code>, ..., <code>s[j]</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7879 The default value for <code>i</code> is 1;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7880 the default value for <code>j</code> is <code>i</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7881 These indices are corrected
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7882 following the same rules of function <a href="#pdf-string.sub"><code>string.sub</code></a>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7883
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7884
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7885 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7886 Numerical codes are not necessarily portable across platforms.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7887
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7888
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7889
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7890
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7891 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7892 <hr><h3><a name="pdf-string.char"><code>string.char (···)</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7893 Receives zero or more integers.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7894 Returns a string with length equal to the number of arguments,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7895 in which each character has the internal numerical code equal
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7896 to its corresponding argument.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7897
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7898
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7899 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7900 Numerical codes are not necessarily portable across platforms.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7901
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7902
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7903
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7904
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7905 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7906 <hr><h3><a name="pdf-string.dump"><code>string.dump (function [, strip])</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7907
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7908
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7909 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7910 Returns a string containing a binary representation
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7911 (a <em>binary chunk</em>)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7912 of the given function,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7913 so that a later <a href="#pdf-load"><code>load</code></a> on this string returns
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7914 a copy of the function (but with new upvalues).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7915 If <code>strip</code> is a true value,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7916 the binary representation is created without debug information
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7917 about the function
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7918 (local variable names, lines, etc.).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7919
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7920
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7921 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7922 Functions with upvalues have only their number of upvalues saved.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7923 When (re)loaded,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7924 those upvalues receive fresh instances containing <b>nil</b>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7925 (You can use the debug library to serialize
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7926 and reload the upvalues of a function
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7927 in a way adequate to your needs.)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7928
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7929
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7930
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7931
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7932 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7933 <hr><h3><a name="pdf-string.find"><code>string.find (s, pattern [, init [, plain]])</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7934
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7935
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7936 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7937 Looks for the first match of
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7938 <code>pattern</code> (see <a href="#6.4.1">§6.4.1</a>) in the string <code>s</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7939 If it finds a match, then <code>find</code> returns the indices of <code>s</code>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7940 where this occurrence starts and ends;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7941 otherwise, it returns <b>nil</b>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7942 A third, optional numerical argument <code>init</code> specifies
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7943 where to start the search;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7944 its default value is 1 and can be negative.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7945 A value of <b>true</b> as a fourth, optional argument <code>plain</code>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7946 turns off the pattern matching facilities,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7947 so the function does a plain "find substring" operation,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7948 with no characters in <code>pattern</code> being considered magic.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7949 Note that if <code>plain</code> is given, then <code>init</code> must be given as well.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7950
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7951
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7952 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7953 If the pattern has captures,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7954 then in a successful match
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7955 the captured values are also returned,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7956 after the two indices.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7957
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7958
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7959
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7960
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7961 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7962 <hr><h3><a name="pdf-string.format"><code>string.format (formatstring, ···)</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7963
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7964
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7965 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7966 Returns a formatted version of its variable number of arguments
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7967 following the description given in its first argument (which must be a string).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7968 The format string follows the same rules as the ISO C function <code>sprintf</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7969 The only differences are that the options/modifiers
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7970 <code>*</code>, <code>h</code>, <code>L</code>, <code>l</code>, <code>n</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7971 and <code>p</code> are not supported
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7972 and that there is an extra option, <code>q</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7973 The <code>q</code> option formats a string between double quotes,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7974 using escape sequences when necessary to ensure that
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7975 it can safely be read back by the Lua interpreter.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7976 For instance, the call
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7977
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7978 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7979 string.format('%q', 'a string with "quotes" and \n new line')
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7980 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7981 may produce the string:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7982
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7983 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7984 "a string with \"quotes\" and \
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7985 new line"
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7986 </pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7987
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7988 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7989 Options
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7990 <code>A</code> and <code>a</code> (when available),
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7991 <code>E</code>, <code>e</code>, <code>f</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7992 <code>G</code>, and <code>g</code> all expect a number as argument.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7993 Options <code>c</code>, <code>d</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7994 <code>i</code>, <code>o</code>, <code>u</code>, <code>X</code>, and <code>x</code>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7995 expect an integer.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7996 Option <code>q</code> expects a string;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7997 option <code>s</code> expects a string without embedded zeros.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7998 If the argument to option <code>s</code> is not a string,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7999 it is converted to one following the same rules of <a href="#pdf-tostring"><code>tostring</code></a>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8000
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8001
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8002
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8003
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8004 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8005 <hr><h3><a name="pdf-string.gmatch"><code>string.gmatch (s, pattern)</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8006 Returns an iterator function that,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8007 each time it is called,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8008 returns the next captures from <code>pattern</code> (see <a href="#6.4.1">§6.4.1</a>)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8009 over the string <code>s</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8010 If <code>pattern</code> specifies no captures,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8011 then the whole match is produced in each call.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8012
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8013
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8014 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8015 As an example, the following loop
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8016 will iterate over all the words from string <code>s</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8017 printing one per line:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8018
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8019 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8020 s = "hello world from Lua"
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8021 for w in string.gmatch(s, "%a+") do
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8022 print(w)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8023 end
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8024 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8025 The next example collects all pairs <code>key=value</code> from the
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8026 given string into a table:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8027
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8028 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8029 t = {}
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8030 s = "from=world, to=Lua"
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8031 for k, v in string.gmatch(s, "(%w+)=(%w+)") do
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8032 t[k] = v
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8033 end
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8034 </pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8035
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8036 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8037 For this function, a caret '<code>^</code>' at the start of a pattern does not
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8038 work as an anchor, as this would prevent the iteration.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8039
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8040
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8041
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8042
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8043 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8044 <hr><h3><a name="pdf-string.gsub"><code>string.gsub (s, pattern, repl [, n])</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8045 Returns a copy of <code>s</code>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8046 in which all (or the first <code>n</code>, if given)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8047 occurrences of the <code>pattern</code> (see <a href="#6.4.1">§6.4.1</a>) have been
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8048 replaced by a replacement string specified by <code>repl</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8049 which can be a string, a table, or a function.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8050 <code>gsub</code> also returns, as its second value,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8051 the total number of matches that occurred.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8052 The name <code>gsub</code> comes from <em>Global SUBstitution</em>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8053
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8054
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8055 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8056 If <code>repl</code> is a string, then its value is used for replacement.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8057 The character <code>%</code> works as an escape character:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8058 any sequence in <code>repl</code> of the form <code>%<em>d</em></code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8059 with <em>d</em> between 1 and 9,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8060 stands for the value of the <em>d</em>-th captured substring.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8061 The sequence <code>%0</code> stands for the whole match.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8062 The sequence <code>%%</code> stands for a single <code>%</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8063
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8064
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8065 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8066 If <code>repl</code> is a table, then the table is queried for every match,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8067 using the first capture as the key.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8068
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8069
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8070 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8071 If <code>repl</code> is a function, then this function is called every time a
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8072 match occurs, with all captured substrings passed as arguments,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8073 in order.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8074
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8075
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8076 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8077 In any case,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8078 if the pattern specifies no captures,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8079 then it behaves as if the whole pattern was inside a capture.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8080
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8081
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8082 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8083 If the value returned by the table query or by the function call
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8084 is a string or a number,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8085 then it is used as the replacement string;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8086 otherwise, if it is <b>false</b> or <b>nil</b>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8087 then there is no replacement
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8088 (that is, the original match is kept in the string).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8089
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8090
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8091 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8092 Here are some examples:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8093
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8094 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8095 x = string.gsub("hello world", "(%w+)", "%1 %1")
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8096 --> x="hello hello world world"
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8097
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8098 x = string.gsub("hello world", "%w+", "%0 %0", 1)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8099 --> x="hello hello world"
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8100
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8101 x = string.gsub("hello world from Lua", "(%w+)%s*(%w+)", "%2 %1")
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8102 --> x="world hello Lua from"
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8103
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8104 x = string.gsub("home = $HOME, user = $USER", "%$(%w+)", os.getenv)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8105 --> x="home = /home/roberto, user = roberto"
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8106
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8107 x = string.gsub("4+5 = $return 4+5$", "%$(.-)%$", function (s)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8108 return load(s)()
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8109 end)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8110 --> x="4+5 = 9"
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8111
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8112 local t = {name="lua", version="5.3"}
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8113 x = string.gsub("$name-$version.tar.gz", "%$(%w+)", t)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8114 --> x="lua-5.3.tar.gz"
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8115 </pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8116
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8117
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8118
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8119 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8120 <hr><h3><a name="pdf-string.len"><code>string.len (s)</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8121 Receives a string and returns its length.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8122 The empty string <code>""</code> has length 0.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8123 Embedded zeros are counted,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8124 so <code>"a\000bc\000"</code> has length 5.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8125
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8126
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8127
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8128
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8129 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8130 <hr><h3><a name="pdf-string.lower"><code>string.lower (s)</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8131 Receives a string and returns a copy of this string with all
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8132 uppercase letters changed to lowercase.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8133 All other characters are left unchanged.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8134 The definition of what an uppercase letter is depends on the current locale.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8135
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8136
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8137
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8138
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8139 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8140 <hr><h3><a name="pdf-string.match"><code>string.match (s, pattern [, init])</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8141 Looks for the first <em>match</em> of
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8142 <code>pattern</code> (see <a href="#6.4.1">§6.4.1</a>) in the string <code>s</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8143 If it finds one, then <code>match</code> returns
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8144 the captures from the pattern;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8145 otherwise it returns <b>nil</b>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8146 If <code>pattern</code> specifies no captures,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8147 then the whole match is returned.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8148 A third, optional numerical argument <code>init</code> specifies
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8149 where to start the search;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8150 its default value is 1 and can be negative.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8151
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8152
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8153
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8154
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8155 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8156 <hr><h3><a name="pdf-string.pack"><code>string.pack (fmt, v1, v2, ···)</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8157
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8158
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8159 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8160 Returns a binary string containing the values <code>v1</code>, <code>v2</code>, etc.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8161 packed (that is, serialized in binary form)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8162 according to the format string <code>fmt</code> (see <a href="#6.4.2">§6.4.2</a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8163
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8164
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8165
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8166
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8167 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8168 <hr><h3><a name="pdf-string.packsize"><code>string.packsize (fmt)</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8169
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8170
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8171 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8172 Returns the size of a string resulting from <a href="#pdf-string.pack"><code>string.pack</code></a>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8173 with the given format.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8174 The format string cannot have the variable-length options
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8175 '<code>s</code>' or '<code>z</code>' (see <a href="#6.4.2">§6.4.2</a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8176
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8177
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8178
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8179
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8180 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8181 <hr><h3><a name="pdf-string.rep"><code>string.rep (s, n [, sep])</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8182 Returns a string that is the concatenation of <code>n</code> copies of
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8183 the string <code>s</code> separated by the string <code>sep</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8184 The default value for <code>sep</code> is the empty string
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8185 (that is, no separator).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8186 Returns the empty string if <code>n</code> is not positive.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8187
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8188
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8189
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8190
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8191 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8192 <hr><h3><a name="pdf-string.reverse"><code>string.reverse (s)</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8193 Returns a string that is the string <code>s</code> reversed.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8194
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8195
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8196
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8197
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8198 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8199 <hr><h3><a name="pdf-string.sub"><code>string.sub (s, i [, j])</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8200 Returns the substring of <code>s</code> that
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8201 starts at <code>i</code> and continues until <code>j</code>;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8202 <code>i</code> and <code>j</code> can be negative.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8203 If <code>j</code> is absent, then it is assumed to be equal to -1
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8204 (which is the same as the string length).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8205 In particular,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8206 the call <code>string.sub(s,1,j)</code> returns a prefix of <code>s</code>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8207 with length <code>j</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8208 and <code>string.sub(s, -i)</code> returns a suffix of <code>s</code>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8209 with length <code>i</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8210
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8211
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8212 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8213 If, after the translation of negative indices,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8214 <code>i</code> is less than 1,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8215 it is corrected to 1.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8216 If <code>j</code> is greater than the string length,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8217 it is corrected to that length.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8218 If, after these corrections,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8219 <code>i</code> is greater than <code>j</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8220 the function returns the empty string.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8221
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8222
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8223
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8224
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8225 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8226 <hr><h3><a name="pdf-string.unpack"><code>string.unpack (fmt, s [, pos])</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8227
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8228
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8229 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8230 Returns the values packed in string <code>s</code> (see <a href="#pdf-string.pack"><code>string.pack</code></a>)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8231 according to the format string <code>fmt</code> (see <a href="#6.4.2">§6.4.2</a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8232 An optional <code>pos</code> marks where
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8233 to start reading in <code>s</code> (default is 1).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8234 After the read values,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8235 this function also returns the index of the first unread byte in <code>s</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8236
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8237
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8238
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8239
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8240 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8241 <hr><h3><a name="pdf-string.upper"><code>string.upper (s)</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8242 Receives a string and returns a copy of this string with all
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8243 lowercase letters changed to uppercase.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8244 All other characters are left unchanged.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8245 The definition of what a lowercase letter is depends on the current locale.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8246
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8247
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8248
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8249
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8250
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8251 <h3>6.4.1 – <a name="6.4.1">Patterns</a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8252
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8253 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8254 Patterns in Lua are described by regular strings,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8255 which are interpreted as patterns by the pattern-matching functions
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8256 <a href="#pdf-string.find"><code>string.find</code></a>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8257 <a href="#pdf-string.gmatch"><code>string.gmatch</code></a>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8258 <a href="#pdf-string.gsub"><code>string.gsub</code></a>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8259 and <a href="#pdf-string.match"><code>string.match</code></a>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8260 This section describes the syntax and the meaning
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8261 (that is, what they match) of these strings.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8262
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8263
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8264
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8265 <h4>Character Class:</h4><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8266 A <em>character class</em> is used to represent a set of characters.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8267 The following combinations are allowed in describing a character class:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8268
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8269 <ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8270
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8271 <li><b><em>x</em>: </b>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8272 (where <em>x</em> is not one of the <em>magic characters</em>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8273 <code>^$()%.[]*+-?</code>)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8274 represents the character <em>x</em> itself.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8275 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8276
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8277 <li><b><code>.</code>: </b> (a dot) represents all characters.</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8278
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8279 <li><b><code>%a</code>: </b> represents all letters.</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8280
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8281 <li><b><code>%c</code>: </b> represents all control characters.</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8282
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8283 <li><b><code>%d</code>: </b> represents all digits.</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8284
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8285 <li><b><code>%g</code>: </b> represents all printable characters except space.</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8286
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8287 <li><b><code>%l</code>: </b> represents all lowercase letters.</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8288
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8289 <li><b><code>%p</code>: </b> represents all punctuation characters.</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8290
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8291 <li><b><code>%s</code>: </b> represents all space characters.</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8292
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8293 <li><b><code>%u</code>: </b> represents all uppercase letters.</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8294
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8295 <li><b><code>%w</code>: </b> represents all alphanumeric characters.</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8296
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8297 <li><b><code>%x</code>: </b> represents all hexadecimal digits.</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8298
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8299 <li><b><code>%<em>x</em></code>: </b> (where <em>x</em> is any non-alphanumeric character)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8300 represents the character <em>x</em>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8301 This is the standard way to escape the magic characters.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8302 Any non-alphanumeric character
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8303 (including all punctuations, even the non-magical)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8304 can be preceded by a '<code>%</code>'
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8305 when used to represent itself in a pattern.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8306 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8307
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8308 <li><b><code>[<em>set</em>]</code>: </b>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8309 represents the class which is the union of all
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8310 characters in <em>set</em>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8311 A range of characters can be specified by
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8312 separating the end characters of the range,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8313 in ascending order, with a '<code>-</code>'.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8314 All classes <code>%</code><em>x</em> described above can also be used as
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8315 components in <em>set</em>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8316 All other characters in <em>set</em> represent themselves.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8317 For example, <code>[%w_]</code> (or <code>[_%w]</code>)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8318 represents all alphanumeric characters plus the underscore,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8319 <code>[0-7]</code> represents the octal digits,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8320 and <code>[0-7%l%-]</code> represents the octal digits plus
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8321 the lowercase letters plus the '<code>-</code>' character.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8322
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8323
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8324 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8325 The interaction between ranges and classes is not defined.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8326 Therefore, patterns like <code>[%a-z]</code> or <code>[a-%%]</code>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8327 have no meaning.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8328 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8329
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8330 <li><b><code>[^<em>set</em>]</code>: </b>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8331 represents the complement of <em>set</em>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8332 where <em>set</em> is interpreted as above.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8333 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8334
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8335 </ul><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8336 For all classes represented by single letters (<code>%a</code>, <code>%c</code>, etc.),
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8337 the corresponding uppercase letter represents the complement of the class.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8338 For instance, <code>%S</code> represents all non-space characters.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8339
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8340
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8341 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8342 The definitions of letter, space, and other character groups
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8343 depend on the current locale.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8344 In particular, the class <code>[a-z]</code> may not be equivalent to <code>%l</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8345
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8346
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8347
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8348
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8349
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8350 <h4>Pattern Item:</h4><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8351 A <em>pattern item</em> can be
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8352
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8353 <ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8354
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8355 <li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8356 a single character class,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8357 which matches any single character in the class;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8358 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8359
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8360 <li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8361 a single character class followed by '<code>*</code>',
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8362 which matches zero or more repetitions of characters in the class.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8363 These repetition items will always match the longest possible sequence;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8364 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8365
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8366 <li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8367 a single character class followed by '<code>+</code>',
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8368 which matches one or more repetitions of characters in the class.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8369 These repetition items will always match the longest possible sequence;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8370 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8371
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8372 <li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8373 a single character class followed by '<code>-</code>',
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8374 which also matches zero or more repetitions of characters in the class.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8375 Unlike '<code>*</code>',
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8376 these repetition items will always match the shortest possible sequence;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8377 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8378
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8379 <li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8380 a single character class followed by '<code>?</code>',
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8381 which matches zero or one occurrence of a character in the class.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8382 It always matches one occurrence if possible;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8383 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8384
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8385 <li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8386 <code>%<em>n</em></code>, for <em>n</em> between 1 and 9;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8387 such item matches a substring equal to the <em>n</em>-th captured string
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8388 (see below);
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8389 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8390
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8391 <li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8392 <code>%b<em>xy</em></code>, where <em>x</em> and <em>y</em> are two distinct characters;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8393 such item matches strings that start with <em>x</em>, end with <em>y</em>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8394 and where the <em>x</em> and <em>y</em> are <em>balanced</em>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8395 This means that, if one reads the string from left to right,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8396 counting <em>+1</em> for an <em>x</em> and <em>-1</em> for a <em>y</em>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8397 the ending <em>y</em> is the first <em>y</em> where the count reaches 0.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8398 For instance, the item <code>%b()</code> matches expressions with
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8399 balanced parentheses.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8400 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8401
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8402 <li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8403 <code>%f[<em>set</em>]</code>, a <em>frontier pattern</em>;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8404 such item matches an empty string at any position such that
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8405 the next character belongs to <em>set</em>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8406 and the previous character does not belong to <em>set</em>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8407 The set <em>set</em> is interpreted as previously described.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8408 The beginning and the end of the subject are handled as if
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8409 they were the character '<code>\0</code>'.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8410 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8411
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8412 </ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8413
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8414
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8415
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8416
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8417 <h4>Pattern:</h4><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8418 A <em>pattern</em> is a sequence of pattern items.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8419 A caret '<code>^</code>' at the beginning of a pattern anchors the match at the
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8420 beginning of the subject string.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8421 A '<code>$</code>' at the end of a pattern anchors the match at the
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8422 end of the subject string.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8423 At other positions,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8424 '<code>^</code>' and '<code>$</code>' have no special meaning and represent themselves.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8425
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8426
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8427
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8428
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8429
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8430 <h4>Captures:</h4><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8431 A pattern can contain sub-patterns enclosed in parentheses;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8432 they describe <em>captures</em>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8433 When a match succeeds, the substrings of the subject string
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8434 that match captures are stored (<em>captured</em>) for future use.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8435 Captures are numbered according to their left parentheses.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8436 For instance, in the pattern <code>"(a(.)%w(%s))"</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8437 the part of the string matching <code>"a(.)%w(%s)"</code> is
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8438 stored as the first capture (and therefore has number 1);
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8439 the character matching "<code>.</code>" is captured with number 2,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8440 and the part matching "<code>%s*</code>" has number 3.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8441
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8442
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8443 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8444 As a special case, the empty capture <code>()</code> captures
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8445 the current string position (a number).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8446 For instance, if we apply the pattern <code>"()aa()"</code> on the
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8447 string <code>"flaaap"</code>, there will be two captures: 3 and 5.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8448
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8449
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8450
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8451
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8452
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8453
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8454
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8455 <h3>6.4.2 – <a name="6.4.2">Format Strings for Pack and Unpack</a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8456
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8457 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8458 The first argument to <a href="#pdf-string.pack"><code>string.pack</code></a>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8459 <a href="#pdf-string.packsize"><code>string.packsize</code></a>, and <a href="#pdf-string.unpack"><code>string.unpack</code></a>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8460 is a format string,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8461 which describes the layout of the structure being created or read.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8462
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8463
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8464 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8465 A format string is a sequence of conversion options.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8466 The conversion options are as follows:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8467
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8468 <ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8469 <li><b><code><</code>: </b>sets little endian</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8470 <li><b><code>></code>: </b>sets big endian</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8471 <li><b><code>=</code>: </b>sets native endian</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8472 <li><b><code>![<em>n</em>]</code>: </b>sets maximum alignment to <code>n</code>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8473 (default is native alignment)</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8474 <li><b><code>b</code>: </b>a signed byte (<code>char</code>)</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8475 <li><b><code>B</code>: </b>an unsigned byte (<code>char</code>)</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8476 <li><b><code>h</code>: </b>a signed <code>short</code> (native size)</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8477 <li><b><code>H</code>: </b>an unsigned <code>short</code> (native size)</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8478 <li><b><code>l</code>: </b>a signed <code>long</code> (native size)</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8479 <li><b><code>L</code>: </b>an unsigned <code>long</code> (native size)</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8480 <li><b><code>j</code>: </b>a <code>lua_Integer</code></li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8481 <li><b><code>J</code>: </b>a <code>lua_Unsigned</code></li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8482 <li><b><code>T</code>: </b>a <code>size_t</code> (native size)</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8483 <li><b><code>i[<em>n</em>]</code>: </b>a signed <code>int</code> with <code>n</code> bytes
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8484 (default is native size)</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8485 <li><b><code>I[<em>n</em>]</code>: </b>an unsigned <code>int</code> with <code>n</code> bytes
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8486 (default is native size)</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8487 <li><b><code>f</code>: </b>a <code>float</code> (native size)</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8488 <li><b><code>d</code>: </b>a <code>double</code> (native size)</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8489 <li><b><code>n</code>: </b>a <code>lua_Number</code></li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8490 <li><b><code>c<em>n</em></code>: </b>a fixed-sized string with <code>n</code> bytes</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8491 <li><b><code>z</code>: </b>a zero-terminated string</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8492 <li><b><code>s[<em>n</em>]</code>: </b>a string preceded by its length
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8493 coded as an unsigned integer with <code>n</code> bytes
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8494 (default is a <code>size_t</code>)</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8495 <li><b><code>x</code>: </b>one byte of padding</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8496 <li><b><code>X<em>op</em></code>: </b>an empty item that aligns
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8497 according to option <code>op</code>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8498 (which is otherwise ignored)</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8499 <li><b>'<code> </code>': </b>(empty space) ignored</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8500 </ul><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8501 (A "<code>[<em>n</em>]</code>" means an optional integral numeral.)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8502 Except for padding, spaces, and configurations
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8503 (options "<code>xX <=>!</code>"),
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8504 each option corresponds to an argument (in <a href="#pdf-string.pack"><code>string.pack</code></a>)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8505 or a result (in <a href="#pdf-string.unpack"><code>string.unpack</code></a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8506
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8507
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8508 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8509 For options "<code>!<em>n</em></code>", "<code>s<em>n</em></code>", "<code>i<em>n</em></code>", and "<code>I<em>n</em></code>",
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8510 <code>n</code> can be any integer between 1 and 16.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8511 All integral options check overflows;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8512 <a href="#pdf-string.pack"><code>string.pack</code></a> checks whether the given value fits in the given size;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8513 <a href="#pdf-string.unpack"><code>string.unpack</code></a> checks whether the read value fits in a Lua integer.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8514
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8515
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8516 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8517 Any format string starts as if prefixed by "<code>!1=</code>",
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8518 that is,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8519 with maximum alignment of 1 (no alignment)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8520 and native endianness.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8521
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8522
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8523 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8524 Alignment works as follows:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8525 For each option,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8526 the format gets extra padding until the data starts
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8527 at an offset that is a multiple of the minimum between the
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8528 option size and the maximum alignment;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8529 this minimum must be a power of 2.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8530 Options "<code>c</code>" and "<code>z</code>" are not aligned;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8531 option "<code>s</code>" follows the alignment of its starting integer.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8532
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8533
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8534 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8535 All padding is filled with zeros by <a href="#pdf-string.pack"><code>string.pack</code></a>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8536 (and ignored by <a href="#pdf-string.unpack"><code>string.unpack</code></a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8537
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8538
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8539
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8540
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8541
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8542
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8543
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8544 <h2>6.5 – <a name="6.5">UTF-8 Support</a></h2>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8545
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8546 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8547 This library provides basic support for UTF-8 encoding.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8548 It provides all its functions inside the table <a name="pdf-utf8"><code>utf8</code></a>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8549 This library does not provide any support for Unicode other
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8550 than the handling of the encoding.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8551 Any operation that needs the meaning of a character,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8552 such as character classification, is outside its scope.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8553
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8554
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8555 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8556 Unless stated otherwise,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8557 all functions that expect a byte position as a parameter
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8558 assume that the given position is either the start of a byte sequence
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8559 or one plus the length of the subject string.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8560 As in the string library,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8561 negative indices count from the end of the string.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8562
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8563
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8564 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8565 <hr><h3><a name="pdf-utf8.char"><code>utf8.char (···)</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8566 Receives zero or more integers,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8567 converts each one to its corresponding UTF-8 byte sequence
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8568 and returns a string with the concatenation of all these sequences.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8569
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8570
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8571
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8572
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8573 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8574 <hr><h3><a name="pdf-utf8.charpattern"><code>utf8.charpattern</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8575 The pattern (a string, not a function) "<code>[\0-\x7F\xC2-\xF4][\x80-\xBF]*</code>"
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8576 (see <a href="#6.4.1">§6.4.1</a>),
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8577 which matches exactly one UTF-8 byte sequence,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8578 assuming that the subject is a valid UTF-8 string.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8579
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8580
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8581
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8582
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8583 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8584 <hr><h3><a name="pdf-utf8.codes"><code>utf8.codes (s)</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8585
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8586
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8587 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8588 Returns values so that the construction
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8589
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8590 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8591 for p, c in utf8.codes(s) do <em>body</em> end
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8592 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8593 will iterate over all characters in string <code>s</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8594 with <code>p</code> being the position (in bytes) and <code>c</code> the code point
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8595 of each character.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8596 It raises an error if it meets any invalid byte sequence.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8597
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8598
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8599
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8600
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8601 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8602 <hr><h3><a name="pdf-utf8.codepoint"><code>utf8.codepoint (s [, i [, j]])</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8603 Returns the codepoints (as integers) from all characters in <code>s</code>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8604 that start between byte position <code>i</code> and <code>j</code> (both included).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8605 The default for <code>i</code> is 1 and for <code>j</code> is <code>i</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8606 It raises an error if it meets any invalid byte sequence.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8607
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8608
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8609
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8610
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8611 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8612 <hr><h3><a name="pdf-utf8.len"><code>utf8.len (s [, i [, j]])</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8613 Returns the number of UTF-8 characters in string <code>s</code>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8614 that start between positions <code>i</code> and <code>j</code> (both inclusive).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8615 The default for <code>i</code> is 1 and for <code>j</code> is -1.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8616 If it finds any invalid byte sequence,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8617 returns a false value plus the position of the first invalid byte.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8618
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8619
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8620
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8621
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8622 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8623 <hr><h3><a name="pdf-utf8.offset"><code>utf8.offset (s, n [, i])</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8624 Returns the position (in bytes) where the encoding of the
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8625 <code>n</code>-th character of <code>s</code>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8626 (counting from position <code>i</code>) starts.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8627 A negative <code>n</code> gets characters before position <code>i</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8628 The default for <code>i</code> is 1 when <code>n</code> is non-negative
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8629 and <code>#s + 1</code> otherwise,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8630 so that <code>utf8.offset(s, -n)</code> gets the offset of the
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8631 <code>n</code>-th character from the end of the string.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8632 If the specified character is neither in the subject
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8633 nor right after its end,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8634 the function returns <b>nil</b>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8635
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8636
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8637 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8638 As a special case,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8639 when <code>n</code> is 0 the function returns the start of the encoding
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8640 of the character that contains the <code>i</code>-th byte of <code>s</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8641
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8642
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8643 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8644 This function assumes that <code>s</code> is a valid UTF-8 string.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8645
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8646
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8647
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8648
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8649
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8650
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8651
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8652 <h2>6.6 – <a name="6.6">Table Manipulation</a></h2>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8653
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8654 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8655 This library provides generic functions for table manipulation.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8656 It provides all its functions inside the table <a name="pdf-table"><code>table</code></a>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8657
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8658
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8659 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8660 Remember that, whenever an operation needs the length of a table,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8661 the table must be a proper sequence
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8662 or have a <code>__len</code> metamethod (see <a href="#3.4.7">§3.4.7</a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8663 All functions ignore non-numeric keys
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8664 in the tables given as arguments.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8665
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8666
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8667 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8668 <hr><h3><a name="pdf-table.concat"><code>table.concat (list [, sep [, i [, j]]])</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8669
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8670
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8671 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8672 Given a list where all elements are strings or numbers,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8673 returns the string <code>list[i]..sep..list[i+1] ··· sep..list[j]</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8674 The default value for <code>sep</code> is the empty string,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8675 the default for <code>i</code> is 1,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8676 and the default for <code>j</code> is <code>#list</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8677 If <code>i</code> is greater than <code>j</code>, returns the empty string.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8678
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8679
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8680
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8681
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8682 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8683 <hr><h3><a name="pdf-table.insert"><code>table.insert (list, [pos,] value)</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8684
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8685
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8686 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8687 Inserts element <code>value</code> at position <code>pos</code> in <code>list</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8688 shifting up the elements
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8689 <code>list[pos], list[pos+1], ···, list[#list]</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8690 The default value for <code>pos</code> is <code>#list+1</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8691 so that a call <code>table.insert(t,x)</code> inserts <code>x</code> at the end
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8692 of list <code>t</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8693
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8694
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8695
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8696
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8697 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8698 <hr><h3><a name="pdf-table.move"><code>table.move (a1, f, e, t [,a2])</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8699
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8700
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8701 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8702 Moves elements from table <code>a1</code> to table <code>a2</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8703 This function performs the equivalent to the following
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8704 multiple assignment:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8705 <code>a2[t],··· = a1[f],···,a1[e]</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8706 The default for <code>a2</code> is <code>a1</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8707 The destination range can overlap with the source range.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8708 Index <code>f</code> must be positive.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8709
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8710
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8711
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8712
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8713 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8714 <hr><h3><a name="pdf-table.pack"><code>table.pack (···)</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8715
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8716
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8717 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8718 Returns a new table with all parameters stored into keys 1, 2, etc.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8719 and with a field "<code>n</code>" with the total number of parameters.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8720 Note that the resulting table may not be a sequence.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8721
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8722
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8723
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8724
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8725 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8726 <hr><h3><a name="pdf-table.remove"><code>table.remove (list [, pos])</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8727
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8728
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8729 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8730 Removes from <code>list</code> the element at position <code>pos</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8731 returning the value of the removed element.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8732 When <code>pos</code> is an integer between 1 and <code>#list</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8733 it shifts down the elements
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8734 <code>list[pos+1], list[pos+2], ···, list[#list]</code>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8735 and erases element <code>list[#list]</code>;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8736 The index <code>pos</code> can also be 0 when <code>#list</code> is 0,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8737 or <code>#list + 1</code>;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8738 in those cases, the function erases the element <code>list[pos]</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8739
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8740
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8741 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8742 The default value for <code>pos</code> is <code>#list</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8743 so that a call <code>table.remove(l)</code> removes the last element
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8744 of list <code>l</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8745
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8746
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8747
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8748
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8749 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8750 <hr><h3><a name="pdf-table.sort"><code>table.sort (list [, comp])</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8751
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8752
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8753 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8754 Sorts list elements in a given order, <em>in-place</em>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8755 from <code>list[1]</code> to <code>list[#list]</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8756 If <code>comp</code> is given,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8757 then it must be a function that receives two list elements
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8758 and returns true when the first element must come
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8759 before the second in the final order
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8760 (so that <code>not comp(list[i+1],list[i])</code> will be true after the sort).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8761 If <code>comp</code> is not given,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8762 then the standard Lua operator <code><</code> is used instead.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8763
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8764
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8765 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8766 The sort algorithm is not stable;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8767 that is, elements considered equal by the given order
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8768 may have their relative positions changed by the sort.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8769
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8770
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8771
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8772
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8773 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8774 <hr><h3><a name="pdf-table.unpack"><code>table.unpack (list [, i [, j]])</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8775
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8776
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8777 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8778 Returns the elements from the given list.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8779 This function is equivalent to
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8780
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8781 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8782 return list[i], list[i+1], ···, list[j]
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8783 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8784 By default, <code>i</code> is 1 and <code>j</code> is <code>#list</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8785
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8786
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8787
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8788
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8789
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8790
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8791
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8792 <h2>6.7 – <a name="6.7">Mathematical Functions</a></h2>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8793
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8794 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8795 This library provides basic mathematical functions.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8796 It provides all its functions and constants inside the table <a name="pdf-math"><code>math</code></a>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8797 Functions with the annotation "<code>integer/float</code>" give
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8798 integer results for integer arguments
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8799 and float results for float (or mixed) arguments.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8800 Rounding functions
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8801 (<a href="#pdf-math.ceil"><code>math.ceil</code></a>, <a href="#pdf-math.floor"><code>math.floor</code></a>, and <a href="#pdf-math.modf"><code>math.modf</code></a>)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8802 return an integer when the result fits in the range of an integer,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8803 or a float otherwise.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8804
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8805
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8806 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8807 <hr><h3><a name="pdf-math.abs"><code>math.abs (x)</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8808
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8809
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8810 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8811 Returns the absolute value of <code>x</code>. (integer/float)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8812
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8813
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8814
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8815
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8816 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8817 <hr><h3><a name="pdf-math.acos"><code>math.acos (x)</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8818
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8819
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8820 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8821 Returns the arc cosine of <code>x</code> (in radians).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8822
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8823
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8824
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8825
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8826 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8827 <hr><h3><a name="pdf-math.asin"><code>math.asin (x)</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8828
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8829
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8830 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8831 Returns the arc sine of <code>x</code> (in radians).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8832
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8833
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8834
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8835
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8836 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8837 <hr><h3><a name="pdf-math.atan"><code>math.atan (y [, x])</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8838
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8839
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8840 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8841
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8842 Returns the arc tangent of <code>y/x</code> (in radians),
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8843 but uses the signs of both parameters to find the
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8844 quadrant of the result.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8845 (It also handles correctly the case of <code>x</code> being zero.)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8846
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8847
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8848 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8849 The default value for <code>x</code> is 1,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8850 so that the call <code>math.atan(y)</code>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8851 returns the arc tangent of <code>y</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8852
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8853
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8854
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8855
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8856 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8857 <hr><h3><a name="pdf-math.ceil"><code>math.ceil (x)</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8858
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8859
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8860 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8861 Returns the smallest integral value larger than or equal to <code>x</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8862
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8863
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8864
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8865
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8866 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8867 <hr><h3><a name="pdf-math.cos"><code>math.cos (x)</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8868
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8869
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8870 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8871 Returns the cosine of <code>x</code> (assumed to be in radians).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8872
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8873
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8874
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8875
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8876 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8877 <hr><h3><a name="pdf-math.deg"><code>math.deg (x)</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8878
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8879
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8880 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8881 Converts the angle <code>x</code> from radians to degrees.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8882
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8883
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8884
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8885
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8886 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8887 <hr><h3><a name="pdf-math.exp"><code>math.exp (x)</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8888
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8889
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8890 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8891 Returns the value <em>e<sup>x</sup></em>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8892 (where <code>e</code> is the base of natural logarithms).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8893
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8894
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8895
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8896
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8897 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8898 <hr><h3><a name="pdf-math.floor"><code>math.floor (x)</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8899
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8900
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8901 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8902 Returns the largest integral value smaller than or equal to <code>x</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8903
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8904
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8905
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8906
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8907 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8908 <hr><h3><a name="pdf-math.fmod"><code>math.fmod (x, y)</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8909
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8910
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8911 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8912 Returns the remainder of the division of <code>x</code> by <code>y</code>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8913 that rounds the quotient towards zero. (integer/float)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8914
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8915
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8916
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8917
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8918 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8919 <hr><h3><a name="pdf-math.huge"><code>math.huge</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8920
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8921
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8922 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8923 The float value <code>HUGE_VAL</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8924 a value larger than any other numerical value.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8925
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8926
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8927
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8928
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8929 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8930 <hr><h3><a name="pdf-math.log"><code>math.log (x [, base])</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8931
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8932
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8933 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8934 Returns the logarithm of <code>x</code> in the given base.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8935 The default for <code>base</code> is <em>e</em>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8936 (so that the function returns the natural logarithm of <code>x</code>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8937
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8938
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8939
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8940
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8941 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8942 <hr><h3><a name="pdf-math.max"><code>math.max (x, ···)</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8943
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8944
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8945 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8946 Returns the argument with the maximum value,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8947 according to the Lua operator <code><</code>. (integer/float)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8948
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8949
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8950
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8951
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8952 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8953 <hr><h3><a name="pdf-math.maxinteger"><code>math.maxinteger</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8954 An integer with the maximum value for an integer.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8955
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8956
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8957
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8958
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8959 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8960 <hr><h3><a name="pdf-math.min"><code>math.min (x, ···)</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8961
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8962
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8963 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8964 Returns the argument with the minimum value,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8965 according to the Lua operator <code><</code>. (integer/float)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8966
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8967
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8968
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8969
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8970 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8971 <hr><h3><a name="pdf-math.mininteger"><code>math.mininteger</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8972 An integer with the minimum value for an integer.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8973
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8974
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8975
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8976
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8977 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8978 <hr><h3><a name="pdf-math.modf"><code>math.modf (x)</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8979
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8980
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8981 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8982 Returns the integral part of <code>x</code> and the fractional part of <code>x</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8983 Its second result is always a float.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8984
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8985
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8986
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8987
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8988 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8989 <hr><h3><a name="pdf-math.pi"><code>math.pi</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8990
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8991
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8992 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8993 The value of <em>π</em>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8994
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8995
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8996
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8997
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8998 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8999 <hr><h3><a name="pdf-math.rad"><code>math.rad (x)</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9000
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9001
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9002 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9003 Converts the angle <code>x</code> from degrees to radians.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9004
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9005
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9006
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9007
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9008 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9009 <hr><h3><a name="pdf-math.random"><code>math.random ([m [, n]])</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9010
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9011
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9012 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9013 When called without arguments,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9014 returns a pseudo-random float with uniform distribution
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9015 in the range <em>[0,1)</em>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9016 When called with two integers <code>m</code> and <code>n</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9017 <code>math.random</code> returns a pseudo-random integer
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9018 with uniform distribution in the range <em>[m, n]</em>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9019 (The value <em>m-n</em> cannot be negative and must fit in a Lua integer.)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9020 The call <code>math.random(n)</code> is equivalent to <code>math.random(1,n)</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9021
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9022
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9023 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9024 This function is an interface to the underling
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9025 pseudo-random generator function provided by C.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9026 No guarantees can be given for its statistical properties.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9027
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9028
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9029
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9030
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9031 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9032 <hr><h3><a name="pdf-math.randomseed"><code>math.randomseed (x)</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9033
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9034
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9035 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9036 Sets <code>x</code> as the "seed"
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9037 for the pseudo-random generator:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9038 equal seeds produce equal sequences of numbers.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9039
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9040
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9041
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9042
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9043 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9044 <hr><h3><a name="pdf-math.sin"><code>math.sin (x)</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9045
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9046
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9047 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9048 Returns the sine of <code>x</code> (assumed to be in radians).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9049
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9050
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9051
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9052
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9053 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9054 <hr><h3><a name="pdf-math.sqrt"><code>math.sqrt (x)</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9055
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9056
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9057 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9058 Returns the square root of <code>x</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9059 (You can also use the expression <code>x^0.5</code> to compute this value.)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9060
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9061
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9062
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9063
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9064 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9065 <hr><h3><a name="pdf-math.tan"><code>math.tan (x)</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9066
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9067
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9068 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9069 Returns the tangent of <code>x</code> (assumed to be in radians).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9070
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9071
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9072
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9073
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9074 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9075 <hr><h3><a name="pdf-math.tointeger"><code>math.tointeger (x)</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9076
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9077
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9078 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9079 If the value <code>x</code> is convertible to an integer,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9080 returns that integer.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9081 Otherwise, returns <b>nil</b>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9082
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9083
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9084
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9085
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9086 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9087 <hr><h3><a name="pdf-math.type"><code>math.type (x)</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9088
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9089
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9090 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9091 Returns "<code>integer</code>" if <code>x</code> is an integer,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9092 "<code>float</code>" if it is a float,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9093 or <b>nil</b> if <code>x</code> is not a number.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9094
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9095
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9096
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9097
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9098 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9099 <hr><h3><a name="pdf-math.ult"><code>math.ult (m, n)</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9100
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9101
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9102 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9103 Returns a boolean,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9104 true if integer <code>m</code> is below integer <code>n</code> when
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9105 they are compared as unsigned integers.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9106
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9107
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9108
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9109
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9110
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9111
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9112
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9113 <h2>6.8 – <a name="6.8">Input and Output Facilities</a></h2>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9114
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9115 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9116 The I/O library provides two different styles for file manipulation.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9117 The first one uses implicit file handles;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9118 that is, there are operations to set a default input file and a
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9119 default output file,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9120 and all input/output operations are over these default files.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9121 The second style uses explicit file handles.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9122
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9123
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9124 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9125 When using implicit file handles,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9126 all operations are supplied by table <a name="pdf-io"><code>io</code></a>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9127 When using explicit file handles,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9128 the operation <a href="#pdf-io.open"><code>io.open</code></a> returns a file handle
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9129 and then all operations are supplied as methods of the file handle.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9130
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9131
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9132 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9133 The table <code>io</code> also provides
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9134 three predefined file handles with their usual meanings from C:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9135 <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>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9136 The I/O library never closes these files.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9137
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9138
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9139 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9140 Unless otherwise stated,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9141 all I/O functions return <b>nil</b> on failure
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9142 (plus an error message as a second result and
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9143 a system-dependent error code as a third result)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9144 and some value different from <b>nil</b> on success.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9145 On non-POSIX systems,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9146 the computation of the error message and error code
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9147 in case of errors
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9148 may be not thread safe,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9149 because they rely on the global C variable <code>errno</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9150
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9151
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9152 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9153 <hr><h3><a name="pdf-io.close"><code>io.close ([file])</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9154
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9155
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9156 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9157 Equivalent to <code>file:close()</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9158 Without a <code>file</code>, closes the default output file.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9159
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9160
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9161
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9162
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9163 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9164 <hr><h3><a name="pdf-io.flush"><code>io.flush ()</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9165
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9166
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9167 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9168 Equivalent to <code>io.output():flush()</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9169
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9170
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9171
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9172
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9173 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9174 <hr><h3><a name="pdf-io.input"><code>io.input ([file])</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9175
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9176
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9177 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9178 When called with a file name, it opens the named file (in text mode),
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9179 and sets its handle as the default input file.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9180 When called with a file handle,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9181 it simply sets this file handle as the default input file.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9182 When called without parameters,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9183 it returns the current default input file.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9184
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9185
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9186 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9187 In case of errors this function raises the error,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9188 instead of returning an error code.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9189
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9190
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9191
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9192
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9193 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9194 <hr><h3><a name="pdf-io.lines"><code>io.lines ([filename ···])</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9195
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9196
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9197 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9198 Opens the given file name in read mode
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9199 and returns an iterator function that
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9200 works like <code>file:lines(···)</code> over the opened file.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9201 When the iterator function detects the end of file,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9202 it returns no values (to finish the loop) and automatically closes the file.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9203
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9204
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9205 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9206 The call <code>io.lines()</code> (with no file name) is equivalent
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9207 to <code>io.input():lines("*l")</code>;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9208 that is, it iterates over the lines of the default input file.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9209 In this case it does not close the file when the loop ends.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9210
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9211
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9212 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9213 In case of errors this function raises the error,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9214 instead of returning an error code.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9215
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9216
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9217
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9218
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9219 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9220 <hr><h3><a name="pdf-io.open"><code>io.open (filename [, mode])</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9221
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9222
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9223 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9224 This function opens a file,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9225 in the mode specified in the string <code>mode</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9226 It returns a new file handle,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9227 or, in case of errors, <b>nil</b> plus an error message.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9228
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9229
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9230 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9231 The <code>mode</code> string can be any of the following:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9232
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9233 <ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9234 <li><b>"<code>r</code>": </b> read mode (the default);</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9235 <li><b>"<code>w</code>": </b> write mode;</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9236 <li><b>"<code>a</code>": </b> append mode;</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9237 <li><b>"<code>r+</code>": </b> update mode, all previous data is preserved;</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9238 <li><b>"<code>w+</code>": </b> update mode, all previous data is erased;</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9239 <li><b>"<code>a+</code>": </b> append update mode, previous data is preserved,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9240 writing is only allowed at the end of file.</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9241 </ul><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9242 The <code>mode</code> string can also have a '<code>b</code>' at the end,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9243 which is needed in some systems to open the file in binary mode.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9244
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9245
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9246
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9247
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9248 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9249 <hr><h3><a name="pdf-io.output"><code>io.output ([file])</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9250
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9251
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9252 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9253 Similar to <a href="#pdf-io.input"><code>io.input</code></a>, but operates over the default output file.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9254
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9255
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9256
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9257
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9258 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9259 <hr><h3><a name="pdf-io.popen"><code>io.popen (prog [, mode])</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9260
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9261
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9262 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9263 This function is system dependent and is not available
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9264 on all platforms.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9265
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9266
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9267 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9268 Starts program <code>prog</code> in a separated process and returns
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9269 a file handle that you can use to read data from this program
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9270 (if <code>mode</code> is <code>"r"</code>, the default)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9271 or to write data to this program
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9272 (if <code>mode</code> is <code>"w"</code>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9273
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9274
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9275
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9276
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9277 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9278 <hr><h3><a name="pdf-io.read"><code>io.read (···)</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9279
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9280
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9281 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9282 Equivalent to <code>io.input():read(···)</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9283
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9284
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9285
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9286
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9287 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9288 <hr><h3><a name="pdf-io.tmpfile"><code>io.tmpfile ()</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9289
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9290
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9291 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9292 Returns a handle for a temporary file.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9293 This file is opened in update mode
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9294 and it is automatically removed when the program ends.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9295
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9296
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9297
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9298
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9299 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9300 <hr><h3><a name="pdf-io.type"><code>io.type (obj)</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9301
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9302
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9303 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9304 Checks whether <code>obj</code> is a valid file handle.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9305 Returns the string <code>"file"</code> if <code>obj</code> is an open file handle,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9306 <code>"closed file"</code> if <code>obj</code> is a closed file handle,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9307 or <b>nil</b> if <code>obj</code> is not a file handle.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9308
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9309
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9310
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9311
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9312 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9313 <hr><h3><a name="pdf-io.write"><code>io.write (···)</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9314
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9315
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9316 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9317 Equivalent to <code>io.output():write(···)</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9318
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9319
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9320
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9321
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9322 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9323 <hr><h3><a name="pdf-file:close"><code>file:close ()</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9324
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9325
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9326 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9327 Closes <code>file</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9328 Note that files are automatically closed when
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9329 their handles are garbage collected,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9330 but that takes an unpredictable amount of time to happen.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9331
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9332
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9333 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9334 When closing a file handle created with <a href="#pdf-io.popen"><code>io.popen</code></a>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9335 <a href="#pdf-file:close"><code>file:close</code></a> returns the same values
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9336 returned by <a href="#pdf-os.execute"><code>os.execute</code></a>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9337
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9338
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9339
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9340
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9341 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9342 <hr><h3><a name="pdf-file:flush"><code>file:flush ()</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9343
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9344
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9345 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9346 Saves any written data to <code>file</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9347
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9348
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9349
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9350
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9351 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9352 <hr><h3><a name="pdf-file:lines"><code>file:lines (···)</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9353
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9354
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9355 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9356 Returns an iterator function that,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9357 each time it is called,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9358 reads the file according to the given formats.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9359 When no format is given,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9360 uses "<code>l</code>" as a default.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9361 As an example, the construction
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9362
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9363 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9364 for c in file:lines(1) do <em>body</em> end
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9365 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9366 will iterate over all characters of the file,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9367 starting at the current position.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9368 Unlike <a href="#pdf-io.lines"><code>io.lines</code></a>, this function does not close the file
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9369 when the loop ends.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9370
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9371
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9372 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9373 In case of errors this function raises the error,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9374 instead of returning an error code.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9375
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9376
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9377
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9378
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9379 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9380 <hr><h3><a name="pdf-file:read"><code>file:read (···)</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9381
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9382
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9383 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9384 Reads the file <code>file</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9385 according to the given formats, which specify what to read.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9386 For each format,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9387 the function returns a string or a number with the characters read,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9388 or <b>nil</b> if it cannot read data with the specified format.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9389 (In this latter case,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9390 the function does not read subsequent formats.)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9391 When called without formats,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9392 it uses a default format that reads the next line
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9393 (see below).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9394
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9395
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9396 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9397 The available formats are
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9398
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9399 <ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9400
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9401 <li><b>"<code>n</code>": </b>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9402 reads a numeral and returns it as a float or an integer,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9403 following the lexical conventions of Lua.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9404 (The numeral may have leading spaces and a sign.)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9405 This format always reads the longest input sequence that
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9406 is a valid prefix for a number;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9407 if that prefix does not form a valid number
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9408 (e.g., an empty string, "<code>0x</code>", or "<code>3.4e-</code>"),
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9409 it is discarded and the function returns <b>nil</b>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9410 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9411
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9412 <li><b>"<code>i</code>": </b>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9413 reads an integral number and returns it as an integer.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9414 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9415
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9416 <li><b>"<code>a</code>": </b>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9417 reads the whole file, starting at the current position.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9418 On end of file, it returns the empty string.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9419 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9420
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9421 <li><b>"<code>l</code>": </b>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9422 reads the next line skipping the end of line,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9423 returning <b>nil</b> on end of file.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9424 This is the default format.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9425 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9426
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9427 <li><b>"<code>L</code>": </b>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9428 reads the next line keeping the end-of-line character (if present),
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9429 returning <b>nil</b> on end of file.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9430 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9431
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9432 <li><b><em>number</em>: </b>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9433 reads a string with up to this number of bytes,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9434 returning <b>nil</b> on end of file.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9435 If <code>number</code> is zero,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9436 it reads nothing and returns an empty string,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9437 or <b>nil</b> on end of file.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9438 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9439
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9440 </ul><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9441 The formats "<code>l</code>" and "<code>L</code>" should be used only for text files.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9442
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9443
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9444
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9445
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9446 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9447 <hr><h3><a name="pdf-file:seek"><code>file:seek ([whence [, offset]])</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9448
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9449
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9450 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9451 Sets and gets the file position,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9452 measured from the beginning of the file,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9453 to the position given by <code>offset</code> plus a base
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9454 specified by the string <code>whence</code>, as follows:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9455
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9456 <ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9457 <li><b>"<code>set</code>": </b> base is position 0 (beginning of the file);</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9458 <li><b>"<code>cur</code>": </b> base is current position;</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9459 <li><b>"<code>end</code>": </b> base is end of file;</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9460 </ul><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9461 In case of success, <code>seek</code> returns the final file position,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9462 measured in bytes from the beginning of the file.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9463 If <code>seek</code> fails, it returns <b>nil</b>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9464 plus a string describing the error.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9465
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9466
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9467 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9468 The default value for <code>whence</code> is <code>"cur"</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9469 and for <code>offset</code> is 0.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9470 Therefore, the call <code>file:seek()</code> returns the current
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9471 file position, without changing it;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9472 the call <code>file:seek("set")</code> sets the position to the
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9473 beginning of the file (and returns 0);
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9474 and the call <code>file:seek("end")</code> sets the position to the
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9475 end of the file, and returns its size.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9476
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9477
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9478
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9479
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9480 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9481 <hr><h3><a name="pdf-file:setvbuf"><code>file:setvbuf (mode [, size])</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9482
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9483
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9484 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9485 Sets the buffering mode for an output file.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9486 There are three available modes:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9487
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9488 <ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9489
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9490 <li><b>"<code>no</code>": </b>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9491 no buffering; the result of any output operation appears immediately.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9492 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9493
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9494 <li><b>"<code>full</code>": </b>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9495 full buffering; output operation is performed only
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9496 when the buffer is full or when
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9497 you explicitly <code>flush</code> the file (see <a href="#pdf-io.flush"><code>io.flush</code></a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9498 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9499
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9500 <li><b>"<code>line</code>": </b>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9501 line buffering; output is buffered until a newline is output
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9502 or there is any input from some special files
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9503 (such as a terminal device).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9504 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9505
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9506 </ul><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9507 For the last two cases, <code>size</code>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9508 specifies the size of the buffer, in bytes.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9509 The default is an appropriate size.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9510
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9511
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9512
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9513
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9514 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9515 <hr><h3><a name="pdf-file:write"><code>file:write (···)</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9516
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9517
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9518 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9519 Writes the value of each of its arguments to <code>file</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9520 The arguments must be strings or numbers.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9521
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9522
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9523 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9524 In case of success, this function returns <code>file</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9525 Otherwise it returns <b>nil</b> plus a string describing the error.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9526
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9527
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9528
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9529
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9530
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9531
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9532
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9533 <h2>6.9 – <a name="6.9">Operating System Facilities</a></h2>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9534
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9535 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9536 This library is implemented through table <a name="pdf-os"><code>os</code></a>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9537
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9538
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9539 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9540 <hr><h3><a name="pdf-os.clock"><code>os.clock ()</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9541
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9542
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9543 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9544 Returns an approximation of the amount in seconds of CPU time
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9545 used by the program.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9546
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9547
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9548
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9549
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9550 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9551 <hr><h3><a name="pdf-os.date"><code>os.date ([format [, time]])</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9552
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9553
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9554 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9555 Returns a string or a table containing date and time,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9556 formatted according to the given string <code>format</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9557
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9558
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9559 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9560 If the <code>time</code> argument is present,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9561 this is the time to be formatted
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9562 (see the <a href="#pdf-os.time"><code>os.time</code></a> function for a description of this value).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9563 Otherwise, <code>date</code> formats the current time.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9564
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9565
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9566 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9567 If <code>format</code> starts with '<code>!</code>',
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9568 then the date is formatted in Coordinated Universal Time.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9569 After this optional character,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9570 if <code>format</code> is the string "<code>*t</code>",
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9571 then <code>date</code> returns a table with the following fields:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9572 <code>year</code> (four digits), <code>month</code> (1–12), <code>day</code> (1–31),
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9573 <code>hour</code> (0–23), <code>min</code> (0–59), <code>sec</code> (0–61),
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9574 <code>wday</code> (weekday, Sunday is 1),
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9575 <code>yday</code> (day of the year),
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9576 and <code>isdst</code> (daylight saving flag, a boolean).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9577 This last field may be absent
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9578 if the information is not available.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9579
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9580
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9581 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9582 If <code>format</code> is not "<code>*t</code>",
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9583 then <code>date</code> returns the date as a string,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9584 formatted according to the same rules as the ISO C function <code>strftime</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9585
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9586
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9587 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9588 When called without arguments,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9589 <code>date</code> returns a reasonable date and time representation that depends on
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9590 the host system and on the current locale
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9591 (that is, <code>os.date()</code> is equivalent to <code>os.date("%c")</code>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9592
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9593
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9594 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9595 On non-POSIX systems,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9596 this function may be not thread safe
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9597 because of its reliance on C function <code>gmtime</code> and C function <code>localtime</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9598
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9599
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9600
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9601
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9602 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9603 <hr><h3><a name="pdf-os.difftime"><code>os.difftime (t2, t1)</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9604
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9605
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9606 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9607 Returns the difference, in seconds,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9608 from time <code>t1</code> to time <code>t2</code>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9609 (where the times are values returned by <a href="#pdf-os.time"><code>os.time</code></a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9610 In POSIX, Windows, and some other systems,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9611 this value is exactly <code>t2</code><em>-</em><code>t1</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9612
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9613
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9614
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9615
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9616 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9617 <hr><h3><a name="pdf-os.execute"><code>os.execute ([command])</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9618
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9619
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9620 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9621 This function is equivalent to the ISO C function <code>system</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9622 It passes <code>command</code> to be executed by an operating system shell.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9623 Its first result is <b>true</b>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9624 if the command terminated successfully,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9625 or <b>nil</b> otherwise.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9626 After this first result
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9627 the function returns a string plus a number,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9628 as follows:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9629
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9630 <ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9631
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9632 <li><b>"<code>exit</code>": </b>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9633 the command terminated normally;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9634 the following number is the exit status of the command.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9635 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9636
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9637 <li><b>"<code>signal</code>": </b>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9638 the command was terminated by a signal;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9639 the following number is the signal that terminated the command.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9640 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9641
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9642 </ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9643
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9644 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9645 When called without a <code>command</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9646 <code>os.execute</code> returns a boolean that is true if a shell is available.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9647
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9648
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9649
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9650
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9651 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9652 <hr><h3><a name="pdf-os.exit"><code>os.exit ([code [, close]])</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9653
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9654
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9655 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9656 Calls the ISO C function <code>exit</code> to terminate the host program.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9657 If <code>code</code> is <b>true</b>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9658 the returned status is <code>EXIT_SUCCESS</code>;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9659 if <code>code</code> is <b>false</b>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9660 the returned status is <code>EXIT_FAILURE</code>;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9661 if <code>code</code> is a number,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9662 the returned status is this number.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9663 The default value for <code>code</code> is <b>true</b>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9664
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9665
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9666 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9667 If the optional second argument <code>close</code> is true,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9668 closes the Lua state before exiting.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9669
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9670
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9671
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9672
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9673 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9674 <hr><h3><a name="pdf-os.getenv"><code>os.getenv (varname)</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9675
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9676
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9677 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9678 Returns the value of the process environment variable <code>varname</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9679 or <b>nil</b> if the variable is not defined.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9680
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9681
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9682
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9683
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9684 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9685 <hr><h3><a name="pdf-os.remove"><code>os.remove (filename)</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9686
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9687
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9688 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9689 Deletes the file (or empty directory, on POSIX systems)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9690 with the given name.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9691 If this function fails, it returns <b>nil</b>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9692 plus a string describing the error and the error code.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9693
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9694
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9695
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9696
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9697 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9698 <hr><h3><a name="pdf-os.rename"><code>os.rename (oldname, newname)</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9699
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9700
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9701 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9702 Renames file or directory named <code>oldname</code> to <code>newname</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9703 If this function fails, it returns <b>nil</b>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9704 plus a string describing the error and the error code.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9705
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9706
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9707
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9708
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9709 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9710 <hr><h3><a name="pdf-os.setlocale"><code>os.setlocale (locale [, category])</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9711
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9712
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9713 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9714 Sets the current locale of the program.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9715 <code>locale</code> is a system-dependent string specifying a locale;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9716 <code>category</code> is an optional string describing which category to change:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9717 <code>"all"</code>, <code>"collate"</code>, <code>"ctype"</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9718 <code>"monetary"</code>, <code>"numeric"</code>, or <code>"time"</code>;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9719 the default category is <code>"all"</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9720 The function returns the name of the new locale,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9721 or <b>nil</b> if the request cannot be honored.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9722
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9723
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9724 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9725 If <code>locale</code> is the empty string,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9726 the current locale is set to an implementation-defined native locale.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9727 If <code>locale</code> is the string "<code>C</code>",
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9728 the current locale is set to the standard C locale.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9729
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9730
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9731 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9732 When called with <b>nil</b> as the first argument,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9733 this function only returns the name of the current locale
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9734 for the given category.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9735
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9736
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9737 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9738 This function may be not thread safe
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9739 because of its reliance on C function <code>setlocale</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9740
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9741
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9742
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9743
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9744 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9745 <hr><h3><a name="pdf-os.time"><code>os.time ([table])</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9746
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9747
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9748 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9749 Returns the current time when called without arguments,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9750 or a time representing the date and time specified by the given table.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9751 This table must have fields <code>year</code>, <code>month</code>, and <code>day</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9752 and may have fields
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9753 <code>hour</code> (default is 12),
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9754 <code>min</code> (default is 0),
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9755 <code>sec</code> (default is 0),
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9756 and <code>isdst</code> (default is <b>nil</b>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9757 For a description of these fields, see the <a href="#pdf-os.date"><code>os.date</code></a> function.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9758
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9759
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9760 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9761 The returned value is a number, whose meaning depends on your system.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9762 In POSIX, Windows, and some other systems,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9763 this number counts the number
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9764 of seconds since some given start time (the "epoch").
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9765 In other systems, the meaning is not specified,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9766 and the number returned by <code>time</code> can be used only as an argument to
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9767 <a href="#pdf-os.date"><code>os.date</code></a> and <a href="#pdf-os.difftime"><code>os.difftime</code></a>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9768
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9769
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9770
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9771
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9772 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9773 <hr><h3><a name="pdf-os.tmpname"><code>os.tmpname ()</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9774
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9775
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9776 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9777 Returns a string with a file name that can
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9778 be used for a temporary file.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9779 The file must be explicitly opened before its use
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9780 and explicitly removed when no longer needed.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9781
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9782
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9783 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9784 On POSIX systems,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9785 this function also creates a file with that name,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9786 to avoid security risks.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9787 (Someone else might create the file with wrong permissions
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9788 in the time between getting the name and creating the file.)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9789 You still have to open the file to use it
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9790 and to remove it (even if you do not use it).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9791
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9792
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9793 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9794 When possible,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9795 you may prefer to use <a href="#pdf-io.tmpfile"><code>io.tmpfile</code></a>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9796 which automatically removes the file when the program ends.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9797
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9798
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9799
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9800
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9801
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9802
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9803
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9804 <h2>6.10 – <a name="6.10">The Debug Library</a></h2>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9805
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9806 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9807 This library provides
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9808 the functionality of the debug interface (<a href="#4.9">§4.9</a>) to Lua programs.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9809 You should exert care when using this library.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9810 Several of its functions
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9811 violate basic assumptions about Lua code
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9812 (e.g., that variables local to a function
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9813 cannot be accessed from outside;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9814 that userdata metatables cannot be changed by Lua code;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9815 that Lua programs do not crash)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9816 and therefore can compromise otherwise secure code.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9817 Moreover, some functions in this library may be slow.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9818
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9819
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9820 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9821 All functions in this library are provided
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9822 inside the <a name="pdf-debug"><code>debug</code></a> table.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9823 All functions that operate over a thread
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9824 have an optional first argument which is the
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9825 thread to operate over.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9826 The default is always the current thread.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9827
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9828
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9829 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9830 <hr><h3><a name="pdf-debug.debug"><code>debug.debug ()</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9831
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9832
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9833 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9834 Enters an interactive mode with the user,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9835 running each string that the user enters.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9836 Using simple commands and other debug facilities,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9837 the user can inspect global and local variables,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9838 change their values, evaluate expressions, and so on.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9839 A line containing only the word <code>cont</code> finishes this function,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9840 so that the caller continues its execution.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9841
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9842
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9843 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9844 Note that commands for <code>debug.debug</code> are not lexically nested
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9845 within any function and so have no direct access to local variables.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9846
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9847
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9848
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9849
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9850 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9851 <hr><h3><a name="pdf-debug.gethook"><code>debug.gethook ([thread])</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9852
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9853
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9854 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9855 Returns the current hook settings of the thread, as three values:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9856 the current hook function, the current hook mask,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9857 and the current hook count
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9858 (as set by the <a href="#pdf-debug.sethook"><code>debug.sethook</code></a> function).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9859
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9860
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9861
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9862
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9863 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9864 <hr><h3><a name="pdf-debug.getinfo"><code>debug.getinfo ([thread,] f [, what])</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9865
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9866
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9867 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9868 Returns a table with information about a function.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9869 You can give the function directly
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9870 or you can give a number as the value of <code>f</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9871 which means the function running at level <code>f</code> of the call stack
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9872 of the given thread:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9873 level 0 is the current function (<code>getinfo</code> itself);
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9874 level 1 is the function that called <code>getinfo</code>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9875 (except for tail calls, which do not count on the stack);
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9876 and so on.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9877 If <code>f</code> is a number larger than the number of active functions,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9878 then <code>getinfo</code> returns <b>nil</b>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9879
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9880
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9881 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9882 The returned table can contain all the fields returned by <a href="#lua_getinfo"><code>lua_getinfo</code></a>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9883 with the string <code>what</code> describing which fields to fill in.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9884 The default for <code>what</code> is to get all information available,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9885 except the table of valid lines.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9886 If present,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9887 the option '<code>f</code>'
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9888 adds a field named <code>func</code> with the function itself.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9889 If present,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9890 the option '<code>L</code>'
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9891 adds a field named <code>activelines</code> with the table of
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9892 valid lines.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9893
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9894
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9895 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9896 For instance, the expression <code>debug.getinfo(1,"n").name</code> returns
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9897 a table with a name for the current function,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9898 if a reasonable name can be found,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9899 and the expression <code>debug.getinfo(print)</code>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9900 returns a table with all available information
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9901 about the <a href="#pdf-print"><code>print</code></a> function.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9902
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9903
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9904
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9905
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9906 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9907 <hr><h3><a name="pdf-debug.getlocal"><code>debug.getlocal ([thread,] f, local)</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9908
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9909
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9910 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9911 This function returns the name and the value of the local variable
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9912 with index <code>local</code> of the function at level <code>f</code> of the stack.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9913 This function accesses not only explicit local variables,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9914 but also parameters, temporaries, etc.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9915
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9916
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9917 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9918 The first parameter or local variable has index 1, and so on,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9919 following the order that they are declared in the code,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9920 counting only the variables that are active
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9921 in the current scope of the function.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9922 Negative indices refer to vararg parameters;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9923 -1 is the first vararg parameter.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9924 The function returns <b>nil</b> if there is no variable with the given index,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9925 and raises an error when called with a level out of range.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9926 (You can call <a href="#pdf-debug.getinfo"><code>debug.getinfo</code></a> to check whether the level is valid.)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9927
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9928
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9929 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9930 Variable names starting with '<code>(</code>' (open parenthesis)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9931 represent variables with no known names
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9932 (internal variables such as loop control variables,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9933 and variables from chunks saved without debug information).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9934
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9935
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9936 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9937 The parameter <code>f</code> may also be a function.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9938 In that case, <code>getlocal</code> returns only the name of function parameters.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9939
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9940
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9941
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9942
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9943 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9944 <hr><h3><a name="pdf-debug.getmetatable"><code>debug.getmetatable (value)</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9945
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9946
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9947 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9948 Returns the metatable of the given <code>value</code>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9949 or <b>nil</b> if it does not have a metatable.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9950
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9951
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9952
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9953
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9954 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9955 <hr><h3><a name="pdf-debug.getregistry"><code>debug.getregistry ()</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9956
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9957
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9958 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9959 Returns the registry table (see <a href="#4.5">§4.5</a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9960
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9961
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9962
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9963
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9964 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9965 <hr><h3><a name="pdf-debug.getupvalue"><code>debug.getupvalue (f, up)</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9966
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9967
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9968 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9969 This function returns the name and the value of the upvalue
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9970 with index <code>up</code> of the function <code>f</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9971 The function returns <b>nil</b> if there is no upvalue with the given index.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9972
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9973
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9974 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9975 Variable names starting with '<code>(</code>' (open parenthesis)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9976 represent variables with no known names
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9977 (variables from chunks saved without debug information).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9978
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9979
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9980
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9981
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9982 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9983 <hr><h3><a name="pdf-debug.getuservalue"><code>debug.getuservalue (u)</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9984
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9985
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9986 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9987 Returns the Lua value associated to <code>u</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9988 If <code>u</code> is not a userdata,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9989 returns <b>nil</b>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9990
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9991
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9992
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9993
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9994 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9995 <hr><h3><a name="pdf-debug.sethook"><code>debug.sethook ([thread,] hook, mask [, count])</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9996
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9997
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9998 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9999 Sets the given function as a hook.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10000 The string <code>mask</code> and the number <code>count</code> describe
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10001 when the hook will be called.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10002 The string mask may have any combination of the following characters,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10003 with the given meaning:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10004
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10005 <ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10006 <li><b>'<code>c</code>': </b> the hook is called every time Lua calls a function;</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10007 <li><b>'<code>r</code>': </b> the hook is called every time Lua returns from a function;</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10008 <li><b>'<code>l</code>': </b> the hook is called every time Lua enters a new line of code.</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10009 </ul><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10010 Moreover,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10011 with a <code>count</code> different from zero,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10012 the hook is called also after every <code>count</code> instructions.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10013
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10014
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10015 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10016 When called without arguments,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10017 <a href="#pdf-debug.sethook"><code>debug.sethook</code></a> turns off the hook.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10018
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10019
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10020 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10021 When the hook is called, its first parameter is a string
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10022 describing the event that has triggered its call:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10023 <code>"call"</code> (or <code>"tail call"</code>),
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10024 <code>"return"</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10025 <code>"line"</code>, and <code>"count"</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10026 For line events,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10027 the hook also gets the new line number as its second parameter.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10028 Inside a hook,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10029 you can call <code>getinfo</code> with level 2 to get more information about
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10030 the running function
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10031 (level 0 is the <code>getinfo</code> function,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10032 and level 1 is the hook function).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10033
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10034
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10035
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10036
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10037 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10038 <hr><h3><a name="pdf-debug.setlocal"><code>debug.setlocal ([thread,] level, local, value)</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10039
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10040
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10041 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10042 This function assigns the value <code>value</code> to the local variable
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10043 with index <code>local</code> of the function at level <code>level</code> of the stack.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10044 The function returns <b>nil</b> if there is no local
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10045 variable with the given index,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10046 and raises an error when called with a <code>level</code> out of range.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10047 (You can call <code>getinfo</code> to check whether the level is valid.)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10048 Otherwise, it returns the name of the local variable.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10049
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10050
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10051 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10052 See <a href="#pdf-debug.getlocal"><code>debug.getlocal</code></a> for more information about
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10053 variable indices and names.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10054
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10055
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10056
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10057
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10058 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10059 <hr><h3><a name="pdf-debug.setmetatable"><code>debug.setmetatable (value, table)</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10060
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10061
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10062 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10063 Sets the metatable for the given <code>value</code> to the given <code>table</code>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10064 (which can be <b>nil</b>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10065 Returns <code>value</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10066
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10067
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10068
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10069
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10070 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10071 <hr><h3><a name="pdf-debug.setupvalue"><code>debug.setupvalue (f, up, value)</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10072
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10073
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10074 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10075 This function assigns the value <code>value</code> to the upvalue
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10076 with index <code>up</code> of the function <code>f</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10077 The function returns <b>nil</b> if there is no upvalue
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10078 with the given index.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10079 Otherwise, it returns the name of the upvalue.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10080
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10081
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10082
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10083
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10084 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10085 <hr><h3><a name="pdf-debug.setuservalue"><code>debug.setuservalue (udata, value)</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10086
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10087
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10088 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10089 Sets the given <code>value</code> as
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10090 the Lua value associated to the given <code>udata</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10091 <code>udata</code> must be a full userdata.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10092
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10093
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10094 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10095 Returns <code>udata</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10096
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10097
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10098
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10099
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10100 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10101 <hr><h3><a name="pdf-debug.traceback"><code>debug.traceback ([thread,] [message [, level]])</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10102
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10103
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10104 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10105 If <code>message</code> is present but is neither a string nor <b>nil</b>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10106 this function returns <code>message</code> without further processing.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10107 Otherwise,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10108 it returns a string with a traceback of the call stack.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10109 The optional <code>message</code> string is appended
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10110 at the beginning of the traceback.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10111 An optional <code>level</code> number tells at which level
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10112 to start the traceback
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10113 (default is 1, the function calling <code>traceback</code>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10114
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10115
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10116
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10117
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10118 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10119 <hr><h3><a name="pdf-debug.upvalueid"><code>debug.upvalueid (f, n)</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10120
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10121
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10122 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10123 Returns a unique identifier (as a light userdata)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10124 for the upvalue numbered <code>n</code>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10125 from the given function.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10126
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10127
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10128 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10129 These unique identifiers allow a program to check whether different
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10130 closures share upvalues.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10131 Lua closures that share an upvalue
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10132 (that is, that access a same external local variable)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10133 will return identical ids for those upvalue indices.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10134
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10135
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10136
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10137
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10138 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10139 <hr><h3><a name="pdf-debug.upvaluejoin"><code>debug.upvaluejoin (f1, n1, f2, n2)</code></a></h3>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10140
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10141
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10142 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10143 Make the <code>n1</code>-th upvalue of the Lua closure <code>f1</code>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10144 refer to the <code>n2</code>-th upvalue of the Lua closure <code>f2</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10145
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10146
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10147
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10148
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10149
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10150
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10151
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10152 <h1>7 – <a name="7">Lua Standalone</a></h1>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10153
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10154 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10155 Although Lua has been designed as an extension language,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10156 to be embedded in a host C program,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10157 it is also frequently used as a standalone language.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10158 An interpreter for Lua as a standalone language,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10159 called simply <code>lua</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10160 is provided with the standard distribution.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10161 The standalone interpreter includes
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10162 all standard libraries, including the debug library.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10163 Its usage is:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10164
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10165 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10166 lua [options] [script [args]]
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10167 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10168 The options are:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10169
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10170 <ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10171 <li><b><code>-e <em>stat</em></code>: </b> executes string <em>stat</em>;</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10172 <li><b><code>-l <em>mod</em></code>: </b> "requires" <em>mod</em>;</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10173 <li><b><code>-i</code>: </b> enters interactive mode after running <em>script</em>;</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10174 <li><b><code>-v</code>: </b> prints version information;</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10175 <li><b><code>-E</code>: </b> ignores environment variables;</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10176 <li><b><code>--</code>: </b> stops handling options;</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10177 <li><b><code>-</code>: </b> executes <code>stdin</code> as a file and stops handling options.</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10178 </ul><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10179 After handling its options, <code>lua</code> runs the given <em>script</em>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10180 When called without arguments,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10181 <code>lua</code> behaves as <code>lua -v -i</code>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10182 when the standard input (<code>stdin</code>) is a terminal,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10183 and as <code>lua -</code> otherwise.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10184
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10185
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10186 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10187 When called without option <code>-E</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10188 the interpreter checks for an environment variable <a name="pdf-LUA_INIT_5_3"><code>LUA_INIT_5_3</code></a>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10189 (or <a name="pdf-LUA_INIT"><code>LUA_INIT</code></a> if the versioned name is not defined)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10190 before running any argument.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10191 If the variable content has the format <code>@<em>filename</em></code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10192 then <code>lua</code> executes the file.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10193 Otherwise, <code>lua</code> executes the string itself.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10194
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10195
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10196 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10197 When called with option <code>-E</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10198 besides ignoring <code>LUA_INIT</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10199 Lua also ignores
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10200 the values of <code>LUA_PATH</code> and <code>LUA_CPATH</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10201 setting the values of
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10202 <a href="#pdf-package.path"><code>package.path</code></a> and <a href="#pdf-package.cpath"><code>package.cpath</code></a>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10203 with the default paths defined in <code>luaconf.h</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10204
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10205
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10206 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10207 All options are handled in order, except <code>-i</code> and <code>-E</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10208 For instance, an invocation like
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10209
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10210 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10211 $ lua -e'a=1' -e 'print(a)' script.lua
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10212 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10213 will first set <code>a</code> to 1, then print the value of <code>a</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10214 and finally run the file <code>script.lua</code> with no arguments.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10215 (Here <code>$</code> is the shell prompt. Your prompt may be different.)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10216
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10217
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10218 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10219 Before running any code,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10220 <code>lua</code> collects all command-line arguments
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10221 in a global table called <code>arg</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10222 The script name goes to index 0,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10223 the first argument after the script name goes to index 1,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10224 and so on.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10225 Any arguments before the script name
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10226 (that is, the interpreter name plus its options)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10227 go to negative indices.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10228 For instance, in the call
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10229
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10230 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10231 $ lua -la b.lua t1 t2
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10232 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10233 the table is like this:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10234
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10235 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10236 arg = { [-2] = "lua", [-1] = "-la",
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10237 [0] = "b.lua",
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10238 [1] = "t1", [2] = "t2" }
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10239 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10240 If there is no script in the call,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10241 the interpreter name goes to index 0,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10242 followed by the other arguments.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10243 For instance, the call
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10244
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10245 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10246 $ lua -e "print(arg[1])"
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10247 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10248 will print "<code>-e</code>".
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10249 If there is a script,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10250 the script is called with parameters
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10251 <code>arg[1]</code>, ···, <code>arg[#arg]</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10252 (Like all chunks in Lua,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10253 the script is compiled as a vararg function.)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10254
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10255
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10256 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10257 In interactive mode,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10258 Lua repeatedly prompts and waits for a line.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10259 After reading a line,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10260 Lua first try to interpret the line as an expression.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10261 If it succeeds, it prints its value.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10262 Otherwise, it interprets the line as a statement.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10263 If you write an incomplete statement,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10264 the interpreter waits for its completion
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10265 by issuing a different prompt.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10266
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10267
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10268 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10269 In case of unprotected errors in the script,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10270 the interpreter reports the error to the standard error stream.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10271 If the error object is not a string but
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10272 has a metamethod <code>__tostring</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10273 the interpreter calls this metamethod to produce the final message.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10274 Otherwise, the interpreter converts the error object to a string
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10275 and adds a stack traceback to it.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10276
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10277
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10278 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10279 When finishing normally,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10280 the interpreter closes its main Lua state
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10281 (see <a href="#lua_close"><code>lua_close</code></a>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10282 The script can avoid this step by
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10283 calling <a href="#pdf-os.exit"><code>os.exit</code></a> to terminate.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10284
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10285
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10286 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10287 To allow the use of Lua as a
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10288 script interpreter in Unix systems,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10289 the standalone interpreter skips
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10290 the first line of a chunk if it starts with <code>#</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10291 Therefore, Lua scripts can be made into executable programs
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10292 by using <code>chmod +x</code> and the <code>#!</code> form,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10293 as in
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10294
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10295 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10296 #!/usr/local/bin/lua
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10297 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10298 (Of course,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10299 the location of the Lua interpreter may be different in your machine.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10300 If <code>lua</code> is in your <code>PATH</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10301 then
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10302
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10303 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10304 #!/usr/bin/env lua
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10305 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10306 is a more portable solution.)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10307
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10308
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10309
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10310 <h1>8 – <a name="8">Incompatibilities with the Previous Version</a></h1>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10311
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10312 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10313 Here we list the incompatibilities that you may find when moving a program
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10314 from Lua 5.2 to Lua 5.3.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10315 You can avoid some incompatibilities by compiling Lua with
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10316 appropriate options (see file <code>luaconf.h</code>).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10317 However,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10318 all these compatibility options will be removed in the future.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10319
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10320
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10321 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10322 Lua versions can always change the C API in ways that
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10323 do not imply source-code changes in a program,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10324 such as the numeric values for constants
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10325 or the implementation of functions as macros.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10326 Therefore,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10327 you should not assume that binaries are compatible between
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10328 different Lua versions.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10329 Always recompile clients of the Lua API when
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10330 using a new version.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10331
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10332
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10333 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10334 Similarly, Lua versions can always change the internal representation
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10335 of precompiled chunks;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10336 precompiled chunks are not compatible between different Lua versions.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10337
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10338
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10339 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10340 The standard paths in the official distribution may
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10341 change between versions.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10342
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10343
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10344
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10345 <h2>8.1 – <a name="8.1">Changes in the Language</a></h2>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10346 <ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10347
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10348 <li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10349 The main difference between Lua 5.2 and Lua 5.3 is the
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10350 introduction of an integer subtype for numbers.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10351 Although this change should not affect "normal" computations,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10352 some computations
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10353 (mainly those that involve some kind of overflow)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10354 can give different results.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10355
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10356
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10357 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10358 You can fix these differences by forcing a number to be a float
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10359 (in Lua 5.2 all numbers were float),
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10360 in particular writing constants with an ending <code>.0</code>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10361 or using <code>x = x + 0.0</code> to convert a variable.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10362 (This recommendation is only for a quick fix
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10363 for an occasional incompatibility;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10364 it is not a general guideline for good programming.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10365 For good programming,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10366 use floats where you need floats
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10367 and integers where you need integers.)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10368 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10369
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10370 <li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10371 The conversion of a float to a string now adds a <code>.0</code> suffix
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10372 to the result if it looks like an integer.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10373 (For instance, the float 2.0 will be printed as <code>2.0</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10374 not as <code>2</code>.)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10375 You should always use an explicit format
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10376 when you need a specific format for numbers.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10377
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10378
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10379 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10380 (Formally this is not an incompatibility,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10381 because Lua does not specify how numbers are formatted as strings,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10382 but some programs assumed a specific format.)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10383 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10384
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10385 <li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10386 The generational mode for the garbage collector was removed.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10387 (It was an experimental feature in Lua 5.2.)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10388 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10389
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10390 </ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10391
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10392
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10393
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10394
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10395 <h2>8.2 – <a name="8.2">Changes in the Libraries</a></h2>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10396 <ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10397
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10398 <li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10399 The <code>bit32</code> library has been deprecated.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10400 It is easy to require a compatible external library or,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10401 better yet, to replace its functions with appropriate bitwise operations.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10402 (Keep in mind that <code>bit32</code> operates on 32-bit integers,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10403 while the bitwise operators in standard Lua operate on 64-bit integers.)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10404 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10405
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10406 <li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10407 The Table library now respects metamethods
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10408 for setting and getting elements.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10409 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10410
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10411 <li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10412 The <a href="#pdf-ipairs"><code>ipairs</code></a> iterator now respects metamethods and
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10413 its <code>__ipairs</code> metamethod has been deprecated.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10414 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10415
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10416 <li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10417 Option names in <a href="#pdf-io.read"><code>io.read</code></a> do not have a starting '<code>*</code>' anymore.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10418 For compatibility, Lua will continue to ignore this character.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10419 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10420
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10421 <li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10422 The following functions were deprecated in the mathematical library:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10423 <code>atan2</code>, <code>cosh</code>, <code>sinh</code>, <code>tanh</code>, <code>pow</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10424 <code>frexp</code>, and <code>ldexp</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10425 You can replace <code>math.pow(x,y)</code> with <code>x^y</code>;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10426 you can replace <code>math.atan2</code> with <code>math.atan</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10427 which now accepts one or two parameters;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10428 you can replace <code>math.ldexp(x,exp)</code> with <code>x * 2.0^exp</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10429 For the other operations,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10430 you can either use an external library or
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10431 implement them in Lua.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10432 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10433
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10434 <li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10435 The searcher for C loaders used by <a href="#pdf-require"><code>require</code></a>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10436 changed the way it handles versioned names.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10437 Now, the version should come after the module name
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10438 (as is usual in most other tools).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10439 For compatibility, that searcher still tries the old format
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10440 if it cannot find an open function according to the new style.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10441 (Lua 5.2 already worked that way,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10442 but it did not document the change.)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10443 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10444
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10445 </ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10446
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10447
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10448
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10449
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10450 <h2>8.3 – <a name="8.3">Changes in the API</a></h2>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10451
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10452
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10453 <ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10454
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10455 <li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10456 Continuation functions now receive as parameters what they needed
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10457 to get through <code>lua_getctx</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10458 so <code>lua_getctx</code> has been removed.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10459 Adapt your code accordingly.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10460 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10461
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10462 <li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10463 Function <a href="#lua_dump"><code>lua_dump</code></a> has an extra parameter, <code>strip</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10464 Use 0 as the value of this parameter to get the old behavior.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10465 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10466
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10467 <li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10468 Functions to inject/project unsigned integers
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10469 (<code>lua_pushunsigned</code>, <code>lua_tounsigned</code>, <code>lua_tounsignedx</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10470 <code>luaL_checkunsigned</code>, <code>luaL_optunsigned</code>)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10471 were deprecated.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10472 Use their signed equivalents with a type cast.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10473 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10474
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10475 <li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10476 Macros to project non-default integer types
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10477 (<code>luaL_checkint</code>, <code>luaL_optint</code>, <code>luaL_checklong</code>, <code>luaL_optlong</code>)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10478 were deprecated.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10479 Use their equivalent over <a href="#lua_Integer"><code>lua_Integer</code></a> with a type cast
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10480 (or, when possible, use <a href="#lua_Integer"><code>lua_Integer</code></a> in your code).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10481 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10482
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10483 </ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10484
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10485
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10486
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10487
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10488 <h1>9 – <a name="9">The Complete Syntax of Lua</a></h1>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10489
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10490 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10491 Here is the complete syntax of Lua in extended BNF.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10492 As usual in extended BNF,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10493 {A} means 0 or more As,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10494 and [A] means an optional A.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10495 (For operator precedences, see <a href="#3.4.8">§3.4.8</a>;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10496 for a description of the terminals
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10497 Name, Numeral,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10498 and LiteralString, see <a href="#3.1">§3.1</a>.)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10499
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10500
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10501
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10502
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10503 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10504
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10505 chunk ::= block
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10506
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10507 block ::= {stat} [retstat]
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10508
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10509 stat ::= ‘<b>;</b>’ \|
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10510 varlist ‘<b>=</b>’ explist \|
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10511 functioncall \|
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10512 label \|
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10513 <b>break</b> \|
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10514 <b>goto</b> Name \|
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10515 <b>do</b> block <b>end</b> \|
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10516 <b>while</b> exp <b>do</b> block <b>end</b> \|
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10517 <b>repeat</b> block <b>until</b> exp \|
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10518 <b>if</b> exp <b>then</b> block {<b>elseif</b> exp <b>then</b> block} [<b>else</b> block] <b>end</b> \|
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10519 <b>for</b> Name ‘<b>=</b>’ exp ‘<b>,</b>’ exp [‘<b>,</b>’ exp] <b>do</b> block <b>end</b> \|
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10520 <b>for</b> namelist <b>in</b> explist <b>do</b> block <b>end</b> \|
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10521 <b>function</b> funcname funcbody \|
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10522 <b>local</b> <b>function</b> Name funcbody \|
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10523 <b>local</b> namelist [‘<b>=</b>’ explist]
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10524
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10525 retstat ::= <b>return</b> [explist] [‘<b>;</b>’]
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10526
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10527 label ::= ‘<b>::</b>’ Name ‘<b>::</b>’
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10528
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10529 funcname ::= Name {‘<b>.</b>’ Name} [‘<b>:</b>’ Name]
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10530
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10531 varlist ::= var {‘<b>,</b>’ var}
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10532
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10533 var ::= Name \| prefixexp ‘<b>[</b>’ exp ‘<b>]</b>’ \| prefixexp ‘<b>.</b>’ Name
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10534
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10535 namelist ::= Name {‘<b>,</b>’ Name}
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10536
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10537 explist ::= exp {‘<b>,</b>’ exp}
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10538
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10539 exp ::= <b>nil</b> \| <b>false</b> \| <b>true</b> \| Numeral \| LiteralString \| ‘<b>...</b>’ \| functiondef \|
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10540 prefixexp \| tableconstructor \| exp binop exp \| unop exp
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10541
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10542 prefixexp ::= var \| functioncall \| ‘<b>(</b>’ exp ‘<b>)</b>’
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10543
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10544 functioncall ::= prefixexp args \| prefixexp ‘<b>:</b>’ Name args
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10545
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10546 args ::= ‘<b>(</b>’ [explist] ‘<b>)</b>’ \| tableconstructor \| LiteralString
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10547
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10548 functiondef ::= <b>function</b> funcbody
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10549
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10550 funcbody ::= ‘<b>(</b>’ [parlist] ‘<b>)</b>’ block <b>end</b>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10551
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10552 parlist ::= namelist [‘<b>,</b>’ ‘<b>...</b>’] \| ‘<b>...</b>’
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10553
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10554 tableconstructor ::= ‘<b>{</b>’ [fieldlist] ‘<b>}</b>’
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10555
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10556 fieldlist ::= field {fieldsep field} [fieldsep]
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10557
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10558 field ::= ‘<b>[</b>’ exp ‘<b>]</b>’ ‘<b>=</b>’ exp \| Name ‘<b>=</b>’ exp \| exp
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10559
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10560 fieldsep ::= ‘<b>,</b>’ \| ‘<b>;</b>’
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10561
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10562 binop ::= ‘<b>+</b>’ \| ‘<b>-</b>’ \| ‘<b>*</b>’ \| ‘<b>/</b>’ \| ‘<b>//</b>’ \| ‘<b>^</b>’ \| ‘<b>%</b>’ \|
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10563 ‘<b>&</b>’ \| ‘<b>~</b>’ \| ‘<b>\|</b>’ \| ‘<b>>></b>’ \| ‘<b><<</b>’ \| ‘<b>..</b>’ \|
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10564 ‘<b><</b>’ \| ‘<b><=</b>’ \| ‘<b>></b>’ \| ‘<b>>=</b>’ \| ‘<b>==</b>’ \| ‘<b>~=</b>’ \|
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10565 <b>and</b> \| <b>or</b>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10566
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10567 unop ::= ‘<b>-</b>’ \| <b>not</b> \| ‘<b>#</b>’ \| ‘<b>~</b>’
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10568
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10569 </pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10570
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10571 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10572
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10573
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10574
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10575
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10576
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10577
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10578
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10579
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10580 <HR>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10581 <SMALL CLASS="footer">
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10582 Last update:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10583 Fri Jan 16 00:58:20 BRST 2015
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10584 </SMALL>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10585 <!--
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10586 Last change: minor edit
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10587 -->
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10588
372 f08cefa4594c start editing manual Franklin Schmidt <fschmidt@gmail.com> parents: 371 diff changeset	10589 </div>
f08cefa4594c start editing manual Franklin Schmidt <fschmidt@gmail.com> parents: 371 diff changeset	10590 </body>
f08cefa4594c start editing manual Franklin Schmidt <fschmidt@gmail.com> parents: 371 diff changeset	10591 </html>

Mercurial Hosting > luan

annotate website/src/manual.html @ 373:571057b1666b