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

annotate website/src/manual.html @ 380:6c6c3537035e

work on manual

author	Franklin Schmidt <fschmidt@gmail.com>
date	Wed, 22 Apr 2015 13:10:48 -0600
parents	571057b1666b
children	8557581740db

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>
380 6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	45 <li><a href="#gc">Garbage Collection</a></li>
6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	46 </ul>
6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	47 </div>
6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	48
6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	49 <div margin-bottom="1em">
6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	50 <a href="#lang">The Language</a>
6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	51 <ul>
6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	52 <li><a href="#lex">Lexical Conventions</a></li>
6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	53 <li><a href="#vars">Variables</a></li>
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	54 </ul>
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	55 </div>
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	56
372 f08cefa4594c start editing manual Franklin Schmidt <fschmidt@gmail.com> parents: 371 diff changeset	57 <hr/>
f08cefa4594c start editing manual Franklin Schmidt <fschmidt@gmail.com> parents: 371 diff changeset	58
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	59
372 f08cefa4594c start editing manual Franklin Schmidt <fschmidt@gmail.com> parents: 371 diff changeset	60 <h2 margin-top="1em"><a name="intro">Introduction</a></h2>
f08cefa4594c start editing manual Franklin Schmidt <fschmidt@gmail.com> parents: 371 diff changeset	61
f08cefa4594c start editing manual Franklin Schmidt <fschmidt@gmail.com> parents: 371 diff changeset	62 <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	63
f08cefa4594c start editing manual Franklin Schmidt <fschmidt@gmail.com> parents: 371 diff changeset	64 <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	65
f08cefa4594c start editing manual Franklin Schmidt <fschmidt@gmail.com> parents: 371 diff changeset	66 <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	67
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	68
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	69 <h2 margin-top="1em"><a name="basic">Basic Concepts</a></h2>
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	70
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	71 <p>This section describes the basic concepts of the language.</p>
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	72
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	73 <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	74
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	75 <p>
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	76 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	77 This means that
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	78 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	79 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	80 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	81
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	82
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	83 <p>
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	84 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	85 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	86 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	87
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	88
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	89 <p>
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	90 There are eight basic types in Luan:
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	91 <i>nil</i>, <i>boolean</i>, <i>number</i>,
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	92 <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	93 and <i>table</i>.
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	94 <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	95 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	96 it usually represents the absence of a useful value.
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	97 <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	98 <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	99 <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	100 <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	101 integer numbers and real (floating-point) numbers.
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	102 <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	103 the underlying Java implementation.
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 <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	106 <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	107
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	108
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	109 <p>
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	110 Luan can call (and manipulate) functions written in Luan and
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	111 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	112 Both are represented by the type <i>function</i>.
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 <p>
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	116 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	117 be stored in Luan variables.
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	118 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	119 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	120 except assignment and identity test.
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	121 Userdata is useful then Java access is enabled in Luan
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	122
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	123
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	124
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	125 <p>
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	126 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	127 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	128 but with any Luan value except <b>nil</b>.
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	129 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	130 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	131 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	132 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	133 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	134
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	135
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	136 <p>
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	137 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	138 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	139 symbol tables, sets, records, graphs, trees, etc.
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	140 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	141 The language supports this representation by
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	142 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	143 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	144 (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	145
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	146
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	147 <p>
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	148 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	149 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	150 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	151 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	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 Like indices,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	156 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	157 In particular,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	158 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	159 table fields can contain functions.
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	160 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	161
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	162
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	163 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	164 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	165 the definition of raw equality in the language.
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	166 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	167 denote the same table element
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	168 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	169 (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	170 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	171 are equal to their respective integers
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	172 (e.g., <tt>1.0 == 1</tt>).
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	173
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	174
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	175 <p>
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	176 Luan values are <i>objects</i>:
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	177 variables do not actually <i>contain</i> values,
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	178 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	179 Assignment, parameter passing, and function returns
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	180 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	181 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	182
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	183
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	184 <p>
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	185 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	186 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	187
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	188
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	189
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	190
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	191
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	192 <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	193
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	194 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	195 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	196 any reference to a free name
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	197 (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	198 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	199 Moreover, every chunk is compiled in the scope of
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	200 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	201 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	202
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	203
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	204 <p>
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	205 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	206 the translation of free names,
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	207 <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	208 In particular,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	209 you can define new variables and parameters with that name.
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	210 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	211 visible at that point in the program,
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	212 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	213
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	214
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	215 <p>
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	216 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	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 <p>
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	220 When Luan loads a chunk,
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	221 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	222
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	223 <p>
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	224 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	225
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	226
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	227
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	228
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	229 <h3 margin-top="1em"><a name="error">Error Handling</a></h3>
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	230
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	231 <p>
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	232 Luan code can explicitly generate an error by calling the
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	233 <a href="#pdf-error"><tt>error</tt></a> function.
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	234 If you need to catch errors in Luan,
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	235 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	236 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	237
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	238
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	239 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	240 Whenever there is an error,
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	241 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	242 is propagated with information about the error.
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	243 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	244 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	245 any value as the error object.
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	246 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	247
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	248
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	249
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	250
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	251
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	252 <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	253
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	254 <p>
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	255 Every table in Luan can have a <i>metatable</i>.
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	256 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	257 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	258 under certain special operations.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	259 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	260 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	261 For instance, when a table is the operand of an addition,
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	262 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	263 If it finds one,
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	264 Luan calls this function to perform the addition.
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	265
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	266
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	267 <p>
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	268 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	269 the corresponding values are called <ii>metamethods</i>.
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	270 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	271 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	272
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	273
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	274 <p>
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	275 You can query the metatable of any table
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	276 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	277
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	278
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	279 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	280 You can replace the metatable of tables
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	281 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	282
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	283
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	284 <p>
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	285 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	286 arithmetic operations, bitwise operations,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	287 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	288
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	289
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	290 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	291 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	292 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	293 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	294 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	295 for instance, the key for operation "add" is the
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	296 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	297 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	298 the access to a metamethod does not invoke other metamethods.
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	299 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	300 with the following code:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	301
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	302 <tt><pre>
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	303 raw_get(get_metatable(obj) or {}, "__" .. event_name)
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	304
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	305 </pre></tt>
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	306
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	307 <p>
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	308 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	309
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	310 <ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	311
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	312 <li><b>"add": </b>
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	313 the <tt>+</tt> operation.
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	314
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	315 If any operand for an addition is a table,
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	316 Luan will try to call a metamethod.
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	317 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	318 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	319 then Luan will check the second operand.
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	320 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	321 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	322 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	323 (adjusted to one value)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	324 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	325 Otherwise,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	326 it raises an error.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	327 </li>
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 <li><b>"sub": </b>
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	330 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	331
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	332 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	333 </li>
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 <li><b>"mul": </b>
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	336 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	337
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	338 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	339 </li>
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 <li><b>"div": </b>
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	342 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	343
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	344 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	345 </li>
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 <li><b>"mod": </b>
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	348 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	349
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	350 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	351 </li>
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 <li><b>"pow": </b>
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	354 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	355
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	356 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	357 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	358
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	359 <li><b>"unm": </b>
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	360 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	361
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	362 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	363 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	364
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	365 <li><b>"concat": </b>
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	366 the <tt>..</tt> (concatenation) operation.
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	367
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	368 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	369 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	370
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	371 <li><b>"len": </b>
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	372 the <tt>#</tt> (length) operation.
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	373
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	374 If there is a metamethod,
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	375 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	376 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	377 (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	378 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	379 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	380 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	381 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	382 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	383
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	384 <li><b>"eq": </b>
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	385 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	386
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	387 Behavior similar to the "add" operation,
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	388 except that Luan will try a metamethod only when the values
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	389 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	390 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	391 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	392 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	393
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	394 <li><b>"lt": </b>
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	395 the <tt><</tt> (less than) operation.
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	396
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	397 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	398 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	399 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	400
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	401 <li><b>"le": </b>
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	402 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	403
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	404 Unlike other operations,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	405 The less-equal operation can use two different events.
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	406 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	407 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	408 If it cannot find such a metamethod,
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	409 then it will try the "<tt>__lt</tt>" event,
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	410 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	411 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	412 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	413 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	414
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	415 <li><b>"index": </b>
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	416 The indexing access <tt>table[key]</tt>.
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	417
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	418 This event happens
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	419 when <tt>key</tt> is not present in <tt>table</tt>.
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	420 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	421
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	422
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	423 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	424 Despite the name,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	425 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	426 If it is a function,
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	427 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	428 If it is a table,
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	429 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	430 (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	431 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	432 </li>
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 <li><b>"newindex": </b>
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	435 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	436
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	437 Like the index event,
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	438 this event happens when
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	439 when <tt>key</tt> is not present in <tt>table</tt>.
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	440 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	441
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	442
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	443 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	444 Like with indexing,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	445 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	446 If it is a function,
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	447 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	448 If it is a table,
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	449 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	450 (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	451 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	452
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	453
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	454 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	455 Whenever there is a "newindex" metamethod,
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	456 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	457 (If necessary,
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	458 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	459 to do the assignment.)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	460 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	461
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	462 <li><b>"call": </b>
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	463 The call operation <tt>func(args)</tt>.
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	464
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	465 This event happens when Luan tries to call a table.
571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	466 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	467 If present,
373 571057b1666b work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 372 diff changeset	468 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	469 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	470 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	471
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	472 </ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	473
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	474
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	475
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	476
380 6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	477 <h3 margin-top="1em"><a name="gc">Garbage Collection</a></h3>
6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	478
6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	479 <p>
6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	480 Luan uses Java's garbage collection.
6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	481
6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	482
6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	483
6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	484
6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	485
6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	486 <h2 margin-top="1em"><a name="lang">The Language</a></h2>
6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	487
6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	488 <p>
6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	489 This section describes the lexis, the syntax, and the semantics of Luan.
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	490 In other words,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	491 this section describes
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	492 which tokens are valid,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	493 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	494 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	495
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	496
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	497 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	498 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	499 in which
380 6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	500 {<i>a</i>} means 0 or more <i>a</i>'s, and
6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	501 [<i>a</i>] means an optional <i>a</i>.
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	502 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	503 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	504 and other terminal symbols are shown like ‘<b>=</b>’.
380 6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	505 The complete syntax of Luan can be found in <a href="#9">§9</a>
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	506 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	507
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	508
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	509
380 6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	510 <h3 margin-top="1em"><a name="lex">Lexical Conventions</a></h3>
6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	511
6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	512 <p>
6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	513 Luan ignores spaces and comments
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	514 between lexical elements (tokens),
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	515 except as delimiters between names and keywords.
380 6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	516 Luan generally considers the end of a line to be the end of a statement. This catches errors and encourages readability. The exception to this is in paranthesis ( <i>(...)</i>, <i>[...]</i>, and <i>{...}</i> ) where the end of line is treated as white space.
6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	517
6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	518 <p>
6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	519 <i>Names</i>
6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	520 (also called <i>identifiers</i>)
6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	521 in Luan can be any string of letters,
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	522 digits, and underscores,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	523 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	524 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	525
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	526
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	527 <p>
380 6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	528 The following <i>keywords</i> are reserved
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	529 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	530
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 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	533 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	534 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	535 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	536 then true until while
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	537 </pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	538
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	539 <p>
380 6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	540 Luan is a case-sensitive language:
6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	541 <tt>and</tt> is a reserved word, but <tt>And</tt> and <tt>AND</tt>
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	542 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	543
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	544
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	545 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	546 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	547
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	548 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	549 + - * / % ^ #
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 == ~= <= >= < > =
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	552 ( ) { } [ ] ::
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	553 ; : , . .. ...
380 6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	554
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	555 </pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	556
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	557 <p>
380 6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	558 <i>Literal strings</i>
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	559 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	560 and can contain the following C-like escape sequences:
380 6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	561 '<tt>\a</tt>' (bell),
6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	562 '<tt>\b</tt>' (backspace),
6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	563 '<tt>\f</tt>' (form feed),
6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	564 '<tt>\n</tt>' (newline),
6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	565 '<tt>\r</tt>' (carriage return),
6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	566 '<tt>\t</tt>' (horizontal tab),
6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	567 '<tt>\v</tt>' (vertical tab),
6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	568 '<tt>\\</tt>' (backslash),
6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	569 '<tt>\"</tt>' (quotation mark [double quote]),
6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	570 and '<tt>\'</tt>' (apostrophe [single quote]).
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	571 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	572 results in a newline in the string.
380 6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	573 The escape sequence '<tt>\z</tt>' skips the following span
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	574 of white-space characters,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	575 including line breaks;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	576 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	577 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	578 into the string contents.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	579
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	580
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	581 <p>
380 6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	582 Luan can specify any character in a literal string by its numerical value.
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	583 This can be done
380 6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	584 with the escape sequence <tt>\x<i>XX</i></tt>,
6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	585 where <i>XX</i> is a sequence of exactly two hexadecimal digits,
6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	586 or with the escape sequence <tt>\<i>ddd</i></tt>,
6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	587 where <i>ddd</i> is a sequence of up to three decimal digits.
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	588 (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	589 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	590
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	591
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	592 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	593 Literal strings can also be defined using a long format
380 6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	594 enclosed by <i>long brackets</i>.
6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	595 We define an <i>opening long bracket of level <i>n</i></i> as an opening
6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	596 square bracket followed by <i>n</i> equal signs followed by another
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	597 opening square bracket.
380 6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	598 So, an opening long bracket of level 0 is written as <tt>[[</tt>,
6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	599 an opening long bracket of level 1 is written as <tt>[=[</tt>,
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	600 and so on.
380 6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	601 A <i>closing long bracket</i> is defined similarly;
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	602 for instance,
380 6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	603 a closing long bracket of level 4 is written as <tt>]====]</tt>.
6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	604 A <i>long literal</i> starts with an opening long bracket of any level and
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	605 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	606 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	607 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	608 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	609 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	610 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	611 (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	612 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	613 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	614
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	615
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	616 <p>
380 6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	617 Any character in a literal string not
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	618 explicitly affected by the previous rules represents itself.
380 6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	619 However, Luan opens files for parsing in text mode,
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	620 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	621 some control characters.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	622 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	623 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	624 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	625
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	626
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	627 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	628 For convenience,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	629 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	630 the newline is not included in the string.
380 6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	631 As an example
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	632 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	633
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	634 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	635 a = 'alo\n123"'
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	636 a = "alo\n123\""
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	637 a = '\97lo\10\04923"'
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	638 a = [[alo
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	639 123"]]
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	640 a = [==[
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	641 alo
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	642 123"]==]
380 6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	643
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	644 </pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	645
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	646 <p>
380 6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	647 A <i>numerical constant</i> (or <i>numeral</i>)
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	648 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	649 and an optional decimal exponent,
380 6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	650 marked by a letter '<tt>e</tt>' or '<tt>E</tt>'.
6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	651 Luan also accepts hexadecimal constants,
6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	652 which start with <tt>0x</tt> or <tt>0X</tt>.
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	653 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	654 plus an optional binary exponent,
380 6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	655 marked by a letter '<tt>p</tt>' or '<tt>P</tt>'.
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	656 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	657 denotes a float;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	658 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	659 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	660
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	661 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	662 3 345 0xff 0xBEBADA
380 6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	663
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	664 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	665 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	666
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	667 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	668 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	669 0x0.1E 0xA23p-4 0X1.921FB54442D18P+1
380 6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	670
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	671 </pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	672
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	673 <p>
380 6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	674 A <i>comment</i> starts with a double hyphen (<tt>--</tt>)
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	675 anywhere outside a string.
380 6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	676 If the text immediately after <tt>--</tt> is not an opening long bracket,
6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	677 the comment is a <i>short comment</i>,
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	678 which runs until the end of the line.
380 6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	679 Otherwise, it is a <i>long comment</i>,
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	680 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	681 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	682
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	683
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	684
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
380 6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	687 <h3 margin-top="1em"><a name="vars">Variables</a></h3>
371 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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	690 Variables are places that store values.
380 6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	691 There are three kinds of variables in Luan:
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	692 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	693
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	694
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	695 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	696 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	697 (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	698 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	699
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	700 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	701 var ::= Name
380 6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	702
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	703 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	704 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	705
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	706
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	707 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	708 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	709 as a local (see <a href="#3.3.7">§3.3.7</a>).
380 6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	710 Local variables are <i>lexically scoped</i>:
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	711 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	712 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	713
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	714
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	715 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	716 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	717
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	718
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	719 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	720 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	721
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	722 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	723 var ::= prefixexp ‘<b>[</b>’ exp ‘<b>]</b>’
380 6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	724
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	725 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	726 The meaning of accesses to table fields can be changed via metatables.
380 6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	727 An access to an indexed variable <tt>t[i]</tt> is equivalent to
6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	728 a call <tt>gettable_event(t,i)</tt>.
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	729 (See <a href="#2.4">§2.4</a> for a complete description of the
380 6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	730 <tt>gettable_event</tt> function.
6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	731 This function is not defined or callable in Luan.
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	732 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	733
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	734
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	735 <p>
380 6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	736 The syntax <tt>var.Name</tt> is just syntactic sugar for
6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	737 <tt>var["Name"]</tt>:
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	738
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	739 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	740 var ::= prefixexp ‘<b>.</b>’ Name
380 6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	741
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	742 </pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	743
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	744 <p>
380 6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	745 An access to a global variable <tt>x</tt>
6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	746 is equivalent to <tt>_ENV.x</tt>.
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	747 Due to the way that chunks are compiled,
380 6c6c3537035e work on manual Franklin Schmidt <fschmidt@gmail.com> parents: 373 diff changeset	748 <tt>_ENV</tt> is never a global name (see <a href="#2.2">§2.2</a>).
371 e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	749
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	753
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	754 <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	755
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	756 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	757 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	758 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	759 This set includes
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	760 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	761 and variable declarations.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	762
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	763
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 <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	766
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	767 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	768 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	769 which are executed sequentially:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	770
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	771 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	772 block ::= {stat}
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	773 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	774 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	775 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	776 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	777 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	778
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	779 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	780 stat ::= ‘<b>;</b>’
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	781 </pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	782
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	783 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	784 Function calls and assignments
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	785 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	786 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	787 Consider the following fragment:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	788
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	789 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	790 a = b + c
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	791 (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	792 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	793 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	794
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	795 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	796 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	797
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	798 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	799 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	800 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	801 in the first way,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	802 interpreting the open parenthesis
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	803 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	804 To avoid this ambiguity,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	805 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	806 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	807
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	808 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	809 ;(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	810 </pre>
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	813 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	814
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	815 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	816 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	817 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	818 Explicit blocks are useful
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	819 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	820 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	821 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	822 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	823
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	824
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	825
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	826
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	827
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	828 <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	829
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	830 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	831 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	832 Syntactically,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	833 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	834
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	835 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	836 chunk ::= block
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	837 </pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	838
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	839 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	840 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	841 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	842 (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	843 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	844 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	845 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	846 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	847 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	848 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	849
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	850
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	851 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	852 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	853 To execute a chunk,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	854 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	855 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	856 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	857 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	858
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	859
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	860 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	861 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	862 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	863 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	864 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	865
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	866
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	867
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	868
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	869
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	870 <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	871
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	872 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	873 Lua allows multiple assignments.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	874 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	875 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	876 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	877 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	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 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	881 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	882 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	883 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	884 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	885
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 Before the assignment,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	889 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	890 the list of variables.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	891 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	892 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	893 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	894 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	895 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	896 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	897 before the adjustment
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	898 (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	899
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	900
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	901 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	902 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	903 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	904 Thus the code
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	905
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	906 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	907 i = 3
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	908 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	909 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	910 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	911 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	912 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	913 Similarly, the line
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	914
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	915 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	916 x, y = y, x
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	917 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	918 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	919 and
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	920
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	921 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	922 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	923 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	924 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	925
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	926
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	927 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	928 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	929 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	930 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	931 <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	932 (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	933 <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	934 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	935 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	936
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	937
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	938 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	939 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	940 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	941 <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	942
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	943
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	944
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	945
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	946
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	947 <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	948 The control structures
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	949 <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	950 familiar syntax:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	951
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	952
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	953
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	954
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	955 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	956 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	957 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	958 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	959 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	960 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	961
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	962
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	963 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	964 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	965 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	966 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	967 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	968 (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	969
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	970
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	971 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	972 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	973 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	974 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	975 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	976 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	977
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	978
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	979 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	980 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	981 For syntactical reasons,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	982 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	983
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	984
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	985
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	986 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	987 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	988 stat ::= label
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	989 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	990 </pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	991
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	992 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	993 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	994 except
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	995 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	996 inside nested functions.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	997 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	998 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	999
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1000
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1001 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1002 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	1003 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	1004
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1005
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1006 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1007 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	1008 <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	1009 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	1010
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1011
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 stat ::= <b>break</b>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1014 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1015 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	1016
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1017
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1018 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1019 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	1020 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	1021 (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	1022
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1023 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	1024 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	1025
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1026 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1027 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	1028 </pre>
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 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	1032 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	1033 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	1034 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	1035 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	1036 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	1037
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1038
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1039
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1042 <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	1043
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1044 <p>
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 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	1047 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	1048
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1049
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1050 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1051 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	1052 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	1053 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	1054
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1055 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1056 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	1057 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1058 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	1059 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	1060 third <em>exp</em>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1061 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	1062
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1063 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1064 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	1065 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1066 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	1067
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1068 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1069 do
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1070 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	1071 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	1072 <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	1073 while true do
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1074 <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	1075 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	1076 break
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1077 end
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1078 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	1079 <em>block</em>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1080 end
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1081 end
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1082 </pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1083
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1084 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1085 Note the following:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1086
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1087 <ul>
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 <li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1090 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	1091 before the loop starts.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1092 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	1093 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1094
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1095 <li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1096 <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	1097 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	1098 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1099
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1100 <li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1101 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	1102 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	1103 </li>
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 <li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1106 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	1107 </li>
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 <li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1110 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	1111 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	1112 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	1113 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1114
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1115 </ul>
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1118 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	1119 called <em>iterators</em>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1120 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	1121 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	1122 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	1123
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1124 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1125 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	1126 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	1127 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1128 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	1129
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1130 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1131 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	1132 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1133 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	1134
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1135 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1136 do
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1137 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	1138 while true do
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1139 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	1140 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	1141 <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	1142 <em>block</em>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1143 end
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1144 end
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1145 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1146 Note the following:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1147
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1148 <ul>
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 <li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1151 <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	1152 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	1153 a <em>state</em>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1154 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	1155 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1156
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1157 <li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1158 <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	1159 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	1160 </li>
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 <li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1163 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	1164 </li>
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 <li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1167 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	1168 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	1169 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	1170 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	1171 </li>
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 </ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1174
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1175
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1178 <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	1179 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	1180 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	1181
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1182 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1183 stat ::= functioncall
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1184 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1185 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	1186 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	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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1190
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1191
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1192 <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	1193 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	1194 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	1195
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1196 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1197 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	1198 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1199 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	1200 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	1201 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	1202
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1205 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	1206 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	1207
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1208
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1209 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1210 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	1211
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1212
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1213
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1214
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1215
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1218 <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	1219
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1220 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1221 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	1222
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1223 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1224 exp ::= prefixexp
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1225 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	1226 exp ::= Numeral
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1227 exp ::= LiteralString
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1228 exp ::= functiondef
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1229 exp ::= tableconstructor
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1230 exp ::= ‘<b>...</b>’
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1231 exp ::= exp binop exp
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1232 exp ::= unop exp
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1233 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	1234 </pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1235
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1236 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1237 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	1238 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	1239 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	1240 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	1241 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	1242 Vararg expressions,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1243 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	1244 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	1245 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	1246
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1247
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1248 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1249 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	1250 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	1251 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	1252 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	1253 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	1254 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	1255 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	1256 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	1257
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1260 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	1261 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	1262 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	1263 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	1264 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	1265 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	1266 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	1267 (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	1268 In all other contexts,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1269 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	1270 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	1271 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	1272
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1273
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1274 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1275 Here are some examples:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1276
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1277 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1278 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	1279 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	1280 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	1281 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	1282 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	1283 -- 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	1284 -- 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	1285
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1286 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	1287 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	1288 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	1289 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	1290 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	1291 {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	1292 {...} -- 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	1293 {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	1294 </pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1295
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1296 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1297 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	1298 Thus,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1299 <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	1300 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	1301 (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	1302 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	1303
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1304
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1305
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1306 <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	1307 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	1308
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1309 <ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1310 <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	1311 <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	1312 <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	1313 <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	1314 <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	1315 <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	1316 <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	1317 <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	1318 </ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1319
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1320 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1321 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	1322 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	1323 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	1324 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	1325 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	1326 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	1327 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	1328 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	1329 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	1330 for floating-point arithmetic
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1331 (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	1332 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	1333
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1334
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1335 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1336 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	1337 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	1338 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	1339 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	1340 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	1341
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1344 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	1345 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	1346 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	1347
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1350 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	1351 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	1352
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1353
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1354 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1355 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	1356 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	1357 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	1358 (In other words,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1359 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	1360 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	1361
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1362
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 <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	1365 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	1366
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1367 <ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1368 <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	1369 <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	1370 <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	1371 <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	1372 <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	1373 <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	1374 </ul>
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1377 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	1378 (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	1379 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	1380 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	1381
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1382
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1383 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1384 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	1385 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	1386 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	1387 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	1388 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	1389
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1390
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1391
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1394 <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	1395 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	1396 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	1397 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	1398 Exponentiation and float division
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1399 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	1400 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	1401 (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	1402 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	1403 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	1404 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	1405 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	1406 besides strings.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1407
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1408
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1409 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1410 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	1411 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	1412
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1413
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1414 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1415 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	1416 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	1417 that is the result.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1418 Otherwise,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1419 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	1420 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	1421 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	1422
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1423
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1424 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1425 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	1426 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	1427 (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	1428 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	1429 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	1430 Otherwise, the conversion fails.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1431
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1434 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	1435 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	1436 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	1437 (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	1438 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	1439 (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	1440
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1441
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1442 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1443 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	1444 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	1445 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	1446 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	1447 (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	1448
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1449
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1450
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1451
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 <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	1454 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	1455
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1456 <ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1457 <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	1458 <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	1459 <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	1460 <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	1461 <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	1462 <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	1463 </ul><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1464 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	1465
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1466
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1467 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1468 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	1469 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	1470 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	1471 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	1472 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	1473 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	1474 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	1475 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	1476 and compared as such.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1477
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1478
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1479 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1480 Tables, userdata, and threads
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1481 are compared by reference:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1482 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	1483 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	1484 (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	1485 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	1486 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	1487 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	1488 (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	1489
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1490
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1491 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1492 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	1493 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	1494
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1495
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1496 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1497 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	1498 or vice versa.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1499 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	1500 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	1501 entries in a table.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1502
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1505 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	1506
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1507
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1508 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1509 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	1510 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	1511 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	1512 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	1513 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	1514 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	1515 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	1516 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	1517 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	1518 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	1519
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1520
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1521
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1522
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1523
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1524 <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	1525 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	1526 <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	1527 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	1528 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	1529 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	1530
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1531
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1532 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1533 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	1534 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	1535 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	1536 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	1537 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	1538 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	1539 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	1540 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	1541 that is,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1542 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	1543 Here are some examples:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1544
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1545 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1546 10 or 20 --> 10
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1547 10 or error() --> 10
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1548 nil or "a" --> "a"
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1549 nil and 10 --> nil
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1550 false and error() --> false
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1551 false and nil --> false
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1552 false or nil --> nil
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1553 10 and 20 --> 20
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1554 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1555 (In this manual,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1556 <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	1557
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1558
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1559
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1562 <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	1563 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	1564 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	1565 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	1566 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	1567 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	1568
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1569
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1570
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1571
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1572
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1573 <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	1574
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1575 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1576 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	1577 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	1578 (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	1579 character is one byte).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1580
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1581
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1582 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1583 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	1584 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	1585
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1586
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1587 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1588 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	1589 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	1590 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	1591 that is,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1592 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	1593 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	1594 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	1595 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	1596
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1597 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1598 {10, 20, nil, 40}
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1599 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1600 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	1601 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	1602 (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	1603 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	1604 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	1605 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	1606
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1607
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1608
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1609
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 <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	1612 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	1613 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	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 or
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1617 and
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1618 < > <= >= ~= ==
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1619 \|
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1620 ~
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1621 &
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1622 << >>
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 + -
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1625 * / // %
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1626 unary operators (not # - ~)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1627 ^
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1628 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1629 As usual,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1630 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	1631 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	1632 operators are right associative.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1633 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	1634
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1635
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1636
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1637
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1638
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1639 <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	1640 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	1641 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	1642 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	1643 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	1644 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	1645
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1646 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1647 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	1648 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	1649 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	1650 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	1651 </pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1652
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1653 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1654 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	1655 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	1656 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	1657 <code>["name"] = exp</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1658 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	1659 <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	1660 starting with 1.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1661 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	1662 For example,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1663
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1664 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1665 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	1666 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1667 is equivalent to
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1668
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1669 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1670 do
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1671 local t = {}
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1672 t[f(1)] = g
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1673 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	1674 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	1675 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	1676 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	1677 t[30] = 23
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1678 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	1679 a = t
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1680 end
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1681 </pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1682
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1683 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1684 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	1685 (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	1686
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1687
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1688 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1689 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	1690 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	1691 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	1692 (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	1693
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1694
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1695 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1696 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	1697 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	1698
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1703 <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	1704 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	1705
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1706 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1707 functioncall ::= prefixexp args
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1708 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1709 In a function call,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1710 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	1711 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	1712 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	1713 with the given arguments.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1714 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	1715 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	1716 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	1717 (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	1718
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1721 The form
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1722
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1723 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1724 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	1725 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1726 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	1727 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	1728 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	1729 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	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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1733 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	1734
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1735 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1736 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	1737 args ::= tableconstructor
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1738 args ::= LiteralString
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1739 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1740 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	1741 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	1742 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	1743 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	1744 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	1745 (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	1746 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	1747 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	1748
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1749
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1750 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1751 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	1752 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	1753 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	1754 (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	1755 in a tail call,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1756 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	1757 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	1758 a program can execute.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1759 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	1760 calling function.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1761 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	1762 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	1763 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	1764 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	1765 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	1766
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1767 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1768 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	1769 return 2 * f(x)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1770 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	1771 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	1772 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	1773 </pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1774
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1775
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1776
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1777
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1778 <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	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 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	1782
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1783 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1784 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	1785 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	1786 </pre>
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1789 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	1790
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1791 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1792 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	1793 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	1794 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	1795 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1796 The statement
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1797
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1798 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1799 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	1800 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1801 translates to
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1802
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1803 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1804 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	1805 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1806 The statement
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1807
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1808 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1809 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	1810 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1811 translates to
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1812
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1813 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1814 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	1815 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1816 The statement
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1817
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1818 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1819 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	1820 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1821 translates to
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1822
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1823 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1824 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	1825 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1826 not to
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 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1829 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	1830 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1831 (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	1832 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	1833
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1834
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1835 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1836 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	1837 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	1838 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	1839 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	1840 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	1841 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	1842 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	1843 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	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 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	1848 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	1849
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1850 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1851 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	1852 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1853 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	1854 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	1855 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	1856 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	1857 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	1858 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	1859 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	1860 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	1861 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	1862 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	1863 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	1864 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	1865 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	1866 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	1867 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	1868 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	1869 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	1870 (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	1871
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1872
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1873 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1874 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	1875
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1876 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1877 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	1878 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	1879 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	1880 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1881 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	1882 to the vararg expression:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1883
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1884 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1885 CALL PARAMETERS
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1886
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1887 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	1888 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	1889 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	1890 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	1891 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	1892
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1893 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	1894 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	1895 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	1896 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	1897 </pre>
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1900 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	1901 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	1902 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	1903 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	1904
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1905
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1906 <p>
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 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	1909 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	1910 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	1911
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 <em>colon</em> syntax
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1915 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	1916 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	1917 Thus, the statement
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 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1920 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	1921 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1922 is syntactic sugar for
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 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1925 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	1926 </pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1927
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1928
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1929
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1930
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1931
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1932
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1933 <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	1934
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1935 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1936
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1937 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	1938 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	1939 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	1940 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	1941 Consider the following example:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1942
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1943 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1944 x = 10 -- global variable
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1945 do -- new block
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1946 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	1947 print(x) --> 10
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1948 x = x+1
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1949 do -- another block
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1950 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	1951 print(x) --> 12
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1952 end
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1953 print(x) --> 11
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1954 end
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1955 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	1956 </pre>
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1959 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	1960 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	1961 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	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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1965 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	1966 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	1967 defined inside their scope.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1968 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	1969 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	1970 inside the inner function.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1971
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1974 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	1975 defines new local variables.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1976 Consider the following example:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1977
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1978 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1979 a = {}
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1980 local x = 20
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1981 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	1982 local y = 0
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1983 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	1984 end
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1985 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1986 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	1987 (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	1988 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	1989 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	1990
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1991
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1992
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1993
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1994
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1995 <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	1996
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1997 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1998
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	1999 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	2000 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	2001 with Lua.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2002 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	2003 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	2004
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2005
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2006 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2007 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	2008 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	2009 Except where stated otherwise,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2010 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	2011 (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	2012 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	2013
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2014
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2015 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2016 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	2017 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	2018 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	2019 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	2020
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2021
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2022
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2023 <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	2024
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2025 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2026 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	2027 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	2028 (<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	2029
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2030
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2031 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2032 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	2033 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	2034 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	2035 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	2036 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	2037 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	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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2041 For convenience,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2042 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	2043 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	2044 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	2045 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	2046 (starting at 1);
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2047 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	2048 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	2049 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	2050 (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	2051 and
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2052 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	2053 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	2054 (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	2055 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	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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2059
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 <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	2062
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2063 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2064 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	2065 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	2066 In particular,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2067 <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	2068 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	2069 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	2070
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2071
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2072 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2073 Whenever Lua calls C,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2074 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	2075 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	2076 <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	2077 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	2078 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	2079
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2080
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2081 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2082 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	2083 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	2084 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	2085 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	2086 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	2087 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	2088
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2089
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2090
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2091
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2092
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2093 <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	2094
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2095 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2096 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	2097 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	2098
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2099
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2100 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2101 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	2102 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	2103 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	2104 (<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	2105
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2106 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	2107 require valid indices.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2108
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2109
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2110 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2111 Unless otherwise noted,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2112 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	2113 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	2114 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	2115 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	2116 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	2117
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2118
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2119 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2120 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	2121 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	2122 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	2123 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	2124 including the pseudo-indices,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2125 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	2126 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	2127 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	2128 (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	2129 Except when noted otherwise,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2130 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	2131
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2132
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2133 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2134 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	2135 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	2136 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	2137 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	2138 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	2139
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2142 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	2143 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	2144 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	2145 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	2146
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2147
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2148
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2149
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 <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	2152
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2153 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2154 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	2155 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	2156 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	2157 (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	2158 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	2159 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	2160
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2161
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2162 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2163 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	2164 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	2165 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	2166 <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	2167 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	2168 <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	2169 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	2170 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	2171 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	2172 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	2173
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2174
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2175
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2176
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2177
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2178 <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	2179
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2180 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2181 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	2182 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	2183 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	2184 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	2185 <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	2186 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	2187 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	2188 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	2189 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	2190 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	2191 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	2192 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	2193 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	2194 As with variable names,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2195 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	2196 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	2197
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2198
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2199 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2200 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	2201 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	2202 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	2203 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	2204
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2205
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2206 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2207 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	2208 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	2209 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	2210 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	2211 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	2212
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2213 <ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2214 <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	2215 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	2216 (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	2217 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2218
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2219 <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	2220 the global environment.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2221 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2222 </ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2223
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2226
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2227 <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	2228
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2229 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2230 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	2231 (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	2232 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	2233 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	2234 (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	2235 and runtime errors)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2236 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	2237 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	2238 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	2239 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	2240 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	2241
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2244 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	2245 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	2246 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	2247 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	2248 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	2249 never returning
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2250 (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	2251
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2252
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2253 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2254 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	2255 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	2256 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	2257 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	2258 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	2259
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2260
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2261 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2262 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	2263 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	2264 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	2265 it can raise errors.
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2269 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	2270
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2271
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
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 <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	2276
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2277 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2278 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	2279 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	2280 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	2281 (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	2282 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	2283 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	2284
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2285
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2286 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2287 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	2288 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	2289 except for three functions:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2290 <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	2291 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	2292 (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	2293
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2294
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2295 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2296 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	2297 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	2298 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	2299 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	2300 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	2301 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	2302 (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	2303 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	2304 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	2305
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2306
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2307 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2308 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	2309 After the thread resumes,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2310 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	2311 However,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2312 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	2313 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	2314 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	2315 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	2316 As the name implies,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2317 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	2318 of the original function.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2319
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2320
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2321 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2322 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	2323
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2324 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2325 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	2326 ... /* code 1 */
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2327 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	2328 ... /* code 2 */
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 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2331 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	2332 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	2333 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	2334
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2335 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2336 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	2337 ... /* code 2 */
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2338 }
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2339
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2340 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	2341 ... /* code 1 */
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2342 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	2343 }
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2344 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2345 In the above code,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2346 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	2347 <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	2348 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	2349 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	2350 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	2351 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	2352 (errors or yielding),
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2353 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	2354 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	2355
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2356 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2357 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	2358 ... /* code 1 */
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2359 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	2360 }
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2361 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2362 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	2363 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	2364 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	2365 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	2366 <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	2367 (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	2368 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	2369
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2370
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2371 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2372 Besides the Lua state,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2373 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	2374 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	2375 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	2376 (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	2377 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	2378 continuation function.)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2379 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	2380 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	2381 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	2382 (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	2383 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	2384 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	2385 (For these two functions,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2386 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	2387 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	2388 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	2389 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	2390 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	2391 (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	2392 directly the continuation function,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2393 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	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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2397 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	2398 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	2399 from the original function,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2400 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	2401 (For instance,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2402 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	2403 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	2404 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	2405 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	2406 of the original function.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2407
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2411
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2412 <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	2413
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2414 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2415 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	2416 alphabetical order.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2417 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	2418 <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	2419
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2420
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2421 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2422 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	2423 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	2424 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	2425 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	2426 (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	2427 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	2428 <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	2429 depending on the situation;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2430 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	2431 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	2432 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	2433 (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	2434 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	2435 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	2436 '<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	2437 '<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	2438 '<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	2439
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2440
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2441
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2442 <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	2443 <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	2444 <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	2445
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2446 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2447 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	2448 (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	2449
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2450
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2451
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2452
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2453
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2454 <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	2455 <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	2456 void *ptr,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2457 size_t osize,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2458 size_t nsize);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2459
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2460 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2461 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	2462 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	2463 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	2464 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	2465 Its arguments are
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2466 <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	2467 <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	2468 <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	2469 is being allocated;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2470 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	2471
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2472
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2473 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2474 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	2475 <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	2476 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	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 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	2481 <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	2482 <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	2483 <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	2484 <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	2485 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	2486 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	2487 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	2488
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2489
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2490 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2491 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	2492
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2493
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2494 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2495 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	2496 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	2497 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	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 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	2502 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	2503 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	2504 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	2505 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	2506 <code>osize >= nsize</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2507
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2508
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2509 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2510 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	2511 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	2512
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2513 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2514 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	2515 size_t nsize) {
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2516 (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	2517 if (nsize == 0) {
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2518 free(ptr);
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2519 return NULL;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2520 }
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2521 else
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2522 return realloc(ptr, nsize);
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2523 }
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2524 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2525 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	2526 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	2527 <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	2528 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	2529 (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	2530 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	2531
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2532
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2533
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2534
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 <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	2537 <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	2538 <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	2539
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2540 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2541 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	2542 (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	2543 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	2544 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	2545 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	2546 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	2547 (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	2548
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2549
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2550 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2551 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	2552
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2553 <ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2554
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2555 <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	2556 <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	2557 <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	2558 <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	2559 <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	2560 <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	2561 <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	2562 <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	2563 <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	2564 <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	2565 <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	2566 <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	2567 <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	2568 <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	2569
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2570 </ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2571
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2572
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2573
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2574
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2575 <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	2576 <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	2577 <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	2578
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2579 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2580 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	2581
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2582
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2583
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2584
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2585
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2586 <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	2587 <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	2588 <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	2589
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2590 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2591 Calls a function.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2592
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2593
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2594 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2595 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	2596 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	2597 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	2598 in direct order;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2599 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	2600 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	2601 <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	2602 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	2603 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	2604 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	2605 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	2606 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	2607 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	2608 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	2609 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	2610 (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	2611 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	2612
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2613
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2614 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2615 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	2616 (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	2617
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2618
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2619 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2620 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	2621 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	2622
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2623 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2624 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	2625 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2626 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	2627
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2628 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2629 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	2630 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	2631 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	2632 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	2633 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	2634 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	2635 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	2636 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	2637 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2638 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	2639 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	2640 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	2641
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2642
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2646 <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	2647 <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	2648 <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	2649 int nargs,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2650 int nresults,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2651 lua_KContext ctx,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2652 lua_KFunction k);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2653
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2654 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2655 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	2656 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	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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2660
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 <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	2663 <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	2664
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2665 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2666 Type for C functions.
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2669 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2670 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	2671 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	2672 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	2673 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	2674 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	2675 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	2676 <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	2677 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	2678 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	2679 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	2680 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	2681 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	2682 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	2683 discarded by Lua.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2684 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	2685 many results.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2686
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2687
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2688 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2689 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	2690 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	2691
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2692 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2693 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	2694 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	2695 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	2696 int i;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2697 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	2698 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	2699 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	2700 lua_error(L);
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2701 }
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2702 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	2703 }
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2704 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	2705 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	2706 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	2707 }
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2708 </pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2709
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2710
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2711
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2712
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2713 <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	2714 <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	2715 <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	2716
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2717 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2718 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	2719 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	2720 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	2721 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	2722 (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	2723 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	2724 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	2725 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	2726 it is left unchanged.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2727
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2728
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2729
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2730
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2731
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2732 <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	2733 <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	2734 <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	2735
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2736 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2737 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	2738 (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	2739 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	2740 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	2741 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	2742 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	2743 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	2744 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	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 <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	2751 <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	2752 <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	2753
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2754 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2755 Compares two Lua values.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2756 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	2757 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	2758 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	2759 (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	2760 Otherwise returns 0.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2761 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	2762
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2763
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2764 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2765 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	2766
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2767 <ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2768
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2769 <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	2770 <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	2771 <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	2772
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2773 </ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2774
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2775
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2776
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 <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	2779 <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	2780 <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	2781
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2782 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2783 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	2784 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	2785 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	2786 (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	2787 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	2788 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	2789 (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	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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2793
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2794
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2795 <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	2796 <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	2797 <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	2798
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2799 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2800 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	2801 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	2802 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	2803 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	2804
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2805
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2806
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2807
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2808
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2809 <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	2810 <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	2811 <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	2812
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2813 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2814 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	2815 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	2816 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	2817 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	2818 the table will have.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2819 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	2820 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	2821 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	2822 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	2823
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2824
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2825
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 <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	2829 <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	2830 <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	2831 lua_Writer writer,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2832 void *data,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2833 int strip);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2834
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2835 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2836 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	2837 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	2838 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	2839 if loaded again,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2840 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	2841 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	2842 <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	2843 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	2844 to write them.
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 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	2849 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	2850 about the function.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2851
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2852
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2853 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2854 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	2855 call to the writer;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2856 0 means no errors.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2857
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2860 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	2861
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2862
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2863
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2864
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2865
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2866 <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	2867 <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	2868 <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	2869
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2870 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2871 Generates a Lua error,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2872 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	2873 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	2874 and therefore never returns
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2875 (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	2876
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2879
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2880
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2881 <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	2882 <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	2883 <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	2884
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2885 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2886 Controls the garbage collector.
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2889 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2890 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	2891 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	2892
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2893 <ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2894
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2895 <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	2896 stops the garbage collector.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2897 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2898
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2899 <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	2900 restarts the garbage collector.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2901 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2902
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2903 <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	2904 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	2905 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2906
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2907 <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	2908 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	2909 </li>
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 <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	2912 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	2913 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	2914 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2915
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2916 <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	2917 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	2918 </li>
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 <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	2921 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	2922 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	2923 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	2924 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2925
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2926 <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	2927 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	2928 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	2929 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	2930 </li>
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 <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	2933 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	2934 (i.e., not stopped).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2935 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2936
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2937 </ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2938
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2939 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2940 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	2941 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	2942
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2943
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2944
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2945
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2946
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2947 <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	2948 <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	2949 <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	2950
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2951 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2952 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	2953 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	2954 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	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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2958
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2959
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2960 <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	2961 <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	2962 <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	2963
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2964 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2965 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	2966 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	2967 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	2968 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	2969
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2970
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2971 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2972 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	2973
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2974
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2975
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2976
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2977
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2978 <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	2979 <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	2980 <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	2981
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2982 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2983 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	2984 given Lua state.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2985 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	2986 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	2987
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2988
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2989 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2990 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	2991 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	2992
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2993
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2994 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	2995 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	2996 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	2997 (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	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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3001
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 <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	3004 <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	3005 <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	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 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	3009 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	3010
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3011
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3012
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3013
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3014
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3015 <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	3016 <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	3017 <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	3018
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3019 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3020 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	3021 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	3022 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	3023 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	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 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	3028
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3031
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3032
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3033 <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	3034 <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	3035 <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	3036
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3037 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3038 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	3039 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	3040 Otherwise,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3041 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	3042
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3043
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3044
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3047 <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	3048 <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	3049 <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	3050
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3051 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3052 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	3053 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	3054 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	3055
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3056
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3057 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3058 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	3059 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	3060 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	3061 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	3062
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3063
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3064 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3065 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	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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3071 <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	3072 <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	3073 <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	3074
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3075 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3076 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	3077 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	3078 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	3079 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	3080
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3081
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3082
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 <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	3086 <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	3087 <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	3088
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3089 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3090 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	3091 at the given index.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3092
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3093
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3094 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3095 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	3096
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3097
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3098
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3099
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 <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	3102 <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	3103 <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	3104
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3105 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3106 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	3107 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	3108 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	3109 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	3110
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3111
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 <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	3116 <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	3117
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3118 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3119 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	3120
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3121
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3122 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3123 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	3124 (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	3125 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	3126 (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	3127 (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	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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3131 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	3132 <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	3133 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	3134
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3135
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3138
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3139 <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	3140 <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	3141 <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	3142
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3143 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3144 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	3145 and 0 otherwise.
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3148
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3149
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 <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	3152 <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	3153 <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	3154
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3155 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3156 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	3157 and 0 otherwise.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3158
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3159
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3160
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 <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	3164 <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	3165 <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	3166
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3167 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3168 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	3169 (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	3170
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3171
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3174
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3175 <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	3176 <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	3177 <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	3178
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3179 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3180 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	3181 (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	3182 and 0 otherwise.
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3186
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3187
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3188 <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	3189 <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	3190 <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	3191
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3192 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3193 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	3194 and 0 otherwise.
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3198
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 <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	3201 <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	3202 <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	3203
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3204 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3205 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	3206 and 0 otherwise.
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3209
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3210
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3211
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3212 <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	3213 <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	3214 <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	3215
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3216 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3217 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	3218 and 0 otherwise.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3219
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3220
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3221
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3224 <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	3225 <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	3226 <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	3227
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3228 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3229 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	3230 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	3231 and 0 otherwise.
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3234
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3235
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 <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	3238 <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	3239 <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	3240
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3241 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3242 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	3243 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	3244 and 0 otherwise.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3245
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3246
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3247
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3250 <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	3251 <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	3252 <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	3253
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3254 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3255 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	3256 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	3257 and 0 otherwise.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3258
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3259
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3260
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3261
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3262
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3263 <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	3264 <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	3265 <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	3266
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3267 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3268 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	3269 and 0 otherwise.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3270
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3271
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3272
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3273
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 <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	3276 <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	3277 <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	3278
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3279 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3280 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	3281 and 0 otherwise.
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3286
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3287 <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	3288 <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	3289 <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	3290
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3291 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3292 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	3293 (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	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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3299 <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	3300 <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	3301 <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	3302
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3303 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3304 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	3305 and 0 otherwise.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3306
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3310
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3311 <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	3312 <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	3313
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3314 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3315 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	3316 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	3317 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	3318 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	3319 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	3320 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	3321
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3322
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3323
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3324
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 <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	3327 <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	3328
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3329 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3330 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	3331
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3332
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3333
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3334
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3335
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3336 <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	3337 <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	3338 <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	3339
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3340 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3341 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	3342 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	3343 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	3344 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	3345
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3346
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3347
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 <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	3351 <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	3352 <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	3353 lua_Reader reader,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3354 void *data,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3355 const char *chunkname,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3356 const char *mode);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3357
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3358 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3359 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	3360 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	3361 <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	3362 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	3363 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	3364
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3365
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3366 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3367 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	3368
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3369 <ul>
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 <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	3372
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3373 <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	3374 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	3375
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3376 <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	3377 memory allocation error;</li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3378
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3379 <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	3380 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	3381 (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	3382 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	3383 </li>
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 </ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3386
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3387 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3388 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	3389 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	3390 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	3391
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3392
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3393 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3394 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	3395 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	3396
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3397
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3398 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3399 <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	3400 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	3401 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	3402 with the addition that
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3403 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	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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3407 <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	3408 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	3409 unmodified when returning.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3410
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3411
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3412 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3413 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	3414 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	3415 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	3416 When loading main chunks,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3417 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	3418 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	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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3424 <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	3425 <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	3426 <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	3427
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3428 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3429 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	3430 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	3431 (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	3432 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	3433 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	3434 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	3435 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	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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3440
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3441 <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	3442 <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	3443 <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	3444
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3445 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3446 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	3447 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	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_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	3454 <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	3455 <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	3456
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3457 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3458 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	3459 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	3460 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	3461 its global environment,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3462 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	3463
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3464
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3465 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3466 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	3467 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	3468 like any Lua object.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3469
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3470
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3471
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 <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	3475 <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	3476 <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	3477
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3478 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3479 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	3480 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	3481 and returns this address.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3482 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	3483
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 <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	3489 <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	3490 <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	3491
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3492 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3493 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	3494 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	3495 (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	3496 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	3497 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	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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3501 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	3502
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3503 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3504 /* 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	3505 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	3506 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	3507 /* 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	3508 printf("%s - %s\n",
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3509 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	3510 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	3511 /* 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	3512 lua_pop(L, 1);
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3513 }
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3514 </pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3515
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3516 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3517 While traversing a table,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3518 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	3519 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	3520 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	3521 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	3522 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	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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3526 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	3527 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	3528
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3531
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3532
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3533 <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	3534 <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	3535
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3536 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3537 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	3538
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3539
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3540 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3541 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	3542 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	3543 (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	3544
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 <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	3550 <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	3551
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3552 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3553 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	3554 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	3555 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	3556 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	3557 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	3558 conversion was successful.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3559 (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	3560 correctly without this macro,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3561 due to roundings.)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3562
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3563
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3564 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3565 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	3566
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3567
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3568
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3569
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 <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	3572 <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	3573 <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	3574
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3575 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3576 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	3577
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 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	3581 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	3582 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	3583 <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	3584 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	3585 <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	3586 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	3587 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	3588 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	3589 <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	3590 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	3591
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3592
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3593 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3594 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	3595 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	3596 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	3597 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	3598 <em>message handler</em>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3599 (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	3600 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	3601 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	3602 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	3603 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	3604
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3605
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3606 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3607 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	3608 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	3609 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	3610 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	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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3614 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	3615 (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	3616
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3617 <ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3618
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3619 <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	3620 success.</li>
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 <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	3623 a runtime error.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3624 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3625
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3626 <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	3627 memory allocation error.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3628 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	3629 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3630
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3631 <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	3632 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	3633 </li>
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 <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	3636 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	3637 (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	3638 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3639
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3640 </ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3641
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3642
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3643
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 <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	3646 <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	3647 <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	3648 int nargs,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3649 int nresults,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3650 int msgh,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3651 lua_KContext ctx,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3652 lua_KFunction k);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3653
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3654 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3655 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	3656 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	3657
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3658
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 <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	3663 <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	3664 <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	3665
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3666 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3667 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	3668
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 <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	3674 <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	3675 <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	3676
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3677 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3678 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	3679
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3680
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3681
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3682
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 <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	3685 <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	3686 <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	3687
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3688 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3689 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	3690
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3691
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3692 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3693 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	3694 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	3695 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	3696 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	3697 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	3698 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	3699 (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	3700 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	3701 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	3702 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	3703 associated with the function.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3704 <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	3705
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3708 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	3709
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3712 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	3713 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	3714 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	3715 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	3716
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3717
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3718
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3719
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3720
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3721 <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	3722 <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	3723 <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	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 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	3727 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	3728 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	3729 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	3730
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3731
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3732 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3733 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	3734 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	3735 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	3736
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3737
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3738 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3739 <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	3740
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3741 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3742 #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	3743 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3744 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	3745
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3746
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3747
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 <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	3751 <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	3752 <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	3753
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3754 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3755 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	3756 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	3757 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	3758 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	3759
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3760 <ul>
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 <li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3763 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	3764 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	3765 (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	3766 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3767
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3768 <li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3769 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	3770 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	3771 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	3772 '<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	3773 '<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	3774 '<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	3775 '<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	3776 '<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	3777 '<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	3778 '<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	3779 '<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	3780 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3781
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3782 </ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3783
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3784
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3785
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 <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	3788 <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	3789 <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	3790
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3791 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3792 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	3793
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3796
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3797
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3798 <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	3799 <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	3800 <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	3801
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3802 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3803 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	3804
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3805
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3806
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 <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	3810 <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	3811 <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	3812
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3813 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3814 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	3815
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3816
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3817 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3818 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	3819 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	3820 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	3821 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	3822 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	3823 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	3824 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	3825
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3826
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3827
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3828
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 <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	3831 <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	3832 <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	3833
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3834 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3835 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	3836 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	3837 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	3838
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3839
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3842
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3843 <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	3844 <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	3845 <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	3846
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3847 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3848 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	3849 onto the stack.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3850 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	3851 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	3852 the function returns.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3853 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	3854 including embedded zeros.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3855
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3856
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3857 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3858 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	3859
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3860
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3864 <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	3865 <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	3866 <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	3867
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3868 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3869 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	3870
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3871
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3872
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3875 <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	3876 <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	3877 <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	3878
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3879 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3880 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	3881
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 <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	3887 <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	3888 <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	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 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	3892 onto the stack.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3893 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	3894 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	3895 the function returns.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3896
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3897
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3898 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3899 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	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 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	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_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	3910 <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	3911 <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	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 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	3915 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	3916
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3917
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3918
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3919
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3920
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3921 <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	3922 <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	3923 <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	3924
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3925 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3926 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	3927 onto the stack.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3928
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3932
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3933 <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	3934 <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	3935 <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	3936 const char *fmt,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3937 va_list argp);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3938
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3939 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3940 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	3941 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	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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3945
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3946
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3947 <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	3948 <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	3949 <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	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 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	3953 <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	3954 (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	3955 Otherwise returns 0.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3956 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	3957
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3958
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3961
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3962 <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	3963 <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	3964 <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	3965
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3966 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3967 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	3968 (i.e., without metamethods).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3969
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3970
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3971
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3974 <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	3975 <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	3976 <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	3977
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3978 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3979 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	3980 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	3981 The access is raw;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3982 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	3983
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3984
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3985 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3986 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	3987
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3988
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3989
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3990
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 <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	3993 <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	3994 <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	3995
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3996 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	3997 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	3998 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	3999 <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	4000 The access is raw;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4001 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	4002
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 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	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_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	4012 <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	4013 <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	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 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	4017 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	4018 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	4019 with no metamethods;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4020 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	4021 for the userdata;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4022 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	4023
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4024
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4027
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4028 <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	4029 <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	4030 <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	4031
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4032 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4033 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	4034 (i.e., without metamethods).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4035
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4036
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4037
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4038
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4039
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4040 <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	4041 <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	4042 <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	4043
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4044 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4045 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	4046 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	4047 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	4048
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4049
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4050 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4051 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	4052 The assignment is raw;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4053 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	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_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	4060 <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	4061 <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	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 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	4065 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	4066 <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	4067 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	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 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	4072 The assignment is raw;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4073 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	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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4077
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 <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	4080 <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	4081 void *data,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4082 size_t *size);</pre>
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4085 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	4086 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	4087 <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	4088 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	4089 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	4090 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	4091 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	4092 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	4093 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	4094 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	4095 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	4096
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
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4101 <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	4102 <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	4103 <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	4104
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4105 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4106 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	4107 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	4108
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4109 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4110 #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	4111 (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	4112 </pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4113
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4114
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4115
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4116
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4117 <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	4118 <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	4119 <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	4120
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4121 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4122 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	4123 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	4124 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	4125 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	4126
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4127
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4130
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4131 <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	4132 <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	4133 <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	4134
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4135 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4136 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	4137 without shifting any element
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4138 (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	4139 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	4140
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4141
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 <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	4146 <span class="apii">[-?, +?, –]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4147 <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	4148
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4149 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4150 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	4151
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4152
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4153 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4154 To start a coroutine,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4155 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	4156 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	4157 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	4158 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	4159 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	4160 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	4161 <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	4162 <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	4163 <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	4164 without errors,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4165 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	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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4169 In case of errors,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4170 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	4171 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	4172 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	4173
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4174
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4175 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4176 To resume a coroutine,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4177 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	4178 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	4179 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	4180 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	4181
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4182
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4183 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4184 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	4185 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	4186 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	4187
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4188
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4189
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4190
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4191
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4192 <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	4193 <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	4194 <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	4195
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4196 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4197 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	4198 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	4199 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	4200 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	4201 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	4202 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	4203
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4204
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4207
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4208 <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	4209 <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	4210 <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	4211
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4212 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4213 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	4214 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	4215
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4218
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 <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	4221 <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	4222 <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	4223
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4224 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4225 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	4226 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	4227 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	4228
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4229
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4230 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4231 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	4232 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	4233 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	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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4237
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 <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	4240 <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	4241 <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	4242
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4243 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4244 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	4245 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	4246
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4247
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4248
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4249
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 <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	4252 <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	4253 <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	4254
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4255 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4256 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	4257 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	4258 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	4259
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4260
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4261 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4262 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	4263 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	4264 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	4265
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 <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	4271 <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	4272 <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	4273
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4274 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4275 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	4276 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	4277
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4278
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4279
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 <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	4283 <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	4284 <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	4285
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4286 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4287 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	4288 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	4289 <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	4290 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	4291
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4292
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4293 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4294 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	4295 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	4296 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	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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4301
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4302 <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	4303 <span class="apii">[-?, +?, –]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4304 <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	4305
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4306 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4307 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	4308 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	4309 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	4310 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	4311 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	4312
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4313
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4314
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4317 <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	4318 <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	4319 <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	4320
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4321 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4322 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	4323 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	4324
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 <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	4330 <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	4331
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4332 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4333 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	4334 (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	4335 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	4336 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	4337 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	4338
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4339
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4340 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4341 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	4342 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	4343 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	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_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	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>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	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 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	4355
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4356
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4357 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4358 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	4359 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	4360 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	4361 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	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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4365 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	4366 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	4367 (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	4368 (to resume a coroutine).
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4371
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4372
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 <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	4375 <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	4376 <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	4377
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4378 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4379 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	4380 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	4381 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	4382 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	4383 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	4384 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	4385 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	4386 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	4387 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	4388 (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	4389 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	4390
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4391
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 <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	4396 <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	4397 <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	4398
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4399 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4400 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	4401 value (0 or 1).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4402 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	4403 <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	4404 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	4405 otherwise it returns false.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4406 (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	4407 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	4408
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4409
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4410
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4411
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 <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	4414 <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	4415 <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	4416
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4417 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4418 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	4419 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	4420 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	4421
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4422
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4423
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4424
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4425
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4426 <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	4427 <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	4428 <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	4429
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4430 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4431 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	4432
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4433
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 <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	4438 <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	4439 <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	4440
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4441 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4442 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	4443 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	4444 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	4445 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	4446 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	4447
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4448
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4449 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4450 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	4451 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	4452 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	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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4456
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4457
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4458 <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	4459 <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	4460 <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	4461
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4462 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4463 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	4464 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	4465 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	4466 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	4467 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	4468 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	4469 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	4470 <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	4471 (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	4472 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	4473
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4474
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4475 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4476 <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	4477 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	4478 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	4479 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	4480 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	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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4484 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	4485 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	4486 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	4487
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4488
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4492 <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	4493 <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	4494 <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	4495
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4496 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4497 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	4498
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4499
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4500
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4501
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4502
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4503 <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	4504 <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	4505 <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	4506
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4507 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4508 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	4509 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	4510 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	4511 (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	4512 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	4513
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4514
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4515 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4516 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	4517 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	4518 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	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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4522
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4523
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4524 <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	4525 <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	4526 <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	4527
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4528 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4529 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	4530 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	4531 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	4532 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	4533 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	4534 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	4535
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4536
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4537 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4538 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	4539
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4540
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 <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	4545 <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	4546 <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	4547
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4548 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4549 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	4550
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4551
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4552
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 <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	4556 <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	4557 <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	4558
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4559 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4560 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	4561 (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	4562 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	4563 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	4564
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4565
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4569 <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	4570 <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	4571 <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	4572
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4573 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4574 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	4575 returns its block address.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4576 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	4577 returns its pointer.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4578 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	4579
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4582
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4583
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4584 <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	4585 <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	4586 <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	4587
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4588 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4589 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	4590 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	4591 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	4592 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	4593 <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	4594 <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	4595 <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	4596 <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	4597 <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	4598 <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	4599 <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	4600 <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	4601 and
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4602 <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	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_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	4609 <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	4610 <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	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 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	4614 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	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_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	4621 <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	4622
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4623 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4624 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	4625
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4626
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4627
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4628
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 <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	4631 <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	4632 <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	4633
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4634 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4635 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	4636 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	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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4641
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4642 <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	4643 <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	4644 <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	4645
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4646 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4647 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	4648 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	4649 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	4650 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	4651 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	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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4656
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4657 <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	4658 <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	4659 const void* p,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4660 size_t sz,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4661 void* ud);</pre>
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4664 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	4665 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	4666 <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	4667 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	4668 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	4669 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	4670
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4671
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4672 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4673 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	4674 0 means no errors;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4675 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	4676 calling the writer again.
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4679
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4680
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4681
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4682 <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	4683 <span class="apii">[-?, +?, –]</span>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4684 <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	4685
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4686 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4687 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	4688
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4689
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4690 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4691 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	4692 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	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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4696
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4697
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4698 <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	4699 <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	4700 <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	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 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	4704 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	4705 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	4706 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	4707 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	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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4713 <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	4714 <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	4715 <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	4716 int nresults,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4717 lua_KContext ctx,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4718 lua_KFunction k);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4719
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4720 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4721 Yields a coroutine (thread).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4722
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4723
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4724 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4725 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	4726 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	4727 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	4728 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	4729 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	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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4733 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	4734 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	4735 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	4736 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	4737 from the previous function,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4738 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	4739 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	4740 Moreover,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4741 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	4742 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	4743
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4744
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4745 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4746 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	4747 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	4748 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	4749 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	4750 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	4751 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	4752 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	4753 (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	4754 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	4755 Lua will yield and,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4756 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	4757 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	4758 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	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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4762 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	4763 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	4764 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	4765 (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	4766
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4769
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 <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	4774
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4775 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4776 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	4777 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	4778 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	4779 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	4780 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	4781 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	4782
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4783
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4784
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4785 <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	4786 <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	4787 int event;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4788 const char name; / (n) */
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4789 const char namewhat; / (n) */
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4790 const char what; / (S) */
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4791 const char source; / (S) */
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4792 int currentline; /* (l) */
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4793 int linedefined; /* (S) */
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4794 int lastlinedefined; /* (S) */
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4795 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	4796 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	4797 char isvararg; /* (u) */
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4798 char istailcall; /* (t) */
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4799 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	4800 /* private part */
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4801 <em>other fields</em>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4802 } lua_Debug;</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4803
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4804 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4805 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	4806 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	4807 <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	4808 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	4809 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	4810 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	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 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	4815
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4816 <ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4817
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4818 <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	4819 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	4820 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	4821 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	4822 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	4823 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	4824 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	4825 Otherwise,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4826 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	4827 <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	4828 </li>
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 <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	4831 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	4832 </li>
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 <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	4835 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	4836 </li>
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 <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	4839 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	4840 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4841
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4842 <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	4843 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	4844 <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	4845 <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	4846 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4847
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4848 <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	4849 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	4850 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	4851 <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	4852 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4853
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4854 <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	4855 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	4856 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	4857 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	4858 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	4859 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	4860 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	4861 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	4862 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	4863 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	4864 </li>
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 <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	4867 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	4868 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	4869 <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	4870 <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	4871 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	4872 (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	4873 </li>
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 <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	4876 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	4877 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	4878 </li>
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 <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	4881 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	4882 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4883
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4884 <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	4885 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	4886 (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	4887 </li>
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 <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	4890 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	4891 (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	4892 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4893
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4894 </ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4895
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4898
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4899 <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	4900 <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	4901 <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	4902
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4903 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4904 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	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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4908
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4909
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4910 <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	4911 <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	4912 <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	4913
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4914 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4915 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	4916
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 <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	4922 <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	4923 <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	4924
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4925 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4926 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	4927
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4928
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4929
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4930
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4931
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4932 <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	4933 <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	4934 <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	4935
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4936 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4937 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	4938
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4939
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4940 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4941 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	4942 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	4943 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	4944 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	4945
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4946
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4947 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4948 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	4949 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	4950 (In that case,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4951 <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	4952 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	4953 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	4954
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4955 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4956 lua_Debug ar;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4957 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	4958 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	4959 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	4960 </pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4961
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4962 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4963 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	4964 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	4965 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	4966
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4967 <ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4968
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4969 <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	4970 </li>
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 <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	4973 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	4974 <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	4975 </li>
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 <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	4978 </li>
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 <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	4981 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4982
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4983 <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	4984 <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	4985 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4986
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4987 <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	4988 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	4989 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	4990 </li>
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 <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	4993 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	4994 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	4995 (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	4996 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	4997 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	4998
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	4999
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5000 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5001 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	5002 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	5003 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5004
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5005 </ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5006
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5007 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5008 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	5009 (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	5010
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5011
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5012
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5013
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5014
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5015 <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	5016 <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	5017 <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	5018
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5019 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5020 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	5021 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	5022
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 In the first case,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5026 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	5027 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	5028 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	5029 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	5030 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	5031 and names.
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5035 <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	5036 and returns its name.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5037
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5038
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5039 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5040 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	5041 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	5042 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	5043 (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	5044 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	5045
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5048 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	5049 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	5050 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	5051
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5052
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5053
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5054
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5055
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5056 <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	5057 <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	5058 <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	5059
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5060 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5061 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	5062
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5063
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5064 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5065 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	5066 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	5067 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	5068 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	5069 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	5070 (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	5071 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	5072 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	5073 it returns 0.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5074
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5075
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5076
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5077
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5078
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5079 <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	5080 <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	5081 <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	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 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	5085 (For Lua functions,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5086 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	5087 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	5088 <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	5089 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	5090 and returns its name.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5091 <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	5092 (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	5093 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	5094 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	5095
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5096
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5097 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5098 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	5099 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	5100 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	5101 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	5102
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5103
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 <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	5108 <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	5109
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5110 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5111 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	5112
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5113
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5114 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5115 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	5116 <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	5117 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	5118 <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	5119 <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	5120 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	5121 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	5122 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	5123 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	5124
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5125
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5126 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5127 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	5128 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	5129 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	5130
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5131
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5132 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5133 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	5134 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	5135 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	5136
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5137
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5138 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5139 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	5140 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	5141 <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	5142
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5143
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5144 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5145 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	5146 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	5147 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	5148 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	5149 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	5150
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5151
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5152
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5155 <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	5156 <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	5157 <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	5158
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5159 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5160 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	5161
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5162
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5163 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5164 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	5165 <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	5166 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	5167 <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	5168 <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	5169 <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	5170 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	5171 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	5172 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	5173 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	5174
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5175 <ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5176
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5177 <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	5178 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	5179 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	5180 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5181
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5182 <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	5183 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	5184 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	5185 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	5186 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5187
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5188 <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	5189 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	5190 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	5191 (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	5192 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5193
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5194 <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	5195 <code>count</code> instructions.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5196 (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	5197 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5198
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5199 </ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5200
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5201 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5202 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	5203
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5204
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5205
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5206
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5207
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5208 <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	5209 <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	5210 <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	5211
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5212 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5213 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	5214 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	5215 (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	5216 <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	5217 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	5218 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	5219
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5220
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5221 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5222 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	5223 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	5224 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	5225
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5228
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5229
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5230 <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	5231 <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	5232 <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	5233
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5234 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5235 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	5236 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	5237 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	5238 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	5239 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	5240 (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	5241
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5242
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5243 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5244 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	5245 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	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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5249
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5250
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5251 <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	5252 <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	5253 <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	5254
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5255 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5256 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	5257 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	5258 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	5259 (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	5260 (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	5261
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 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	5265 closures share upvalues.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5266 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	5267 (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	5268 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	5269
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5270
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5271
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5272
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 <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	5275 <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	5276 <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	5277 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	5278
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5279 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5280 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	5281 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	5282
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5286
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5287
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5288
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5289 <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	5290
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5291 <p>
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 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	5294 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	5295 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	5296 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	5297 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	5298 common tasks.
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5301 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5302 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	5303 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	5304 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	5305
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5308 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	5309 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	5310 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	5311 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	5312 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	5313
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5316 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	5317 extra stack slots.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5318 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	5319 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	5320 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	5321
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5322
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5323 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5324 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	5325 check C function arguments.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5326 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	5327 (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	5328 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	5329
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5330
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5331 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5332 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	5333 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	5334
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5335
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 <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	5338
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5339 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5340 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	5341 in alphabetical order.
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
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 <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	5346 <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	5347 <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	5348
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5349 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5350 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	5351 (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	5352
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5353
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5354
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5355
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 <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	5358 <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	5359 <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	5360
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5361 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5362 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	5363 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	5364 (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	5365 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	5366
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5367
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5368
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5369
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 <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	5372 <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	5373 <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	5374
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5375 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5376 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	5377 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	5378 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	5379
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5380
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5381
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5382
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 <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	5385 <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	5386 <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	5387
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5388 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5389 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	5390 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	5391 (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	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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5395
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5396
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5397 <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	5398 <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	5399 <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	5400
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5401 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5402 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	5403 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	5404 (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	5405 Pops the value.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5406
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5407
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5408 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5409 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	5410 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	5411 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	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="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	5418 <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	5419 <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	5420 int cond,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5421 int arg,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5422 const char *extramsg);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5423
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5424 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5425 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	5426 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	5427
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5428
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5429
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5430
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5431
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5432 <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	5433 <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	5434 <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	5435
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5436 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5437 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	5438 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	5439 using a standard message
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5440 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	5441
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5442 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5443 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	5444 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5445 This function never returns.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5446
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5449
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 <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	5452 <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	5453
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5454 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5455 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	5456
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5457
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5458 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5459 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	5460 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	5461
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5462 <ul>
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 <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	5465
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5466 <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	5467
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5468 <li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5469 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	5470 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	5471 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5472
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5473 <li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5474 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	5475 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	5476 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5477
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5478 </ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5479
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5480 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5481 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	5482 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	5483
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5484 <ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5485
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5486 <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	5487
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5488 <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	5489 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	5490
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5491 <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	5492
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5493 <li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5494 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	5495 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	5496 copied into that space.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5497 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5498
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5499 </ul>
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 During its normal operation,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5503 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	5504 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	5505 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	5506 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	5507 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	5508 that is,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5509 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	5510 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	5511 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	5512 (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	5513 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	5514 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	5515 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	5516
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5517
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5518
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5521 <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	5522 <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	5523 <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	5524
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5525 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5526 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	5527 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	5528 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	5529 (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	5530
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5533
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5534
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5535 <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	5536 <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	5537 <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	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 Equivalent to the sequence
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5541 <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	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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5547 <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	5548 <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	5549 <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	5550
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5551 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5552 Calls a metamethod.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5553
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5554
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5555 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5556 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	5557 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	5558 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	5559 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	5560 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	5561 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	5562 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	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="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	5569 <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	5570 <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	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 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	5574 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	5575
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5576
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5577
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5578
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 <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	5581 <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	5582 <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	5583
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5584 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5585 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	5586 (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	5587 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	5588
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5589
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5590
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5591
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 <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	5594 <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	5595 <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	5596
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5597 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5598 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	5599 and returns this string;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5600 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	5601 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	5602
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5603
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5604 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5605 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	5606 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	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="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	5613 <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	5614 <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	5615
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5616 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5617 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	5618 and returns this number.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5619
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 <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	5625 <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	5626 <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	5627 int arg,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5628 const char *def,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5629 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	5630
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5631 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5632 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	5633 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	5634 (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	5635 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	5636 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	5637 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	5638
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5639
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5640 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5641 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	5642 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	5643 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	5644
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5645
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5646 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5647 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	5648 (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	5649 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	5650
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5654
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5655 <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	5656 <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	5657 <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	5658
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5659 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5660 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	5661 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	5662 <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	5663 (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	5664
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5665
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5666
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 <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	5670 <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	5671 <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	5672
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5673 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5674 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	5675 and returns this string.
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5678 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5679 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	5680 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	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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5684
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5685
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5686 <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	5687 <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	5688 <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	5689
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5690 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5691 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	5692 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	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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5696
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5697
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5698 <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	5699 <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	5700 <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	5701
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5702 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5703 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	5704 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	5705 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	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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5710
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5711 <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	5712 <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	5713 <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	5714
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5715 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5716 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	5717 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	5718 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	5719 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	5720 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	5721 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	5722
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5723
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5724
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5727 <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	5728 <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	5729 <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	5730
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5731 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5732 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	5733 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	5734
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5735 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5736 (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	5737 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5738 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	5739 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	5740
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5741
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5742
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5743
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 <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	5746 <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	5747 <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	5748
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5749 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5750 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	5751 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	5752
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5753 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5754 (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	5755 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5756 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	5757 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	5758
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5759
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5760
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5763 <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	5764 <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	5765 <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	5766
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5767 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5768 Raises an error.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5769 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	5770 plus any extra arguments,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5771 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	5772 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	5773 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	5774 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	5775
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5776
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5777 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5778 This function never returns,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5779 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	5780 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	5781
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5782
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5783
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 <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	5787 <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	5788 <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	5789
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5790 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5791 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	5792 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	5793 (<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	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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5797
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5798
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5799 <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	5800 <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	5801 <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	5802
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5803 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5804 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	5805 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	5806 (<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	5807
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5808
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5809
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5812 <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	5813 <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	5814 <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	5815
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5816 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5817 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	5818 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	5819 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	5820 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	5821 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	5822
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
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5827 <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	5828 <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	5829 <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	5830
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5831 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5832 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	5833 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	5834 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	5835 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	5836
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5837
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5840
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5841 <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	5842 <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	5843 <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	5844
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5845 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5846 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	5847 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	5848 is a table,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5849 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	5850 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	5851 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	5852
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5853
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 <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	5858 <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	5859 <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	5860 const char *s,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5861 const char *p,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5862 const char *r);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5863
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5864 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5865 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	5866 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	5867 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	5868 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	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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5874 <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	5875 <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	5876 <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	5877
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5878 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5879 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	5880 as a number;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5881 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	5882 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	5883 (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	5884
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5885
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5886
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5887
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 <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	5890 <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	5891 <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	5892 const char *buff,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5893 size_t sz,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5894 const char *name);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5895
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5896 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5897 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	5898
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5899
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5900
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 <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	5904 <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	5905 <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	5906 const char *buff,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5907 size_t sz,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5908 const char *name,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5909 const char *mode);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5910
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5911 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5912 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	5913 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	5914 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	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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5918 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	5919 <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	5920 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	5921 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	5922
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5923
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5924
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5925
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 <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	5928 <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	5929 <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	5930
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5931 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5932 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	5933
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5936
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5937
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5938 <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	5939 <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	5940 <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	5941 const char *mode);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5942
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5943 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5944 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	5945 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	5946 named <code>filename</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5947 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	5948 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	5949 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	5950
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5951
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5952 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5953 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	5954
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5955
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5956 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5957 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	5958 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	5959 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	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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5963 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	5964 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	5965
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5966
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5967
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5970 <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	5971 <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	5972 <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	5973
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5974 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5975 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	5976 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	5977 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	5978
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5979
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5980 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5981 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	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 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	5986 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	5987
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 <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	5993 <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	5994 <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	5995
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5996 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	5997 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	5998 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	5999
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6000
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6001 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6002 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	6003
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6004 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6005 (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	6006 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6007 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	6008 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	6009
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6012
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6013
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6014 <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	6015 <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	6016 <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	6017
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6018 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6019 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	6020 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	6021 (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	6022 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	6023 (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	6024
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6025
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6026 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6027 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	6028 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	6029 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	6030
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 <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	6036 <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	6037 <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	6038
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6039 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6040 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	6041 returns 0.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6042 Otherwise,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6043 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	6044 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	6045 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	6046 and returns 1.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6047 (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	6048
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6049
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6050 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6051 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	6052 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	6053
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6054
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6055
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6056
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6057
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6058 <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	6059 <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	6060 <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	6061
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6062 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6063 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	6064 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	6065 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	6066 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	6067 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	6068 errors.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6069
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6070
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6071 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6072 Returns the new state,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6073 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	6074
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6075
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6076
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6077
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 <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	6080 <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	6081 <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	6082
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6083 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6084 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	6085
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6088
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6089
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6090 <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	6091 <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	6092 <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	6093 int arg,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6094 lua_Integer d);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6095
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6096 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6097 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	6098 (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	6099 returns this integer.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6100 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	6101 returns <code>d</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6102 Otherwise, raises an error.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6103
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6106
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6107
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6108 <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	6109 <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	6110 <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	6111 int arg,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6112 const char *d,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6113 size_t *l);</pre>
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 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	6117 returns this string.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6118 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	6119 returns <code>d</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6120 Otherwise, raises an error.
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6124 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	6125 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	6126
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6129
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6130
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6131 <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	6132 <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	6133 <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	6134
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6135 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6136 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	6137 returns this number.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6138 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	6139 returns <code>d</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6140 Otherwise, raises an error.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6141
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6142
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6143
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6144
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 <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	6147 <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	6148 <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	6149 int arg,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6150 const char *d);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6151
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6152 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6153 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	6154 returns this string.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6155 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	6156 returns <code>d</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6157 Otherwise, raises an error.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6158
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6159
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 <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	6164 <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	6165 <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	6166
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6167 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6168 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	6169 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	6170
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6171
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6172
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6173
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 <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	6176 <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	6177 <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	6178
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6179 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6180 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	6181 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	6182 (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	6183 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	6184 <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	6185 it to the buffer.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6186
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6187
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6188
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6189
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 <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	6192 <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	6193 <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	6194
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6195 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6196 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	6197 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	6198
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6199
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6200
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6203 <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	6204 <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	6205 <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	6206
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6207 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6208 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	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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6213
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6214 <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	6215 <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	6216 <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	6217
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6218 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6219 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	6220 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	6221 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	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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6225 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	6226 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	6227 <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	6228 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	6229 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	6230 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	6231
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6232
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6233 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6234 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	6235 <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	6236 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	6237 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	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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6242
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6243 <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	6244 <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	6245 const char *name;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6246 lua_CFunction func;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6247 } luaL_Reg;</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 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	6251 <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	6252 <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	6253 the function.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6254 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	6255 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	6256
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6257
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6258
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6259
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 <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	6262 <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	6263 <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	6264 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	6265
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6266 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6267 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	6268 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	6269 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	6270 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	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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6274 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	6275 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	6276
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6277
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6278 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6279 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	6280
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6281
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6282
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6283
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6284
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6285 <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	6286 <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	6287 <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	6288
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6289 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6290 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	6291 (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	6292 (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	6293
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6294
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6295 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6296 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	6297 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	6298 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	6299 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	6300 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	6301
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6302
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 <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	6307 <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	6308 <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	6309
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6310 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6311 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	6312 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	6313 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	6314
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6315
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6319 <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	6320 <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	6321 FILE *f;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6322 lua_CFunction closef;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6323 } luaL_Stream;</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6324
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6325 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6326 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	6327 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	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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6331 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	6332 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	6333 (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	6334 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	6335 (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	6336
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6339 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	6340 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	6341 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	6342 (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	6343 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	6344 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	6345 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	6346 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	6347 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	6348 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	6349 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	6350 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	6351 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	6352
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6353
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6354
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6357 <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	6358 <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	6359 <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	6360
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6361 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6362 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	6363 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	6364 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	6365
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6366
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6367
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 <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	6371 <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	6372 <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	6373
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6374 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6375 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	6376 in a reasonable format.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6377 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	6378 returned by the function.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6379 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	6380 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	6381
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6382
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6383 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6384 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	6385 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	6386 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	6387 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	6388
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6389
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6390
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 <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	6394 <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	6395 <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	6396 int level);</pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6397
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6398 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6399 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	6400 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	6401 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	6402 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	6403 to start the traceback.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6404
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6405
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6406
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 <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	6410 <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	6411 <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	6412
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6413 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6414 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	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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6418
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6419
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6420 <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	6421 <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	6422 <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	6423
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6424 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6425 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	6426 (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	6427 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	6428 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	6429 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	6430
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6431
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6432 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6433 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	6434 <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	6435
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6436
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6437
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6438
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6439
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6440 <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	6441 <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	6442 <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	6443
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6444 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6445 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	6446 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	6447 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	6448
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6449 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6450 <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	6451 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6452 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	6453 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	6454 etc.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6455
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6456
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6457 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6458 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	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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6462
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6463
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 <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	6467
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6468 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6469 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	6470 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	6471 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	6472 (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	6473 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	6474 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	6475 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	6476 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	6477
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6478
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6479 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6480 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	6481 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	6482 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	6483
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6484 <ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6485
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6486 <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	6487
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6488 <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	6489
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6490 <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	6491
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6492 <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	6493
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6494 <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	6495
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6496 <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	6497
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6498 <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	6499
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6500 <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	6501
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6502 <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	6503
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6504 <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	6505
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6506 </ul><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6507 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	6508 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	6509 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	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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6513 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	6514 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	6515 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	6516 Alternatively,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6517 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	6518 <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	6519 <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	6520 <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	6521 <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	6522 <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	6523 <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	6524 <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	6525 <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	6526 <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	6527 <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	6528 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	6529 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	6530
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6531
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 <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	6534
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6535 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6536 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	6537 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	6538 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	6539 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	6540
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6541
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6542 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6543 <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	6544
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6545
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6546 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6547 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	6548 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	6549 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	6550 In case of error,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6551 <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	6552 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	6553
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6554
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6557 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6558 <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	6559
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6562 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	6563 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	6564
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6565 <ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6566
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6567 <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	6568 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	6569 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	6570 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6571
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6572 <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	6573 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	6574 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	6575 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	6576 </li>
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 <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	6579 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	6580 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6581
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6582 <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	6583 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	6584 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	6585 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	6586 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	6587 (except for overflows).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6588 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6589
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6590 <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	6591 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	6592 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	6593 With a zero value,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6594 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	6595 For non-zero values,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6596 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	6597 (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	6598 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	6599 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6600
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6601 <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	6602 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	6603 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	6604 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	6605 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6606
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6607 <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	6608 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	6609 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	6610 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	6611 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6612
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6613 <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	6614 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	6615 (i.e., not stopped).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6616 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6617
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6618 </ul>
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 <p>
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="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	6624 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	6625 When called without arguments,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6626 <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	6627 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	6628 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	6629 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	6630
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6634 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6635 <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	6636 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	6637 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	6638 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	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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6642 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	6643 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	6644 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	6645 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	6646 <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	6647 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	6648 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	6649 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	6650 to the message.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6651
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6656 <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	6657 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	6658 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	6659 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	6660 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	6661 nor vice versa.
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6664
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6665
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6666 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6667 <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	6668
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6669
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6670 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6671 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	6672 Otherwise,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6673 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	6674 returns the associated value.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6675 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	6676
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6677
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6678
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6679
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6680 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6681 <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	6682
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6683
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6684 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6685 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	6686 so that the construction
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6687
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6688 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6689 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	6690 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6691 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	6692 (<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	6693 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	6694
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6695
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6696
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6697
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6698 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6699 <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	6700
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6701
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6702 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6703 Loads a chunk.
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6707 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	6708 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	6709 <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	6710 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	6711 with previous results.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6712 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	6713
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6714
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6715 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6716 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	6717 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	6718 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	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 resulting function has upvalues,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6723 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	6724 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	6725 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	6726 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	6727 (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	6728 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	6729 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	6730 However,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6731 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	6732 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	6733 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	6734 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	6735
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6736
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6737 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6738 <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	6739 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	6740 When absent,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6741 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	6742 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	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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6746 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	6747 (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	6748 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	6749 "<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	6750 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	6751 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	6752
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6755 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	6756 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	6757 the interpreter.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6758
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6759
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6760
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 <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	6764
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6765
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6766 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6767 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	6768 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	6769 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	6770 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	6771
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6772
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6776 <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	6777
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6778
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6779 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6780 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	6781 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	6782 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	6783 <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	6784 and its associated value.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6785 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	6786 <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	6787 and its associated value.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6788 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	6789 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	6790 <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	6791 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	6792 In particular,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6793 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	6794
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6795
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6796 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6797 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	6798 <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	6799 (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	6800 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	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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6804 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	6805 during the traversal,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6806 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	6807 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	6808 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	6809
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6810
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6811
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6812
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6813 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6814 <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	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 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	6819 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	6820 results from the call.
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6823 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6824 Otherwise,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6825 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	6826 so that the construction
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 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6829 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	6830 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6831 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	6832
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6835 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	6836 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	6837
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6838
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6841 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6842 <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	6843
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6844
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6845 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6846 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	6847 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	6848 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	6849 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	6850 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	6851 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	6852 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	6853 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	6854 after this first result.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6855 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	6856
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6857
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6858
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6859
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6860 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6861 <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	6862 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	6863 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	6864 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	6865 <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	6866 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	6867 for instance for debugging.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6868 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	6869 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	6870
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6871
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6874 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6875 <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	6876 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	6877 without invoking any metamethod.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6878 Returns a boolean.
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6881
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6884 <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	6885 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	6886 without invoking any metamethod.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6887 <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	6888 <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	6889
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6890
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6894 <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	6895 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	6896 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	6897 without invoking any metamethod.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6898 Returns an integer.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6899
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6900
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6901
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6904 <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	6905 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	6906 without invoking any metamethod.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6907 <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	6908 <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	6909 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	6910
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6911
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6912 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6913 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	6914
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6917
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6918 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6919 <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	6920
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6921
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6922 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6923 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	6924 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	6925 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	6926 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	6927 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	6928
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6929
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6930
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6931
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6932 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6933 <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	6934
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6935
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6936 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6937 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	6938 (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	6939 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	6940 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	6941 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	6942 raises an error.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6943
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6946 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	6947
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6948
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6949
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6952 <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	6953
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6954
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6955 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6956 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	6957 <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	6958 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	6959 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	6960 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	6961 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	6962
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6963
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6964 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6965 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	6966 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	6967 (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	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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6971 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	6972 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	6973 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	6974 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	6975 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	6976 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	6977 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	6978 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	6979 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	6980
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6981
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6982
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6983
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6984 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6985 <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	6986 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	6987 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	6988 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	6989 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	6990 (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	6991 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	6992
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6993
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6994 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	6995 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	6996 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	6997 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	6998 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	6999
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7004 <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	7005 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	7006 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	7007 "<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	7008 "<code>number</code>",
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7009 "<code>string</code>",
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7010 "<code>boolean</code>",
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7011 "<code>table</code>",
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7012 "<code>function</code>",
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7013 "<code>thread</code>",
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7014 and "<code>userdata</code>".
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7019 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7020 <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	7021 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	7022 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	7023 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	7024
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7027
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7028 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7029 <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	7030
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7031
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7032 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7033 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	7034 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	7035
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7036
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7037
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7041
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7042 <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	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 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	7046 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	7047 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	7048
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7049
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7050 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7051 <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	7052
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7053
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7054 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7055 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	7056 <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	7057 Returns this new coroutine,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7058 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	7059
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7060
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7061
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7062
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7063 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7064 <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	7065
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7066
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7067 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7068 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	7069
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7070
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7071 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7072 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	7073 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	7074
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7075
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7076
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7077
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7078 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7079 <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	7080
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7083 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	7084 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	7085 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	7086 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	7087 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	7088 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	7089 <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	7090 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	7091 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	7092
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7093
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7094 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7095 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	7096 <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	7097 (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	7098 (when the coroutine terminates).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7099 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	7100 <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	7101
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7105 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7106 <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	7107
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7108
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7109 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7110 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	7111 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	7112
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7113
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7114
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7117 <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	7118
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7119
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7120 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7121 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	7122 <code>"running"</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7123 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	7124 <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	7125 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	7126 <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	7127 (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	7128 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	7129 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	7130
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7131
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 <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	7136
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7137
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7138 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7139 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	7140 <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	7141 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	7142 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	7143 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	7144 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	7145 except the first boolean.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7146 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	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-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	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 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	7157 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	7158
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7162
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7163
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7164
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7165 <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	7166
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7167 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7168 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	7169 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	7170 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	7171 <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	7172 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	7173
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7174
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7175 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7176 <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	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 Loads the given module.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7181 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	7182 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	7183 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	7184 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	7185 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	7186
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7187
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7188 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7189 To find a loader,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7190 <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	7191 By changing this sequence,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7192 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	7193 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	7194 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	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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7198 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	7199 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	7200 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	7201 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	7202 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	7203 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	7204 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	7205 If that also fails,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7206 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	7207
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7210 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	7211 <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	7212 <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	7213 (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	7214 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	7215 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	7216 <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	7217 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	7218 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	7219 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	7220 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	7221 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	7222
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7223
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7224 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7225 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	7226 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	7227 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	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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7232 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7233 <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	7234
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7235
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7236 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7237 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	7238 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	7239
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7240 <ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7241
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7242 <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	7243 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	7244
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7245 <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	7246 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	7247
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7248 <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	7249 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	7250 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	7251
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7252 <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	7253 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	7254 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	7255
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7256 <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	7257 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	7258 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	7259
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7260 </ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7261
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7262
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7263
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7264 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7265 <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	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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7269 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	7270
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7271
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7272 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7273 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	7274 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	7275 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	7276 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	7277 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	7278
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7279
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7280
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7283 <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	7284
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7287 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	7288 modules are already loaded.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7289 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	7290 <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	7291 <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	7292
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7293
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7294 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7295 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	7296 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	7297 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	7298
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7299
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 <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	7304
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7305
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7306 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7307 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	7308
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7309
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7310 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7311 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	7312 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	7313 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	7314 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	7315 Otherwise,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7316 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	7317 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	7318 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	7319 (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	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 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	7324 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	7325 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	7326 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	7327 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	7328 <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	7329 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	7330 <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	7331 (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	7332
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7333
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7334 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7335 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	7336 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	7337 (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	7338 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	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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7342
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7343 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7344 <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	7345
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7346
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7347 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7348 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	7349
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7350
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7351 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7352 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	7353 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	7354 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	7355 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	7356 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	7357 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	7358 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	7359
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7360
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7361
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7364 <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	7365
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7366
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7367 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7368 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	7369 (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	7370
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7371
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7372 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7373 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	7374 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	7375 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	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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7381 <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	7382
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7383
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7384 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7385 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	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 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	7390 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	7391 <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	7392 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	7393 sole parameter.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7394 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	7395 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	7396 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	7397 (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	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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7401 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	7402
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7405 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	7406 <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	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 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	7411 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	7412 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	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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7416 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	7417 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	7418 Again,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7419 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	7420 For instance,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7421 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	7422
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7423 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7424 "./?.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	7425 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7426 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	7427 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	7428 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	7429 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	7430 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	7431 application with the library.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7432 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	7433 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	7434 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	7435 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	7436 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	7437 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	7438 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	7439 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	7440 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	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 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	7445 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	7446 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	7447 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	7448 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	7449 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	7450 the submodule;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7451 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	7452 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	7453 into one single library,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7454 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	7455
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7458 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	7459 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	7460 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	7461 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	7462
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7463
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7464
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7465
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7466 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7467 <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	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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7471 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	7472
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7473
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7474 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7475 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	7476 <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	7477 For each template,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7478 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	7479 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	7480 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	7481 (a dot, by default)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7482 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	7483 (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	7484 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	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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7488 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	7489
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7490 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7491 "./?.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	7492 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7493 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	7494 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	7495 <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	7496 <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	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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7500 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	7501 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	7502 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	7503 (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	7504
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7505
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7506
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7507
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7508
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7509
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7510
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7511 <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	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 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	7515 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	7516 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	7517 (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	7518 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	7519 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	7520 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	7521
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7522
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7523 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7524 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	7525 <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	7526 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	7527 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	7528 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	7529 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	7530 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	7531
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7532
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7533 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7534 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	7535
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7536
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7537 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7538 <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	7539 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	7540 <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	7541 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	7542 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	7543 These indices are corrected
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7544 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	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 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	7549
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7550
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7551
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7552
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7553 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7554 <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	7555 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	7556 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	7557 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	7558 to its corresponding argument.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7559
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7562 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	7563
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7564
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7565
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7568 <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	7569
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7570
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7571 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7572 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	7573 (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	7574 of the given function,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7575 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	7576 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	7577 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	7578 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	7579 about the function
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7580 (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	7581
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7584 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	7585 When (re)loaded,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7586 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	7587 (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	7588 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	7589 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	7590
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7591
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7592
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7595 <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	7596
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7599 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	7600 <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	7601 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	7602 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	7603 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	7604 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	7605 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	7606 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	7607 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	7608 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	7609 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	7610 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	7611 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	7612
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7613
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7614 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7615 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	7616 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	7617 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	7618 after the two indices.
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7621
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7624 <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	7625
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7626
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7627 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7628 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	7629 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	7630 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	7631 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	7632 <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	7633 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	7634 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	7635 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	7636 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	7637 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	7638 For instance, the call
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 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7641 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	7642 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7643 may produce the string:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7644
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7645 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7646 "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	7647 new line"
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7648 </pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7649
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7650 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7651 Options
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7652 <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	7653 <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	7654 <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	7655 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	7656 <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	7657 expect an integer.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7658 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	7659 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	7660 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	7661 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	7662
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7663
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7664
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7665
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7666 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7667 <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	7668 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	7669 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	7670 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	7671 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	7672 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	7673 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	7674
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7675
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7676 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7677 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	7678 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	7679 printing one per line:
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 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7682 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	7683 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	7684 print(w)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7685 end
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7686 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7687 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	7688 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	7689
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7690 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7691 t = {}
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7692 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	7693 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	7694 t[k] = v
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7695 end
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7696 </pre>
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7699 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	7700 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	7701
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7702
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 <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	7707 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	7708 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	7709 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	7710 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	7711 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	7712 <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	7713 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	7714 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	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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7718 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	7719 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	7720 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	7721 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	7722 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	7723 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	7724 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	7725
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7726
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7727 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7728 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	7729 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	7730
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7731
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7732 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7733 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	7734 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	7735 in order.
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 In any case,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7740 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	7741 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	7742
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7743
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7744 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7745 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	7746 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	7747 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	7748 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	7749 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	7750 (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	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 Here are some examples:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7755
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7756 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7757 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	7758 --> 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	7759
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7760 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	7761 --> x="hello hello world"
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7762
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7763 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	7764 --> 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	7765
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7766 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	7767 --> 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	7768
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7769 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	7770 return load(s)()
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7771 end)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7772 --> x="4+5 = 9"
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7773
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7774 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	7775 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	7776 --> 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	7777 </pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7778
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 <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	7783 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	7784 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	7785 Embedded zeros are counted,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7786 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	7787
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7788
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7789
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7790
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7791 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7792 <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	7793 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	7794 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	7795 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	7796 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	7797
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7798
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7799
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7802 <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	7803 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	7804 <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	7805 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	7806 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	7807 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	7808 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	7809 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	7810 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	7811 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	7812 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	7813
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7814
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7815
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7816
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7817 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7818 <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	7819
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7820
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7821 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7822 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	7823 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	7824 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	7825
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7826
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7829 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7830 <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	7831
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7832
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7833 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7834 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	7835 with the given format.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7836 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	7837 '<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	7838
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7839
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7840
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7841
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7842 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7843 <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	7844 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	7845 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	7846 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	7847 (that is, no separator).
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7848 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	7849
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7852
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7853 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7854 <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	7855 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	7856
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7857
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7858
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7861 <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	7862 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	7863 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	7864 <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	7865 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	7866 (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	7867 In particular,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7868 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	7869 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	7870 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	7871 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	7872
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7875 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	7876 <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	7877 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	7878 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	7879 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	7880 If, after these corrections,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7881 <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	7882 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	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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7886
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7887 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7888 <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	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 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	7893 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	7894 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	7895 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	7896 After the read values,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7897 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	7898
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7899
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7900
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7903 <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	7904 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	7905 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	7906 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	7907 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	7908
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7909
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7910
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7911
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7912
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7913 <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	7914
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7915 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7916 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	7917 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	7918 <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	7919 <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	7920 <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	7921 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	7922 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	7923 (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	7924
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7925
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7926
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7927 <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	7928 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	7929 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	7930
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7931 <ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7932
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7933 <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	7934 (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	7935 <code>^$()%.[]*+-?</code>)
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7936 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	7937 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7938
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7939 <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	7940
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7941 <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	7942
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7943 <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	7944
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7945 <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	7946
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7947 <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	7948
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7949 <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	7950
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7951 <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	7952
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7953 <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	7954
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7955 <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	7956
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7957 <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	7958
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7959 <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	7960
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7961 <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	7962 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	7963 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	7964 Any non-alphanumeric character
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7965 (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	7966 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	7967 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	7968 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7969
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7970 <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	7971 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	7972 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	7973 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	7974 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	7975 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	7976 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	7977 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	7978 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	7979 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	7980 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	7981 <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	7982 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	7983 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	7984
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7985
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7986 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7987 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	7988 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	7989 have no meaning.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7990 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7991
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7992 <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	7993 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	7994 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	7995 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7996
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7997 </ul><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	7998 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	7999 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	8000 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	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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8004 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	8005 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	8006 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	8007
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8008
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8009
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8010
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8011
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8012 <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	8013 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	8014
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8015 <ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8016
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8017 <li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8018 a single character class,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8019 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	8020 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8021
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8022 <li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8023 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	8024 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	8025 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	8026 </li>
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 <li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8029 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	8030 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	8031 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	8032 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8033
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8034 <li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8035 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	8036 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	8037 Unlike '<code>*</code>',
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8038 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	8039 </li>
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 <li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8042 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	8043 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	8044 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	8045 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8046
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8047 <li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8048 <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	8049 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	8050 (see below);
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8051 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8052
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8053 <li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8054 <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	8055 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	8056 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	8057 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	8058 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	8059 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	8060 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	8061 balanced parentheses.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8062 </li>
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 <li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8065 <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	8066 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	8067 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	8068 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	8069 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	8070 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	8071 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	8072 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8073
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8074 </ul>
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8077
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8078
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8079 <h4>Pattern:</h4><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8080 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	8081 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	8082 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	8083 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	8084 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	8085 At other positions,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8086 '<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	8087
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8088
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8092 <h4>Captures:</h4><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8093 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	8094 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	8095 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	8096 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	8097 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	8098 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	8099 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	8100 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	8101 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	8102 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	8103
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8104
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8105 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8106 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	8107 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	8108 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	8109 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	8110
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8113
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8114
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8115
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 <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	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 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	8121 <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	8122 is a format string,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8123 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	8124
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8127 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	8128 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	8129
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8130 <ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8131 <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	8132 <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	8133 <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	8134 <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	8135 (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	8136 <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	8137 <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	8138 <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	8139 <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	8140 <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	8141 <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	8142 <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	8143 <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	8144 <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	8145 <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	8146 (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	8147 <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	8148 (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	8149 <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	8150 <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	8151 <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	8152 <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	8153 <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	8154 <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	8155 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	8156 (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	8157 <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	8158 <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	8159 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	8160 (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	8161 <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	8162 </ul><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8163 (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	8164 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	8165 (options "<code>xX <=>!</code>"),
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8166 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	8167 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	8168
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8171 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	8172 <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	8173 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	8174 <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	8175 <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	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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8179 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	8180 that is,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8181 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	8182 and native endianness.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8183
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8184
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8185 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8186 Alignment works as follows:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8187 For each option,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8188 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	8189 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	8190 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	8191 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	8192 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	8193 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	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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8197 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	8198 (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	8199
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8200
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8201
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8202
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8203
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8204
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8205
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8206 <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	8207
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8208 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8209 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	8210 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	8211 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	8212 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	8213 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	8214 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	8215
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8216
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8217 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8218 Unless stated otherwise,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8219 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	8220 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	8221 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	8222 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	8223 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	8224
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8225
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8226 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8227 <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	8228 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	8229 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	8230 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	8231
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8232
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8233
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8234
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8235 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8236 <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	8237 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	8238 (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	8239 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	8240 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	8241
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8242
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8243
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8244
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8245 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8246 <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	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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8250 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	8251
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8252 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8253 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	8254 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8255 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	8256 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	8257 of each character.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8258 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	8259
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8260
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8261
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8264 <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	8265 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	8266 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	8267 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	8268 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	8269
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8272
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8273 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8274 <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	8275 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	8276 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	8277 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	8278 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	8279 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	8280
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8281
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8284 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8285 <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	8286 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	8287 <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	8288 (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	8289 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	8290 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	8291 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	8292 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	8293 <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	8294 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	8295 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	8296 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	8297
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8300 As a special case,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8301 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	8302 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	8303
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8304
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8305 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8306 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	8307
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8308
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8309
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8310
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8311
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8312
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8313
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8314 <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	8315
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8316 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8317 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	8318 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	8319
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8320
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8321 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8322 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	8323 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	8324 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	8325 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	8326 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	8327
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8328
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8329 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8330 <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	8331
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8332
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8333 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8334 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	8335 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	8336 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	8337 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	8338 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	8339 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	8340
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8341
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8342
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8343
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8344 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8345 <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	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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8349 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	8350 shifting up the elements
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8351 <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	8352 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	8353 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	8354 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	8355
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8356
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8357
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8358
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8359 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8360 <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	8361
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8362
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8363 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8364 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	8365 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	8366 multiple assignment:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8367 <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	8368 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	8369 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	8370 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	8371
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8372
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8373
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8374
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8375 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8376 <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	8377
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8380 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	8381 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	8382 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	8383
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8386
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8387 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8388 <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	8389
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8392 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	8393 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	8394 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	8395 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	8396 <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	8397 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	8398 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	8399 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	8400 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	8401
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8402
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8403 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8404 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	8405 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	8406 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	8407
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8408
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8409
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8410
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8411 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8412 <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	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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8416 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	8417 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	8418 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	8419 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	8420 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	8421 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	8422 (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	8423 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	8424 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	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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8428 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	8429 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	8430 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	8431
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8432
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8433
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8434
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8435 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8436 <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	8437
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8438
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8439 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8440 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	8441 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	8442
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8443 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8444 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	8445 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8446 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	8447
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 <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	8455
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8456 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8457 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	8458 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	8459 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	8460 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	8461 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	8462 Rounding functions
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8463 (<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	8464 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	8465 or a float otherwise.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8466
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8469 <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	8470
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8471
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8472 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8473 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	8474
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8475
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8476
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8477
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8478 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8479 <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	8480
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8481
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8482 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8483 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	8484
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8485
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8486
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8487
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8488 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8489 <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	8490
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8491
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8492 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8493 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	8494
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8495
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8496
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8497
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8498 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8499 <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	8500
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8501
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8502 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8503
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8504 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	8505 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	8506 quadrant of the result.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8507 (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	8508
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8509
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8510 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8511 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	8512 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	8513 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	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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8517
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8518 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8519 <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	8520
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8523 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	8524
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8525
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8526
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8527
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8528 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8529 <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	8530
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8531
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8532 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8533 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	8534
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8535
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8536
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8539 <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	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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8543 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	8544
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8547
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8548 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8549 <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	8550
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8551
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8552 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8553 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	8554 (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	8555
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8556
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8557
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8558
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8559 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8560 <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	8561
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8564 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	8565
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8566
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8567
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8568
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8569 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8570 <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	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 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	8575 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	8576
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8577
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8578
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8581 <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	8582
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8583
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8584 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8585 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	8586 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	8587
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8588
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8591 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8592 <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	8593
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8594
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8595 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8596 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	8597 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	8598 (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	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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8602
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8603 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8604 <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	8605
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8606
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8607 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8608 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	8609 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	8610
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8611
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8612
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8613
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8614 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8615 <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	8616 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	8617
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8622 <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	8623
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8624
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8625 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8626 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	8627 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	8628
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8629
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8630
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8631
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8632 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8633 <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	8634 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	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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8638
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8639 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8640 <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	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 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	8645 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	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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8651 <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	8652
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 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	8656
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8660 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8661 <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	8662
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8663
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8664 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8665 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	8666
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8667
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8668
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8671 <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	8672
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8673
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8674 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8675 When called without arguments,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8676 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	8677 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	8678 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	8679 <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	8680 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	8681 (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	8682 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	8683
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8686 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	8687 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	8688 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	8689
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8690
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8691
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8692
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8693 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8694 <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	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 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	8699 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	8700 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	8701
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8702
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8703
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8704
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8705 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8706 <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	8707
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8708
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8709 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8710 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	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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8714
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8715 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8716 <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	8717
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8718
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8719 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8720 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	8721 (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	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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8726 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8727 <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	8728
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8729
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8730 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8731 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	8732
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8733
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8734
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8735
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8736 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8737 <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	8738
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8741 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	8742 returns that integer.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8743 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	8744
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8749 <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	8750
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8753 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	8754 "<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	8755 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	8756
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8757
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8758
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8759
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8760 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8761 <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	8762
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8765 Returns a boolean,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8766 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	8767 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	8768
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8774
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8775 <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	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 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	8779 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	8780 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	8781 default output file,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8782 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	8783 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	8784
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8787 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	8788 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	8789 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	8790 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	8791 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	8792
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 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	8796 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	8797 <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	8798 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	8799
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8800
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8801 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8802 Unless otherwise stated,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8803 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	8804 (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	8805 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	8806 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	8807 On non-POSIX systems,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8808 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	8809 in case of errors
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8810 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	8811 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	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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8815 <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	8816
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8817
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8818 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8819 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	8820 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	8821
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8826 <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	8827
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8830 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	8831
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8836 <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	8837
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8840 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	8841 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	8842 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	8843 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	8844 When called without parameters,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8845 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	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 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	8850 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	8851
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8856 <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	8857
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8860 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	8861 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	8862 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	8863 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	8864 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	8865
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8866
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8867 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8868 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	8869 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	8870 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	8871 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	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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8875 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	8876 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	8877
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8881 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8882 <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	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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8886 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	8887 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	8888 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	8889 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	8890
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8891
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8892 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8893 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	8894
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8895 <ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8896 <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	8897 <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	8898 <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	8899 <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	8900 <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	8901 <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	8902 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	8903 </ul><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8904 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	8905 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	8906
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8907
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8908
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8911 <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	8912
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8913
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8914 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8915 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	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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8919
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8920 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8921 <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	8922
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8923
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8924 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8925 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	8926 on all platforms.
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 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	8931 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	8932 (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	8933 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	8934 (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	8935
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8936
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8940 <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	8941
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8942
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8943 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8944 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	8945
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8946
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8947
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8950 <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	8951
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8952
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8953 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8954 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	8955 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	8956 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	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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8960
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8961 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8962 <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	8963
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8964
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8965 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8966 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	8967 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	8968 <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	8969 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	8970
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8971
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8972
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8975 <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	8976
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8977
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8978 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8979 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	8980
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8981
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8982
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8983
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8984 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8985 <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	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 Closes <code>file</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8990 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	8991 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	8992 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	8993
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	8996 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	8997 <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	8998 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	8999
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9003 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9004 <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	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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9008 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	9009
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9013 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9014 <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	9015
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9016
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9017 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9018 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	9019 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	9020 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	9021 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	9022 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	9023 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	9024
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9025 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9026 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	9027 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9028 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	9029 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	9030 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	9031 when the loop ends.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9032
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9035 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	9036 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	9037
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9038
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9042 <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	9043
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9044
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9045 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9046 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	9047 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	9048 For each format,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9049 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	9050 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	9051 (In this latter case,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9052 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	9053 When called without formats,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9054 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	9055 (see below).
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9058 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9059 The available formats are
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 <ul>
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 <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	9064 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	9065 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	9066 (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	9067 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	9068 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	9069 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	9070 (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	9071 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	9072 </li>
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 <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	9075 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	9076 </li>
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 <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	9079 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	9080 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	9081 </li>
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 <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	9084 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	9085 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	9086 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	9087 </li>
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 <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	9090 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	9091 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	9092 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9093
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9094 <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	9095 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	9096 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	9097 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	9098 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	9099 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	9100 </li>
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 </ul><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9103 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	9104
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9105
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9109 <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	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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9113 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	9114 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	9115 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	9116 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	9117
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9118 <ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9119 <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	9120 <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	9121 <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	9122 </ul><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9123 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	9124 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	9125 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	9126 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	9127
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9128
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9129 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9130 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	9131 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	9132 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	9133 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	9134 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	9135 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	9136 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	9137 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	9138
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9139
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9140
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9141
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9142 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9143 <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	9144
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9145
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9146 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9147 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	9148 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	9149
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9150 <ul>
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 <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	9153 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	9154 </li>
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 <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	9157 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	9158 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	9159 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	9160 </li>
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 <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	9163 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	9164 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	9165 (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	9166 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9167
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9168 </ul><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9169 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	9170 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	9171 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	9172
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9173
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9174
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9177 <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	9178
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9179
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9180 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9181 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	9182 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	9183
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9186 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	9187 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	9188
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9194
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9195 <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	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 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	9199
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9200
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9201 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9202 <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	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 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	9207 used by the program.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9208
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9209
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 <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	9214
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9217 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	9218 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	9219
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9220
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9221 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9222 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	9223 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	9224 (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	9225 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	9226
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9227
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9228 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9229 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	9230 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	9231 After this optional character,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9232 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	9233 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	9234 <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	9235 <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	9236 <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	9237 <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	9238 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	9239 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	9240 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	9241
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9242
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9243 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9244 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	9245 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	9246 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	9247
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9248
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9249 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9250 When called without arguments,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9251 <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	9252 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	9253 (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	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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9257 On non-POSIX systems,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9258 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	9259 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	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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9263
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9264 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9265 <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	9266
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9267
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9268 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9269 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	9270 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	9271 (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	9272 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	9273 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	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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9278 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9279 <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	9280
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9281
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9282 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9283 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	9284 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	9285 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	9286 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	9287 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	9288 After this first result
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9289 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	9290 as follows:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9291
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9292 <ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9293
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9294 <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	9295 the command terminated normally;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9296 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	9297 </li>
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 <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	9300 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	9301 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	9302 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9303
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9304 </ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9305
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9306 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9307 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	9308 <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	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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9313 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9314 <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	9315
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9316
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9317 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9318 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	9319 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	9320 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	9321 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	9322 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	9323 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	9324 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	9325 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	9326
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9327
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9328 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9329 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	9330 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	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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9334
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9335 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9336 <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	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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9340 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	9341 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	9342
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9346 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9347 <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	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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9351 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	9352 with the given name.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9353 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	9354 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	9355
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9356
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9357
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9358
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9359 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9360 <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	9361
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9364 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	9365 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	9366 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	9367
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9368
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9369
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9372 <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	9373
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9374
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9375 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9376 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	9377 <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	9378 <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	9379 <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	9380 <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	9381 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	9382 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	9383 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	9384
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9385
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9386 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9387 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	9388 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	9389 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	9390 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	9391
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9392
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9393 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9394 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	9395 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	9396 for the given category.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9397
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9400 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	9401 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	9402
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9403
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9404
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9405
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9406 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9407 <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	9408
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9409
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9410 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9411 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	9412 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	9413 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	9414 and may have fields
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9415 <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	9416 <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	9417 <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	9418 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	9419 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	9420
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9421
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9422 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9423 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	9424 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	9425 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	9426 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	9427 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	9428 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	9429 <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	9430
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9433
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9434 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9435 <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	9436
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9437
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9438 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9439 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	9440 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	9441 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	9442 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	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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9446 On POSIX systems,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9447 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	9448 to avoid security risks.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9449 (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	9450 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	9451 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	9452 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	9453
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9454
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9455 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9456 When possible,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9457 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	9458 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	9459
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9460
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9461
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9462
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9463
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9464
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 <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	9467
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9468 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9469 This library provides
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9470 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	9471 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	9472 Several of its functions
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9473 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	9474 (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	9475 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	9476 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	9477 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	9478 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	9479 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	9480
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9481
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9482 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9483 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	9484 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	9485 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	9486 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	9487 thread to operate over.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9488 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	9489
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9490
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9491 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9492 <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	9493
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9494
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9495 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9496 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	9497 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	9498 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	9499 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	9500 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	9501 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	9502 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	9503
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9504
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9505 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9506 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	9507 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	9508
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9509
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9513 <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	9514
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9515
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9516 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9517 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	9518 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	9519 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	9520 (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	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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9524
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9525 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9526 <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	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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9530 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	9531 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	9532 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	9533 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	9534 of the given thread:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9535 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	9536 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	9537 (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	9538 and so on.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9539 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	9540 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	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 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	9545 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	9546 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	9547 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	9548 If present,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9549 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	9550 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	9551 If present,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9552 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	9553 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	9554 valid lines.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9555
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9556
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9557 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9558 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	9559 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	9560 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	9561 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	9562 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	9563 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	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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9567
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9568 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9569 <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	9570
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9571
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9572 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9573 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	9574 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	9575 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	9576 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	9577
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9578
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9579 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9580 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	9581 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	9582 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	9583 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	9584 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	9585 -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	9586 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	9587 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	9588 (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	9589
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9590
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9591 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9592 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	9593 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	9594 (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	9595 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	9596
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9597
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9598 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9599 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	9600 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	9601
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9602
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9603
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9606 <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	9607
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9608
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9609 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9610 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	9611 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	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-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	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 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	9622
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9623
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9624
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9625
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9626 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9627 <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	9628
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9631 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	9632 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	9633 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	9634
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9635
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9636 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9637 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	9638 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	9639 (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	9640
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
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 <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	9646
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9649 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	9650 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	9651 returns <b>nil</b>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9652
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9656 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9657 <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	9658
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9659
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9660 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9661 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	9662 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	9663 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	9664 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	9665 with the given meaning:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9666
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9667 <ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9668 <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	9669 <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	9670 <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	9671 </ul><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9672 Moreover,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9673 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	9674 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	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 When called without arguments,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9679 <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	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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9683 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	9684 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	9685 <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	9686 <code>"return"</code>,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9687 <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	9688 For line events,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9689 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	9690 Inside a hook,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9691 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	9692 the running function
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9693 (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	9694 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	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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9698
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9699 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9700 <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	9701
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9702
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9703 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9704 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	9705 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	9706 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	9707 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	9708 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	9709 (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	9710 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	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 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	9715 variable indices and names.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9716
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9717
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9718
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9719
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9720 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9721 <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	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 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	9726 (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	9727 Returns <code>value</code>.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9728
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9732 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9733 <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	9734
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9737 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	9738 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	9739 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	9740 with the given index.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9741 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	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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9745
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9746 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9747 <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	9748
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9749
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9750 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9751 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	9752 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	9753 <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	9754
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9755
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9756 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9757 Returns <code>udata</code>.
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9761
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9762 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9763 <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	9764
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9765
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9766 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9767 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	9768 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	9769 Otherwise,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9770 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	9771 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	9772 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	9773 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	9774 to start the traceback
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9775 (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	9776
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9777
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9778
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9779
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9780 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9781 <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	9782
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9783
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9784 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9785 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	9786 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	9787 from the given function.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9788
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9789
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9790 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9791 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	9792 closures share upvalues.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9793 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	9794 (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	9795 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	9796
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9801 <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	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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9805 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	9806 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	9807
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9808
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9809
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9810
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9811
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9812
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9813
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9814 <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	9815
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9816 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9817 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	9818 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	9819 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	9820 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	9821 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	9822 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	9823 The standalone interpreter includes
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9824 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	9825 Its usage is:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9826
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9827 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9828 lua [options] [script [args]]
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9829 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9830 The options are:
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 <ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9833 <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	9834 <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	9835 <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	9836 <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	9837 <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	9838 <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	9839 <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	9840 </ul><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9841 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	9842 When called without arguments,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9843 <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	9844 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	9845 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	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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9849 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	9850 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	9851 (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	9852 before running any argument.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9853 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	9854 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	9855 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	9856
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9857
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9858 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9859 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	9860 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	9861 Lua also ignores
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9862 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	9863 setting the values of
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9864 <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	9865 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	9866
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9867
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9868 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9869 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	9870 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	9871
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9872 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9873 $ 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	9874 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9875 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	9876 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	9877 (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	9878
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9881 Before running any code,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9882 <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	9883 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	9884 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	9885 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	9886 and so on.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9887 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	9888 (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	9889 go to negative indices.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9890 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	9891
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9892 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9893 $ 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	9894 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9895 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	9896
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9897 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9898 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	9899 [0] = "b.lua",
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9900 [1] = "t1", [2] = "t2" }
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9901 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9902 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	9903 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	9904 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	9905 For instance, the call
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9906
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9907 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9908 $ 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	9909 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9910 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	9911 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	9912 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	9913 <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	9914 (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	9915 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	9916
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9917
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9918 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9919 In interactive mode,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9920 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	9921 After reading a line,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9922 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	9923 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	9924 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	9925 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	9926 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	9927 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	9928
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9929
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9930 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9931 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	9932 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	9933 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	9934 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	9935 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	9936 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	9937 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	9938
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9941 When finishing normally,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9942 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	9943 (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	9944 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	9945 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	9946
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9947
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9948 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9949 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	9950 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	9951 the standalone interpreter skips
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9952 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	9953 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	9954 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	9955 as in
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 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9958 #!/usr/local/bin/lua
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9959 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9960 (Of course,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9961 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	9962 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	9963 then
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9964
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9965 <pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9966 #!/usr/bin/env lua
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9967 </pre><p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9968 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	9969
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9970
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9971
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9972 <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	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 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	9976 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	9977 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	9978 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	9979 However,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9980 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	9981
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9982
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9983 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9984 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	9985 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	9986 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	9987 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	9988 Therefore,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9989 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	9990 different Lua versions.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9991 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	9992 using a new version.
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9995 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9996 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	9997 of precompiled chunks;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	9998 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	9999
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10000
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10001 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10002 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	10003 change between versions.
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10006
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10007 <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	10008 <ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10009
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10010 <li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10011 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	10012 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	10013 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	10014 some computations
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10015 (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	10016 can give different results.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10017
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 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10020 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	10021 (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	10022 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	10023 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	10024 (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	10025 for an occasional incompatibility;
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10026 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	10027 For good programming,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10028 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	10029 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	10030 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10031
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10032 <li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10033 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	10034 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	10035 (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	10036 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	10037 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	10038 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	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 (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	10043 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	10044 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	10045 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10046
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10047 <li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10048 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	10049 (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	10050 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10051
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10052 </ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10053
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 <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	10058 <ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10059
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10060 <li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10061 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	10062 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	10063 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	10064 (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	10065 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	10066 </li>
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 <li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10069 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	10070 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	10071 </li>
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 <li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10074 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	10075 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	10076 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10077
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10078 <li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10079 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	10080 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	10081 </li>
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 <li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10084 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	10085 <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	10086 <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	10087 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	10088 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	10089 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	10090 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	10091 For the other operations,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10092 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	10093 implement them in Lua.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10094 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10095
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10096 <li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10097 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	10098 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	10099 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	10100 (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	10101 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	10102 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	10103 (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	10104 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	10105 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10106
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10107 </ul>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10108
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10109
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10110
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10111
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10112 <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	10113
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 <ul>
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 <li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10118 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	10119 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	10120 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	10121 Adapt your code accordingly.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10122 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10123
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10124 <li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10125 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	10126 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	10127 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10128
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10129 <li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10130 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	10131 (<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	10132 <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	10133 were deprecated.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10134 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	10135 </li>
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 <li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10138 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	10139 (<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	10140 were deprecated.
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10141 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	10142 (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	10143 </li>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10144
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10145 </ul>
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 <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	10151
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10152 <p>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10153 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	10154 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	10155 {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	10156 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	10157 (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	10158 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	10159 Name, Numeral,
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10160 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	10161
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10162
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10163
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10167 chunk ::= block
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10168
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10169 block ::= {stat} [retstat]
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10170
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10171 stat ::= ‘<b>;</b>’ \|
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10172 varlist ‘<b>=</b>’ explist \|
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10173 functioncall \|
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10174 label \|
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10175 <b>break</b> \|
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10176 <b>goto</b> Name \|
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10177 <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	10178 <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	10179 <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	10180 <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	10181 <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	10182 <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	10183 <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	10184 <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	10185 <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	10186
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10187 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	10188
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10189 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	10190
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10191 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	10192
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10193 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	10194
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10195 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	10196
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10197 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	10198
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10199 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	10200
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10201 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	10202 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	10203
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10204 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	10205
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10206 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	10207
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10208 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	10209
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10210 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	10211
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10212 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	10213
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10214 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	10215
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10216 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	10217
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10218 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	10219
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10220 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	10221
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10222 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	10223
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10224 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	10225 ‘<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	10226 ‘<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	10227 <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	10228
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10229 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	10230
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10231 </pre>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10232
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10233 <p>
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
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10236
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10237
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10238
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10239
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10240
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10241
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10242 <HR>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10243 <SMALL CLASS="footer">
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10244 Last update:
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10245 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	10246 </SMALL>
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10247 <!--
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10248 Last change: minor edit
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10249 -->
e01cddba3433 add manual.html as copy of Lua 5.3 Reference Manual Franklin Schmidt <fschmidt@gmail.com> parents: diff changeset	10250
372 f08cefa4594c start editing manual Franklin Schmidt <fschmidt@gmail.com> parents: 371 diff changeset	10251 </div>
f08cefa4594c start editing manual Franklin Schmidt <fschmidt@gmail.com> parents: 371 diff changeset	10252 </body>
f08cefa4594c start editing manual Franklin Schmidt <fschmidt@gmail.com> parents: 371 diff changeset	10253 </html>

Mercurial Hosting > luan

annotate website/src/manual.html @ 380:6c6c3537035e